@neo-one/smart-contract

@neo-one/smart-contract contains the standard library for NEO•ONE smart contracts.

This reference uses dot syntax to indicate static properties and # to indicate instance properties. For example:

  • Foo.bar is the static property bar on the value Foo.
  • Foo#bar is the property bar on an instance of Foo.


Smart Contract


Address

Buffer that represents a NEO address. Stored as a script hash (Hash160) internally. See the Standard Library chapter of the main guide for more information.

Address.from(value: string): Address

Creates an Address from a literal string. Accepts either a NEO address or a script hash.

Example:

const address = Address.from('ALq7AWrhAueN6mJNqk6FHJjnsEoPRytLdW');

Example:

const address = Address.from('0xcef0c0fdcfe7838eff6ff104f9cdec2922297537');
Address.isCaller(address: Address): boolean

Verifies that the invocation was directly called AND approved by Address. Smart contracts should invoke this function before taking transferring items for Addresses, like transferring tokens, that require the permission of the Address.

Example:

if (!Address.isCaller(address)) {
  return false;
}
Address.isSender(address: Address): boolean

Verifies that the Transaction was signed by the address. In most cases, smart contracts should instead use Address.isCaller.

if (!Address.isSender(address)) {
  return false;
}

Hash256

Buffer that represents a NEO 256 bit hash. Examples of Hash256 include Block hashes and Transaction hashes. See the Standard Library chapter of the main guide for more information.

Hash256.from(value: string): Hash256

Creates a Hash256 from a literal string.

Example:

const hash = Hash256.from('0xd6572a459b95d9136b7a713c5485ca709f9efa4f08f1c25dd792672d2bd75bfb');
Hash256.NEO

Hash256 of the NEO Asset.

Hash256.GAS

Hash256 of the GAS Asset.

PublicKey

Buffer that represents a public key. See the Standard Library chapter of the main guide for more information.

PublicKey.from(value: string): PublicKey

Creates a PublicKey from a literal string.

Example:

const publicKey = PublicKey.from('02028a99826edc0c97d18e22b6932373d908d323aa7f92656a77ec26e8861699ef');

Fixed<Decimals extends number>

Integer which represents a number with the specified decimals. See the Standard Library chapter of the main guide for more information.

Integer

Integer that represents a number with 0 decimals. See the Standard Library chapter of the main guide for more information.

Fixed8

Integer that represents a number with 8 decimals. See the Standard Library chapter of the main guide for more information.

SerializableKey

Value that can be used as a key in MapStorage and a value for SetStorage. See the Properties and Storage chapter of the main guide for more information.

type SerializableKey = number | string | boolean | Buffer | [SerializableKey, SerializableKey] | [SerializableKey, SerializableKey, ...SerializableKey];

SerializableValue

Value that can be serialized for storage. See the Properties and Storage chapter of the main guide for more information.

type SerializableValue =
  | undefined
  | null
  | number
  | string
  | boolean
  | Buffer
  | ReadonlyArray<SerializableValue>
  | ReadonlyMap<SerializableValue, SerializableValue>
  | ReadonlySet<SerializableValue>
  | { [key: string]: SerializableValue };

ArrayStorage<T extends SerializableValue>

Persistent smart contract array storage. Only usable as a SmartContract property. See Properties and Storage in the main guide for more information.

Example:

class MySmartContract extends SmartContract {
  private readonly pendingAddresses = ArrayStorage.for<Address>();

  public addPendingAddress(address: Address): void {
    this.pendingAddresses.push(address);
  }
}
ArrayStorage.for<T extends SerializableValue>(): ArrayStorage<T>

Constructs a new ArrayStorage instance. Only usable as a SmartContract property.

ArrayStorage#length

Gets the length of the array. This is a number one higher than the highest element defined in an array.

ArrayStorage#forEach(callback: (value: T, idx: number) => void): void

Executes a provided function once per each value in storage.

ArrayStorage#push(...items: T[]): number

Appends new elements to storage, and returns the new length of the array.

ArrayStorage#pop(): T | undefined

Removes the last element from an array and returns it.

ArrayStorage#[n: number]: T

Access the value at index n.

MapStorage<K extends SerializableKey, V extends SerializableValue>

Persistent smart contract storage. Only usable as a SmartContract property. See the Properties and Storage chapter of the main guide for more information.

MapStorage.for<K extends SerializableKey, V extends SerializableValue>(): MapStorage<K, V>

Constructs a new MapStorage instance. Only usable as a SmartContract property.

MapStorage#forEach(callback: (value: V, key: K) => void): void

