Trait pallet_contracts::api_doc::Current

pub trait Current {
    // Required methods
    fn account_reentrance_count(account_ptr: u32) -> Result<u32, TrapReason>;
    fn add_delegate_dependency(code_hash_ptr: u32) -> Result<(), TrapReason>;
    fn address(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn balance(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn block_number(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn call(
        flags: u32,
        callee_ptr: u32,
        ref_time_limit: u64,
        proof_size_limit: u64,
        deposit_ptr: u32,
        value_ptr: u32,
        input_data_ptr: u32,
        input_data_len: u32,
        output_ptr: u32,
        output_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn call_chain_extension(
        id: u32,
        input_ptr: u32,
        input_len: u32,
        output_ptr: u32,
        output_len_ptr: u32
    ) -> Result<u32, TrapReason>;
    fn call_runtime(
        call_ptr: u32,
        call_len: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn caller(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn caller_is_origin() -> Result<u32, TrapReason>;
    fn caller_is_root() -> Result<u32, TrapReason>;
    fn clear_storage(key_ptr: u32, key_len: u32) -> Result<u32, TrapReason>;
    fn code_hash(
        account_ptr: u32,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn contains_storage(key_ptr: u32, key_len: u32) -> Result<u32, TrapReason>;
    fn debug_message(
        str_ptr: u32,
        str_len: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn delegate_call(
        flags: u32,
        code_hash_ptr: u32,
        input_data_ptr: u32,
        input_data_len: u32,
        output_ptr: u32,
        output_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn deposit_event(
        topics_ptr: u32,
        topics_len: u32,
        data_ptr: u32,
        data_len: u32
    ) -> Result<(), TrapReason>;
    fn ecdsa_recover(
        signature_ptr: u32,
        message_hash_ptr: u32,
        output_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn ecdsa_to_eth_address(
        key_ptr: u32,
        out_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn gas_left(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn get_storage(
        key_ptr: u32,
        key_len: u32,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn hash_blake2_128(
        input_ptr: u32,
        input_len: u32,
        output_ptr: u32
    ) -> Result<(), TrapReason>;
    fn hash_blake2_256(
        input_ptr: u32,
        input_len: u32,
        output_ptr: u32
    ) -> Result<(), TrapReason>;
    fn hash_keccak_256(
        input_ptr: u32,
        input_len: u32,
        output_ptr: u32
    ) -> Result<(), TrapReason>;
    fn hash_sha2_256(
        input_ptr: u32,
        input_len: u32,
        output_ptr: u32
    ) -> Result<(), TrapReason>;
    fn input(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn instantiate(
        code_hash_ptr: u32,
        ref_time_limit: u64,
        proof_size_limit: u64,
        deposit_ptr: u32,
        value_ptr: u32,
        input_data_ptr: u32,
        input_data_len: u32,
        address_ptr: u32,
        address_len_ptr: u32,
        output_ptr: u32,
        output_len_ptr: u32,
        salt_ptr: u32,
        salt_len: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn instantiation_nonce() -> Result<u64, TrapReason>;
    fn is_contract(account_ptr: u32) -> Result<u32, TrapReason>;
    fn minimum_balance(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn now(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn own_code_hash(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn random(
        subject_ptr: u32,
        subject_len: u32,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<(), TrapReason>;
    fn reentrance_count() -> Result<u32, TrapReason>;
    fn remove_delegate_dependency(code_hash_ptr: u32) -> Result<(), TrapReason>;
    fn rent_allowance(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>;
    fn restore_to(
        _dest_ptr: u32,
        _code_hash_ptr: u32,
        _rent_allowance_ptr: u32,
        _delta_ptr: u32,
        _delta_count: u32
    ) -> Result<(), TrapReason>;
    fn seal_return(
        flags: u32,
        data_ptr: u32,
        data_len: u32
    ) -> Result<(), TrapReason>;
    fn set_code_hash(code_hash_ptr: u32) -> Result<ReturnCode, TrapReason>;
    fn set_rent_allowance(_value_ptr: u32) -> Result<(), TrapReason>;
    fn set_storage(
        key_ptr: u32,
        key_len: u32,
        value_ptr: u32,
        value_len: u32
    ) -> Result<u32, TrapReason>;
    fn sr25519_verify(
        signature_ptr: u32,
        pub_key_ptr: u32,
        message_len: u32,
        message_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn take_storage(
        key_ptr: u32,
        key_len: u32,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn terminate(beneficiary_ptr: u32) -> Result<(), TrapReason>;
    fn tombstone_deposit(
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<(), TrapReason>;
    fn transfer(
        account_ptr: u32,
        _account_len: u32,
        value_ptr: u32,
        _value_len: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn value_transferred(
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<(), TrapReason>;
    fn weight_to_fee(
        ref_time_limit: u64,
        proof_size_limit: u64,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<(), TrapReason>;
}

Contains only the latest version of each function.

In reality there are more functions available but they are all obsolete: When a function is updated a new version is added and the old versions stays available as-is. We only list the newest version here. Some functions are available under additional names (aliases) for historic reasons which are omitted here.

If you want an overview of all the functions available to a contact all you need to look at is this trait. It contains only the latest version of each function and no aliases. If you are writing a contract(language) from scratch this is where you should look at.

Required Methods

fn account_reentrance_count(account_ptr: u32) -> Result<u32, TrapReason>

Returns the number of times specified contract exists on the call stack. Delegated calls are not counted as separate calls.

Parameters

• account_ptr: a pointer to the contract address.

Return Value

Returns 0 when the contract does not exist on the call stack.

Wasm Import Statement

(import "seal0" "account_reentrance_count" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn add_delegate_dependency(code_hash_ptr: u32) -> Result<(), TrapReason>

Adds a new delegate dependency to the contract.

Parameters

• code_hash_ptr: A pointer to the code hash of the dependency.

Wasm Import Statement

(import "seal0" "add_delegate_dependency" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn address(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the address of the current contract into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

Wasm Import Statement

(import "seal0" "address" (func ...))

fn balance(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the free balance of the current account into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

The data is encoded as T::Balance.

Wasm Import Statement

(import "seal0" "balance" (func ...))

fn block_number(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the current block number of the current contract into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

Wasm Import Statement

(import "seal0" "block_number" (func ...))

fn call( flags: u32, callee_ptr: u32, ref_time_limit: u64, proof_size_limit: u64, deposit_ptr: u32, value_ptr: u32, input_data_ptr: u32, input_data_len: u32, output_ptr: u32, output_len_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Make a call to another contract.

The callees output buffer is copied to output_ptr and its length to output_len_ptr. The copy of the output buffer can be skipped by supplying the sentinel value of SENTINEL to output_ptr.

Parameters

• flags: See crate::wasm::runtime::CallFlags for a documentation of the supported flags.
• callee_ptr: a pointer to the address of the callee contract. Should be decodable as an T::AccountId. Traps otherwise.
• ref_time_limit: how much ref_time Weight to devote to the execution.
• proof_size_limit: how much proof_size Weight to devote to the execution.
• deposit_ptr: a pointer to the buffer with value of the storage deposit limit for the call. Should be decodable as a T::Balance. Traps otherwise. Passing SENTINEL means setting no specific limit for the call, which implies storage usage up to the limit of the parent call.
• value_ptr: a pointer to the buffer with value, how much value to send. Should be decodable as a T::Balance. Traps otherwise.
• input_data_ptr: a pointer to a buffer to be used as input data to the callee.
• input_data_len: length of the input data buffer.
• output_ptr: a pointer where the output buffer is copied to.
• output_len_ptr: in-out pointer to where the length of the buffer is read from and the actual length is written to.

Errors

An error means that the call wasn’t successful output buffer is returned unless stated otherwise.

• ReturnCode::CalleeReverted: Output buffer is returned.
• ReturnCode::CalleeTrapped
• ReturnCode::TransferFailed
• ReturnCode::NotCallable

Wasm Import Statement

(import "seal2" "call" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn call_chain_extension( id: u32, input_ptr: u32, input_len: u32, output_ptr: u32, output_len_ptr: u32 ) -> Result<u32, TrapReason>

Call into the chain extension provided by the chain if any.

Handling of the input values is up to the specific chain extension and so is the return value. The extension can decide to use the inputs as primitive inputs or as in/out arguments by interpreting them as pointers. Any caller of this function must therefore coordinate with the chain that it targets.

Note

If no chain extension exists the contract will trap with the NoChainExtension module error.

Wasm Import Statement

(import "seal0" "call_chain_extension" (func ...))

fn call_runtime(call_ptr: u32, call_len: u32) -> Result<ReturnCode, TrapReason>

Call some dispatchable of the runtime.

This function decodes the passed in data as the overarching Call type of the runtime and dispatches it. The weight as specified in the runtime is charged from the gas meter. Any weight refunds made by the dispatchable are considered.

The filter specified by Config::CallFilter is attached to the origin of the dispatched call.

Parameters

• call_ptr: the pointer into the linear memory where the input data is placed.
• call_len: the length of the input data in bytes.

Return Value

Returns ReturnCode::Success when the dispatchable was successfully executed and returned Ok. When the dispatchable was exeuted but returned an error ReturnCode::CallRuntimeFailed is returned. The full error is not provided because it is not guaranteed to be stable.

Comparison with ChainExtension

Just as a chain extension this API allows the runtime to extend the functionality of contracts. While making use of this function is generally easier it cannot be used in all cases. Consider writing a chain extension if you need to do perform one of the following tasks:

• Return data.
• Provide functionality exclusively to contracts.
• Provide custom weights.
• Avoid the need to keep the Call data structure stable.

Wasm Import Statement

(import "seal0" "call_runtime" (func ...))

fn caller(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the address of the caller into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

If this is a top-level call (i.e. initiated by an extrinsic) the origin address of the extrinsic will be returned. Otherwise, if this call is initiated by another contract then the address of the contract will be returned. The value is encoded as T::AccountId.

If there is no address associated with the caller (e.g. because the caller is root) then it traps with BadOrigin.

Wasm Import Statement

(import "seal0" "caller" (func ...))

fn caller_is_origin() -> Result<u32, TrapReason>

Checks whether the caller of the current contract is the origin of the whole call stack.

Prefer this over is_contract() when checking whether your contract is being called by a contract or a plain account. The reason is that it performs better since it does not need to do any storage lookups.

A return value of true indicates that this contract is being called by a plain account and false indicates that the caller is another contract.

Returned value is a u32-encoded boolean: (0 = false, 1 = true).

Wasm Import Statement

(import "seal0" "caller_is_origin" (func ...))

fn caller_is_root() -> Result<u32, TrapReason>

Checks whether the caller of the current contract is root.

Note that only the origin of the call stack can be root. Hence this function returning true implies that the contract is being called by the origin.

A return value of true indicates that this contract is being called by a root origin, and false indicates that the caller is a signed origin.

Returned value is a u32-encoded boolean: (0 = false, 1 = true).

Wasm Import Statement

(import "seal0" "caller_is_root" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn clear_storage(key_ptr: u32, key_len: u32) -> Result<u32, TrapReason>

Clear the value at the given key in the contract storage.

Parameters

• key_ptr: pointer into the linear memory where the key is placed.
• key_len: the length of the key in bytes.

Return Value

Returns the size of the pre-existing value at the specified key if any. Otherwise SENTINEL is returned as a sentinel value.

Wasm Import Statement

(import "seal1" "clear_storage" (func ...))

fn code_hash( account_ptr: u32, out_ptr: u32, out_len_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Retrieve the code hash for a specified contract address.

Parameters

• account_ptr: a pointer to the address in question. Should be decodable as an T::AccountId. Traps otherwise.
• out_ptr: pointer to the linear memory where the returning value is written to.
• out_len_ptr: in-out pointer into linear memory where the buffer length is read from and the value length is written to.

Errors

• ReturnCode::KeyNotFound

Wasm Import Statement

(import "seal0" "code_hash" (func ...))

fn contains_storage(key_ptr: u32, key_len: u32) -> Result<u32, TrapReason>

Checks whether there is a value stored under the given key.

The key length must not exceed the maximum defined by the contracts module parameter.

Parameters

• key_ptr: pointer into the linear memory where the key of the requested value is placed.
• key_len: the length of the key in bytes.

Return Value

Returns the size of the pre-existing value at the specified key if any. Otherwise SENTINEL is returned as a sentinel value.

Wasm Import Statement

(import "seal1" "contains_storage" (func ...))

fn debug_message(str_ptr: u32, str_len: u32) -> Result<ReturnCode, TrapReason>

Emit a custom debug message.

No newlines are added to the supplied message. Specifying invalid UTF-8 just drops the message with no trap.

This is a no-op if debug message recording is disabled which is always the case when the code is executing on-chain. The message is interpreted as UTF-8 and appended to the debug buffer which is then supplied to the calling RPC client.

Note

Even though no action is taken when debug message recording is disabled there is still a non trivial overhead (and weight cost) associated with calling this function. Contract languages should remove calls to this function (either at runtime or compile time) when not being executed as an RPC. For example, they could allow users to disable logging through compile time flags (cargo features) for on-chain deployment. Additionally, the return value of this function can be cached in order to prevent further calls at runtime.

Wasm Import Statement

(import "seal0" "debug_message" (func ...))

fn delegate_call( flags: u32, code_hash_ptr: u32, input_data_ptr: u32, input_data_len: u32, output_ptr: u32, output_len_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Execute code in the context (storage, caller, value) of the current contract.

Reentrancy protection is always disabled since the callee is allowed to modify the callers storage. This makes going through a reentrancy attack unnecessary for the callee when it wants to exploit the caller.

Parameters

• flags: see crate::wasm::runtime::CallFlags for a documentation of the supported flags.
• code_hash: a pointer to the hash of the code to be called.
• input_data_ptr: a pointer to a buffer to be used as input data to the callee.
• input_data_len: length of the input data buffer.
• output_ptr: a pointer where the output buffer is copied to.
• output_len_ptr: in-out pointer to where the length of the buffer is read from and the actual length is written to.

Errors

An error means that the call wasn’t successful and no output buffer is returned unless stated otherwise.

• ReturnCode::CalleeReverted: Output buffer is returned.
• ReturnCode::CalleeTrapped
• ReturnCode::CodeNotFound

Wasm Import Statement

(import "seal0" "delegate_call" (func ...))

fn deposit_event( topics_ptr: u32, topics_len: u32, data_ptr: u32, data_len: u32 ) -> Result<(), TrapReason>

Deposit a contract event with the data buffer and optional list of topics. There is a limit on the maximum number of topics specified by event_topics.

• topics_ptr: a pointer to the buffer of topics encoded as Vec<T::Hash>. The value of this is ignored if topics_len is set to 0. The topics list can’t contain duplicates.
• topics_len: the length of the topics buffer. Pass 0 if you want to pass an empty vector.
• data_ptr: a pointer to a raw data buffer which will saved along the event.
• data_len: the length of the data buffer.

Wasm Import Statement

(import "seal0" "deposit_event" (func ...))

fn ecdsa_recover( signature_ptr: u32, message_hash_ptr: u32, output_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Recovers the ECDSA public key from the given message hash and signature.

Writes the public key into the given output buffer. Assumes the secp256k1 curve.

Parameters

• signature_ptr: the pointer into the linear memory where the signature is placed. Should be decodable as a 65 bytes. Traps otherwise.
• message_hash_ptr: the pointer into the linear memory where the message hash is placed. Should be decodable as a 32 bytes. Traps otherwise.
• output_ptr: the pointer into the linear memory where the output data is placed. The buffer should be 33 bytes. The function will write the result directly into this buffer.

Errors

• ReturnCode::EcdsaRecoverFailed

Wasm Import Statement

(import "seal0" "ecdsa_recover" (func ...))

fn ecdsa_to_eth_address( key_ptr: u32, out_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Calculates Ethereum address from the ECDSA compressed public key and stores it into the supplied buffer.

Parameters

• key_ptr: a pointer to the ECDSA compressed public key. Should be decodable as a 33 bytes value. Traps otherwise.
• out_ptr: the pointer into the linear memory where the output data is placed. The function will write the result directly into this buffer.

The value is stored to linear memory at the address pointed to by out_ptr. If the available space at out_ptr is less than the size of the value a trap is triggered.

Errors

• ReturnCode::EcdsaRecoverFailed

Wasm Import Statement

(import "seal0" "ecdsa_to_eth_address" (func ...))

fn gas_left(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the amount of weight left into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

The data is encoded as Weight.

Wasm Import Statement

(import "seal1" "gas_left" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn get_storage( key_ptr: u32, key_len: u32, out_ptr: u32, out_len_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Retrieve the value under the given key from storage.

This version is to be used with a fixed sized storage key. For runtimes supporting transparent hashing, please use the newer version of this function.

The key length must not exceed the maximum defined by the contracts module parameter.

Parameters

• key_ptr: pointer into the linear memory where the key of the requested value is placed.
• key_len: the length of the key in bytes.
• out_ptr: pointer to the linear memory where the value is written to.
• out_len_ptr: in-out pointer into linear memory where the buffer length is read from and the value length is written to.

Errors

• ReturnCode::KeyNotFound

Wasm Import Statement

(import "seal1" "get_storage" (func ...))

fn hash_blake2_128( input_ptr: u32, input_len: u32, output_ptr: u32 ) -> Result<(), TrapReason>

Computes the BLAKE2 128-bit hash on the given input buffer.

Returns the result directly into the given output buffer.

Note

• The input and output buffer may overlap.
• The output buffer is expected to hold at least 16 bytes (128 bits).
• It is the callers responsibility to provide an output buffer that is large enough to hold the expected amount of bytes returned by the chosen hash function.

Parameters

• input_ptr: the pointer into the linear memory where the input data is placed.
• input_len: the length of the input data in bytes.
• output_ptr: the pointer into the linear memory where the output data is placed. The function will write the result directly into this buffer.

Wasm Import Statement

(import "seal0" "hash_blake2_128" (func ...))

fn hash_blake2_256( input_ptr: u32, input_len: u32, output_ptr: u32 ) -> Result<(), TrapReason>

Computes the BLAKE2 256-bit hash on the given input buffer.

Returns the result directly into the given output buffer.

Note

• The input and output buffer may overlap.
• The output buffer is expected to hold at least 32 bytes (256 bits).
• It is the callers responsibility to provide an output buffer that is large enough to hold the expected amount of bytes returned by the chosen hash function.

Parameters

• input_ptr: the pointer into the linear memory where the input data is placed.
• input_len: the length of the input data in bytes.
• output_ptr: the pointer into the linear memory where the output data is placed. The function will write the result directly into this buffer.

Wasm Import Statement

(import "seal0" "hash_blake2_256" (func ...))

fn hash_keccak_256( input_ptr: u32, input_len: u32, output_ptr: u32 ) -> Result<(), TrapReason>

Computes the KECCAK 256-bit hash on the given input buffer.

Returns the result directly into the given output buffer.

Note

• The input and output buffer may overlap.
• The output buffer is expected to hold at least 32 bytes (256 bits).
• It is the callers responsibility to provide an output buffer that is large enough to hold the expected amount of bytes returned by the chosen hash function.

Parameters

• input_ptr: the pointer into the linear memory where the input data is placed.
• input_len: the length of the input data in bytes.
• output_ptr: the pointer into the linear memory where the output data is placed. The function will write the result directly into this buffer.

Wasm Import Statement

(import "seal0" "hash_keccak_256" (func ...))

fn hash_sha2_256( input_ptr: u32, input_len: u32, output_ptr: u32 ) -> Result<(), TrapReason>

Computes the SHA2 256-bit hash on the given input buffer.

Returns the result directly into the given output buffer.

Note

• The input and output buffer may overlap.
• The output buffer is expected to hold at least 32 bytes (256 bits).
• It is the callers responsibility to provide an output buffer that is large enough to hold the expected amount of bytes returned by the chosen hash function.

Parameters

• input_ptr: the pointer into the linear memory where the input data is placed.
• input_len: the length of the input data in bytes.
• output_ptr: the pointer into the linear memory where the output data is placed. The function will write the result directly into this buffer.

Wasm Import Statement

(import "seal0" "hash_sha2_256" (func ...))

fn input(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the input passed by the caller into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

Note

This function traps if the input was previously forwarded by a call().

Wasm Import Statement

(import "seal0" "input" (func ...))

fn instantiate( code_hash_ptr: u32, ref_time_limit: u64, proof_size_limit: u64, deposit_ptr: u32, value_ptr: u32, input_data_ptr: u32, input_data_len: u32, address_ptr: u32, address_len_ptr: u32, output_ptr: u32, output_len_ptr: u32, salt_ptr: u32, salt_len: u32 ) -> Result<ReturnCode, TrapReason>

Instantiate a contract with the specified code hash.

This function creates an account and executes the constructor defined in the code specified by the code hash. The address of this new account is copied to address_ptr and its length to address_len_ptr. The constructors output buffer is copied to output_ptr and its length to output_len_ptr. The copy of the output buffer and address can be skipped by supplying the sentinel value of SENTINEL to output_ptr or address_ptr.

Parameters

• code_hash_ptr: a pointer to the buffer that contains the initializer code.
• ref_time_limit: how much ref_time Weight to devote to the execution.
• proof_size_limit: how much proof_size Weight to devote to the execution.
• deposit_ptr: a pointer to the buffer with value of the storage deposit limit for instantiation. Should be decodable as a T::Balance. Traps otherwise. Passing SENTINEL means setting no specific limit for the call, which implies storage usage up to the limit of the parent call.
• value_ptr: a pointer to the buffer with value, how much value to send. Should be decodable as a T::Balance. Traps otherwise.
• input_data_ptr: a pointer to a buffer to be used as input data to the initializer code.
• input_data_len: length of the input data buffer.
• address_ptr: a pointer where the new account’s address is copied to. SENTINEL means not to copy.
• address_len_ptr: pointer to where put the length of the address.
• output_ptr: a pointer where the output buffer is copied to. SENTINEL means not to copy.
• output_len_ptr: in-out pointer to where the length of the buffer is read from and the actual length is written to.
• salt_ptr: Pointer to raw bytes used for address derivation. See fn contract_address.
• salt_len: length in bytes of the supplied salt.

Errors

Please consult the ReturnCode enum declaration for more information on those errors. Here we only note things specific to this function.

An error means that the account wasn’t created and no address or output buffer is returned unless stated otherwise.

• ReturnCode::CalleeReverted: Output buffer is returned.
• ReturnCode::CalleeTrapped
• ReturnCode::TransferFailed
• ReturnCode::CodeNotFound

Wasm Import Statement

(import "seal2" "instantiate" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn instantiation_nonce() -> Result<u64, TrapReason>

Returns a nonce that is unique per contract instantiation.

The nonce is incremented for each successful contract instantiation. This is a sensible default salt for contract instantiations.

Wasm Import Statement

(import "seal0" "instantiation_nonce" (func ...))

fn is_contract(account_ptr: u32) -> Result<u32, TrapReason>

Checks whether a specified address belongs to a contract.

Parameters

• account_ptr: a pointer to the address of the beneficiary account Should be decodable as an T::AccountId. Traps otherwise.

Returned value is a u32-encoded boolean: (0 = false, 1 = true).

Wasm Import Statement

(import "seal0" "is_contract" (func ...))

fn minimum_balance(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the minimum balance (a.k.a. existential deposit) into the supplied buffer.

The data is encoded as T::Balance.

Wasm Import Statement

(import "seal0" "minimum_balance" (func ...))

fn now(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Load the latest block timestamp into the supplied buffer

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

Wasm Import Statement

(import "seal0" "now" (func ...))

fn own_code_hash(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Retrieve the code hash of the currently executing contract.

Parameters

• out_ptr: pointer to the linear memory where the returning value is written to.
• out_len_ptr: in-out pointer into linear memory where the buffer length is read from and the value length is written to.

Wasm Import Statement

(import "seal0" "own_code_hash" (func ...))

fn random( subject_ptr: u32, subject_len: u32, out_ptr: u32, out_len_ptr: u32 ) -> Result<(), TrapReason>

Deprecated

This function is deprecated and will be removed in future versions. No new code or contracts with this API can be deployed. Stores a random number for the current block and the given subject into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

The data is encoded as (T::Hash, frame_system::pallet_prelude::BlockNumberFor::).

Changes from v0

In addition to the seed it returns the block number since which it was determinable by chain observers.

Note

The returned seed should only be used to distinguish commitments made before the returned block number. If the block number is too early (i.e. commitments were made afterwards), then ensure no further commitments may be made and repeatedly call this on later blocks until the block number returned is later than the latest commitment.

Wasm Import Statement

(import "seal1" "random" (func ...))

fn reentrance_count() -> Result<u32, TrapReason>

Returns the number of times the currently executing contract exists on the call stack in addition to the calling instance.

Return Value

Returns 0 when there is no reentrancy.

Wasm Import Statement

(import "seal0" "reentrance_count" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn remove_delegate_dependency(code_hash_ptr: u32) -> Result<(), TrapReason>

Removes the delegate dependency from the contract.

Parameters

• code_hash_ptr: A pointer to the code hash of the dependency.

Wasm Import Statement

(import "seal0" "remove_delegate_dependency" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn rent_allowance(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Deprecated

This function is deprecated and will be removed in future versions. No new code or contracts with this API can be deployed. Was used to store the rent allowance into the supplied buffer.

Note

The state rent functionality was removed. This is stub only exists for backwards compatibility.

Wasm Import Statement

(import "seal0" "rent_allowance" (func ...))

fn restore_to( _dest_ptr: u32, _code_hash_ptr: u32, _rent_allowance_ptr: u32, _delta_ptr: u32, _delta_count: u32 ) -> Result<(), TrapReason>

Deprecated

This function is deprecated and will be removed in future versions. No new code or contracts with this API can be deployed. Was used to restore the given destination contract sacrificing the caller.

Note

The state rent functionality was removed. This is stub only exists for backwards compatibility

Wasm Import Statement

(import "seal1" "restore_to" (func ...))

fn seal_return( flags: u32, data_ptr: u32, data_len: u32 ) -> Result<(), TrapReason>

Cease contract execution and save a data buffer as a result of the execution.

This function never returns as it stops execution of the caller. This is the only way to return a data buffer to the caller. Returning from execution without calling this function is equivalent to calling:

seal_return(0, 0, 0);

The flags argument is a bitfield that can be used to signal special return conditions to the supervisor: — lsb — bit 0 : REVERT - Revert all storage changes made by the caller. bit [1, 31]: Reserved for future use. — msb —

Using a reserved bit triggers a trap.

Wasm Import Statement

(import "seal0" "seal_return" (func ...))

fn set_code_hash(code_hash_ptr: u32) -> Result<ReturnCode, TrapReason>

Replace the contract code at the specified address with new code.

Note

There are a couple of important considerations which must be taken into account when using this API:

1. The storage at the code address will remain untouched. This means that contract developers must ensure that the storage layout of the new code is compatible with that of the old code.

2. Contracts using this API can’t be assumed as having deterministic addresses. Said another way, when using this API you lose the guarantee that an address always identifies a specific code hash.

3. If a contract calls into itself after changing its code the new call would use the new code. However, if the original caller panics after returning from the sub call it would revert the changes made by set_code_hash() and the next caller would use the old code.

Parameters

• code_hash_ptr: A pointer to the buffer that contains the new code hash.

Errors

• ReturnCode::CodeNotFound

Wasm Import Statement

(import "seal0" "set_code_hash" (func ...))

fn set_rent_allowance(_value_ptr: u32) -> Result<(), TrapReason>

Deprecated

This function is deprecated and will be removed in future versions. No new code or contracts with this API can be deployed. Was used to set rent allowance of the contract.

Note

The state rent functionality was removed. This is stub only exists for backwards compatibility.

Wasm Import Statement

(import "seal1" "set_rent_allowance" (func ...))

fn set_storage( key_ptr: u32, key_len: u32, value_ptr: u32, value_len: u32 ) -> Result<u32, TrapReason>

Set the value at the given key in the contract storage.

The key and value lengths must not exceed the maximums defined by the contracts module parameters. Specifying a value_len of zero will store an empty value.

Parameters

• key_ptr: pointer into the linear memory where the location to store the value is placed.
• key_len: the length of the key in bytes.
• value_ptr: pointer into the linear memory where the value to set is placed.
• value_len: the length of the value in bytes.

Return Value

Returns the size of the pre-existing value at the specified key if any. Otherwise SENTINEL is returned as a sentinel value.

Wasm Import Statement

(import "seal2" "set_storage" (func ...))

fn sr25519_verify( signature_ptr: u32, pub_key_ptr: u32, message_len: u32, message_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Verify a sr25519 signature

Parameters

• signature_ptr: the pointer into the linear memory where the signature is placed. Should be a value of 64 bytes.
• pub_key_ptr: the pointer into the linear memory where the public key is placed. Should be a value of 32 bytes.
• message_len: the length of the message payload.
• message_ptr: the pointer into the linear memory where the message is placed.

Errors

• `ReturnCode::Sr25519VerifyFailed

Wasm Import Statement

(import "seal0" "sr25519_verify" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

fn take_storage( key_ptr: u32, key_len: u32, out_ptr: u32, out_len_ptr: u32 ) -> Result<ReturnCode, TrapReason>

Retrieve and remove the value under the given key from storage.

Parameters

• key_ptr: pointer into the linear memory where the key of the requested value is placed.
• key_len: the length of the key in bytes.
• out_ptr: pointer to the linear memory where the value is written to.
• out_len_ptr: in-out pointer into linear memory where the buffer length is read from and the value length is written to.

Errors

• ReturnCode::KeyNotFound

Wasm Import Statement

(import "seal0" "take_storage" (func ...))

fn terminate(beneficiary_ptr: u32) -> Result<(), TrapReason>

Remove the calling account and transfer remaining free balance.

This function never returns. Either the termination was successful and the execution of the destroyed contract is halted. Or it failed during the termination which is considered fatal and results in a trap + rollback.

• beneficiary_ptr: a pointer to the address of the beneficiary account where all where all remaining funds of the caller are transferred. Should be decodable as an T::AccountId. Traps otherwise.

Traps

• The contract is live i.e is already on the call stack.
• Failed to send the balance to the beneficiary.
• The deletion queue is full.

Wasm Import Statement

(import "seal1" "terminate" (func ...))

fn tombstone_deposit(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Deprecated

This function is deprecated and will be removed in future versions. No new code or contracts with this API can be deployed. Stores the tombstone deposit into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

Note

There is no longer a tombstone deposit. This function always returns 0.

Wasm Import Statement

(import "seal0" "tombstone_deposit" (func ...))

fn transfer( account_ptr: u32, _account_len: u32, value_ptr: u32, _value_len: u32 ) -> Result<ReturnCode, TrapReason>

Transfer some value to another account.

Parameters

• account_ptr: a pointer to the address of the beneficiary account Should be decodable as an T::AccountId. Traps otherwise.
• account_len: length of the address buffer.
• value_ptr: a pointer to the buffer with value, how much value to send. Should be decodable as a T::Balance. Traps otherwise.
• value_len: length of the value buffer.

Errors

• ReturnCode::TransferFailed

Wasm Import Statement

(import "seal0" "transfer" (func ...))

fn value_transferred(out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason>

Stores the value transferred along with this call/instantiate into the supplied buffer.

The value is stored to linear memory at the address pointed to by out_ptr. out_len_ptr must point to a u32 value that describes the available space at out_ptr. This call overwrites it with the size of the value. If the available space at out_ptr is less than the size of the value a trap is triggered.

The data is encoded as T::Balance.

Wasm Import Statement

(import "seal0" "value_transferred" (func ...))

fn weight_to_fee( ref_time_limit: u64, proof_size_limit: u64, out_ptr: u32, out_len_ptr: u32 ) -> Result<(), TrapReason>

Stores the price for the specified amount of weight into the supplied buffer.

Parameters

• out_ptr: pointer to the linear memory where the returning value is written to. If the available space at out_ptr is less than the size of the value a trap is triggered.
• out_len_ptr: in-out pointer into linear memory where the buffer length is read from and the value length is written to.

The data is encoded as T::Balance.

Note

It is recommended to avoid specifying very small values for ref_time_limit and proof_size_limit as the prices for a single gas can be smaller than the basic balance unit.

Wasm Import Statement

(import "seal1" "weight_to_fee" (func ...))

Unstable

This function is unstable and it is a subject to change (or removal) in the future. Do not deploy a contract using it to a production chain.

Implementors