Skip to main content

Using our Basic Examples

We have created a selection of basic smart contracts to help you get started building Smart Contracts on NEAR.

img

These examples cover fundamental concepts such as state management, function calls, and token interactions. Each example is designed to be simple and easy to understand, making them perfect for beginners.

tip

Before tackling these examples, be sure to follow our Quickstart Guide

Examples​

Hello World

Hello World

A simple smart contract that stores a string message on its state

Counter

Counter

A friendly counter that stores a number with methods to increment, decrement, and reset it

Guest Book

Guest Book

Users can sign the guest book, optionally paying 0.01 Ⓝ to mark their messages as "premium

Donation

Donation

Forward NEAR tokens to a beneficiary while tracking all donations. Learn how contracts handle token transfers

Coin Flip

Coin Flip

Guess the outcome of a coin flip and earn points. Demonstrates how to handle randomness on the blockchain

Structure of the Examples​

All examples follow a consistent structure, making it easy to navigate between them. Each repository contains the same smart contract implemented in Rust, Javascript, and sometimes Python, along with a simple frontend to interact with the contract.

┌── contract-rs # contract's code in Rust
│    ├── src    # contract's code
│    ├── tests  # sandbox test
│    ├── Cargo.toml
│    └── rust-toolchain.toml
├── contract-ts # contract's code in Typescript
│    ├── src    # contract's code
│    ├── sandbox-test  # sandbox test
│    ├── package.json
│    └── tsconfig.json
├── contract-py # contract's code in Python (some examples)
│    ├── contract.py  # contract's code
│    ├── tests        # sandbox test
│    ├── pyproject.toml
│    └── uv.lock
├── frontend    # React + Next.JS frontend
│    ├── src    # frontend's implementation
│    ├── public 
│    ├── package.json
│    ├── next.config.js
│    └── jsconfig.json
└── README.md

Frontend​

Each example includes a Next.JS frontend that is very simple to start:

cd frontend
yarn
yarn dev

These frontends are useful to demonstrate how to connect a web application to NEAR, as well as how to interact with the smart contracts.

tip

Each frontend connects to a pre-deployed version of the contract. Check ./frontend/config.js to see which contract is being used, or change it to your own deployed contract

NEAR Connector Hooks​

All frontends use near-connect-hooks, which wrap the functionality of NEAR Connector to handle the connection between the web app and the NEAR blockchain.

The near-connect-hooks expose a NearProvider that is used to wrap the entire application, usually in pages/_app.js:

import { NearProvider } from "near-connect-hooks";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <NearProvider>
      <Navigation />
      <Component {...pageProps} />
    </NearProvider>
  );
}

We can then use the useNearWallet hook within any component to access all NEAR-related functionality, such as login/logout, view and call functions, and sign transactions:

import { useNearWallet } from 'near-connect-hooks';

export default function App() {
  // Login / Logout functionality
  const { loading, signIn, signOut, signedAccountId } = useNearWallet();

  // To interact with the contract
  const { viewFunction, callFunction, signAndSendTransactions } = useNearWallet();
}

Smart Contract​

All repositories include the same smart contract implemented in different languages, including Rust, Javascript, and sometimes Python.

The contracts are implemented following the latest versions of each SDK, and include sandbox tests showcasing how to properly test smart contracts in a realistic environment.

Testing​

Each contract includes sandbox tests that simulate real user interactions. For example, in the Guest Book example, the tests cover scenarios like having multiple accounts signing the guest book, including premium messages.

cd contract-ts
yarn
yarn test

Creating an Account​

All smart contracts can be built and deployed using the NEAR CLI. A good first step is to always create a new NEAR account to deploy your contract:

near create-account <accountId> --useFaucet
tip

Here we are using the --useFaucet flag to create a new account and pre-fund it with the testnet faucet

Building & Deploying​

Once you created an account to host the contract, you can build and deploy it:

cd contract-ts
npm run build
near deploy <accountId> ./build/<contract-name>.wasm

Interacting via CLI​

Once your contract is deployed, check the README.md of each repository to see the available methods you can call.

As a general guide, the NEAR CLI has two main ways to interact with smart contracts:

# Call a read-only (view) method
near view <contractId> <methodName>

# Call a method that changes state
near call <contractId> <methodName> <arguments> --useAccount <yourAccount>

# Call a method and attach NEAR tokens
near call <contractId> <methodName> <arguments> --useAccount <yourAccount> --deposit 1
tip

Check each repository's README for the specific methods available in that contract.

Moving Forward​

After exploring these basic examples, you can:

  • Modify the contracts - Try adding new functionality to deepen your understanding
  • Learn the fundamentals - Check out Contract Anatomy and Storage

Looking for Support?

If you have any questions, connect with us on Telegram or Discord .

Happy coding! 🚀