본문으로 건너뛰기

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 in 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 setup 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 setup WSL and your environment

# Install Node.js using nvm (more option in: https://nodejs.org/en/download)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install latest

# Install NEAR CLI to deploy and interact with the contract
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 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:

├── sandbox-test    # sanbox testing
│ └── main.ava.js
├── src # contract's code
│ └── contract.ts
├── README.md
├── package.json # package manager
└── tsconfig.json

The Contract

The Hello World smart contract stores a greeting on its state, and exposes two functions to interact with it:

  1. set_greeting: to change the greeting
  2. get_greeting: to fetch the greeting
<Github fname="index.js" language="js"
url="https://github.com/near-examples/hello-near-examples/blob/main/contract-ts/src/contract.ts"
start="4" end="18" />

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


Build and Test

Building and testing the contract is as simple as running the test command. The contract will be compiled and the tests will be executed.

```bash
npm run test
````

<details>
<summary> Failing tests? </summary>

Make sure that you are using `node v18`, `v20` or `v22`. You can always use: `nvm use 18` to switch to `node v20`

</details>

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.

```bash
# Replace <your-account-id.testnet> with a custom name
near create-account <your-account-id.testnet> --useFaucet
```

<details>
<summary> Example Result </summary>

```bash
$> near create-account lovely-event.testnet --useFaucet
# New account "lovely-event.testnet" created successfully
```

</details>

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 build and deploy the contract:

npm run build

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


Get Greeting

The get_greeting function only reads from the contract's state, and can thus be called for free.

```bash
> near view <created-account> get_greeting
# "Hello"
```

Set Greeting

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>
# Log: Saving greeting "Hola"

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.

Do not hesitate to reach out on Discord with any questions you have. 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?