Skip to main content

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โ€‹

Working on Windows?

See Getting Started on NEAR Using Windows for a step-by-step guide on how to setup WSL and your environment.

Before starting, make sure you have the following installed:

  1. Node.js, to use our scaffolding tool.
  2. NEAR CLI, to deploy and interact with the contract.
Easy Install
  • NEAR-CLI: Install near-cli tools using

    npm i -g near-cli
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.


Creating the Contractโ€‹

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

img 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

The Contractโ€‹

You are now ready to create your first smart contract that stores and retrieves a message.

Your new smart contract stores a greeting: string attribute in their state, and exposes two methods to interact with it:

  • set_greeting(msg)
  • get_greeting()

Copy this source code to your src/contract.ts file. Here's a quick preview:

There are 3 important things to notice:

  1. The get_greeting method is a view method, meaning it only reads from the contract and can be called for free by anyone.
  2. By default, the contract is initialized with the greeting attribute set to "Hello".
  3. The set_greeting method is a change method, 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.

npm run build
npm run test

# Expected:
# returns the default greeting โœ…
# 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 16 to switch to node v16
  • rustup default 1.68 to switch to toolchain 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.

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.

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.

# 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
tip

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:

Using near-cli:

near deploy <created-account> build/release/hello.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 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.

Using near-cli:

> near view <created-account> get_greeting

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

Using near-cli:

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


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! ๐Ÿš€

Versioning for this article

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
Was this page helpful?