Comment on page
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.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:
The
timestamp() method can be used to fetch the current timestamp. The value returns the UNIX timestamp in seconds. Example:let t = runtime::timestamp();
The
block_height method can be used to fetch the current height of the blockchain. Example:let t = runtime::block_height();
The
address() method can be used to fetch a contract's address. Example:let t = runtime::address();
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();
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();
The
current_blockhash() method can be used to fetch the hash of the current block. Example:let t = runtime::current_blockhash();
The
current_txhash() method can be used to fetch the hash of the current transaction. Example:let t = runtime::current_txhash();
This
sha256() method can be used to fetch the SHA256 encryption of the input parameter. Example:let h = runtime::sha256("test");
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 returnstrue. - 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 thefromis the returned value fromcaller(). Here, thecaller()method returns the contract hash of the contract that invokes the method.
assert!(runtime::check_witness(from));
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);
}
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");
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())
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())
This method is used to delete the on-chain data using the key. Example:
runtime::storage_delete("key".as_bytes())
Last modified 3yr ago