Executes a provided function once per each key/value pair in storage.

MapStorage#get(key: K): V | undefined

Returns a specified element from storage.

MapStorage#has(key: K): boolean

Returns a boolean indicating whether an element with the specified key exists or not.

MapStorage#delete(key: K): boolean

Removes the specified element from storage.

MapStorage#set(key: K, value: V): MapStorage<K, V>

Adds or updates an element with a specified key and value in storage.

MapStorage#at(prefix): MapStorage

Returns a MapStorage instance of the elements from storage with the specified prefix.

Example:

export class Contract extends SmartContract {
  private readonly storage = MapStorage.for<[Address, PublicKey], Fixed<8>>();

  public action(address: Address): void {
    const storageAtAddress: MapStorage<PublicKey, Fixed<8>> = this.storage.at(address);
    storageAtAddress.forEach((value: Fixed<8>, key: PublicKey) => {
      // ...
    });
  }
}

SetStorage<V extends SerializableKey>

Persistent smart contract set storage. Only usable as a SmartContract property. See the Properties and Storage chapter of the main guide for more information.

Example:

class ICO extends SmartContract {
  private readonly whitelistedAddresses = SetStorage.for<Address>();

  public isWhitelisted(address: Address): boolean {
    return this.whitelistedAddresses.has(address);
  }
}
SetStorage.for<V extends SerializableKey>(): SetStorage<V>

Constructs a new SetStorage instance. Only usable as a SmartContract property.

SetStorage#forEach(callback: (value: V) => void): void

Executes a provided function once per each value in storage.

SetStorage#has(value: V): boolean

Returns a boolean indicating whether an element with the specified value exists or not.

SetStorage#delete(value: V): boolean

Removes the specified element from storage.

SetStorage#add(value: V): SetStorage<V>

Adds an element with the specified value in storage.

SetStorage#at(prefix): SetStorage

Returns a SetStorage instance of the elements from storage with the specified prefix.

Example:

export class Contract extends SmartContract {
  private readonly storage = SetStorage.for<[Address, PublicKey]>();

  public action(address: Address): void {
    const storageAtAddress: SetStorage<PublicKey> = this.storage.at(address);
    storageAtAddress.forEach((value: PublicKey) => {
      // ...
    });
  }
}

Blockchain

Holds properties about the current state of the blockchain, the current Transaction and the current caller Contract. See the Standard Library chapter of the main guide for more information.

Blockchain.currentBlockTime

Time of the current Block.

Blockchain.currentHeight

Index of the latest Block persisted to the blockchain.

Blockchain.currentTransaction

InvocationTransaction this smart contract is executed in.

Blockchain.currentCallerContract

The Address of the smart contract that directly invoked the contract. Will be undefined if the smart contract method was not invoked by another smart contract, but instead was invoked by a user directly.

Deploy

Injects values at deployment time. Can only be used for default constructor parameters.

Deploy.senderAddress

Use the sender Address for the constructor parameter.

Example:

import { Address, Deploy, SmartContract } from '@neo-one/smart-contract';

class Token extends SmartContract {
  public constructor(public readonly owner: Address = Deploy.senderAddress) {
    super();
  }
}

createEventNotifier

Creates an event notifier for SmartContract notifications. Must be explicitly typed and contain string literals for the event name and argument names. See the Events and Logs chapter of the main guide for more information.

Example:

const notifyTransfer = createEventNotifier<Address, Address, Fixed<8>>('transfer', 'from', 'to', 'amount');

const from = Address.from('ALq7AWrhAueN6mJNqk6FHJjnsEoPRytLdW');
const to = Address.from('AVf4UGKevVrMR1j3UkPsuoYKSC4ocoAkKx');
notifyTransfer(from, to, 200);

declareEvent

Declares an event for SmartContract notifications. Must be explicitly typed and contain string literals for the event name and argument names. See the Events and Logs chapter of the main guide for more information.

Example:

declareEvent<Address, Address, Fixed<8>>('transfer', 'from', 'to', 'amount');

ForwardValue

An opaque type that represents a method parameter which is typically forwarded as an argument to another smart contract. See the Forward Values chapter of the advanced guide for more information.

ForwardedValue

Marks a parameter or return type of a public SmartContract method as expecting a forwarded value. See the Forward Values chapter of the advanced guide for more information.

SmartContract

Marks a class as a SmartContract.

SmartContract.for<T>(address: Address): T

Returns the singleton instance of the SmartContract defined by the interface T at address. T is checked for validity and SmartContract.for will report an error during compilation if the interface is invalid. See the Calling Smart Contracts chapter of the main guide for more information.

