Trait pallet_contracts::api_doc::seal1::Api

pub trait Api {
    fn set_storage(
        key_ptr: u32,
        value_ptr: u32,
        value_len: u32
    ) -> Result<u32, TrapReason>;
    fn clear_storage(key_ptr: u32, key_len: u32) -> Result<u32, TrapReason>;
    fn get_storage(
        key_ptr: u32,
        key_len: u32,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn contains_storage(key_ptr: u32, key_len: u32) -> Result<u32, TrapReason>;
    fn call(
        flags: u32,
        callee_ptr: u32,
        gas: u64,
        value_ptr: u32,
        input_data_ptr: u32,
        input_data_len: u32,
        output_ptr: u32,
        output_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn instantiate(
        code_hash_ptr: u32,
        gas: u64,
        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 terminate(beneficiary_ptr: u32) -> Result<(), TrapReason>;
    fn random(
        subject_ptr: u32,
        subject_len: u32,
        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 set_rent_allowance(_value_ptr: u32) -> Result<(), TrapReason>;
    fn seal_set_storage(
        key_ptr: u32,
        value_ptr: u32,
        value_len: u32
    ) -> Result<u32, TrapReason>;
    fn seal_clear_storage(key_ptr: u32, key_len: u32) -> Result<u32, TrapReason>;
    fn seal_get_storage(
        key_ptr: u32,
        key_len: u32,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn seal_contains_storage(
        key_ptr: u32,
        key_len: u32
    ) -> Result<u32, TrapReason>;
    fn seal_call(
        flags: u32,
        callee_ptr: u32,
        gas: u64,
        value_ptr: u32,
        input_data_ptr: u32,
        input_data_len: u32,
        output_ptr: u32,
        output_len_ptr: u32
    ) -> Result<ReturnCode, TrapReason>;
    fn seal_instantiate(
        code_hash_ptr: u32,
        gas: u64,
        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 seal_terminate(beneficiary_ptr: u32) -> Result<(), TrapReason>;
    fn seal_random(
        subject_ptr: u32,
        subject_len: u32,
        out_ptr: u32,
        out_len_ptr: u32
    ) -> Result<(), TrapReason>;
    fn seal_restore_to(
        _dest_ptr: u32,
        _code_hash_ptr: u32,
        _rent_allowance_ptr: u32,
        _delta_ptr: u32,
        _delta_count: u32
    ) -> Result<(), TrapReason>;
    fn seal_set_rent_allowance(_value_ptr: u32) -> Result<(), TrapReason>;
}

Every function in this trait represents (at least) one function that can be imported by a contract.

The function’s identifier is to be set as the name in the import definition. Where it is specifically indicated, an alias function having seal_-prefixed identifier and just the same signature and body, is also available (for backwards-compatibility purposes).

Required Methods

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

Set the value at the given key in the contract 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 value length must not exceed the maximum 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.
• 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.

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.

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

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.

fn call(
    flags: u32,
    callee_ptr: u32,
    gas: u64,
    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 documenation of the supported flags.
• callee_ptr: a pointer to the address of the callee contract. Should be decodable as an T::AccountId. Traps otherwise.
• gas: how much gas to devote to the execution.
• 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

fn instantiate(
    code_hash_ptr: u32,
    gas: u64,
    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.

value must be at least the minimum balance. Otherwise the instantiation fails and the contract is not created.

Parameters

• code_hash_ptr: a pointer to the buffer that contains the initializer code.
• gas: how much gas to devote to the execution of the initializer code.
• 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.
• address_len_ptr: in-out pointer to where the length of the buffer is read from and the actual length is written to.
• 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.
• 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

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.

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

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, T::BlockNumber).

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.

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

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 compatiblity

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

Was used to set rent allowance of the contract.

Note

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

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

This is just an alias function to set_storage() with backwards-compatible prefixed identifier.

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

This is just an alias function to clear_storage() with backwards-compatible prefixed identifier.

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

This is just an alias function to get_storage() with backwards-compatible prefixed identifier.

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

This is just an alias function to contains_storage() with backwards-compatible prefixed identifier.

fn seal_call(
    flags: u32,
    callee_ptr: u32,
    gas: u64,
    value_ptr: u32,
    input_data_ptr: u32,
    input_data_len: u32,
    output_ptr: u32,
    output_len_ptr: u32
) -> Result<ReturnCode, TrapReason>

This is just an alias function to call() with backwards-compatible prefixed identifier.

fn seal_instantiate(
    code_hash_ptr: u32,
    gas: u64,
    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>

This is just an alias function to instantiate() with backwards-compatible prefixed identifier.

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

This is just an alias function to terminate() with backwards-compatible prefixed identifier.

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

This is just an alias function to random() with backwards-compatible prefixed identifier.

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

This is just an alias function to restore_to() with backwards-compatible prefixed identifier.

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

This is just an alias function to set_rent_allowance() with backwards-compatible prefixed identifier.

Implementors