Skip to main content
Welcome! NEAR accounts can store small apps known as smart contracts. In this tutorial, we’ll guide you through creating and testing your first contract on NEAR. Create an auction contract that allows users to place bids, track the highest bidder, and claim tokens at the end of the auction.

Prerequisites

Before starting, make sure to set up your development environment.

Creating the contract

Create a smart contract with the cargo near scaffolding tool by following its instructions:
img
For this tutorial, we chose to name the project auction, but feel free to use any name you prefer.

How bidding works

The contract in src/lib.rs stores the highest bid and the auction’s end time. Its bid method accepts a deposit, checks that the auction is still open and the new bid is higher, then records the bid and refunds the previous bidder:
lib.rs
See the auction tutorial for an in-depth guide on the contract’s initialization, view methods, and claiming logic.

Test the contract locally

The project includes unit tests and sandbox tests. The sandbox tests build the contract and test it in a local Sandbox, that allows you to simulate a full NEAR environment locally without needing to create a testnet account or use real tokens.
The test builds the contract, starts a local blockchain, and prepares a signer for transactions:
tests/test_basics.rs
It creates funded accounts for two bidders, the auctioneer, and the contract. All accounts belong to this local sandbox:
tests/test_basics.rs
Next, it deploys and initializes the contract locally, setting the auction to end in one minute:
tests/test_basics.rs
Alice bids 1 NEAR, then Bob bids 2 NEAR. After each transaction, the test reads the highest bid and checks both the bidder and the amount:
tests/test_basics.rs
The sandbox can advance the blockchain so the auction ends without waiting a minute. The auctioneer can then claim the proceeds:
tests/test_basics.rs
Finally, the test checks that the auctioneer’s balance includes the winning 2 NEAR bid, minus gas fees, on top of the initial 10 NEAR:
tests/test_basics.rs
Run cargo test throughout development to check these interactions locally. Learn more about unit tests and sandbox tests.

Deploy and initialize on testnet

When you are ready to make the contract available to others, build it and deploy it to a testnet account. Testnet uses test tokens with no real value.

Build and create an account

From the auction directory, build the contract and create an account to host it. Replace your-auction.testnet with your desired account name:
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. Set CONTRACT_ID to that account’s name.
When working in WSL—or another headless Linux environment—you might encounter issues creating an account because the CLI tries to save keys to the system keychain.In such cases, you can try the following command to create the account:

Deploy and initialize the auction

The contract’s init function sets the auction end time and the auctioneer who receives the winning bid. Here, we set the end time to five minutes from now, in nanoseconds, and use the contract account as the auctioneer. You can set AUCTIONEER_ID to another existing testnet account if you prefer. Deploy and initialize in the same transaction so the auction is ready to use as soon as it is deployed:
The command uses the contract account’s key to sign the transaction. After the transaction succeeds, your auction is deployed and initialized on testnet.

Try placing a bid

To try the auction through the CLI, create a bidder account and place a bid before the five-minute auction ends. Replace your-bidder.testnet with your desired account name:
The result should show your bidder account and a bid of "10000000000000000000000" yoctoNEAR, equal to 0.01 NEAR.

That’s it!

You can now interact with the contract through a frontend or call its functions directly using the CLI.

Frequently Asked Questions

Once your contract is ready for release, follow the deployment guide to deploy to mainnet.
The cost of deploying a contract depends on its size: approximately 1 Ⓝ per 100 KB.
Yes. Redeploy with near deploy <account> <wasm-file>. The account stays the same, and the code is updated.
Run cargo test from your project directory. The sandbox tests handle local accounts and contract setup for you, so you can test the contract without a testnet account.
Use near-sdk-rs, NEAR’s only official smart-contract SDK. It provides the Rust APIs used throughout this guide.

Moving forward

Create a Frontend

Check the auction frontend tutorial to learn how to build a simple web app that interacts with the auction contract.

Extend the Contract

Follow the auction NFT tutorial to award the highest bidder a Non-Fungible Token (NFT) and allow users to bid using Fungible Tokens (FT).

Learn More about the SDK

Check our Anatomy of a Contract page to understand the different components that make up a NEAR smart contract.