This is essentially a clone of the starter--near-sdk-as repo from Learn-NEAR, with changes only to ./src/simple/assembly/index.ts. A call to the contract 'GetMagicWords', passing in an integer in 'wordcount' will return an array of random words with the specified size. Also takes parameter 'extra' which is a string that gets stored to the blockchain. Requires a deposit of at least 100000 yoctonear.
This is a good project to use as a starting point for your AssemblyScript project.
This repository includes a complete project structure for AssemblyScript contracts targeting the NEAR platform.
The example here is very basic. It's a simple contract demonstrating the following concepts:
- a single contract
- the difference between
viewvs.changemethods - basic contract storage
There are 2 AssemblyScript contracts in this project, each in their own folder:
- simple in the
src/simplefolder - singleton in the
src/singletonfolder
We say that an AssemblyScript contract is written in the "simple style" when the index.ts file (the contract entry point) includes a series of exported functions.
In this case, all exported functions become public contract methods.
// return the string 'hello world'
export function helloWorld(): string {}
// read the given key from account (contract) storage
export function read(key: string): string {}
// write the given value at the given key to account (contract) storage
export function write(key: string, value: string): string {}
// private helper method used by read() and write() above
private storageReport(): string {}We say that an AssemblyScript contract is written in the "singleton style" when the index.ts file (the contract entry point) has a single exported class (the name of the class doesn't matter) that is decorated with @nearBindgen.
In this case, all methods on the class become public contract methods unless marked private. Also, all instance variables are stored as a serialized instance of the class under a special storage key named STATE. AssemblyScript uses JSON for storage serialization (as opposed to Rust contracts which use a custom binary serialization format called borsh).
@nearBindgen
export class Contract {
// return the string 'hello world'
helloWorld(): string {}
// read the given key from account (contract) storage
read(key: string): string {}
// write the given value at the given key to account (contract) storage
@mutateState()
write(key: string, value: string): string {}
// private helper method used by read() and write() above
private storageReport(): string {}
}(see below for video recordings of each of the following steps)
- clone this repo to a local folder
- run
yarn - run
./scripts/1.dev-deploy.sh - run
./scripts/2.use-contract.sh - run
./scripts/2.use-contract.sh(yes, run it to see changes) - run
./scripts/3.cleanup.sh
1.dev-deploy.sh
This video shows the build and deployment of the contract.
2.use-contract.sh
This video shows contract methods being called. You should run the script twice to see the effect it has on contract state.
3.cleanup.sh
This video shows the cleanup script running. Make sure you add the BENEFICIARY environment variable. The script will remind you if you forget.
export BENEFICIARY=<your-account-here> # this account receives contract account balance
-
See
./scripts/README.mdfor documentation about the scripts -
Watch this video where Willem Wyndham walks us through refactoring a simple example of a NEAR smart contract written in AssemblyScript
There are 2 "styles" of implementing AssemblyScript NEAR contracts: - the contract interface can either be a collection of exported functions - or the contract interface can be the methods of a an exported class We call the second style "Singleton" because there is only one instance of the class which is serialized to the blockchain storage. Rust contracts written for NEAR do this by default with the contract struct. 0:00 noise (to cut) 0:10 Welcome 0:59 Create project starting with "npm init" 2:20 Customize the project for AssemblyScript development 9:25 Import the Counter example and get unit tests passing 18:30 Adapt the Counter example to a Singleton style contract 21:49 Refactoring unit tests to access the new methods 24:45 Review and summary
├── README.md # this file
├── as-pect.config.js # configuration for as-pect (AssemblyScript unit testing)
├── asconfig.json # configuration for AssemblyScript compiler (supports multiple contracts)
├── package.json # NodeJS project manifest
├── scripts
│ ├── 1.dev-deploy.sh # helper: build and deploy contracts
│ ├── 2.use-contract.sh # helper: call methods on ContractPromise
│ ├── 3.cleanup.sh # helper: delete build and deploy artifacts
│ └── README.md # documentation for helper scripts
├── src
│ ├── as_types.d.ts # AssemblyScript headers for type hints
│ ├── simple # Contract 1: "Simple example"
│ │ ├── __tests__
│ │ │ ├── as-pect.d.ts # as-pect unit testing headers for type hints
│ │ │ └── index.unit.spec.ts # unit tests for contract 1
│ │ ├── asconfig.json # configuration for AssemblyScript compiler (one per contract)
│ │ └── assembly
│ │ └── index.ts # contract code for contract 1
│ ├── singleton # Contract 2: "Singleton-style example"
│ │ ├── __tests__
│ │ │ ├── as-pect.d.ts # as-pect unit testing headers for type hints
│ │ │ └── index.unit.spec.ts # unit tests for contract 2
│ │ ├── asconfig.json # configuration for AssemblyScript compiler (one per contract)
│ │ └── assembly
│ │ └── index.ts # contract code for contract 2
│ ├── tsconfig.json # Typescript configuration
│ └── utils.ts # common contract utility functions
└── yarn.lock # project manifest version lockYou may clone this repo to get started OR create everything from scratch.
Please note that, in order to create the AssemblyScript and tests folder structure, you may use the command asp --init which will create the following folders and files:
./assembly/
./assembly/tests/
./assembly/tests/example.spec.ts
./assembly/tests/as-pect.d.ts