diff --git a/docs/smart-contracts/quickstart.md b/docs/smart-contracts/quickstart.md index d95ef608871..0c3126a46f7 100644 --- a/docs/smart-contracts/quickstart.md +++ b/docs/smart-contracts/quickstart.md @@ -5,22 +5,27 @@ sidebar_label: Quickstart description: "Create your first contract using your favorite language." --- -import {Github} from '@site/src/components/UI/Codetabs'; +import {Github, Language} from '@site/src/components/UI/Codetabs'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import Card from '@site/src/components/UI/Card'; import MovingForwardSupportSection from '@site/src/components/MovingForwardSupportSection'; Welcome! [NEAR accounts](../protocol/account-model.md) can store small apps known as smart contracts. In this quick tutorial, we will guide you in creating your first contract on the NEAR **testnet**! -Join us in creating a friendly contract that stores a greeting, and exposes functions to interact with it. +Join us in creating a friendly auction contract, which allows users to place bids, track the highest bidder and claim tokens at the end of the auction. + +
+ + Prefer an online IDE? -:::tip Want to jump right into the code without setting up a local dev environment? - Checkout [NEAR Playground](https://nearplay.app/) for an easy-to-use online IDE w/ pre-configured templates. + Check out [NEAR Playground](https://nearplay.app/) for an easy-to-use online IDE with pre-configured templates. ![NEAR Playground](@site/static/assets/docs/smart-contracts/NEAR-Playground.png) -::: + +
--- @@ -36,22 +41,6 @@ Before starting, make sure to set up your development environment. - - -```bash -# Install Node.js using nvm (more options in: https://nodejs.org/en/download) -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash -nvm install latest - -# ⚠️ For Mac Silicon users only, Rosetta is needed to compile contracts -# /usr/sbin/softwareupdate --install-rosetta --agree-to-license - -# Install NEAR CLI to deploy and interact with the contract -npm install -g near-cli-rs@latest -``` - - - ```bash @@ -70,9 +59,31 @@ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/release - + ```bash +# Install Node.js using nvm (more options in: https://nodejs.org/en/download) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash +nvm install latest + +# ⚠️ For Mac Silicon users only, Rosetta is needed to compile contracts +# /usr/sbin/softwareupdate --install-rosetta --agree-to-license + +# Install NEAR CLI to deploy and interact with the contract +npm install -g near-cli-rs@latest +``` + + + + + +:::note +Python quickstart tutorial is coming soon! + +In the meantime, please check out the [hello-near](https://github.com/near-examples/hello-near-examples/tree/main/contract-py) example. +::: + + - - - -```bash -# Install Go (version <= 1.23.9) using GVM: https://github.com/moovweb/gvm -# or the official Go installation method: https://go.dev/doc/install - -# GVM Go installation method (recommended for managing different versions of Go) -sudo apt update -sudo apt install gcc make -sudo apt install bison -bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer) -gvm install go1.23.9 -B -gvm use go1.23.9 --default - -# Install TinyGo: https://tinygo.org/getting-started/install/ - -# Linux AMD64 (x86_64) -wget https://github.com/tinygo-org/tinygo/releases/download/v0.37.0/tinygo_0.37.0_amd64.deb -sudo dpkg -i tinygo_0.37.0_amd64.deb - -# Linux ARM64 -wget https://github.com/tinygo-org/tinygo/releases/download/v0.37.0/tinygo_0.37.0_arm64.deb -sudo dpkg -i tinygo_0.37.0_arm64.deb - -# macOS -brew tap tinygo-org/tools -brew install tinygo - -# Install NEAR Go CLI to manage and interact with smart contracts easily -# Alternatively, download it from GitHub Releases and move it manually to your bin folder. - -curl -LO https://github.com/vlmoon99/near-cli-go/releases/latest/download/install.sh && bash install.sh - -``` -:::note -Some `near-cli` commands have two versions - a **full** one and a **short** one. If you want to explore all options provided by `near-cli` use [the interactive mode](../tools/cli.md#interactive-mode). -::: - -:::tip Testnet Account - -There is no need to have a `testnet` account to follow this tutorial. - -However, if you want to create one, you can do so through [a wallet](https://testnet.mynearwallet.com), and use it from the `near-cli` by invoking `near login`. - -::: - -:::info Testnet tokens - -Need some `testnet` tokens? Use the [faucet](../faucet.md) to top-up your account. - -::: - --- ## Creating the Contract @@ -169,72 +127,30 @@ Need some `testnet` tokens? Use the [faucet](../faucet.md) to top-up your accoun Create a smart contract by using one of the scaffolding tools and following their instructions: - - - -```bash - npx create-near-app@latest -``` - -![img](@site/static/assets/docs/smart-contracts/hello-near-ts.gif) -_Creating a project using `create-near-app`_ - -This will generate a project with the following structure: - -```bash -hello-near -β”œβ”€β”€ sandbox-test # sandbox testing -β”‚ └── main.ava.js -β”œβ”€β”€ src # contract's code -β”‚ └── contract.ts -β”œβ”€β”€ README.md -β”œβ”€β”€ package.json # package manager -└── tsconfig.json -``` - -:::tip - -We recommend you to name your project `hello-near` for this tutorial, but feel free to use any name you prefer - -::: - - - ```bash - cargo near +cargo near ``` ![img](@site/static/assets/docs/smart-contracts/hello-near-rs.gif) _Creating a project using `cargo near new`_ -This will generate a project with the following structure: - -```bash -hello-near -β”œβ”€β”€ src # contract's code -β”‚ └── lib.rs -β”œβ”€β”€ tests # sandbox testing -β”‚ └── test_basics.rs -β”œβ”€β”€ Cargo.toml # package manager -β”œβ”€β”€ README.md -└── rust-toolchain.toml -``` + -:::tip + -You can skip the interactive menu and create a new project with specific name running the following command: ```bash - cargo near new hello-near +npx create-near-app@latest ``` -::: +![img](@site/static/assets/docs/smart-contracts/hello-near-ts.gif) +_Creating a project using `npx create-near-app@latest`_ -:::tip +:::important -`hello-near` is the name we chose for this project so the tutorial is simpler to follow, but for future projects feel free to use any name you prefer +When prompted to choose a template, select the basic `Auction` template to scaffold the auction contract ::: @@ -242,7 +158,13 @@ You can skip the interactive menu and create a new project with specific name ru -```bash +:::note +Python quickstart tutorial is coming soon! + +In the meantime, please check out the [hello-near](https://github.com/near-examples/hello-near-examples/tree/main/contract-py) example. +::: + + - -Create a new project using `near-go create`: - -```bash -near-go create -p "hello-world" -m "github.com/near/hello-world" -t "smart-contract-empty" -cd hello-world/contract -``` - -This creates a Go project with the following structure: - -```bash -hello-world/contract -β”œβ”€β”€ go.mod -β”œβ”€β”€ go.sum -└── main.go -``` + - +:::tip - +For this tutorial we chose to name the project `auction`, but feel free to use any name you prefer +::: --- ## The Contract -The `Hello World` smart contract stores a greeting in its state, and exposes two functions to interact with it: -1. `set_greeting`: to change the greeting -2. `get_greeting`: to fetch the greeting - - - +The auction smart contract allows users to place bids, track the highest bidder and claim tokens at the end of the auction. - - - +Do not worry about the code just yet β€” for now, it is enough to know that the most relevant function is `bid`, which allows users to place bids by attaching NEAR tokens: + - - + url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-rs/01-basic-auction/src/lib.rs" + start="37" end="63" /> - - - - + + - - Edit a `main.go` file for your contract: + + :::note + Python quickstart tutorial is coming soon! - + In the meantime, please check out the [hello-near](https://github.com/near-examples/hello-near-examples/tree/main/contract-py) example. + ::: + -:::tip - -After finishing this tutorial, check our [contract's anatomy](./anatomy/anatomy.md) page to learn more about the contract's structure - -::: +Besides `bid`, the contract exposes methods to initialize the auction (`init`), query the highest bidder (`get_highest_bid`), and claim tokens once the auction ends (`claim`). --- ## Test the Contract -Building and testing the contract is as simple as running the `test` command. The contract will be compiled and the tests will be executed. +Lets make sure the contract is working as expected by running its tests. Simply run the `test` command, the contract will then be compiled and deployed to a local sandbox for testing: + + + ```bash + cargo test + ``` + + + ```bash @@ -364,142 +261,45 @@ Building and testing the contract is as simple as running the `test` command. Th
Failing tests? - Make sure that you are using `node v18`, `v20` or `v22` - you can manage multiple versions using `nvm` - and that you have `Rosetta` installed on MacOS if you have an Apple Silicon processor. + Make sure that you are using `node v24 / 22 / 20`, and that you have installed `Rosetta` if you have a Mac with Apple Silicon
- - - - ```bash - cargo test - ``` - - ```bash - uv run pytest - ``` - - :::tip - - If you have multiple test files and want to run only one of them just pass the path to the file as an command line argument: - - ```bash - uv run pytest tests/test_mod.py - ``` + :::note + Python quickstart tutorial is coming soon! + In the meantime, please check out the [hello-near](https://github.com/near-examples/hello-near-examples/tree/main/contract-py) example. ::: - - - - - Create a test file for your contract (make sure you are inside the hello-world/contract directory) : - - ```bash - # Create a tests directory - touch main_test.go - ``` - - Add the following content to `main_test.go`: - - - - Run the test (make sure you are inside the hello-world/contract directory): - - ```bash - # Test package level - near-go test package - - # Test project level - near-go test project + - -In the background, these commands are calling the build tools for each language and using a [Sandbox](./testing/integration-test.md) to test the contract. - -:::tip Sandbox - -Testing the contracts within a Sandbox allows you to understand how the contract will behave once deployed to the network while having total control over the testing environment. - -::: +Feel free to check the test files to see how they interact with the contract. In short, a local NEAR sandbox is created, the contract is deployed, and different methods are called to verify the expected behavior. --- -## Create a Testnet Account - -Now that you know the contract is passing the tests, let's create a `testnet` account in which to deploy the contract. [`near-cli`](../tools/cli.md) supports two versions of some commands - full and short one. It's up to you which format you prefer, but full version provides more features. - - - - - ```bash - # Replace with a custom name - near create-account --useFaucet - ``` - -
- Example Result - - ```bash - $> near create-account lovely-event.testnet --useFaucet - # New account "lovely-event.testnet" created successfully - ``` - -
- - - - - ```bash - # Replace with a custom name - near account create-account sponsor-by-faucet-service autogenerate-new-keypair save-to-keychain network-config testnet create - ```` - -
- Example Result - - ```bash - $> near account create-account sponsor-by-faucet-service lovely-event.testnet autogenerate-new-keypair save-to-keychain network-config testnet create +## Build & Deploy the Contract - # New account "lovely-event.testnet" created successfully - ``` +Now that we know the tests are passing, let us deploy the contract! First, we need to compile it into WebAssembly: -
+ + + ```bash + cargo near build non-reproducible-wasm + ``` + - - - -:::tip - -Remember that you can create a named account through any wallet (i.e. [MyNearWallet](https://testnet.mynearwallet.com)) and then use it from the `near-cli` by invoking `near login`. - -::: - -:::warning - -When running the near account create-account command in a headless Linux environment (e.g., WSL), the `save-to-keychain` option may fail due to platform limitations. Use `save-to-legacy-keychain` instead of `save-to-keychain` to ensure compatibility. - -::: - - ---- - -## Build the Contract - -When you are ready to create a build of the contract run a one-line command depending on your environment. - - ```bash @@ -507,25 +307,16 @@ When you are ready to create a build of the contract run a one-line command depe ``` - - - - ```bash - cargo near build - ``` - - :::info + - For this tutorial we will use the `non-reproducible-wasm` option when building the contract, but please know that you can create a reproducible build if you have `Docker` installed + :::note + Python quickstart tutorial is coming soon! + In the meantime, please check out the [hello-near](https://github.com/near-examples/hello-near-examples/tree/main/contract-py) example. ::: - - - - - ```bash + - - - ```bash - near-go build - ``` - ---- +
-## Deploy the Contract +### Create an Account -Having our account created, we can now deploy the contract: +Let us now create a NEAR account where we will deploy the contract: - - - - +```bash +# Replace with a nameΒ for your contract account +near create-account --useFaucet +``` - ```bash - near deploy ./build/hello_near.wasm - ``` +:::tip Already have a testnet account? - - +If you already have a `testnet` account and would like to use it instead, you can log in with the command `near login`. - ```bash - near contract deploy use-file ./build/hello_near.wasm without-init-call network-config testnet sign-with-keychain send - ``` +::: - - - - +
+ + Got an error on Windows? + +When working on `WSL` - or any other headless Linux environment - you might encounter issues when trying to create an account as the `cli` tries to save the keys into the system's keychain. + +In such cases, you can try the following command to create the account: - - +```bash +near account create-account sponsor-by-faucet-service autogenerate-new-keypair save-to-legacy-keychain network-config testnet create +``` - ```bash - near deploy ./target/near/hello_near.wasm - ``` +
- +
- +### Deploy it! - ```bash - near contract deploy use-file ./target/near/hello_near.wasm without-init-call network-config testnet sign-with-keychain send - ``` +With the contract ready, we can now deploy it to the `testnet` account we created earlier: - - + + + ```bash + near deploy ./target/near/auction.wasm + ``` + + + + ```bash + near deploy ./build/auction.wasm + ``` - - - - ```bash - near deploy ./greeting_contract.wasm - ``` - - - + :::note + Python quickstart tutorial is coming soon! - ```bash - near contract deploy use-file ./greeting_contract.wasm without-init-call network-config testnet sign-with-keychain send - ``` + In the meantime, please check out the [hello-near](https://github.com/near-examples/hello-near-examples/tree/main/contract-py) example. + ::: - - - - - - ```bash - #Run (make sure you are inside the hello-world/contract directory) - - near-go build && near-go deploy -id "" -n "testnet" - ``` - - - ```bash - near deploy ./main.wasm - ``` - - - ```bash - near contract deploy use-file ./main.wasm without-init-call network-config testnet sign-with-keychain send - ``` - - - - -**Congrats**! Your contract now lives in the NEAR testnet network. +**Congrats!** Your contract now lives in the NEAR testnet network. --- @@ -655,83 +412,125 @@ Having our account created, we can now deploy the contract: To interact with your deployed smart contract, you can call its functions through the command line. +#### Initialize the Contract +Let us initialize the auction by setting when it ends and who receives the funds (the auctioneer): + +```bash +# Get a timestamp for 5 minutes from now (in nanoseconds) +FIVE_MINUTES_FROM_NOW=$(( $(date +%s%N) + 5 * 60 * 1000000000 )) + +# Initialize the auction +near call init "{\"end_time\": \"$FIVE_MINUTES_FROM_NOW\", \"auctioneer\": \"influencer.testnet\"}" --useAccount +``` + +:::tip +Feel free to replace `influencer.testnet` with any valid testnet account β€” this is where the winning bid will be sent +::: +
-#### Get Greeting -Let's start by fetching the greeting stored in the contract. The `get_greeting` function only reads from the contract's state, and can thus be called for **free**. +#### Place a Bid - - +We can now place a bid in the auction by calling the `bid` method while attaching some NEAR deposit. On each bid, the highest bid and bidder information will be recorded in the contract's [storage](./anatomy/storage.md). - ```bash - > near view get_greeting - # "Hello, NEAR world!" - ``` - +```bash +# Create a new account to place the bid +near create-account --useFaucet - +# Place a bid of 0.01 NEAR +near call bid '{}' --deposit 0.01 --useAccount +``` - ```bash - > near contract call-function as-read-only get_greeting json-args {} network-config testnet now - # "Hello, NEAR world!" - ``` - - +:::note -
+Note how in this case we are using the `` account (remember to rename it!) to call the `bid` function, while attaching a deposit of `0.01` NEAR as our bid -#### Set Greeting +::: -We can now change the greeting stored in the contract. The `set_greeting` method writes on the contract's [storage](./anatomy/storage.md), and thus requires a user to sign a transaction in order to be executed. +
- - +#### Get Highest Bid - ```bash - > near call set_greeting '{"greeting": "Hola"}' --accountId - # {"success": true} - ``` - +The `get_highest_bid` function only reads from the contract state, so it does not require a transaction or signature: - +```bash +near view get_highest_bid '{}' +``` - ```bash - > near contract call-function as-transaction set_greeting json-args '{"greeting": "Hola"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as network-config testnet sign-with-keychain send - # {"success": true} - ``` - - +
+ Expected Output + + ```json + { + "bidder": "", + "amount": "10000000000000000000000" + } + ``` +
:::tip -Notice that we are signing the transaction using ``, so in this case, we are asking the contract's account to call its own function +Feel free to create as many bidder accounts as you want and place more bids to see how the highest bid changes! ::: +
+ +#### Claim + +After the auction ends, anyone can call the `claim` method, which will transfer the `highest bid` amount to the auctioneer and end the auction. + +```bash +near call claim '{}' --useAccount +``` + +:::info Who won? + +After the auction ends, the highest bidder can be determined by simply calling the `get_highest_bid` method again + +::: --- ## Moving Forward -That's it for the quickstart tutorial. You have now seen a fully functional contract with a minimal user interface and testing. +
+
+ + Check the [auction frontend tutorial](../tutorials/auction/2.1-frontend.md) to learn how to build a simple web app that interacts with the auction contract + +
+
+ + Follow the [auction NFT tutorial](../tutorials/auction/3.1-nft.md) to award the highest bidder a Non-Fungible Token (NFT) and allow users to bid using Fungible Tokens (FT) + +
+
+
+
+ + Check our [Anatomy of a Contract](./anatomy/anatomy.md) page to understand the different components that make up a NEAR smart contract + +
+
-To better understand the contract's structure, check our [contract's anatomy](./anatomy/anatomy.md) page. + -If you prefer to see more examples, check our [examples](/tutorials/examples/count-near) page. +
- +
-:::note Versioning for this article + Versioning for this article At the time of this writing, this example works with the following versions: -- node: `20.18.0` -- rustc: `1.81.0` -- near-cli-rs: `0.17.0` -- cargo-near: `0.13.2` +- node: `22.18.0` +- rustc: `1.86.0` +- near-cli-rs: `0.22.0` +- cargo-near: `0.16.1` - Python: `3.13` - near-sdk-py: `0.7.3` - uvx nearc: `0.9.2` - emscripten: `4.0.9` (required for Python contracts) -::: +
\ No newline at end of file diff --git a/website/static/assets/docs/smart-contracts/hello-near-ts.gif b/website/static/assets/docs/smart-contracts/hello-near-ts.gif index dbbd28613ad..182e75942e7 100644 Binary files a/website/static/assets/docs/smart-contracts/hello-near-ts.gif and b/website/static/assets/docs/smart-contracts/hello-near-ts.gif differ diff --git a/website/static/css/custom.scss b/website/static/css/custom.scss index 6a1fcae71d5..9b2faf408df 100644 --- a/website/static/css/custom.scss +++ b/website/static/css/custom.scss @@ -349,6 +349,19 @@ li>ul { background: none !important; } +// ============================================================================ +// TABS STYLES +// ============================================================================ +.tabs__item { + padding: 0.4rem 0.8rem; + font-size: 0.9rem; + border-width: 2px; +} + +.margin-top--md { + margin-top: .5rem !important; +} + // ============================================================================ // CARD COMPONENTS // ============================================================================ @@ -577,7 +590,7 @@ html:not(.blog-post-page) .avatar__photo { border-radius: 0%; } -video+p>em,img+p>em, .monaco+em { +video+p>em,img+p>em,img+em, .monaco+em { font-style: normal; display: inherit; text-align: center;