Hello Contract
NEAR accounts can host programs known as smart contracts. Smart contracts can store data, and expose methods so other users and contracts interact with them.
In this quickstart tutorial, we will guide you in creating your first smart contract in the NEAR testnet that stores and retrieves a greeting.
Prerequisitesโ
- ๐ JavaScript
- ๐ฆ Rust
Before starting, make sure you have the following installed:
-
NEAR-CLI: Install
near-clitools usingnpm i -g near-cli
Before starting, make sure you have the following installed:
- NEAR CLI-RS, to deploy and interact with the contract.
- cargo-near, to easily create testnet accounts.
- Rust, to create Rust contracts.
- Node.js(Optional), to install the tools.
- NEAR-CLI-RS: Install both
near-cli-rsandcargo-neartools using
# Using node
npm i -g near-cli-rs cargo-near
# Using macOS, Linux, WSL
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/releases/latest/download/cargo-near-installer.sh | sh
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, and use it from the near-cli by invoking near login.
Creating the Contractโ
- ๐ JavaScript
- ๐ฆ Rust
Create a smart contract by running our create-near-app scaffolding tool and following the interactive menu.
- What do you want to build? โบ
A Near Smart Contract - Select a smart contract template for your project โบ
JS/TS Contract - Name your project โบ
hello-near
npx create-near-app@latest
create-near-app in action
The resulting folder structure will change slightly depending on the chosen language. Here is the general structure you can expect to see:
โโโ sandbox-ts # sanbox testing
โ โโโ src
โ โโโ โโโ main.ava.ts
โ โโโ ava.config.cjs
โ โโโ package.json
โโโ src
โ โโโ contract.ts # contract's code
โโโ package.json # package manager
โโโ README.md
โโโ tsconfig.json
Create a smart contract by running our near Rust CLI tool and following the interactive menu.
cargo near new <project_name>
create-near-app in action
The resulting folder structure will change slightly depending on the chosen language. Here is the general structure you can expect to see:
โโโ src
โ โโโ lib.rs # contract's code
โโโ test
โ โโโ test_basics.rs # testing code
โโโ Cargo.toml # package manager
โโโ README.md
โโโ rust-toolchain.toml
The Contractโ
Your new smart contract stores a greeting: string attribute in their state, and exposes two methods to interact with it (set_greeting, get_greeting).
- ๐ JavaScript
- ๐ฆ Rust
loading...
loading...
There are 3 important things to notice:
- The
get_greetingmethod is aviewmethod, meaning it only reads from the contract and can be called for free by anyone. - By default, the contract is initialized with the
greetingattribute set to"Hello". - The
set_greetingmethod is achangemethod, meaning it modifies the contract's state and requires a user to sign a transaction in order to be executed.
Build and Testโ
Building and testing the contract is as simple as running two commands.
- ๐ JavaScript
- ๐ฆ Rust
npm run build
npm run test
# Expected:
# returns the default greeting โ
# changes the greeting โ
cargo build
cargo test
# Expected:
# Passed โ
gets default greeting
# Passed โ
changes the greeting
Failing tests?
If the tests are failing, make sure that you are using node v16 and the toolchain v1.69 in rust. You can always use
nvm use 16to switch tonode v16rustup default 1.68to switch totoolchain v1.69
In the background, these commands are calling the build tools for each language and invoking the Sandbox tests from the sandbox-ts/rs directory.
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.
Create a Testnet Accountโ
Now that we know the contract is passing the tests, let's create a testnet account in which to deploy the contract.
While there are different ways to create accounts in NEAR, in this quickstart we will use the cargo-near tool to create a new random named account.
- ๐ JavaScript
- ๐ฆ Rust
# Create a new testnet account
# Replace <created-account> with a custom name
near create-account <created-account> --useFaucet
Example Result
> near create-account lovely-event.testnet --useFaucet
# Console response
New account "lovely-event.testnet" created successfully. # Response
# Create a new testnet account with a random name
cargo-near near create-dev-account use-random-account-id autogenerate-new-keypair save-to-legacy-keychain network-config testnet create
# Create a new testnet account
# Replace <lovely-event.testnet> with a custom name
cargo-near near create-dev-account use-specific-account-id lovely-event.testnet autogenerate-new-keypair save-to-keychain network-config testnet create
Example Result
# If you want to create account with a random name
> cargo-near near create-dev-account use-random-account-id autogenerate-new-keypair save-to-legacy-keychain network-config testnet create
New account "lovely-event.testnet" created successfully. # Response
# If you want to create account with a custom name
> cargo-near near create-dev-account use-specific-account-id lovely-event.testnet autogenerate-new-keypair save-to-keychain network-config testnet create
New account "lovely-event.testnet" created successfully. # Response
Here we are creating a random account since we do not care about the account's name. Remember that you can create a named account through any wallet (i.e. MyNearWallet) and then use it from the near-cli by invoking near login.
Deploy the Contractโ
Having our account created, we can now deploy the contract into it:
- ๐ JavaScript
- ๐ฆ Rust
near deploy <created-account> build/release/hello.wasm
near contract deploy <created-account> use-file ./target/wasm32-unknown-unknown/release/contract_rs.wasm without-init-call network-config testnet sign-with-keychain send
Congrats! your contract now lives in the NEAR testnet network.
Interacting with the Contractโ
To interact with your deployed smart contract, you can call its methods using the near-cli or near-cli-rs tools.
Get Greetingโ
The get_greeting method is a view method, meaning it only reads from the contract's state, and can thus be called for free.
- near-cli
- near-cli-rs
> near view <created-account> get_greeting
"Hello" # Response
> near contract call-function as-read-only <created-account> get_greeting json-args {} network-config testnet now
"Hello" # Response
Set Greetingโ
The set_greeting method is a change method, meaning it modifies the contract's state, and thus requires a user to sign a transaction in order to be executed.
- near-cli
- near-cli-rs
> near call <created-account> set_greeting '{"greeting": "Hola"}' --accountId <created-account>
Log: Saving greeting "Hola" # Response
In this case we are asking the account that stores the contract to call its own contract's method (--accountId <created-account>).
> near contract call-function as-transaction <created-account> set_greeting json-args '{"greeting": "Hola"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as <created-account> network-config testnet sign-with-keychain send
Log: Saving greeting "Hola" # Response
In this case, we are asking the account that stores the contract to call its own contract's method (sign-as <created-account>).
Moving Forwardโ
That's it for the quickstart tutorial. You have now seen a fully functional contract with a minimal user interface and testing.
Go ahead and check other examples or proceed straight to the Develop section to know how to write your own contract.
If you have any questions, do not hesitate to join us on Discord. We regularly host Office Hours, in which you can join our voice channel and ask questions.
Happy coding! ๐
At the time of this writing, this example works with the following versions:
- near-cli:
4.0.13 - node:
18.19.1 - rustc:
1.77.0 - near-cli-rs:
0.8.1 - cargo-near:
0.6.1