Example:

interface Token {
  readonly transfer: (from: Address, to: Address, amount: Fixed<8>) => boolean;
}

const address = Address.from('ALfnhLg7rUyL6Jr98bzzoxz5J7m64fbR4s');
const contract = SmartContract.for<Token>(address);
LinkedSmartContract.for<T>(): T

Returns the singleton instance of the statically linked contract T. T is checked for validity and LinkedSmartContract.for will report an error during compilation if the interface is invalid. See the Calling Smart Contracts chapter of the main guide for more information.

Example:

import { Token } from './Token';

const contract = LinkedSmartContract.for<Token>();
const from = Address.from('ALfnhLg7rUyL6Jr98bzzoxz5J7m64fbR4s');
const to = Address.from('AVf4UGKevVrMR1j3UkPsuoYKSC4ocoAkKx');
contract.transfer(from, to, 10);

Hashable

Types that can be hashed the various crypto functions.

crypto

Contains various cryptography functions.

crypto#sha1

Returns a Buffer of the SHA1 hash of the input

crypto#sha256

Returns a Buffer of the SHA256 hash of the input

crypto#hash160

Returns a Buffer of the SHA256 hash of the input

crypto#hash256

Returns a Buffer of the SHA256 hash of the SHA256 hash of the input.

Transfer

Represents a native Asset transfer.

Transfer#amount

The amount transferred.

Transfer#asset

The Hash256 of the Asset transferred.

Transfer#to

The desination Address of the transfer.

@send

Marks a SmartContract method that verifies Asset transfers from the SmartContract. Method must return a boolean indicating whether the SmartContract wishes to approve sending the transferred Assets. Method can take the Transfer as the final argument. See the Native Assets chapter of the advanced guide for more information.

Example:

export class Contract extends SmartContract {
  @send
  public withdraw(arg0: Address, arg1: Fixed<8>, transfer: Transfer): boolean {
    // Don't allow sending anything but NEO
    if (!transfer.asset.equals(Hash256.NEO)) {
      return false;
    }
    // Do some additional checks on the transfer.to and transfer.amount being sent and other arguments.
    return true;
  }
}

@sendUnsafe

Marks a SmartContract method that verifies Asset transfers from the SmartContract. Method must return a boolean indicating whether the SmartContract wishes to approve sending the transferred Assets. Note that unlike @send, @sendUnsafe does not use a two-phase send. Smart contract authors must implement their own logic for safely sending assets from the contract. May be used in combination with @receive. See the Native Assets chapter of the advanced guide for more information.

@receive

Marks a SmartContract method that verifies receiving Assets to the SmartContract. Method must return a boolean indicating whether the SmartContract wishes to receive the transferred Assets. May be used in combination with @sendUnsafe. See the Native Assets chapter of the advanced guide for more information.

@claim

Marks a SmartContract method that verifies GAS claims from the SmartContract. Method must return a boolean indicating whether the SmartContract wishes to allow GAS to be claimed. May optionally take the ClaimTransaction this SmartContract is executed in as the last argument. Accessing Blockchain.currentTransaction will result in an error. See the Native Assets chapter of the advanced guide for more information.

@constant

Marks a SmartContract method as not modifying storage. See the Methods chapter of the main guide for more information.


Blockchain Data Types


AttributeUsage

Attribute usage flag indicates the type of the data.

Attribute

Attributes are used to store additional data on Transactions. Most Attributes are used to store arbitrary data, whereas some, like AddressAttribute, have specific uses in the NEO protocol.

Attribute#usage

AttributeUsage this Attribute corresponds to.

Attribute#data

The data of the Attribute. Attribute data is specialized by their Attribute#usage into BufferAttribute, PublicKeyAttribute, AddressAttribute, Hash256Attribute.

BufferAttribute

Attribute whose Attribute#data is an arbitrary Buffer.

PublicKeyAttribute

Attribute whose Attribute#data is a PublicKey.

AddressAttribute

Attribute whose Attribute#data is an Address.

Hash256Attribute

Attribute whose Attribute#data is a Hash256.

Output

Outputs represent the destination Address and amount transferred of a given Asset. The sum of the unspent Outputs of an Address represent the total balance of the Address.

Output#address

Destination Address.

Output#asset

Hash256 of the Asset that was transferred.

Output#value

Amount transferred.

Input

Inputs are a reference to an Output of a Transaction that has been persisted to the blockchain. The sum of the values of the referenced Outputs is the total amount transferred in the Transaction.

