NEAR 102

An introductory workshop

for Ethereum developers

​

near.org

Available Recordings

​

- youtube.com/watch?v=K0Bkc0rsW8U�- crowdcast.io/e/hacktherainbow/13

- crowdcast.io/e/hacktherainbow/7�

​

Workshop Preparation

​

Please complete the following steps before the workshop starts:�

• [5 min] Install Node.js locally
• [2 min] Install NEAR CLI locally
• [3 min] Create a TestNet account on NEAR Protocol�

If you have time, feel free to complete the following steps as well:�

• Read about a few of the key concepts of the NEAR platform:
• Accounts
• Transactions
• Storage Staking�
• Deploy the Fungible Token sample application (Gitpod or locally)

Why NEAR?

NEAR is cheaper, faster and easier to use

Development�

• Contracts are written using AssemblyScript or Rust and compiled to Wasm
• 1 million JavaScript / TypeScript developers can learn AssemblyScript quickly and easily
• Rust toolchain and community support speeds development of complex contracts
• Unique account system makes reasoning about complex contract orchestration simple

​

Production�

• Optimizations built into the protocol
• Gas fees (not just cost of gas) are 10x - 100x lower than those of Ethereum
• Contract accounts earn part of tx fees, reducing total cost of ownership for developers
• Automatic account redistribution among shards maximizes throughput
• 1 second block time and 3 second finality

Several examples and starters

near.dev

​

• several full stack examples in Rust and AssemblyScript�
• many have well commented code to guide your exploration�
• best effort at canonical use of the platform frontend and contract implementations

github.com / near / create-near-app

​

npx create-near-app banana

​

• generate a NEAR-compatible frontend & contract in 1 command�
• frontend: React, plain JS, others?�
• contract: Rust, AssemblyScript�

��Ethereum ⇔ NEAR Cookbook

bit.ly / near-102-recipes

Get started in minutes

Same-same … but different

primitives

Same-same … but different

features

NEAR

​

Deployment typically follows these steps:�

1. Compile contract bytecode
2. Compose transaction using DeployContract with attached bytecode (and optionally CreateAccount, AddKey, Transfer as well)
3. Sign and send transaction to deploy contract
4. Receive transaction outcome�
5. … redeploy to same account with FullAccess private key or remove for trustless operation�

step 2 can be decomposed into multiple Txs

Same-same … but different

Ethereum

​

Deployment typically follows these steps:�

1. Compile contract bytecode
2. Compose transaction by attaching bytecode (and initial value for contract)
3. Sign and send transaction to a special address which creates new account and deploys contract
4. Receive new contract address (or calculate it yourself)

deployment

Same-same … but different

Ethereum Transactions

NEAR Transactions

origin (signer, pk)

destination (receiver)

uniqueness (nonce)

handled elsewhere

recency (block_hash)

origin (v,r,s)

destination (recipient)

uniqueness (nonce)

cost control (gas price & limit)

transactions

attached NEAR tokens

Mapping concepts

NEAR Transactions

attached Ether

transactions

Ethereum Transactions

Four categories of actions

• identity: CreateAccount, DeleteAccount
• security: AddKey (2 types), DeleteKey
• value: Transfer, Stake
• code: DeployContract, FunctionCall

Mapping concepts

NEAR Transactions

selector (function signature)

arguments (encoded)

transactions

Ethereum Transactions

Mapping concepts

NEAR supports 8 composable primitive Actions

​

• CreateAccount to make a new account (for a person, contract, refrigerator, etc)
• DeleteAccount to delete an account (and transfer balance to a beneficiary account)�
• AddKey to add a key to an account (either FullAccess or FunctionCall access)
• DeleteKey to delete an existing key from an account�
• Transfer to move tokens from one account to another
• Stake to express interest in becoming a validator at the next available opportunity�
• DeployContract to deploy a contract
• FunctionCall to invoke a method on a contract (including budget for compute and storage)

transactions

Mapping concepts

Ethereum

�Custom Language → Custom VM

Pros

• Designed for blockchain
• May allow for formal verification

�Cons

• Niche language

NEAR

�AssemblyScript / Rust → Wasm VM

Pros

• Existing tooling and community
• General purpose
• Turing complete

