Runtime API

WASM Contract Runtime API Specifications

The runtime module of the ontology-wasm-cdt-rust Ontology WASM contract development toolkit includes APIs that enable communication between the contract and Ontology blockchain. The API methods can be used to fetch on-chain data and store the contract data on the chain. The API methods have been listed below:

API Methods

Response Value

Description

timestamp

u64

Fetch current timestamp

block_height

u32

Fetch current block height

address

Address

Fetch address of the contract that is run

caller

Address

Fetch the address of the party invoking the contract, mainly used in certain cross contract scenarios

entry_address

Address

Fetch the entry address

current_blockhash

H256

Fetch current block's hash

current_txhash

H256

Fetch current transaction's hash

sha256(data: impl AsRef<[u8]>)

H256

Calculate the SHA256 encryption of the input parameter

check_witness(addr: &Address)

bool

Check whether the specified address's signature exists

input

Vec

Fetch the parameters passed when the contract was invoked

ret(data: &[u8])

!

Returns the result of contract execution

notify(data: &[u8])

!

Save the contract's notify content on the blockchain

panic(msg: &str)

!

Contract's panic message

storage_write(key: &[u8], val: &[u8])

Transmits data to the blockchain

storage_read(key: &[u8])

Option<Vec>

Fetch on-chain data

storage_delete(key: &[u8])

Deleting on-chain data

Next, we will describe the available API methods in detail. Developers are advised to first clone our smart contract template from Github and then add the contract logic in lib.rs file.

API Method Usage Specifications

Developers can use the following command to import the runtime module into the contract.

use ontio_std::runtime;

All the API methods can be called using the runtime module. The available methods are:

timestamp()

The timestamp() method can be used to fetch the current timestamp. The value returns the UNIX timestamp in seconds. Example:

let t = runtime::timestamp();

block_height()

The block_height method can be used to fetch the current height of the blockchain. Example:

let t = runtime::block_height();

address()

The address() method can be used to fetch a contract's address. Example:

let t = runtime::address();

caller()

The caller() method can be used to fetch the address of the party calling the contract. This finds application in cross-contract scenarios, for example if a contract A calls another contract B, contract B can use this method to find out the address of contract A. Example:

let t = runtime::caller();

entry_address()

The entry_address() can be used to fetch the entry address of a contract. A sample application could be where a contract A calls a contract C through contract B, and the contract C uses this method to fetch the address of contract A. Example:

let t = runtime::entry_address();

current_blockhash()

The current_blockhash() method can be used to fetch the hash of the current block. Example:

let t = runtime::current_blockhash();

current_txhash()

The current_txhash() method can be used to fetch the hash of the current transaction. Example:

let t = runtime::current_txhash();

sha256()

This sha256() method can be used to fetch the SHA256 encryption of the input parameter. Example:

let h = runtime::sha256("test");

check_witness()

The check_witness(from) verifies whether the signature of the passed address exists.

  • The method checks whether the party invoking the method contains the signature of from. If true (and signature verification is successful), the method returns true.

  • The method checks whether the invoking party is a contract. If it is, and the method is invoked from this contract, it returns true. It also checks if the from is the returned value from caller(). Here, the caller() method returns the contract hash of the contract that invokes the method.

assert!(runtime::check_witness(from));

notify()

The notify method can be used to pass contract event information to the network along with transmitting it to the blockchain. Example:

runtime::notify("notify".as_bytes())

An event function can be defined when sending a message from the contract using the #[event] annotation. The toolkit provided includes the necessary macros which can be imported using use ostd::macros::event;. Example:

use ostd::macros::event;
mod notify {
use super::*;
#[event]
pub fn transfer(from: &Address, to: &Address, amount: U128) {}
}
fn transfer(from: &Address, to: &Address, amount: U128) -> bool {
...
notify::transfer(from, to, amount);
}

panic()

The panic method stops a transaction when a critical error occurs and then rolls back the current transaction. This method can prove to be very useful in a cross-contract scenario.

For example, before contract A's method calls contract B's method, it transmits and stores certain data to the blockchain, but before contract B's method can be executed a critical error occurs. At this point, the action performed by contract A and the data stored on the chain need to be rolled back. This is carried out by using the panic function in contract B's method. Example:

runtime::panic("test");

storage_write()

This method is used to transmit and store data on the blockchain in the form of key-value pairs. The key and value are both of the bytearray data type. Example:

runtime::storage_write("key".as_bytes(), "value".as_bytes())

storage_read()

The method is used to fetch data from the blockchain using the key. The response is also of the bytearray data type . Example:

runtime::storage_read("key".as_bytes())

storage_delete()

This method is used to delete the on-chain data using the key. Example:

runtime::storage_delete("key".as_bytes())