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())