Cons

• Not originally designed for blockchain
• No formal verification

runtime

Rust

Pros

• Mature, battle-hardened compiler
• Thriving ecosystem
• Real world use cases
• near-sdk-rs makes life easy

Cons

• Steeper learning curve

AssemblyScript

Pros

• Easier for prototyping
• Trivial for JS and TS devs to learn
• Smaller binaries in Wasm
• Binaries are easier to read / debug

Cons

• Current compiler is not stable
• Immature ecosystem

NEAR contract languages

development

In some ways … different

asynchronous calls

B

A

C

D

In some ways … different

asynchronous calls

B

A

C

D

In some ways … same

no surprise here

External “promise” calls which are used to invoke methods on multiple contracts using the standard Promise interface

​

This example was taken from MDN (just assume the functions wrap near-api-js)

​

A

In some ways … same

no surprise here

External “batch” calls are used to chain a series of Actions together to be executed on some target account�

B

In some ways … different

asynchronous calls

Internal “batch” calls which are used to chain a series of Actions together to be executed on some target account (including being applied to the current contract)

C

In some ways … different

asynchronous calls

Internal “promise” calls which are used to invoke methods on other contracts (or recursively on the current contract)

D

​

Rainbow Bridge

near.org / blog / eth-near-rainbow-bridge

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

Rainbow Bridge: NEAR Ethereum

• Decide to send 10 RAIN
• Authorize TokenLocker as escrow for ERC20 token on Ethereum (approve)
• Approve TokenLocker transaction which locks the tokens on Ethereum (lockToken)
• Tokens are locked (emit Locked event)
• Wait 25 blocks for confirmation
• Attach small deposit to offset the cost of storing newly minted nRAIN on NEAR
• Receive nRAIN tokens on NEAR

1

2

3

4

1

2

3

4

Rainbow Bridge: NEAR Ethereum

github.com / near ? q=rainbow

github.com / near-examples / erc20-to-nep21

Rainbow Bridge: NEAR Ethereum

github.com / near / rainbow-bridge-cli

​

How do I

get started?

create-near-app

To start building on NEAR run the following* in your terminal:

npx create-near-app --help

​

​

​

​

​

* you must have Node.js installed to run npx

create-near-app

Choose a frontend and a backend

​

Frontend (UX)

• Vanilla JS
• React

​

Backend (contracts)

• AssemblyScript
• Rust

create-near-app

step #1

​

npx create-near-app banana

create-near-app

step #2

​

yarn dev�

( or use npm run dev )

step #3

​

create-near-app

Sign in to NEAR Wallet

​

​

( 1 ) create new account

( 2 ) authorize your app

step #4

​

create-near-app

Change the message

​

​

( 1 ) edit the greeting

( 2 ) click Save

( 3 ) observe a → b

a

b

b

step #5 … n�

• discover
• where do we setup a connection to NEAR?�hint: search the code for keyStore
• where do we login to the NEAR Wallet?�hint: search the code for requestSignIn
• which lines of code wire up the contract to our JS context?�hint: search the code for viewMethods or changeMethods�
• control
• try to reverse the greeting string before writing on chain�hint 1: search for storage.set … AssemblyScript supports common Array and String functions�hint 2: message.split('').reverse().join('')

create-near-app

​

What just

happened?

NEAR exposes two development interfaces

dApp UX development

• Use near-api-js to connect to NEAR, manage accounts, call contract methods and more�
• Use JSON-RPC API to communicate with NEAR from any context (other than JS / TS)�
• Manage devops with NEAR Shell

dApp Contract Development

• Use near-sdk-as to build contracts using AssemblyScript�
• Use near-sdk-rs to build contracts using Rust�
• Compose deployed contracts using cross-contract calls

NEAR exposes two development interfaces

dApp UX development

• Use near-api-js to connect to NEAR, manage accounts, call contract methods and more�
• Use JSON-RPC API to communicate with NEAR from any context (other than JS / TS)�
• Manage devops with NEAR Shell

dApp Contract Development

• Use near-sdk-as to build contracts using AssemblyScript�
• Use near-sdk-rs to build contracts using Rust�
• Compose deployed contracts using cross-contract calls

