Skip to content

Commit

Permalink
New Landing Page for the Contract Section (#1698)
Browse files Browse the repository at this point in the history
* feat: landing page contracts

* fix: security section

* fix: links

* Update docs/2.develop/contracts/security/checklist.md

---------

Co-authored-by: Damián Parrino <[email protected]>
  • Loading branch information
gagdiez and bucanero authored Jan 31, 2024
1 parent b3c7925 commit 80d6ade
Show file tree
Hide file tree
Showing 12 changed files with 132 additions and 90 deletions.
12 changes: 0 additions & 12 deletions docs/2.develop/contracts/security/audits.md

This file was deleted.

18 changes: 12 additions & 6 deletions docs/2.develop/contracts/security/checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,28 @@ title: ✅ Checklist

Once you finished developing your smart contract please go through the following list in order to ensure everything is safe for the end user.

### Anatomy
1. All private methods are decorated as`private`.
:::info
Check our [security articles](/develop/contracts/security/welcome) to understand how to improve the security of your contract.
:::

### Environment
---

## Anatomy
1. All private methods are decorated as `private`.

## Environment
2. `predecessor` and `signer` are used correctly through the entire contract.

### Storage
## Storage
3. Each time the state grows it is ensured that there is enough balance to cover it
4. All collections (i.e. Vector, Map, Tree, etc) have an unique id
5. Check for underflow and overflow!. In rust, you can do this by simply adding the `overflow-checks = true` flag in your `Cargo.toml`.

### Actions
## Actions
6. When sending money, you leave enough in the contract to cover the storage cost
7. If you are tracking user's fund, you **deduct them before** sending them back to the user.

### Callbacks
## Callbacks
8. All private callbacks are marked as `private`
9. All cross-contract calls have a callback that checks for errors and rolls back the state if necessary
10. All cross-contract calls have a callback that checks for errors and returns money to the `predecessor` if necessary
Expand Down
11 changes: 4 additions & 7 deletions docs/2.develop/contracts/security/welcome.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,14 @@ Please take some time to go through this section, it will help you to keep your

---

### 🔍 Smart Contract Audit Program
Pagoda has an [Smart Contract Audit Program](./audits.md), make sure to check it.

### 🐞 Bug Bounty Program
## 🐞 Bug Bounty Program
NEAR has a [revamped bug bounty program](./bounty.md), use it if you find any security errors in the protocol or mainstream apps.

### ✅ Security Checklist
## ✅ Security Checklist
Make sure to keep your smart contract safe by running through our [security checklist](./checklist.md).

### 🛡️ Security Concepts
Lear important security concepts to keep your dApp safe and sound. Read about:
## 🛡️ Security Concepts
Learn important security concepts to keep your dApp safe and sound. Read about:

- Keeping [callbacks safe](./callbacks.md).
- Understanding [frontrunning](./frontrunning.md).
Expand Down
50 changes: 33 additions & 17 deletions docs/2.develop/contracts/welcome.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,47 @@ id: welcome
title: NEAR Smart Contracts
sidebar_label: Home
hide_table_of_contents: true
hide_breadcrumb: true
---

import {FeatureList, Column, Feature} from "@site/src/components/featurelist"
import ContactUs from '@site/src/components/ContactUs.mdx';


Welcome! Here you will find documentation on how to develop a smart contract on NEAR.

Do not worry if you are new to smart contract technology, we will get you up to speed in no time.
Welcome! Smart contracts are pieces of **executable code** that live in a NEAR account. They can **store data**, **perform transactions** in the account’s name, and **expose methods** so other accounts can interact with them.

<FeatureList>
<Column title="Build dApps">
<Feature url="/develop/contracts/whatisacontract" title="What is a Contract?" subtitle="Learn what a smart contract is" image="guest-book.png" />
<Feature url="/develop/contracts/quickstart" title="Build a Contract" subtitle="Spin-up your first smart contract" image="smartcontract.png" /> <Feature url="/develop/testing/introduction" title="Test the Contract" subtitle="Write unit & integration tests" image="test.png" />
<Feature url="/develop/integrate/frontend" title="Build a Web Frontend" subtitle="Learn how to make a web dApp" image="frontend.png" />
<Feature url="/tools/realtime" title="Track Your Users Activity" subtitle="Learn how to use Indexers" image="monitor.png" />
<Column title="Development Cycle">
<Feature url="/develop/contracts/whatisacontract" title="What is a Contract?"
subtitle="Learn what a smart contract is" image="contract.png" highlight />
<Feature url="/develop/contracts/quickstart" title="Build a Contract"
subtitle="Spin-up your first smart contract" image="smartcontract.png" />
<Feature url="/develop/testing/introduction" title="Test a Contract" subtitle="Write unit & integration tests" image="test.png" />
<Feature url="/develop/contracts/security/checklist" title="Security Checklist"
subtitle="Make sure your contract is safe" image="validation.png" />
<Feature url="/develop/deploy" title="Deploy a Contract" subtitle="Deploy the contract to the network" image="blocks.png" />
</Column>
<Column title="Developer Tools">
<Feature url="/sdk/js/introduction" title="Javascript SDK" subtitle="Write Contracts in Javascript" image="smartcontract-js.png" />
<Feature url="/sdk/rust/introduction" title="Rust SDK" subtitle="Write Contracts in Rust" image="smartcontract-rust.png" />
<Feature url="/tools/near-cli" title="NEAR CLI" subtitle="Use NEAR from the Terminal" image="near-cli.png" />
<Column title="Examples & Tutorials">
<Feature url="/tutorials/examples/guest-book" title="Guest-Book Example"
subtitle="Store multiple messages on-chain" image="guest-book.png" />
<Feature url="/tutorials/examples/xcc" title="Cross-Calls Example"
subtitle="Query and execute methods in other contracts" image="cross-call.png" />
<Feature url="/tutorials/examples/coin-flip" title="Coin Flip Example"
subtitle="Generate random numbers in a contract" image="random.png" />
<Feature url="/tutorials/nfts/introduction" title="Zero-to-Hero NFT"
subtitle="Build a NFT contract from scratch" image="nft-marketplace-rs.png" />
<Feature url="/tutorials/fts/introduction" title="Zero-to-Hero FT"
subtitle="Build a FT contract from scratch" image="ft.png" />


</Column>
<Column title="Unleash the Web3">
<Feature url="/develop/relevant-contracts/ft" title="Fungible Tokens" subtitle="Learn how to use and make FT" image="ft.png" />
<Feature url="/develop/relevant-contracts/nft" title="Non-Fungible Tokens" subtitle="Enter the NFT space" image="nft.png" />
<Feature url="/develop/relevant-contracts/dao" title="Autonomous Organizations" subtitle="Understand DAOs" image="dao.png" />

<Column title="Related Resources">
<Feature url="/develop/integrate/frontend" title="Build a Web Frontend"
subtitle="Use the contract in a frontend" image="frontend.png" />
<Feature url="/develop/monitor" title="Track Your Users Activity" subtitle="Learn how to use Indexers" image="monitor.png" />
<Feature url="/primitives/ft" title="Fungible Tokens" subtitle="Learn how to use and make FT" image="ft.png" />
<Feature url="/primitives/nft" title="Non-Fungible Tokens" subtitle="Enter the NFT space" image="nft.png" />
<Feature url="/primitives/dao" title="Autonomous Organizations" subtitle="Understand DAOs" image="dao.png" />
</Column>
</FeatureList>

Expand Down
51 changes: 37 additions & 14 deletions docs/2.develop/contracts/whatiscontract.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,60 @@ title: What is a Smart Contract?
sidebar_label: What is a Smart Contract?
---

Smart contracts are simple programs that live in a NEAR network. As any modern application, smart contracts store data and expose methods to interact with them.

They are written in human-readable languages, then compiled and deployed to an account where everyone can interact with them.
Smart contracts are pieces of **executable code** that live in a NEAR account. They can **store data**, **perform transactions** in the account’s name, and **expose methods** so other accounts can interact with them.

Do not worry if you don't know how smart-contract blockchains work. As a developer, it is sufficient to understand that NEAR smart-contracts:
1. Have **limited** computational resources.
2. Interact with other contracts in an **asynchronous** way.
3. Deal with **real money**, for which security must be a top concern.

:::info HTTP Requests and Smart Contracts
Smart contracts **cannot perform HTTP requests**, meaning they can't retrieve data from outside the NEAR network. However, they can receive data from any outside source. If needed, you can set up a server to regularly feed them data (this is in short how [Oracles](../relevant-contracts/oracles.md) work).
Smart contracts **cannot perform HTTP requests**, meaning they can't fetch data from outside the NEAR network.
:::

---

## Programming Languages
Developers can choose between using [JavaScript](../../sdk/js/js-sdk.md) or [Rust](../../sdk/rust/rs-sdk.md) to write smart contracts in NEAR.
## Where do Contracts Live?
Smart Contracts are deployed into [**NEAR accounts**](../../1.concepts/basics/accounts/introduction.md). Any NEAR account can hold a contract, needing to pay for the **contract's code** and the **data it stores**. Since storage is cheap (0.01Ⓝ per kb) deploying a contract generally costs just a few cents.

![img](/docs/assets/welcome-pages/contract-landing.png)

Indistinctly from the language chosen, the NEAR SDK will help you to compile the contract into WebAssembly, from which point it can be deployed and executed on the NEAR platform.
Once in an account, anyone can interact with the contract. Thanks to the underlying network structure, executing code from a contract is both **fast** (avg. 1.4s finality) and **cheap**. Moreover, **read-only** operations are **free for everyone**.

While it is not necessary to be an expert in either language, during these docs we will assume you have a basic knowledge of at least one of them.
---

:::caution The [JS-SDK](https://github.com/near/near-sdk-js/releases/) is currently in Alpha
## Life Cycle of a Contract

The JavaScript runtime has not been fully audited. For creating smart contracts that hold value please use [`near-sdk-rs`](https://github.com/near/near-sdk-rs).
Just like any piece of software, smart contracts have a “life cycle” - starting with its creation and ending with monitoring it, all of which we cover in our documentation.

:::
![img](/docs/assets/welcome-pages/contract-lifecycle.png)

- [**Scaffold**](../contracts/quickstart.md): The simplest way to create a project is by starting from a template.
- [**Build**](../contracts/): To write a contract developers can choose between Javascript and Rust.
- [**Test**](../testing/introduction.md): Our Sandbox enables to simulate interactions with one or multiple contracts in a realistic environment.
- [**Deploy**](../deploy.md): After making sure the contract is secure, developers can deploy the contract into their accounts.
- [**Use**](https://mynearwallet.com): Any user can interact with the contract through their NEAR Wallet.
- [**Monitor**](../monitor.md): The contract's activity can be monitored through simple APIs.

### Other Languages
Theoretically, you can use any language that compiles to Wasm for developing NEAR smart contract. However, in order to have a user-friendly experience we would need
to provide a library that wraps around low-level runtime APIs, while also offering other high-level functionalities.
During the whole cycle, developers can choose between [JavaScript](https://www.learn-js.org/) and [Rust](https://www.rust-lang.org/), allowing them to use their favorite language at each step of their journey.

<details>
<summary> Other languages </summary>
Theoretically, you can use any language that compiles to Wasm for developing NEAR smart contract. However, in order to have a user-friendly experience we would need to provide a library that wraps around low-level runtime APIs, while also offering other high-level functionalities.

We envision that in the future, more languages will be supported and the support will be done through the effort from the wider community, not just NEAR alone.
</details>

---

## Contract Primitives
Contract primitives are the fundamental building blocks that can be combined to create a fully functional application. Blockchain primitives include Fungible Tokens (FT), Non Fungible Tokens (NFT), Decentralized Autonomous organizations (DAO), Link Drops and more.

- [Fungible Tokens (FT)](/primitives/ft): Fungible token is representation of an asset on a blockchain that is interchangeable. Besides the native NEAR token, users can issue their own fungible tokens or use those that are already present in the ecosystem and created by other users or projects.

- [Non Fungible Tokens (NFT)](/primitives/nft): In contrast with fungible tokens, non-fungible tokens (NFT) are unitary and therefore unique. This makes NFTs ideal to represent ownership of assets such as a piece of digital content, or a ticket for an event.

- [Decentralized Autonomous organizations (DAO)](/primitives/dao): Decentralized Autonomous Organizations (DAOs) are self-organized groups that form around common purposes. Membership, decision making, and funding are coordinated by publicly voting on proposals through a smart contract.

- [LinkDrops](/primitives/linkdrop): LinkDrops are an easy way to distribute digital assets (NFTs, FTs) via links. You provide a link for users and they can claim your drop.

3 changes: 1 addition & 2 deletions website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,7 @@ const sidebar = {
"id": "develop/contracts/security/welcome"
},
"items": [
"develop/contracts/security/checklist",
"develop/contracts/security/storage",
"develop/contracts/security/callbacks",
"develop/contracts/security/one-yocto",
Expand All @@ -169,7 +170,6 @@ const sidebar = {
"type": "html",
"value": "<hr/>"
},
"develop/contracts/security/audits",
"develop/contracts/security/bounty"
]
}
Expand Down Expand Up @@ -222,7 +222,6 @@ const sidebar = {
},
{
"Tutorials": [
"tutorials/fts/simple-fts",
{
"Non Fungible Tokens": [
"tutorials/nfts/minting-nfts",
Expand Down
71 changes: 40 additions & 31 deletions website/src/components/ContactUs.mdx
Original file line number Diff line number Diff line change
@@ -1,43 +1,52 @@
## Contact us

If you have any questions, or simply would want to chat with us, please do through one of our official channels. Also, jump into our [Discord server](https://near.chat) and join our Office Hours every weekday!
If you have any questions, or simply would want to chat with us, please do through one of our official channels.

<br/>

<div className="container">
<div className="row">
<div className="col" style={{ '--ifm-col-width': '250px', marginBottom: '2em'}}>
<div className="avatar">
<img
className="avatar__photo"
src={require("@site/static/docs/assets/home/twitter.png").default} />
<div className="avatar__intro">
<div className="avatar__name">Twitter</div>
<small className="avatar__subtitle"><a href="https://twitter.com/@nearprotocol">@nearprotocol</a></small>
</div>
<div class="container row">
<div class="col style={{ '--ifm-col-width': '250px', marginBottom: '2em'}}">
<div className="avatar">
<img
className="avatar__photo avatar__photo--sm"
src={require("@site/static/docs/assets/home/twitter.png").default} />
<div className="avatar__intro">
<div className="avatar__name">Twitter</div>
<small className="avatar__subtitle"><a href="https://twitter.com/@nearprotocol">@nearprotocol</a></small>
</div>
</div>
<div className="col" style={{ '--ifm-col-width': '250px', marginBottom: '2em'}}>
<div className="avatar">
<img
className="avatar__photo"
src={require("@site/static/docs/assets/home/discord.png").default} />
<div className="avatar__intro">
<div className="avatar__name">Discord</div>
<small className="avatar__subtitle"><a href="https://near.chat">NEAR Protocol</a></small>
</div>
</div>
<div class="col style={{ '--ifm-col-width': '250px', marginBottom: '2em'}}">
<div className="avatar">
<img
className="avatar__photo avatar__photo--sm"
src={require("@site/static/docs/assets/home/telegram.png").default} />
<div className="avatar__intro">
<div className="avatar__name">Telegram</div>
<small className="avatar__subtitle"><a href="https://t.me/neardev">NEAR Dev</a></small>
</div>
</div>
<div className="col" style={{ '--ifm-col-width': '250px', marginBottom: '2em'}}>
<div className="avatar">
<img
className="avatar__photo"
src={require("@site/static/docs/assets/home/zulip.png").default} />
<div className="avatar__intro">
<div className="avatar__name">Zulip</div>
<small className="avatar__subtitle"><a href="https://near.zulipchat.com/">Near Chat</a></small>
</div>
</div>
<div class="col style={{ '--ifm-col-width': '250px', marginBottom: '2em'}}">
<div className="avatar">
<img
className="avatar__photo"
src={require("@site/static/docs/assets/home/discord.png").default} />
<div className="avatar__intro">
<div className="avatar__name">Discord</div>
<small className="avatar__subtitle"><a href="https://near.chat">NEAR Protocol</a></small>
</div>
</div>
</div>
<div class="col style={{ '--ifm-col-width': '250px', marginBottom: '2em'}}">
<div className="avatar">
<img
className="avatar__photo"
src={require("@site/static/docs/assets/home/zulip.png").default} />
<div className="avatar__intro">
<div className="avatar__name">Zulip</div>
<small className="avatar__subtitle"><a href="https://near.zulipchat.com/">Near Chat</a></small>
</div>
</div>
</div>
</div>
</div>
2 changes: 1 addition & 1 deletion website/src/components/featurelist.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ export function Feature({ image, title, subtitle, url, highlight = false }) {

return <>
<h4> </h4>
<a className="avatar" href={url} style={{ backgroundColor: highlight && "rgb(240, 255, 240)" }}>
<a className="avatar" href={url} style={{ color: highlight && "var(--ifm-color-primary)" }}>
<img
className="avatar__photo"
src={require(`@site/static/docs/assets/welcome-pages/${image}`).default} />
Expand Down
4 changes: 4 additions & 0 deletions website/src/css/custom.scss
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@ hr {
margin: 3.5em 0;
}

.landing {
margin: 2.5em 0 1.5em 0;
}

li hr {
height: 4px;
margin: 0.2em auto;
Expand Down
Binary file added website/static/docs/assets/home/telegram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 80d6ade

Please sign in to comment.