Skip to main content

Hello Contract

Welcome! NEAR accounts 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.

Prerequisites​

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

Working on Windows?

See our blog post getting started on NEAR using Windows for a step-by-step guide on how to set up WSL and your environment

# 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

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.

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, and use it from the near-cli by invoking near login.

Testnet tokens

Need some testnet tokens? Use the faucet to top-up your account.

Creating the Contract​

Create a smart contract by using one of the scaffolding tools and following their instructions:

  npx create-near-app@latest

img Creating a project using create-near-app

This will generate a project with the following structure:

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

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
tip

After finishing this tutorial, check our contract's anatomy page to learn more about the contract's structure

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.

npm run test
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.

In the background, these commands are calling the build tools for each language and using a Sandbox to test the contract.

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.

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 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.

# Replace <your-account-id.testnet> with a custom name
near create-account <your-account-id.testnet> --useFaucet
Example Result 
$> near create-account lovely-event.testnet --useFaucet
# New account "lovely-event.testnet" created successfully
tip

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.

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.

npm run build

Deploy the Contract​

Having our account created, we can now deploy the contract:

near deploy <created-account> ./build/hello_near.wasm

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 functions through the command line.

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.

> near view <created-account> get_greeting
# "Hello, NEAR world!"

Set Greeting​

We can now change the greeting stored in the contract. The set_greeting method writes on the contract's storage, and thus requires a user to sign a transaction in order to be executed.

> near call <created-account> set_greeting '{"greeting": "Hola"}' --accountId <created-account>
# {"success": true}
tip

Notice that we are signing the transaction using <created-account>, so in this case, we are asking the contract's account to call its own function

Moving Forward​

That's it for the quickstart tutorial. You have now seen a fully functional contract with a minimal user interface and testing.

To better understand the contract's structure, check our contract's anatomy page.

If you prefer to see more examples, check our examples page.

Looking for Support?

If you have any questions, connect with us on Dev Telegram or Discord. We also host Office Hours on Discord every Thursday at 11 AM UTC and 6 PM UTC. Join our voice channel to ask your questions and get live support.

Happy coding! 🚀

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
  • Python: 3.11
  • near-sdk-py: 0.4.1
  • uvx nearc: 0.1.0
  • emscripten: 4.0.3 (required for Python contracts)
Was this page helpful?
Need some help? Chat with us or check our Dev Resources!
Twitter
Telegram
Discord
Zulip