NEAR exposes two development interfaces

dApp UX development

• Use near-api-js to connect to NEAR, manage accounts, call contract methods and more�
• Use JSON-RPC API to communicate with NEAR from any context (other than JS / TS)�
• Manage devops with NEAR Shell

dApp Contract Development

• Use near-sdk-as to build contracts using AssemblyScript�
• Use near-sdk-rs to build contracts using Rust�
• Compose deployed contracts using cross-contract calls

NEAR exposes two development interfaces

dApp UX development

• Use near-api-js to connect to NEAR, manage accounts, call contract methods and more�
• Use JSON-RPC API to communicate with NEAR from any context (other than JS / TS)�
• Manage devops with NEAR Shell

dApp Contract Development

• Use near-sdk-as to build contracts using AssemblyScript�
• Use near-sdk-rs to build contracts using Rust�
• Compose deployed contracts using cross-contract calls

Structure of the Sample Application

Runtime Layer

state storage

virtual

machine

code

load

apply

result

read

write

Your dApp

send

receive

Blockchain Layer

​

RPC Interface

​

​

​

• P2P network

​

• Consensus

​

• Block Storage

near-api-js

contracts

near-sdk-as

near-sdk-rs

deploy

write

read`

Runtime Layer

state storage

virtual

machine

code

load

apply

result

Your dApp

send

receive

Blockchain Layer

​

RPC Interface

​

​

​

• P2P network

​

• Consensus

​

• Block Storage

near-api-js

contracts

near-sdk-as

near-sdk-rs

deploy

Structure of the Sample Application

Lifecycle of a transaction

Runtime Layer

state storage

virtual

machine

code

load

apply

result

read

write

Your dApp

send

receive

Blockchain Layer

​

RPC Interface

​

​

​

• P2P network

​

• Consensus

​

• Block Storage

near-api-js

contracts

near-sdk-as

near-sdk-rs

1

2

3

4

5

6

7

deploy

Account ≈ Contract + State

Runtime Layer

state storage

virtual

machine

code

load

read

write

Account ≈ Contract + State

Runtime Layer

virtual

machine

code

load

metadata

result

read

write

data

apply

state storage

Runtime Layer

result

apply

Account ≈ Contract + State

virtual

machine

code

load

read

write

state storage

Writing Contracts

Rust (contract data)

AssemblyScript (contract data)

AssemblyScript & Rust contract alignment

Rust (contract behavior)

AssemblyScript (contract behavior)

AssemblyScript & Rust contract alignment

“To enable WebAssembly to be read and edited by humans, there is a textual representation of the wasm binary format. This is an intermediate form designed to be exposed in text editors, browser developer tools, etc.”

​

-- Understanding WebAssembly text format

​

​

​

Although we will not spend time on this topic, this format has proven consistently readable (especially with AssemblyScript) if only to sanity check that exported contract functions are visible and near-sdk-as runtime components are being called in the right places.

The output is always a .wasm file

Walking through �the Guest Book

Guest Book

User Interface

• there are 2 main folders in the project:
• assembly contains the smart contract and tests
• src contains the application’s UX and tests

​

• there is another folder to be aware of:
• neardev contains contract account details
• this is for development only, your local credentials will be in ~/.near-credentials

​

Guest Book

Filesystem

Guest Book

Contract Data Model : assembly/model.ts

• PostedMessage is a serializable class with three attributes:
• premium to flag messages with attached NEAR tokens
• sender to track the signer of the guest book message
• text to hold the guest book message�
• messages is a collection of guest book messages stored as a PersistentVector of PostedMessage objects

​

​

note: @nearBindgen marks the class as serializable

Contract

Contract Behavior : assembly/main.ts

​

• MESSAGE_LIMIT is used to avoid unbounded calls (ie. potentially expensive) to retrieve guest book messages from storage

​

• two public functions are exposed on the contract:
• addMessage(text: string): void
• getMessages(): PostedMessage[]

​

Guest Book

Contract

Guest Book

Network Connection : src/config.js

​

• data and endpoints required to connect to the NEAR network�
• connection information is included for MainNet, TestNet and BetaNet as well as the default LocalNet configuration

Frontend

Guest Book

Frontend

Configuration : src/index.js

​

• configure connection to NEAR network

​

• configure contract interface by injecting wallet connection and wiring up both contract methods�
• contract is a proxy object for JSON RPC API calls with methods attached�
• contract methods are attached to the object as either view or change type and return a Promise

Guest Book

Authentication : src/App.js

​

• NEAR Wallet is used for authentication�
• near-api-js exposes two related methods
• wallet.requestSignIn()
• wallet.signOut()

�

​

​

​

​

​

​

note: useCallback() is a React Hook

Frontend

CRUD : src/App.js

​

• add a message and, once complete, get a list of all messages (up to MESSAGE_LIMIT)�
• contract.addMessage accepts parameters as a JSON object and returns nothing�
• two other parameters are optional
• gas (a “boatload”) to override client defaults
• attached value (in NEAR tokens)

Guest Book

Frontend

Monitoring the application ...

​

http post https://rpc.testnet.near.org \

jsonrpc=2.0 id=dontcare

method=query params:='{

"request_type": "view_state",

"finality": "final",

"account_id": "test",

"prefix_base64": "U1RBVEU="

}’

​

And, using the watch command and some JSON formatting with jq, automatically

refresh a convenient view while we use

the Guestbook example. Here’s how.

​

​

Also see here for our JSON RPC API docs

�https://docs.near.org/docs/interaction/rpc

Guest Book

Demo: Monitoring

Mapping

Concepts

• ​

Ethereum supports two types of accounts

​

1. Externally Owned Accounts (EOA)
1. identified by last 20 bytes of the keccak-256 hash of a public key
2. controlled by a private key of the same public-private key pair
3. can sign and send transactions to other EOAs or contract accounts�
2. Contract Accounts
• controlled by contract code, no keys involved
• can only send transactions in response to being triggered
• are of two subtypes
1. Simple
2. Multisig

From Ethereum to NEAR

accounts

• ​

From Ethereum to NEAR

NEAR supports one type of account

​

• human readable name (like having ENS baked into the protocol *)
• may represent a user, contract or both
• are controlled by an unlimited number of keys
• two types
• FullAccess: can do anything with the account, including send tokens and delete account
• FunctionCall: can only call contract functions which may be limited in scope and budget

​

​

* NEAR accounts follow a human friendly DNS naming pattern with similar scoping rules for ownership and control. For example user.testnet controls app1.user.testnet and app2.user.testnet.

​

​

accounts

• ​

Ethereum

​

• nonce
• balance
• storageRoot
• codeHash*

​

​

​

​

* codeHash may be either:

• hash of an empty string (EOAs)
• hash of the code of the contract

NEAR

​

• balance
• locked balance (for staking)
• code of the contract **
• storage (key-value store for contract data)
• access keys *** (FullAccess, FunctionCall)
• postponed ActionReceipts (ie. “todo”)
• received DataReceipts (ie. “done”)

​

** code_hash is similar to Ethereum

*** each access key tracks its own nonce��note that receipts are used to manage cross-contract calls

From Ethereum to NEAR

accounts

Exploring the

Platform

• managing NEAR primitives:
• key stores
• accounts
• contracts
• wallets
• connection providers (RPC)

• generating key pairs locally
• creating transactions locally
• signing transactions locally
• sending transactions to the network

near-api-js

Library designed to connect to the NEAR platform from any JavaScript execution context (server-side or client-side JS)

Client-side

​

Server-side

​

near-api-js

Server-side

​

​

​

​

​

�UnencryptedFileSystemKeyStore

Client-side

​

​

​

​

​

�BrowserLocalStorageKeyStore

near-api-js

near-api-js

Your dApp

Examples at near.dev

NEAR Explorer

NEAR Wallet

NEAR CLI

send

receive

RPC Interface

Blockchain Layer

near-api-js uses JSON RPC API

near-api-js

Your dApp

Examples at near.dev

NEAR Explorer

NEAR Wallet

NEAR CLI

send

receive

RPC Interface

Blockchain Layer

near-api-js uses JSON RPC API

share bit.ly / near-102

Thank you!

visit near.help

​

Touch base on Telegram

​

Discover us on Discord

​

Suggest topics on StackOverflow