Learn to build on NEAR with Figment Learn

NEAR 101

NEAR is designed to eliminate the transactional bottlenecks of Layer 1 blockchains. Innovations such as Doomslug and Nightshade enable developers to combine the benefits of a sharded architecture with the power and security of decentralized networks. In addition, NEAR has a reputation for being a developer-friendly platform and offering a simple and quick onboarding process.

Near

< 1 hour

1 hour

1.5 hours

Beginner

Intermediate

Advanced

AssemblyScript

JS/TS

Rust

High Throughput

React

NodeJS

Smart contracts

Javascript

Next.js

Tools & Infra

Time Commitment

Difficulty

Programming Language

Feature

Technology

We no longer host the Pathway pages on this website, the content has moved to the `learn-web3-dapp` repository at <https://github.com/figment-networks/learn-web3-dapp#-get-started>.

The workflow for Pathways is easy to follow:

- Using the `learn-web3-dapp` code repository, you will be running a local development server (`yarn dev`)
- Each Pathway is accessible from the main page displayed when the development server is running
- Once you begin a Pathway, your completion progress is saved in the local storage of your web browser
- Each Pathway has a similar goal: To guide you through using various code libraries to work with different parts of the web3 stack
- Many of the individual steps of a Pathway provide you with coding challenges, so that you can learn by doing
- You will need to complete the code as explained in the instructions before moving on to the next step
- All of the coding challenges have solutions which are blurred until you click on them, to prevent you from being stuck
- Once you have completed a Pathway, you should have a working knowledge of that protocol which will help you tackle larger projects