Input#hash

Hash256 of the Transaction this input references.

Input#index

Output index within the Transaction this input references.

TransactionType

Constants that specify the type of a Transaction.

Transaction

Transactions are persisted to the blockchain and represent various functionality like transferring first class Assets or executing smart contracts.

Example:

const transactionHash = Hash256.from('0xd6572a459b95d9136b7a713c5485ca709f9efa4f08f1c25dd792672d2bd75bfb');
const transaction = Transaction.for(transactionHash);
const transactionOutputs = transaction.outputs;
Transaction.for(hash: Hash256): Transaction

Returns the Transaction for the specified hash.

TransactionBase

Base interface for all Transactions.

TransactionBase#hash

Hash256 of this Transaction.

TransactionBase#type

TransactionType of the Transaction.

TransactionBase#attributes

Attributes attached to the Transaction.

TransactionBase#outputs

Outputs of the Transaction.

TransactionBase#inputs

Inputs of the Transaction.

TransactionBase#references

Corresponding Outputs for the Inputs of the Transaction.

TransactionBase#unspentOutputs

Outputs which have not been spent.

MinerTransaction

extends

First Transaction in each Block which contains the Block rewards for the consensus node that produced the Block.

IssueTransaction

Issues new currency of a first-class Asset.

ClaimTransaction

Claims GAS for a set of spent Outputs.

EnrollmentTransaction deprecated

Enrolls a new validator for a given PublicKey.

RegisterTransaction deprecated

Registers a new first class Asset.

ContractTransaction

Transaction that transfers first class Assets.

StateTransaction

Contains the state of votes.

PublishTransaction deprecated

Registers a new Contract.

InvocationTransaction

Transaction which runs a script in the NEO VM.

InvocationTransaction#script

Code that was executed in NEO VM.

Account

Balance and vote information for an Address.

Example:

const address = Address.from('ALq7AWrhAueN6mJNqk6FHJjnsEoPRytLdW');
const account = Account.for(address);
const neoBalance = account.getBalance(Hash256.NEO);
Account.for(address: Address): Account

Returns the Account for the specified address.

Account#address

Address of this Account.

Account#getBalance(asset: Hash256): Fixed8

Retrieve the balance for a first class Asset based on its Hash256.

AssetType

Constants that specify the type of the Asset.

Asset

Attributes of a first class asset. Smart contract authors will typically only interact with the NEO and GAS Assets.

Example:

const asset = Asset.for(Hash256.NEO);
const neoAmount = asset.amount;
Asset.for(hash: Hash256): Asset

Returns the Asset for the specified hash.

Asset#hash

Hash256 of this Asset.

Asset#type

AssetType of the Asset

Asset#amount

Total possible supply of the Asset

Asset#available

Amount currently available of the Asset

Asset#precision

Precision (number of decimal places) of the Asset

Asset#owner

Owner of the Asset.

Asset#admin

Admin of the Asset.

Asset#issuer

Issuer of the Asset.

Contract

Attributes of a smart contract deployed to the blockchain.

Example:

const contractAddress = Address.from('0xcef0c0fdcfe7838eff6ff104f9cdec2922297537');
const contract = Contract.for(contractAddress);
const contractScript = contract.script;
Contract.for(address: Address): Contract | undefined

Returns the Contract for the specified address. Returns undefined if a Contract does not exist at address.

Contract#script

Contract code.

Contract#payable

Flag that indicates if the Contract supports receiving Assets.

Attributes of a Block persisted to the blockchain. Header includes all information except the list of Transactions.

Example:

const blockHash = Hash256.from('0xd6572a459b95d9136b7a713c5485ca709f9efa4f08f1c25dd792672d2bd75bfb');
const header = Header.for(blockHash);
Header.for(hashOrIndex: Hash256 | Integer): Header

Accepts either the Hash256 or the index of the Block. Returns the Header for the specified hashOrIndex.

Header#hash

Block hash.

Header#version

NEO blockchain version.

Header#previousHash

Previous Block hash.

Header#index

Block index.

Header#merkleRoot

Root of the Transaction hash Merkle Tree.

Header#time

Block time persisted.

Header#nextConsensus

Next consensus address.

Block

Attributes of a Block persisted to the blockchain. Extends Header.

Example:

const genesisBlock = Block.for(0);
Block.for(hashOrIndex: Hash256 | Integer): Block

Accepts either the Hash256 or the index of the Block. Returns the Block for the specified hashOrIndex.

Block#transactions

Transactions contained in the Block.

Previous Article
Configuration
Next Article
@neo-one/client