For less experienced developers or for anybody who wants to dive in without needing to set up a development environment, **[we recommend using Gitpod](https://gitpod.io/#https://github.com/figment-networks/learn-web3-dapp)** to work with the `learn-web3-dapp` project (this requires you to have a GitHub account to sign in). Gitpod can save you a considerable amount of time, as you don't have to install dependencies or set up any software - everything just works! Gitpod provides you with a fully functional Visual Studio Code editor running in your browser, so you can jump right in. This is what it looks like: 

![Gitpod UI](https://raw.githubusercontent.com/figment-networks/learn-tutorials/master/assets/gitpod-firstlook.png?raw=true)

If you are an experienced developer, or if you prefer to use a different code editor, [cloning the repo locally](https://github.com/figment-networks/learn-web3-dapp#-clone-locally) is still possible, however you might encounter various system configuration issues depending on how your local environment is set up. It will be more difficult to develop on a Windows system than on Linux or MacOS, and there are also some known issues with developing Solana programs on Windows. It is strongly recommended to use the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install#manual-installation-steps) (WSL) if you are running Windows 10. 

If you are cloning the repo locally, a minimum of **NodeJS version 14.17 is required**. Some of the Pathways will require use of the [Rust toolchain](https://rustup.rs/). If you are developing on Linux, you will want to make sure you have the [build-essential](https://itsfoss.com/build-essential-ubuntu/) package installed, as the `cc` linker is required for compiling Solana programs.

Deploy a smart contract

Learn how to use the updated NEP-171 token standard on NEAR

Write NEP-171 NFT contracts in Rust

Learn how to create and interact with NFTs on NEAR

Write an NFT contract & mint your NFT

In this tutorial, we are going to write and test a smart contract using Rust

How to write and deploy a smart contract in Rust

🎓 Pathway complete!

Create smart contracts for a simple NFT Marketplace

Create an NFT marketplace

OysterPack SMART STAKE Pool Contract - NEAR Staking Game Changer

It's Time to Put a STAKE Pool in the Ground!

Get the storage of a smart contract

Generate a keypair

OysterPack SMART STAKE Pool Contract API Guide - For Validators

OysterPack SMART STAKE Pool API Guide for Validators

Learn how to build a crowdfunding dApp on the NEAR blockchain with Rust and React

Build a Crowdfunding dApp on NEAR

Setup the project

[The original tutorial can be found in the official NEAR documentation here](https://docs.near.org/docs/tutorials/contracts/cross-contract-calls). 

# Introduction

At some point, you might want to call functions on existing contracts. This is called a _cross contract call_. There are plenty of reasons to do this:

* You want to leverage a code library that others have written and released
* You want your app to integrate with other contracts that have some transferable state $For instance, a game that has transferable inventory$
* You want to build a bot that interacts with existing contracts in some way

Cross contract calls are really similar to calling an external API in the web 2.0 context.

In this tutorial, we will build a very simple example to get you up and running with cross contract calls.

# Description

We're going to create two simple contracts:

* `Calculator` this contract will have the calculation that we want to write for anyone to call
* `Calculator Caller` this contract $no surprise$ will call the calculation available in the other contract

For this example, we'll only implement the `add` functionality, but already we've got a problem! The accounting department at Super Evil Mega Corp sent all these numbers as strings. To make things worse, we don't know how long these strings are going to be. Why this is a problem: the largest integer that JavaScript can deal with is [9007199254740991](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER). To help out everyone who wants to add long numbers together, we're going to deploy a contract that people can incorporate into their own calculators.

# Step 1 - Create a new Token Contract Project in Gitpod

In a new browser tab or window:

* Open a new Token Contract Project in [Gitpod](https://gitpod.io/#https://github.com/near-examples/token-contract-as)

When this opens in GitPod, the code will generate a unique NEAR account for this project and build then deploy the template files. You can take a look at what we're starting with by clicking "Open Browser" to see the token example running.

This sample project has a token smart contract and also some JavaScript tests that invoke smart contract functions. You can try running these tests right away to see the code interacting with the blockchain.

In Gitpod:

* click **Terminal** &gt;&gt; **New Terminal**

In the new tab that opens at the bottom of Gitpod

* type `yarn jest` in the command prompt

Once finished, the tests running in your terminal will appear like this:

![Default Token Contract Test ](https://docs.near.org/docs/assets/default-token-contract-test.png)

Note that `test-account-XXXXXXXXX_tTIMESTAMP-XXXXXXX` here is an automatically generated NEAR account for this particular project. Don't be distracted by these details, just compare the developer log output with the statements in the file `src/test.js`.

> We are not going to keep any of the code from this template. It's just there as a starting point.

# Step 2 - Write the Calculator contract

We're interested in writing only one function for this example. A function that takes in two strings `a` and `b` and returns the result of adding them together as a string.

In the file `assembly/main.ts` :

* Replace the **entire contents of the file** with the code below _$note: this code implements addition of two large numbers as we do on paper$_

```javascript
import { context, storage, logging } from "near-sdk-as";

export function addLongNumbers(a: string, b: string): string {
  // sends logs to the terminal of the contract placing call and the Near Explorer
  logging.log("-------------------------------------------------------")
  logging.log('Contract Called : ' + context.contractName)
  logging.log('Contract Signer : ' + context.predecessor)
  logging.log("- - - - - - - - - - - - - - - - - - - - - - - - - - - -")
  logging.log("Caculating : " + a + " + " + b)
  // Similar to long addition by hand, we start with the least significant digits first
  const aReversed = a.split("").reverse();
  const bReversed = b.split("").reverse();

  // We initialize our resultant variable to be one more than the largest number's length
  const maxLength = max(a.length, b.length);
  let resultArray = new Array<String | null>(maxLength + 1);
  let result = "";
  let carry = 0;

  // Loop through each digit adding the value to the other number, if it exists
  for (let i = 0; i < maxLength; ++i) {
    let aDigit = (i < a.length) ? U32.parseInt(aReversed[i]) : 0;
    let bDigit = (i < b.length) ? U32.parseInt(bReversed[i]) : 0;
    let digitSum = aDigit + bDigit + carry;

    // Keep track of the carry amount
    if (digitSum >= 10) {
      carry = 1;
      digitSum -= 10;
    } else {
      carry = 0;
    }

    resultArray[i] = digitSum.toString();
  }

  // If the final addition has a carry, add it to the extra slot we initialized for it
  if (carry > 0) {
    resultArray[maxLength] = carry.toString();
  }

  // Reverse again and combine the values for the final result
  let reversedResultArray = resultArray.reverse();

  // More terminal / Near Explorer logs
  logging.log(">>> RESULT : " + reversedResultArray.join(""))
  logging.log("-------------------------------------------------------")
  return reversedResultArray.join("");
}
```

Now that we've modified files in our assembly folder we will need to re-deploy the contract.

In your terminal windows:

* Select the first terminal tab on the left that has localhost server running
* Hold `CTRL + C` to stop the server and display the command prompt
* Type `yarn dev` to rebuild and redeploy your modified contract

That's it for our `Calculator` for now.

# Step 3 - Write some tests for the contract

It's a good habit to test code as soon as we've finished writing it, so that's exactly what we're going to do.

In the file `src/test.js` :

* Replace **everything in the file** with the code below

After that is complete:

* Click **File** &gt;&gt; **Save All** to save your changes

```javascript
describe("Calculator", function() {
  let near;
  let contract;
  let alice;
  let bob = "bob.near";
  let eve = "eve.near";
  jasmine.DEFAULT_TIMEOUT_INTERVAL = 10000;

  // Common setup below
  beforeAll(async function () {
    near = await nearAPI.connect(nearConfig);
    accountId = nearConfig.contractName;
    contract = await near.loadContract(accountId, {
      // View methods are read only. They don't modify the state, but usually return some value.
      viewMethods: [],
      // Change methods can modify the state. But you don't receive the returned value when called.
      changeMethods: ["addLongNumbers"],
      sender: nearConfig.contractName
    });
    window.near = near;
  });

  // Multiple tests can be described below. Search Jasmine JS for documentation.
  describe("simple", function() {
    beforeAll(async function() {
    // There can be some common setup for each test.
    });

    it("adds one digit", async function() {
      const params = {
        a: "1",
        b: "3"
      };
      const result = await contract.addLongNumbers(params);
      expect(result).toBe("4");
    });

    it("should work with first string longer", async function() {
      const params = {
        a: "10",
        b: "3"
      };
      const result = await contract.addLongNumbers(params);
      expect(result).toBe("13");
    });

    it("should work with second string longer", async function() {
      const params = {
        a: "4",
        b: "15"
      };
      const result = await contract.addLongNumbers(params);
      expect(result).toBe("19");
    });

    it("should work with carry", async function() {
      const params = {
        a: "19",
        b: "22"
      };
      const result = await contract.addLongNumbers(params);
      expect(result).toBe("41");
    });

    it("should work when result is one digit longer than largest input", async function() {
      const params = {
        a: "91",
        b: "22"
      };
      const result = await contract.addLongNumbers(params);
      expect(result).toBe("113");
    });

    it("should work with really large input", async function() {
      const params = {
        a: "29348756231984613809465238956138947136497182364018246710289467102946710289467198046",
        b: "1"
      };
      const result = await contract.addLongNumbers(params);
      expect(result).toBe("29348756231984613809465238956138947136497182364018246710289467102946710289467198047");
    });
  });
});
```

Now lets run your new tests!

* type `yarn jest` in the command prompt

Once finished, the completed test in your terminal will appear like this:

![Jest tests running for Calculator Contract](https://docs.near.org/docs/assets/jest-tests-for-calculator-contract.png)


> Just make a mental note that the logs, "Contract Called" and the "Contract Signer" are the same. This will be important later.


Normally, we would create a UI at this point, but since we're calling this from elsewhere, let's move on the second contract.

# Step 4 - Create a new contract for Calculator Caller

Keep the tab open that you've been working on, you're going to need the ID of the contract you just created later.

The rest of the ID is the prefix "dev-" to be something like `dev-159372XXXX-XXXXXXX`. In fact the ID of the contract is just the NEAR account created for the contract by Gitpod automatically.

You can read more about [accounts on the NEAR platform here](https://docs.near.org/docs/concepts/account).


So let's make another smart contract. Following the same steps as before in a _new_ tab or window...

* Open another new Token Contract Project in [Gitpod](https://gitpod.io/#https://github.com/near-examples/token-contract-as)
* You should see a **Create Fresh Workspace** box at the top of your window
* click **Create** in the upper right hand corner

![Create fresh workspace](https://docs.near.org/docs/assets/gitpod-create-fresh-workspace.png)

We're doing this because we need to create an entirely separate contract deployed at a different address to demonstrate the capabilities of cross contract calls.

# Step 5 - Write the Calculator Caller code

We want to implement code that actually passes the numbers over to the contract we're calling. Here we're going to do this by creating a single `callAddNumbers` function and add the piping which allows us to make this function work.

We're going to need a few things to make this happen:

* To send two pieces of data $the two numbers we want to add$ from one contract to another, we'll create a new _model_ for our contract to use. `AddArgs` will be a class that we use to encode the arguments we're sending.
* Cross contract calls are always asynchronous so, to capture the return value from the other contract, we'll take advantage of the native `ContractPromise` class from `near-sdk-as`.
* To `CalculatorAPI`, a class we'll create that will send the numbers we want to add to the other contract through an `add` method
* `callAddNumbers`, function which will call the `CalculatorAPI` method we create to add the numbers

Let's start by creating the model first.

Create a new file `assembly/model.ts`:

* Click on the `assembly` folder on the left hand side in your explorer
* Then click **File** &gt;&gt; **New File**
* Enter `model.ts` and then click **OK**
* **Copy/Paste** the code below into this new file
* Click **File** &gt;&gt; **Save**

```javascript
@nearBindgen
export class AddArgs {
  a: string;
  b: string;
}
```

This will allow us to encode arguments to send between contracts as a single value.

Next we'll create the API that we can use to call the contract we've previously deployed.

In the file `assembly/main.ts` replace the **entire contents of the file** with the following code:

```typescript
import { context, storage, logging, ContractPromise } from "near-sdk-as";
import { AddArgs } from "./model";
```

Notice that we're importing `AddArgs` from the model we just created using the syntax `"./model"` AND we're importing `ContractPromise` from `near-sdk-as`.

Here, we're creating a single method `add` that takes the strings we want to add and returns a `ContractPromise`.

We're also using the `AddArgs` model we created to package the strings we want to send to the other contract. When we call `args.encode()` it's a lot like something like `JSON.stringify(args)` to allow us to send this data.

_In order to create this `ContractPromise`, we need to know:_

* The ID of the contract that we created before. **You'll need to replace this with your own.**
* Whatever function we're trying to call on the `Calculator` contract.

> In the file `assembly/main.ts` append the following code to the file:

```typescript
const OTHER_CONTRACT = "dev-REPLACE_THIS_IDENTIFIER";

export class CalculatorApi {
  add(a: string, b: string): ContractPromise {
    let args: AddArgs = { a, b };
    let promise = ContractPromise.create(OTHER_CONTRACT, "addLongNumbers", args.encode(), 100000000000000);
    logging.log("OTHER_CONTRACT: " + "(" + OTHER_CONTRACT + ")")
    return promise;
  }
}
```

_$For more info on making cross-contract calls using `ContractPromise`, check out_ [_ContractPromise_](https://near.github.io/near-sdk-as/classes/_sdk_core_assembly_contract_.contractpromise.html) _and_ [_ContractPromiseResult_](https://near.github.io/near-sdk-as/classes/_sdk_core_assembly_contract_.contractpromiseresult.html)

As a reminder, using the previous contract \(the tab you kept open earlier$, find the ID of the contract. You will use this to replace `dev-REPLACE_THIS_IDENTIFIER`.

You can find your contract ID stored in `neardev/dev-account.env`. In addition, you will see your contract ID displayed in the first terminal window with the running server. Towards the bottom there will be a line that states: "Done deploying to dev-1594333XXXXXX-XXXXXXX".

Next, we're going to use the `CalculatorApi` we just created.

In the file `assembly/main.ts` append the following code to the file:

```typescript
export function calculate(a: string , b: string): void {
  let calculator = new CalculatorApi();
  let promise = calculator.add(a, b);
  promise.returnAsResult();
}
```

You may notice this function returns `void`, which is a bit confusing because the contract is returning a promise. This is because it's calling a function elsewhere and the compiler thinks it's void.

$In future releases this will be changed.$

Now save your changes and redeploy the contract

* Click **File** &gt;&gt; **Save**

Then navigate to your terminal windows

* Select the first terminal tab on the left that has localhost server running
* Hold `CTRL + C` to stop the server and display the command prompt
* Type `yarn dev` to rebuild and redeploy your modified contract

# Step 6 - More tests!

Let's make sure things are working as expected.

In the file `src/test.js`:

* Replace the **entire contents of the file** with the code below

```javascript
const getConfig = require('./config');
let nearConfig = getConfig("development");
require('dotenv').config({ path: '/workspace/token-contract-as/neardev/dev-account.env' })

describe("CalculatorAPI", function() {
  let near;
  let contract;
  jasmine.DEFAULT_TIMEOUT_INTERVAL = 10000;

  // Common setup below
  beforeAll(async function () {
    near = await nearAPI.connect({
    deps: {
     keyStore: new nearAPI.keyStores.UnencryptedFileSystemKeyStore('../../../home/gitpod/.near-credentials')
    },
    ...nearConfig
  })
    accountId = process.env.CONTRACT_NAME;
    contract = await near.loadContract(accountId, {
    // NOTE: This configuration only needed while NEAR is still in development
    // View methods are read only. They don't modify the state, but usually return some value.
    viewMethods: [],
    // Change methods can modify the state. But you don't receive the returned value when called.
    changeMethods: ["calculate", "addLongNumbers"],
    sender: process.env.CONTRACT_NAME
    });
  });

  // Multiple tests can be described below. Search Jasmine JS for documentation.
  describe("simple", function() {
    beforeAll(async function() {
    // There can be some common setup for each test.
    });

    it("add one digit", async function() {
      const params = {
        a: "1",
        b: "99"
      };

      const result = await contract.calculate(params);
      expect(result).toBe("100");
    });
  });
});
```

After that is complete:

* Click **File** &gt;&gt; **Save All** to save your changes

Now let's test it out!

In Gitpod:

* click **Terminal** &gt;&gt; **New Terminal**

In the new tab that opens at the bottom of Gitpod, type `yarn jest` in the command prompt.

You should see a successful test that looks something like this:

![Cross contract call Jest test](https://docs.near.org/docs/assets/cross-contract-call-jest-test.png)

Remember when we took a note that the 'Contract Called' and the 'Contract Signer' were the same in the test environment? Notice that they are different now! Can you figure out what this means?

# Conclusion

And we're done!

You can also view the details of your account & transactions by using the [Near Explorer](https://explorer.testnet.near.org/).

This is a simple example of a contract that calls another contract, but this opens up a lot of opportunities. Now, see if you can figure out how to build the frontend by checking out our [other tutorials](https://docs.near.org/docs/roles/developer/tutorials/introduction) and modifying `src/main.js` and `src/index.html`.

You're ready to cross as many contracts as you want! Happy coding! 🚀

If you had any difficulties following this tutorial or simply want to discuss NEAR tech with us you can [**join our community today**](https://figment.io/devchat)!


Learn how to write smart contracts that talk to each other

Near cross-contract calls

{% hint style="info" %}
Feel Free to skip this section and [start the challenges](https://learn.figment.io/tutorials/setup-the-near-project)
{% endhint %}

------------------------

# What is NEAR?

NEAR is a decentralized application platform that makes blockchain accessible to everyday people who are excited for the future of the Open Web. A web that is more private, more secure, and puts people in control of their money, data, and identity. NEAR’s purpose is to enable community-driven innovation to benefit people around the world.

What makes NEAR special?

1. NEAR is the inevitable evolution of existing platforms 
   1. Bitcoin made digital currency a reality, a global transfer of value programmed on a blockchain. Ethereum took it a step further and made it possible to create basic applications leveraging digital currency on blockchains, but has faced issues with scaling and prohibitive fees.  
   2. NEAR solves these challenges and finally makes building the Open Web possible by introducing a breakthrough sharding design that creates opportunities for innovation never possible in blockchain before. 
2. NEAR is made for the real world 
   1. NEAR is the fastest path to market for builders to create blockchain applications that are as easy to use as they are to build. It uses common development patterns and programming languages that are immediately familiar to web developers. 
   2. NEAR was built with pragmatism of a Silicon Valley tech startup by engineers who have shipped scalable solutions for the world’s leading technology companies. 
   3. NEAR is secure enough for high value assets like Digital Currencies or Identities and performant enough to scale for DeFi or Gaming applications without prohibitively expensive fees or network latency. 
3. NEAR is designed to be interoperable 
   1. NEAR is designed to work with existing blockchain platforms and is easy for existing applications to migrate to. NEAR uses the Ethereum Virtual Machine and Web Assembly so that builders can seamlessly swap from Ethereum to NEAR (and back) on the NEAR Rainbow Bridge to leverage the performance, security, and favorable economics of NEAR without having to rebuild their applications or smart contracts. 
   2. With NEAR, you don’t have to choose between NEAR and Ethereum or commit to only one blockchain. Interoperability and usability across platforms will be key to the mass adoption of blockchain.

NEAR is the first blockchain platform truly built for the real world. It is a builder's fastest path to market to create blockchain applications that are as easy to use as they are to build.

# Why build on NEAR?

**NEAR is easy to learn**. It uses familiar development patterns and languages for portability and ease of access for any web developers.

* “Writing smart contracts on Rust is awesome. It allows you to code error-free and fault-free. It’s a big reason why we chose NEAR. Other blockchains require you to learn less popular programming languages.” - _Carolin Wend, Co-Founder of Mintbase_

**NEAR is versatile**. It's secure enough for high-value assets like money or identity, and performant enough to scale DeFi or Gaming apps. NEAR helps developers avoid high fees and slow speeds to deliver a delightful user experience.

* “Augur gets $1B in volume and users burn $63M in gas fees. Flux gets $1B in volume and users burn only $10k in gas fees.” _Peter Mitchell, CEO of Flux_

**NEAR is by builders for builders**. NEAR is built by a pragmatic team of engineers that have shipped scalable solutions for many of the world’s leading tech companies. They’ve earned the backing of leading investors including Coinbase Ventures, Andressen Horowitz, Pantera Capital and Naval Ravikant.

* “NEAR approached us with a developer-first attitude hellbent on helping creators create seamless and memorable user experiences. We intuitively felt that NEAR could be the silver bullet that ZEST needed.” _Geoff Wellman, Founding Partner, CTO VHS_

**NEAR works with existing blockchain platforms.** Builders can seamlessly swap from Ethereum to NEAR (and back) on the NEAR Rainbow Bridge to leverage the performance, security, and favorable economics of NEAR without having to rebuild their applications. With NEAR, there is no need to choose between chains. Builders and users get the best of both worlds.

**NEAR makes applications easy to use**. In some cases, users don’t realize they’re using a blockchain application. NEAR Accounts combine human-readable names and a flexible contract-based permission structure that enables business models like recurring, free to play, or freemium that were never before possible using blockchain applications.

**NEAR is fast and future proof**. The unique sharding techniques implemented to enable the NEAR protocol to maintain consensus while splitting the network into multiple pieces. This means that throughput and speed will increase exponentially as the number of nodes on the network increases. There is no theoretical limit on the NEAR network’s capacity. As the Open Web grows, NEAR scales to meet it.

# What can you build on NEAR?

1. Open (decentralized) Finance: NEAR provides both a synchronous environment for atomic transactions, which benefits fast-moving financial applications like decentralized exchanges, and an asynchronous environment which allows every other application to hook into these critical financial rails. This will be possible with the upcoming EVM support.  
2. Open Web: because NEAR is basically the “builder’s blockchain”, it has been optimized to provide substantial flexibility and performance for developers to build great experiences for their end users. This means that consumer-facing blockchain-backed apps are finally possible and the use cases of the Open Web can finally be realized: 
   1. Prediction markets -- markets like Augur have been handicapped by the difficulty of building smooth user experiences on Ethereum.  Apps like [Flux](https://flux.market) on NEAR provide much more user-friendly ways to set up programmatically enforceable bets with fast, easy payments. 
   2. NFT marketplaces -- marketplaces like [Mintbase](https://mintbase.io), which transferred from Ethereum, allow creators of unique digital assets to easily implement marketplaces to buy and sell them. On NEAR, they have access to reasonable costs plus intuitive end-user experiences. 
   3. Gaming -- because NEAR allows for performant and usable apps, developers can create gaming experiences that hook into the blockchain without forcing end-users to suffer through wallets or tokens.

[Take a look at these examples from a recent hackathon](https://near.org/blog/winners-of-hack-the-rainbow)

# Network Specifications

## Transaction Fees

First, transaction fees on NEAR are a tiny fraction of the amount of fees paid on other blockchains. 1000 times lower transaction fees than Ethereum for users and developers earn 30% of transaction fees.

NEAR keeps transaction fees low by dynamically resharding to optimize for performance and avoid congestion on the network. However, the most important feature of the NEAR token isn’t related to fees or rewards, it comes back to the usability and developer experience that truly sets NEAR apart.

Complicated blockchain concepts like tokens, rewards, and fees can be almost entirely hidden from end-users of NEAR applications because smart contracts can be configured to pay fees on their behalf. This allows developers to build experiences which feel more like today’s web to their end-users, but still take advantage of the underlying innovations of blockchain.

## Transaction Speed & Finality

The expected block time is around 1s and the expected time to finality is around 2s. 1,000 TPS benchmarked on a single shard for token transfers (contract ops are slower).

## Languages supported

* **Contracts**: Rust and AssemblyScript
* **Command line**: NEAR CLI
* **API**: JavaScript and JSON RPC API

## EVM compatibility

NEAR is fully compatible with the EVM and interoperable with Ethereum. NEAR does not want Ethereum developers to choose between the two networks and commit to only one. Developers can have the same asset on both blockchains and even have apps that seamlessly communicate across the boundary.

This is made possible by the [**Rainbow Bridge**](https://github.com/near/rainbow-bridge), which connects the Ethereum and NEAR blockchains by leveraging the Ethereum miners and NEAR validators. More info can be found [**here**](https://github.com/near/near-evm).

## Role of the NEAR token

The NEAR token is how people who use applications on the network pay to submit transactions to the nodes who actually run the network. The token is thus a utility — if you hold it, you can use applications hosted on the network.


What is NEAR?

Complete guide to unit testing your NEAR Rust smart contracts

Test Now Or Forever Hold Your Peace

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-show-me-code.jpeg)

In the last tutorial, we learned about the new NEAR [Account Storage API $NEP-145$](5-account-storage.md). As promised, in this tutorial we'll see how to code that up on the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) contract. As a bonus, you will get a chance to earn some NEAR at the end for taking the [Account Storage API $NEP-145$](5-account-storage.md) for a test drive on the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) contract.

# Show me the Rust Interface

```rust
#[derive(Serialize, Default, PartialEq, Debug)]
#[serde(crate = "near_sdk::serde")]
pub struct AccountStorageBalance {
    pub total: YoctoNear,
    pub available: YoctoNear,
}

/// Account Storage Standard API - NEP-145
pub trait AccountStorage {

    fn storage_deposit(&mut self, account_id: Option<ValidAccountId>) -> AccountStorageBalance;

    fn storage_withdraw(&mut self, amount: Option<YoctoNear>) -> AccountStorageBalance;

    fn storage_minimum_balance(&self) -> YoctoNear;

    fn storage_balance_of(&self, account_id: ValidAccountId) -> AccountStorageBalance;
}
```

Overall, the Rust interface code is pretty straight forward. However, you may be asking, where is [YoctoNear](https://github.com/oysterpack/oysterpack-near-stake-token/blob/main/contract/src/interface/model/yocto_near.rs) coming from? It's one of my creations, currently residing within the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) project. Your follow up question may be, why not use [U128](https://docs.rs/near-sdk/2.0.1/near_sdk/json_types/struct.U128.html)? My answer is because I am a big fan of domain driven design. I prefer to model the domain and encode it into the type system. It keeps the code cleaner, easier to understand, safer, and smarter.

> My plan is to extract the reusable code from the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) into a shared library and publish it on [https://crates.io](https://crates.io) for the community to leverage. For example, it would be super useful to have reusable libraries for each of the NEAR standards. As I build more contracts, the last thing I want to do is copy and paste code from one project to another.
>
> If there are folks from the NEAR community that are interested, then feel free to reach out to me.

# Show me the Rust Implementation

We'll look at each function in turn and see how it fits into the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) picture.

## storage\_deposit

```rust
#[payable]
fn storage_deposit(&mut self, account_id: Option<ValidAccountId>) -> AccountStorageBalance {
    assert!(env::attached_deposit() > 0, ATTACHED_DEPOSIT_IS_REQUIRED);               // #1

    let account_id = account_id.map_or_else(                                          // #2
        || env::predecessor_account_id(),
        |account_id| account_id.as_ref().to_string(),
    );
    match self.lookup_registered_account(&account_id) {                               // #3
        None => self._register_account(&account_id),
        // deposit funds into account storage escrow
        Some(mut account) => {
            account
                .storage_escrow
                .credit(env::attached_deposit().into());
            self.save_registered_account(&account);
        }
    }
    // track total account storage escrow balance at contract level
    self.total_account_storage_escrow += env::attached_deposit().into();              // #4

    self._storage_balance_of(&account_id)                                             // #5
}
```

In the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) project, accounts have an explicit storage escrow balance. Any funds deposited via `storage_deposit()` will be put into that balance. Currently, there is no [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) use case that requires a storage deposit more than the minimum required balance, i.e., account storage usage is capped. Thus, [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token/blob/main/contract/src/interface/model/yocto_near.rs) accounts will only ever need to make the initial minimum deposit to register the account with the contract. One other note is that if/when NEAR storage prices decrease, [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) contract is designed to update the storage price, which will unlock NEAR from the account's storage balance and make it available for withdrawal.

Let's walk through the code:

1. First thing the code does is perform a quick check to make sure there is an attached deposit. As a best practice, the first thing your functions should do is check args and constraints. `ValidAccountId`, which is provided by the NEAR Rust SDK, has built in validation. The function call will fail fast if an invalid account ID is specified.
2. We determine which account ID is the storage deposit for. Recall that this function enables the predecessor account to deposit storage funds on behalf of the specified `account_id`. If `account_id`, is not specified, the storage deposit is for the predecessor account.
3. Next we check if the account is already registered. If there is no registered account, then the account is registered. I prefer to keep functions small, easy to follow, and focused. The account registration logic is put into its own separate private function:

   ```rust
   fn _register_account(&mut self, account_id: &str) {
    assert!(
        env::attached_deposit() >= self.account_storage_fee().value(),
        INSUFFICIENT_STORAGE_FEE,
    );
    let account = Account::new(env::attached_deposit().into());
    self.save_registered_account(&RegisteredAccount {
        account,
        id: Hash::from(account_id),
    });
   }
   ```

4. The total amount of NEAR that is escrowed for storage across all accounts is tracked on [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token). This is specific to the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) use case related to its "profit sharing" program to boost STAKE token yield - that's a future topic for discussion.
5. Finally, we return the account's storage balance. It uses a private function that is shared with `storage_balance_of`

   ```rust
   fn _storage_balance_of(&self, account_id: &str) -> AccountStorageBalance {
    match self.lookup_registered_account(account_id) {
        None => AccountStorageBalance::default(),
        Some(account) => self.account_storage_balance(&account),
    }
   }
   ```

6. Per the standard, if the account is not registered, then a zero balance is returned, which is the default implementation for `AccountStorageBalance`

## storage\_withdraw

```rust
#[payable]
fn storage_withdraw(&mut self, amount: Option<YoctoNear>) -> AccountStorageBalance {
    assert_yocto_near_attached();                                                           // #1
    if let Some(amount) = amount.as_ref() {                                                 
        assert!(
            amount.value() > 0,
            "withdraw amount must be greater than zero"
        );
    }
    let mut account = self.predecessor_registered_account();                                

    let account_storage_balance = self.account_storage_balance(&account);                   // #2
    let withdraw_amount = amount.unwrap_or(account_storage_balance.available.clone());
    assert!(
        withdraw_amount.value() <= account_storage_balance.available.value(),
        "ERR: account storage available balance is insufficient"
    );

    // update balances                                                                      // #3
    let withdraw_amount = withdraw_amount.into();
    account.storage_escrow.debit(withdraw_amount);
    self.save_registered_account(&account);
    self.total_account_storage_escrow -= withdraw_amount;

    // get updated account storage balance                                                  // #4
    let account_storage_balance = self.account_storage_balance(&account);
    // transfer the withdrawal amount + the attached yoctoNEAR
    Promise::new(env::predecessor_account_id()).transfer(withdraw_amount.value() + 1);      // #5
    account_storage_balance
}
```

1. As usual, we start with checks:
   * Check that exactly 1 yoctoNEAR is attached $per NEP-145$
   * If amount is specified, check that the amount is greater than zero
   * `self.predecessor_registered_account()` kills 2 birds with 1 stone - the function is designed to panic if the account is not registered
2. Check if the requested withdrawal amount is less than or equal to the account's storage available balance. If an amount is not specified, then the total available storage balance will be withdrawn.
3. Update the account storage balance, and persist the account change to storage. In the STAKE contract, accounts are stored using the [LookupMap](https://github.com/oysterpack/oysterpack-near-stake-token/blob/main/contract/src/lib.rs) provided by the NEAR Rust SDK. Any changes made to objects retrieved from the [LookupMap](https://github.com/oysterpack/oysterpack-near-stake-token/blob/main/contract/src/lib.rs) must be explicitly written back out to contract storage. For details on how that exactly works, look at the 

   `self.predecessor_registered_account()` for reading and
   `self.save_registered_account(&account)` for writing to contract storage.

4. Then we get the updated account storage balance to return at the end.
5. Before returning the updated account storage balance, the requested withdrawal amount is transferred back to the predecessor account.

# And the rest of the code

```rust
fn storage_minimum_balance(&self) -> YoctoNear {
  self.account_storage_fee()
}

fn storage_balance_of(&self, account_id: ValidAccountId) -> AccountStorageBalance {
  self._storage_balance_of(account_id.as_ref())
}
```

The above code is pretty simple. What you may find of useful is how the STAKE contract computes the account storage fee. When the contract is first deployed, it measures how much storage is allocated for a "mock" account that is temporarily created and then deleted during the contract initialization phase - see the [Contract::new](https://github.com/oysterpack/oysterpack-near-stake-token/blob/main/contract/src/lib.rs) init function for details.

# Show Me the Demo: Earn Some NEAR

As a bonus, you can earn some NEAR by taking the STAKE token contract for a test drive on testnet and running through the demo below using the [NEAR CLI](https://github.com/near/near-cli). I have deployed the STAKE contract to `stake-demo.oysterpack.testnet` on testnet for the demo. To earn NEAR rewards for exercising the demo, you will need to submit the NEAR requests through [DataHub](https://datahub.figment.io/) using your DataHub access key. If you have earned NEAR on previous NEAR tutorials, then you should already be set. Otherwise, follow the instructions in the following link on [how to obtain your DataHub access key](https://learn.figment.io/network-documentation/near/tutorials/intro-pathway-write-and-deploy-your-first-near-smart-contract/1.-connecting-to-a-near-node-using-datahub#configure-environment). We will use the NEAR CLI to submit the transactions. Plugin your DataHub API Key and NEAR account at the top, and then you should be all set to go.

```bash
export DATAHUB_APIKEY=<DATAHUB_APIKEY>
export NEAR_ACCOUNT=<YOUR-NEAR-ACCOUNT.testnet>

export CONTRACT=stake-demo.oysterpack.testnet
export NEAR_NODE_URL=https://near-testnet--rpc.datahub.figment.io/apikey/$DATAHUB_APIKEY
export NEAR_ENV=testnet

# check what is the account's minimum required storage balance required to register the account with the contract
near view $CONTRACT storage_minimum_balance --node_url $NEAR_NODE_URL

# check your storage balance
# if your account is not registered with the contract, then a zero balance is returned
near view $CONTRACT storage_balance_of --node_url $NEAR_NODE_URL --args "{\"account_id\":\"$NEAR_ACCOUNT\"}" 

# deposit funds into your storage balance
# if this is your initial deposit, then your account will be registered with the contract
near call $CONTRACT storage_deposit --node_url $NEAR_NODE_URL --accountId $NEAR_ACCOUNT --amount 1

# withdraw your storage available balance
# per the NEP-145, 1 yoctoNEAR must be attached to the function call
near call $CONTRACT storage_withdraw --node_url $NEAR_NODE_URL --accountId $NEAR_ACCOUNT --amount 0.000000000000000000000001

# check your storage balance again
# after the withdrawal, your available balance should be zero
near view $CONTRACT storage_balance_of --node_url $NEAR_NODE_URL --args "{\"account_id\":\"$NEAR_ACCOUNT\"}"
```

# Conclusion

The NEAR Rust ecosystem support for writing smart contracts is very young. For now, all you have is the [NEAR Rust SDK](https://crates.io/crates/near-sdk). There is currently no library support for the new standards that are being developed in the ecosystem yet. Until there is, you will need to implement standard contract interfaces yourself. It's pretty straight forward, but much more time consuming for new developers coming onboard to NEAR to write Rust smart contracts. Until then, you have my tutorials and the reference code implementations within the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) project to help you get going faster.

This is where I make my call for action to the community. I invite you to join the Figment and NEAR communities and embark on our common mission to defend and take back the Internet together.

# Next Steps

Here's my plan going forward. As new NEAR standards are released, I plan to document them and provide reference implementations as tutorials. The rest of the time will be spend focused on the core mission, which is to build the [STAKE Token](https://github.com/oysterpack/oysterpack-near-stake-token) with the community and bring it to market. In the next tutorial, I will share with you my vision for the [STAKE Token](https://github.com/oysterpack/oysterpack-near-stake-token) and how it can serve as a cornerstone to help bootstrap the NEAR DeFi ecosystem.

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-stake-cornerstone.png)


STAKE Account Storage NEP-145 Rust Implementation

Show me the Code: STAKE Account Storage NEP-145 Rust Implementation

Complete guide to NEAR's new fungible token standard

The New and Improved Fungible Token Standard (NEP-141) Has Arrived

We no longer host the Pathway pages on this website, the content has moved to the `learn-web3-dapp` repository at <https://github.com/figment-networks/learn-web3-dapp#-get-started>.

For less experienced developers or for anyone who wants to dive in without complicated setup, **[we recommend using Gitpod](https://gitpod.io/#https://github.com/figment-networks/learn-web3-dapp)** to work with the `learn-web3-dapp` project (this requires you to have a GitHub account to sign in). Gitpod can save you a considerable amount of time, as you don't have to install dependencies or set up a development environment - everything just works!

If you are an experienced developer, [cloning the repo locally](https://github.com/figment-networks/learn-web3-dapp#-clone-locally) is still possible, however you might encounter various system configuration issues depending on how your local environment is set up. A minimum of NodeJS version 14.17 is recommended, and you'll want to make sure you have the `build-essential` package installed. You'll also want to make sure your Rust toolchain is up to date and that you have the `wasm32-unknown-unknown` target triple set up and installed.


You can now access the NEAR 101 Pathway on our GitHub repo.

The NEAR Pathway has moved to learn-web3-dapp

Set the storage of a smart contract

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-stake-in-the-ground.jpg)

My vision for STAKE can be summed up in 3 words:

1. Money
2. Income
3. NeFi

If you haven't done so yet, I would recommend reading NEAR's paper on [Economics in a Sharded Blockchain](https://near.org/papers/economics-in-sharded-blockchain/). It opens up with:

> Incentives are a crucial part of any decentralized protocol. These incentives must balance out to provide value to all the participants of the protocol, and ensure the protocol’s future development.

I couldn't agree more. Based on the **"Show Me The Money"** meme that I weave through my tutorials, you know what I believe is the \#1 incentive. The bottom line reality is "money makes the world go round". How does this relate to [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token)? STAKE makes the financial incentives much more attractive for NEAR.

All you need is to provide the right financial incentives to attract enough people to come together at the same place and time and they will start to form complex patterns of connection with one another. This is how new markets are formed. In this regard, I will share with you my vision for the STAKE token and how it will be a game changer for NEAR.

# What is the core problem that STAKE is solving?

The financial incentive to stake NEAR is to earn staking rewards. The problem is that staked NEAR is locked within the staking pool contract. Technically speaking, the staking pool contract owns the NEAR while it is being staked. In order to get back possession of your staked NEAR, you must submit a request to the staking pool contract to unstake your NEAR. You will then need to wait 4 epoch periods, which translates to about 2 days, before the NEAR is available for withdrawal from the staking pool contract back to your account. However, the unstaking process is not exactly that simple because if you submit another unstaking request while an unstaking request has not yet cleared, then it resets the 4 epoch wait period for the total amount that is unstaked. This makes it more complicated to manage access to your staked NEAR.

## The STAKE Solution

The [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) Token provides a solution by issuing fungible tokens for your staked NEAR, which I covered in my prior [You Can Have Your Stake and Trade It Too](https://learn.figment.io/tutorials/3-stake-fungible-token).

However, [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) offers much more than simply providing tradeable fungible tokens for your staked NEAR. It captures more value by combining staking rewards and contract rewards, transforming [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) into **Internet Money with Super Powers**. Contract rewards are a percentage of the transaction fees that are provided back to the contracts that were run during that transaction. The percentage of fees which are allocated to this reward is set to a minimum value of initially 30%. The super powers are provided by the contract rewards coupled with the power of compounding that boost the overall yield for [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) tokens:

![STAKE Token is Internet Money with Super Powers](../https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-near-stake-token-overview-1-.png)

* STAKE token contract contributes contract rewards to the staking pool
* External contracts contribute earnings to the staking pool
* The contract owner chooses what percentage of the contract earnings is shared with the staking pool

This effectively distributes the **income** earned by the STAKE contract and external contracts to all STAKE holders.

## If you stake then there is no reason not to use STAKE

STAKE provides the following benefits over the current staking pool:

1. STAKE enables the staked NEAR value to be transferred. STAKE enables staked NEAR to be used as **MONEY** _backed by the value of the network_.
2. STAKE provides more yield than the staking pool contract leveraging the contract rewards super powers. The more the STAKE contract is used, the higher the yield. The more NEAR that is deposited by external contracts, the higher the yield. This transforms STAKE into an **INCOME** stream.
3. STAKE contract also provides liquidity to unstaking through staking. Basically, the way this works is simple. If you submitted a request to unstake, then normally you would need to wait 2 days. However, if users are depositing NEAR into the STAKE contract to stake, then those funds are used to add liquidity that the unstakers can withdraw against. For example, Bob unstakes STAKE that is worth 1 NEAR. A few seconds later, Alice deposits 1 NEAR to stake. The 1 NEAR that Alice deposited is added to the liquidity pool. Bob's 1 NEAR that was unstaked is simply restaked back into the staking pool. Bob can now immediately withdraw the 1 NEAR from the liquidity pool with out having to wait 2 days. 

# Show me the MONEY!

Let me show you how this is a game changer for NEAR and how it has the potential to help NEAR take off ...

## Competition is the mother of innovation - Prepare for STAKE Wars!

STAKE makes the staking game more interesting. Today, there is a single staking pool contract used by all validators that enable users to delegate their NEAR to stake with the validator. Validators simply "compete" for delegators using the validator's brand and fees sharged. That's pretty boring. STAKE transforms vanilla staking into a more competitive landscape for validators by throwing in contract rewards into the equation. Today, the delegators look at staking pools from the perspective of fees charged. STAKE will change that perspective. Delegators will look at STAKE as an income investment and ask questions such as:

1. What is the overall yield?
2. What percentage of the contract earnings are shared with the staking pool?
3. How much is the STAKE contract earning?
4. What contracts are linked to the STAKE contract and what are the business models?
5. What is the earnings trend?

This expands the economy around staking and brings in more players. This provides more financial incentives to build on NEAR. This also creates more incentive for delegators to diversify their staking investments. Keep in mind also that anyone can deploy a STAKE contract, which expands the playing field. Today, in order to use the staking pool contract, you must run and manage a validator node. Prepare for STAKE wars!

## STAKE brings NeFi to life

By unlocking staked NEAR, STAKE suddenly brings to market the entire value of the NEAR network to the DeFi market. Let that sink in. This would bring **NeFi** $"NEAR" + "DeFi"$ to life. I believe this will attract massive capital investment into NeFi.

## The Case for STAKE: Massive Opportunity is Knocking on the Door

STAKE is a game changer for NEAR that can help it take root and take off.

* STAKE transforms staked NEAR into **Internet Money with Super Powers** backed by the value of the NEAR network
* STAKE can be used for **income** and **investment** through staking rewards, contract monetization, and NeFi
* STAKE unlocks staked NEAR and makes it available for **NeFi** protocols
* STAKE creates a much more competitive staking arena and makes possible whole new staking business models
* STAKE provides users with greater incentives to stake

In the coming years, exponential DeFi growth will create generational wealth opportunities. Let's walk through the STAKE effect:

1. STAKE will make DeFi much more attractive on NEAR - say hello to **NeFi**. 
2. NeFi will provide greater incentive for STAKE. 
3. STAKE will attract massive NeFi capital investment, which will propel demand for NEAR through STAKE.
4. Higher NEAR demand translates into higher NEAR value
5. This will create a natural feedback loop that results in a wealth snowball effect for NEAR. 

STAKE can serve as the cornerstone to build and grow the NeFi ecosystem. Here's my overall vision:

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-stake-vision.png)

* **NEAR** solves the "Scalability Trilemma" problem with a super scalable, fast, cheap network
* **STAKE** solves the problems caused by locked staked NEAR. It transforms staked NEAR into **Internet Money with Super Powers** and brings **NeFi** to life.
* **NeFi Wallet** vision is a mobile wallet strategy that puts NeFi in the users hands - "What's in Your NeFi Wallet?"
* **NeFi DEX** vision is a native DeFi DEX on NEAR

That builds the base for mass adoption explosion.

# It's a wrap folks

I shared with you my vision. The case for STAKE can be summed up in 3 words: **Money + Income + NeFi**. I am so excited about this that I am putting my money where my mouth is and forming a new startup named **OysterPack SMART**. OysterPack SMART mission will be focused on NEAR mass adoption. There are around 8 billion people in the world, and that is scratching the surface because we haven't even talked about [IoT](https://en.wikipedia.org/wiki/Internet_of_things) possibilities yet ... If Facebook can onboard ~2.8 billion people, then that gives me a minimum target.

This is where I make my call for action to the community. I invite you to join the Figment and NEAR communities and embark on our common mission to defend and take back the Internet together.

# Next Steps

The game plan remains the same. As new NEAR standards are released, I plan to document them and provide reference implementations as tutorials. The rest of the time will be focused on the core mission, which is to build the [STAKE Token](https://github.com/oysterpack/oysterpack-near-stake-token) with the community and bring it to market.

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-team-holding-hands.jpeg)



It's Time to Put a STAKE in the Ground!

# Introduction

In this tutorial we will be building a complete dApp for the NEAR Registry. NEAR Registry will allow you to track popular content just like Hacker News. Anyone can post an entry to the Registry. Upvoting the content requires you to connect using your NEAR wallet and attach NEAR to the entry. The Registry is sorted based on the NEAR attached to the entries. The same logic can be extended for any other type of registry.

# Requirements

- A NEAR testnet account: <https://wallet.testnet.near.org/>
- [Nodejs](https://nodejs.org/en/download/) v14 LTS or higher installed
- [yarn](https://yarnpkg.com/) installed

# Setup

```text
git clone https://github.com/viraja1/near-registry.git
cd near-registry
yarn install
yarn test
```

# Exploring The Code

1. The backend code is present in the `/assembly` folder and gets deployed to the NEAR blockchain when you run `yarn deploy`. This sort of code that runs on a blockchain is called a "smart contract". [Learn more about NEAR smart contracts][smart contract docs].
2. The backend test code is present in the `/assembly/__tests__/` folder. We can test the backend code using the command `yarn test`.
3. The frontend code is present in the `/src` folder. It uses near-api-js which is a JavaScript/TypeScript library for development of decentralized applications on the NEAR platform. It works in conjunction with NEAR RPC endpoints to help you connect your application to the NEAR blockchain. [Learn more about NEAR Frontend][NEAR Frontend]. 

NEAR smart contracts can be written in Rust or AssemblyScript. For NEAR Registry we will be using AssemblyScript, which is a dialect of TypeScript that compiles to WebAssembly (WASM).

Contracts are a named collection of exported functions that have access (via **near-sdk-as**) to their execution context (sender, receiver, block height, etc.) as well as storage services (key-value pair and convenience collections like Map, Vector and Dequeue), logging services and some utility functions.

To keep things organized, contracts can use one or more data objects which are commonly added to the model.ts file. All contracts and models must explicitly import the features of the NEAR SDK they intend to use.

**assembly/model.ts**

```typescript
import {context, u128, PersistentVector} from "near-sdk-as";

/**
 * Exporting a new class Entry so it can be used outside of this file.
 */
@nearBindgen
export class Entry {
  sender: string;

  constructor(public title: string, public description: string, public url: string, public id: i32, public votes: u128) {
    this.sender = context.sender;
  }
}

/**
 * collections.vector is a persistent collection. Any changes to it will
 * be automatically saved in the storage.
 * The parameter to the constructor needs to be unique across a single contract.
 * It will be used as a prefix to all keys required to store data in the storage.
 */
export const entries = new PersistentVector<Entry>("entries");
```

In the above `models.ts` file, we define a new custom type named Entry (primitive types like integers, strings and bool are always available by default). Since models are just AssemblyScript classes, they support custom constructors. Each entry has sender, title, description, url, id and votes. Each of these is associated with a specific type and is declared as public. In the constructor, we define the sender as **context.sender**. The context object provides context for contract execution including information about the transaction sender, blockchain height, and attached deposit available for use during contract execution.
                                                              
At the end, we define that entries is a PersistentVector (collection) of type Entry. The PersistentVector writes and reads from storage, abstracting away a lot of what you might want to add to the storage object. It wraps the Storage class with convenience methods so you must always use a unique storage prefix for different collections to avoid data collision. PersistentVector acts like an array. To create entries, we use the syntax `new PersistentVector<Entry>("entries")`. The vector supports the methods like push, pop and length.


**assembly/main.ts**

```typescript
import {Entry, entries} from './model';
import {context, u128} from "near-sdk-as";

// --- contract code goes below

/**
 * Adds a new entry under the name of the sender's account id.
 * NOTE: This is a change method, which means it will modify the state.
 * But right now we don't distinguish them with annotations yet.
 */
export function addEntry(title: string, description: string, url: string): void {
  // Creating a new entry and populating fields with our data
  const entry = new Entry(title, description, url, entries.length, u128.fromU64(0));
  // Adding the entry to end of the the persistent collection
  entries.push(entry);
}


/**
 * Up vote an entry using attachedDeposit
 * NOTE: This is a change method, which means it will modify the state.
 * But right now we don't distinguish them with annotations yet.
 */
export function upVoteEntry(index: i32): void {
  const entry = entries[i32(index)];
  entry.votes = u128.add(entry.votes, context.attachedDeposit);
  entries[i32(index)] = entry;
}

/**
 * Returns an array of entries.
 * NOTE: This is a view method, which means it does not modify the state.
 */
export function getEntries(): Entry[] {
  const result = new Array<Entry>(entries.length);
  for (let i = 0; i < entries.length; i++) {
    result[i] = entries[i];
  }
  return result;
}
```

Contract function calls are stateless. Any state that you want to save to the blockchain needs to be explicitly saved by interacting with the storage object (such as **entries**). In the `main.ts` file, the contract functions like `addEntry`, `upVoteEntry` and `getEntries` are defined. Function declarations follow standard AssemblyScript conventions, including the parameters they take, optional arguments and return values. 

There are two types of functions that can interact with the blockchain -- "view" functions and "change" functions. The difference, however, does not exist on the contract level. View functions like `getEntries` do not modify the state of the blockchain. Change functions like `addEntry` and `upVoteEntry` do modify the state.

In the `addEntry` function, we create a new Entry and add it to the entries PersistentVector using the push method. In the `upVoteEntry` function, we first fetch the entry from the entries PersistentVector using the index. Then we increment the entry votes using context.attachedDeposit. Then we update the entries PersistentVector using the index.

# Unit tests 

**assembly/\_\_tests\_\_/registry.spec.ts**

To make sure our smart contract works as expected, we have written the following unit tests. They test various cases like adding an entry, upvoting an entry, retrieving entries and attaching a deposit to a contract call. Use the command `yarn test` to run the test suite, it will then show the results on the console.

```typescript
import {addEntry, getEntries, upVoteEntry} from '../main';
import {Entry, entries} from '../model';
import {VMContext, Context, u128} from 'near-sdk-as';

function createEntry(title: string, description: string, url: string): Entry {
  return new Entry(title, description, url, 0, u128.fromU64(0));
}

const entry = createEntry('Near Protocol - Infrastructure for Innovation',
  'NEAR is an open source platform that accelerates the development of decentralized applications.',
  'https://near.org/');

describe('entries tests', () => {
  afterEach(() => {
    while (entries.length > 0) {
      entries.pop();
    }
  });

  it('adds a entry', () => {
    addEntry('Near Protocol - Infrastructure for Innovation',
      'NEAR is an open source platform that accelerates the development of decentralized applications.',
      'https://near.org/');
    expect(entries.length).toBe(
      1,
      'should only contain one entry'
    );
    expect(entries[0].url).toStrictEqual(
      'https://near.org/',
      'url matches'
    );
  });

  it('check up vote', () => {
    addEntry('Near Protocol - Infrastructure for Innovation',
      'NEAR is an open source platform that accelerates the development of decentralized applications.',
      'https://near.org/');
    expect(entries[0].votes.toString()).toStrictEqual(u128.fromU32(0).toString(),
      'entry should have 0 vote'
    );
    VMContext.setAttached_deposit(u128.from('10000000000000000000000'));
    upVoteEntry(i32(0));
    expect(entries[0].votes.toString()).toStrictEqual(u128.from('10000000000000000000000').toString(),
      'entry should have a vote'
    );
  });

  it('retrieves entries', () => {
    addEntry('Near Protocol - Infrastructure for Innovation',
      'NEAR is an open source platform that accelerates the development of decentralized applications.',
      'https://near.org/');
    const entriesList = getEntries();
    expect(entriesList.length).toBe(
      1,
      'should be one entry'
    );
    expect(entriesList).toIncludeEqual(
      entry,
      'entries should include:\n' + entry.toJSON()
    );
  });
});

describe('attached deposit tests', () => {
  beforeEach(() => {
    VMContext.setAttached_deposit(u128.fromString('0'));
    VMContext.setAccount_balance(u128.fromString('0'));
  });

  it('attaches a deposit to a contract call', () => {
    log('Initial account balance: ' + Context.accountBalance.toString());

    addEntry('Near Protocol - Infrastructure for Innovation',
      'NEAR is an open source platform that accelerates the development of decentralized applications.',
      'https://near.org/');
    VMContext.setAttached_deposit(u128.from('10'));

    log('Attached deposit: 10');
    log('Account balance after deposit: ' + Context.accountBalance.toString());

    expect(Context.accountBalance.toString()).toStrictEqual(
      '10',
      'balance should be 10'
    );
  });
});
```

# Deploying the smart contract

Every smart contract on NEAR has its [own associated account][NEAR accounts]. When running `yarn dev` to deploy, the smart contracts are deployed to the live NEAR testnet with a throwaway account. To make the deployment permanent, use the following steps:


## Install the NEAR CLI

This command will install the NEAR CLI globally:

```text
npm install --global near-cli
```

Then ensure that it is installed properly using the following command

```text
near --version
```
    
## Create an account for the contract

Visit [NEAR Wallet] and make a new account. You'll be deploying these smart contracts to this new account.

Now authorize via NEAR CLI for this new account, then follow the instructions to complete the process:

```text
near login
```

## Deploy with yarn

```text
yarn deploy
```

As you can see in `package.json`, this builds & deploys smart contracts to NEAR testnet.

```json
{
    "build": "yarn build:contract",
    "build:contract": "asb",
    "build:contract:debug": "asb --target debug",
    "deploy": "yarn build && near deploy",
    "dev": "yarn build:contract:debug && near dev-deploy",
    "test": "yarn build:contract:debug && asp"
}
```

Take note of the smart contract account id from the console and update it in `src/config.js`.

# Run the Frontend locally

To see the frontend as it will appear after deployment, we need to use the local development server. Run the following commands from the `near-registry` directory:

```text
cd src
yarn install
yarn start
```

Now you can visit http://localhost:1234 in your browser to test the NEAR Registry frontend and smart contracts deployed on the NEAR testnet.

# Deploy the Frontend using netlify

When you are happy with the looks and functionality of the dApp, you can deploy to a remote server. Run the following commands from the `near-registry` directory:

```text
cd src
yarn build
yarn global add netlify-cli
netlify login
netlify deploy --prod
```

You must follow the instructions given by the netlify CLI and specify `./dist` as the publish directory.


# Screenshots
![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/near_registry_1.png)

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/near_registry_2.png)

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/near_registry_3.png)

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/near_registry_4.png)

# App Link (NEAR Testnet)
https://near-registry.netlify.app/

# Conclusion
Congratulations! We have successfully deployed the NEAR Registry smart contract on the NEAR testnet. We have also tested the smart contracts by writing the test cases. We have then interacted with the smart contracts using the React frontend.

# References
* NEAR Guest Book - https://github.com/near-examples/guest-book/
* NEAR Smart Contract Docs - https://docs.nearprotocol.com/docs/roles/developer/contracts/assemblyscript
* NEAR Frontend Docs - https://docs.near.org/docs/api/naj-quick-reference

# About the Author
This tutorial was created by [Viraj Anchan](https://github.com/viraja1/).

  [NEAR]: https://nearprotocol.com/
  [yarn]: https://yarnpkg.com/
  [AssemblyScript]: https://docs.assemblyscript.org/
  [smart contract docs]: https://docs.nearprotocol.com/docs/roles/developer/contracts/assemblyscript
  [asp]: https://www.npmjs.com/package/@as-pect/cli
  [NEAR accounts]: https://docs.nearprotocol.com/docs/concepts/account
  [NEAR Wallet]: https://wallet.testnet.near.org/
  [near-cli]: https://github.com/nearprotocol/near-cli
  [CLI]: https://www.w3schools.com/whatis/whatis_cli.asp
  [create-near-app]: https://github.com/nearprotocol/create-near-app
  [NEAR Frontend]: https://docs.near.org/docs/api/naj-quick-reference


Learn how to build a complete registry dApp on NEAR and deploy it easily using Netlify

Build a Registry dApp on NEAR

[Storage staking](https://docs.near.org/docs/concepts/storage-staking) is an issue that needs to be addressed by any multi-user contract that allocates storage for the user on the blockchain. This issue first arose while designing the [Fungible Token Core Standard - NEP-141](https://learn.figment.io/tutorials/2-fungible-token#what-does-account-registration-have-to-do-with-fungible-tokens). Once NEP-141 was finalized, the NEAR community circled back to work on this problem. In this tutorial, I will summarize the lengthy [online discussion](https://github.com/near/NEPs/discussions/145) and present to you the fruits of our labor.

# Motivation: There Is No Free Storage

You can't get something for nothing. Long term contract state storage on the blockchain must be paid for. On the NEAR platform long term storage is paid for using a process called [storage staking](https://docs.near.org/docs/concepts/storage-staking). The contract is responsible to stake NEAR to pay for the contract's storage usage. The NEAR amount that is used for storage staking is effectively locked and cannot be transferred or used to pay for gas. Storage staking costs are the most expensive costs to consider for the contract on NEAR. If storage costs are not managed properly, then they can [break the bank](https://docs.near.org/docs/concepts/storage-staking#the-million-cheap-data-additions-attack) for the contract.


## About "Account Storage Standard $formerly Account Registration$"

If you happened to follow the [online discussion](https://github.com/near/NEPs/discussions/145), it started as "Account Registration". As we dove deeper, the discussion evolved into "Account Storage". The two are related, but with a different focus. The discussion was shifted towards account storage to focus on the core problem we were trying to solve with [storage staking](https://docs.near.org/docs/concepts/storage-staking) for multi-user contracts. Account registration is related but a separate concern, which is to be continued in future discussions ...


## Account Storage API

On NEAR, the contract is responsible to pay for its long term persistent storage. Thus, multi-user contracts should be designed to pass on storage costs to its user accounts. The account storage API provides the following:

1. Accounts can lookup the minimum required account storage balance for the initial deposit in order to be able to use the contract.
2. Accounts can deposit NEAR funds into the contract to pay for storage for either itself or on behalf of another account. The initial deposit for the account must be at least the minimum amount required by the contract.
3. Account storage balances can be looked up. The amount required to pay for the account's storage usage will be locked up in the contract. Any storage balance above storage staking costs is available for withdrawal.
4. Accounts can withdraw NEAR from the account's storage available balance.

## Out of Scope

* How to close the account and be able to withdraw all funds.
* How the contract should account for changes in price for storage on the NEAR blockchain over time.

# Quick API Overview

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-smart-account-storage-api.png)

**NOTES**

* API functions are specified using the lowest common denominator with the goal of being programming language neutral $as much as possible$
* String type is used as the de facto platform neutral type - but we will be leveraging Rust's type system when building the smart contract implementation
  * When interacting with the contract, all amounts and balances MUST be unsigned integers in yoctoNEAR.
* All account storage API functions are namespaced using a prefix naming convention $`account_`$
* `#[payable]` implies that the function supports NEAR to be attached to the function call
* API functions are tagged as either _**change methods**_ or _**view methods**_. This is from the [NEAR JSON RPC API](https://docs.near.org/docs/roles/developer/contracts/api) perspective.
  * Cross contract calls always require gas regardless of whether the function call being invoked is a _**view method**_ or _**change method**_

**Domain Model**

```javascript
class AccountStorageBalance {
  total: string;
  available: string;
}
```

* `total` represents the account's total storage balance in yoctoNEAR
* `available` represents portion of the account's total balance that is available for withdrawal

**Function**

```javascript
#[payable]
function storage_deposit(account_id: string|null): AccountStorageBalance;
```

_change method_

Used by accounts to deposit funds to pay for account storage staking fees. This function supports 2 deposit modes:

1. **self deposit** $`account_id` is not specified$: predecessor account is used as the account
2. **third party deposit** $`account_id` is valid NEAR account ID$:  the function caller is depositing NEAR funds for the specified `account_id`

If this is the initial deposit for the account, then the deposit must be enough to cover the minimum required balance. If the attached deposit is more than the required minimum balance, then the funds are credited to the account storage available balance.

**Example Use Cases**

1. In order for the account to hold tokens, the account must first have enough NEAR funds deposited into the token contract to pay for the account's storage staking fees. The account can deposit NEAR funds for itself into the token contract, or another contract might have deposited NEAR funds into the token contract on the account's behalf to pay for the account's storage staking fees.
2. Account's may use the blockchain to store data that grows over time. The account can use this API to deposit additional funds to pay for additional account storage usage growth.

**Arguments**

* `account_id` - optional NEAR account ID. If not specified, then predecessor account ID will be used.

**Returns**

The account's updated storage balance.

**Panics**

* If the attached deposit is less than the minimum required account storage fee on the initial deposit.
* If `account_id` is not a valid NEAR account ID

**Function**

```javascript
#[payable]
function storage_withdraw(amount: string|null): AccountStorageBalance;
```

_change method_

Used to withdraw NEAR from the predecessor account's storage available balance. If amount is not specified, then all of the account's storage available balance will be withdrawn.

The attached yoctoNEAR will be refunded with the withdrawal transfer.

The account is required to attach exactly 1 yoctoNEAR to the function call to prevent restricted function-call access-key calls.

**Arguments**

* `amount` - the amount to withdraw from the account's storage available balance expressed in yoctoNEAR

**Returns**

The account's updated storage balance.

**Panics**

* If the attached deposit does not equal 1 yoctoNEAR
* If the account is not registered with the contract
* If the specified withdrawal amount is greater than the account's available storage balance

**Function**

```javascript
function storage_minimum_balance(): string;
```

_view method_

Used to look up the minimum balance required for the initial deposit.

**Returns**

Amount in yoctoNEAR

**Function**

```javascript
function storage_balance_of(account_id: string): AccountStorageBalance;
```

_view method_

Used to lookup the account storage balance for the specified account. If the account is unknown to the contract then the total account storage balance returned will be zero.

**Panics**

* If `account_id` is not a valid NEAR account ID

# Conclusion

Overall, the Account Storage API itself is pretty straight forward. The key is to know its purpose and what problem it is trying to solve. Let's recap:

* We discussed why contract storage costs must be carefully managed and accounted for by the contract.
* We learned about how [storage staking](https://docs.near.org/docs/concepts/storage-staking) works on NEAR and how it impacts multi-user contracts.
* We reviewed the new standard Account Storage API $NEP-145$ in detail.

# Next Steps

Enough theoretical discussion for now ... in the next tutorial we will get back to coding where we will implement the Account Storage API for the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) token contract. Until next time, I leave you with these final words ...

The Internet is the greatest revolution in humanity's history. It provides the people of the world with an opportunity to connect and unite to build a global community that knows no borders. I invite you to join the Figment and NEAR communities and embark on our common mission to defend and take back the Internet together.

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-smart-coder.jpeg)


Complete guide to NEAR's new account storage standard

Account Storage Standard (NEP-145)

Create an account

# Introduction

I invite you to join me In this tutorial series and learn how to design, build, and monetize smart contracts on the NEAR platform. Learning is fun, applying what you learn to build is more fun, and making money from what you have built is rewarding. I believe in the philosophy of the "proof is in the pudding". In this tutorial series, we will be building a real-world smart contract called the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) token. The goals for this tutorial series are:

1. Showcase the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) token project on how to monetize NEAR smart contracts
2. Share with you my approach to architect, design, and code smart contracts in Rust
3. Take you step by step through designing, coding, and testing on the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) 

   token project.

4. Share with you design patterns and best practices I have learned while working on the STAKE token project
5. Make this a collaborative experience with the community

Regarding the last point, I welcome community participation in the [STAKE](https://github.com/oysterpack/oysterpack-near-stake-token) open source project.

# NEAR Technology + Economics = Game Changer

When I first discovered NEAR, what caught my attention was NEAR's economic model. It is well thought out and designed to provide economic incentive and value. Coupling that with NEAR's sharded scalability, speed, and low predictable operational cost provides a platform that can deliver real-world business and economic value. NEAR has the potential and all the key ingredients to becoming the first true economical decentralized cloud platform - to compete with centralized cloud platforms owned by a few big tech companies ...

# You can have your STAKE and trade it too

The STAKE token contract enables you to delegate your NEAR to stake, and in return, you are issued STAKE tokens. This enables you to trade your STAKE tokens while your NEAR is locked for staking and earning staking rewards. In addition, to earning staking rewards, the staked NEAR earns contract rewards from transaction fees. The STAKE token transforms your staked NEAR into a tradeable asset that is backed by revenue streams.

The STAKE token business model leverages the following from NEAR:

1. [Staking pool delegation](https://docs.near.org/docs/validator/delegation#staking-pool-delegation)
   * Anyone holding NEAR tokens can earn staking rewards by [delegating](https://docs.near.org/docs/validator/staking-overview#for-delegators) their tokens to staking pools
2. [Staking pool](https://github.com/near/core-contracts/tree/master/staking-pool) core contract
   * STAKE token contract integrates with [staking pool](https://github.com/near/core-contracts/tree/master/staking-pool) contracts for staking NEAR
3. Contract rewards
   * NEAR provides out of the box the ability to collect a portion of transaction fees and distributes them to the contracts that were run as part of the transaction
   * STAKE token contract distributes a share of its contract rewards through staking
   * STAKE token contract is also able to collect earnings from external contracts and distribute the funds through the staking mechanism

# STAKE Token Contract High-Level Overview

![](https://github.com/figment-networks/learn-tutorials/raw/master/assets/oysterpack-near-stake-token-overview-1-.png)

* Users must register with the contract in order to use it. When registering, users are required to pay an upfront account storage fee to cover storage staking costs. On NEAR long term storage is not free. The account storage fee is escrowed and will be refunded back to the user when the account unregisters.
* Contract is linked to a single staking pool contract, i.e., STAKE token contract is deployed per staking pool contract.
* Contract will implement the new fungible token standard defined by [NEP-141](https://github.com/near/NEPs/discussions/146)
* Contract has concept of contract ownership.
* Contract supports an operator role that is managed by the contract owner.
* Contract supports distributing contract rewards and earnings through the staking mechanism.
* Contract supports adding liquidity for unstaking and withdrawals

## What you will learn from the STAKE Token project from a technical perspective

The STAKE token project is fairly complex and showcases the following

1. Applying interface-driven design and domain modeling 
   * Leveraging Rust strong type system and compiler 
2. Cross-contract workflows
   * High level and low-level approaches
   * Making use of batch transactions
   * Gas considerations
3. State management
   * Storage staking considerations
4. Financial computation considerations
   * Protecting against overflows
5. New fungible token standard - [NEP-141](https://github.com/near/NEPs/discussions/146)
6. Unit testing
7. Simulation testing
8. Contract deployment
9. ... And the learning never ends

## The World Is Your Oyster

Decentralized network platforms, such as NEAR, provide tremendous economic opportunity. To put it into perspective, Amazon's market capitalization is currently valued at 1.56 trillion USD and 2021 revenue estimates are in the 411 - 488 billion USD range. That is just scratching the service. How much do you think the global economy is worth? Decentralized and scalable global cloud platforms such as NEAR provides an opportunity for all to participate in the global economy.

# Conclusion

NEAR is a super-fast smart contract platform with super low transaction fees that is user and developer-friendly for building real-world applications for the Open Web. I am excited about NEAR, and I hope I have inspired you to learn with me on this thrilling journey.

# Next Steps

If you are wondering what is NEP-41, then you are in luck. In the [next tutorial](https://learn.figment.io/tutorials/stake-fungible-token), we'll do a deep dive into the new and improved Fungible Token Core Standard NEP-141.

