Contract host functions

This is a reference of the functions in the concordium module supplied by a host running smart contract Wasm module.

Warning

These functions are not meant to be called directly by smart contract writers. Instead, they are to be used behind a more idiomatic, language-specific API supplied by a library, such as concordium-std for Rust.

Logging events

concordium.log_event(start, length)

Adds a log item from an array of bytes. If not enough data can be read then this function will trap and abort execution of the smart contract.

Parameters

  • start (i32) – Pointer to start of the item in linear memory.

  • length (i32) – Number of bytes in the item.

Function parameter

concordium.get_parameter_size() → i32

Get the byte size of the parameter.

Returns

byte size of the parameter

Return type

i32

concordium.get_parameter_section(location, length, offset) → i32

Read a section of the parameter to the given location. Return the number of bytes read. The location is assumed to contain enough memory to write the requested length into.

Parameters

  • location (i32) – Pointer (in Wasm linear memory) of the write location.

  • length (i32) – Number of bytes to read from the parameter.

  • offset (i32) – Starting offset in the parameter bytes.

Returns

The number of actual bytes read. This is always less than or equal to length. It is less if the parameter does not have enough bytes available (i.e., if offset + length > parameter_size).

Return type

i32

Smart contract instance state

concordium.state_size() → i32

Get the byte size of the contract state.

Returns

byte size of the contract state

Return type

i32

concordium.load_state(location, length, offset) → i32

Read a section of the state to the given location. Return the number of bytes written. The location is assumed to contain enough memory to write the requested length into. If not, the function will trap and abort execution of the contract.

Parameters

  • location (i32) – Pointer to write location.

  • length (i32) – Number of bytes to read

  • offset (i32) – Starting offset in the bytes

Returns

The number of read bytes

Return type

i32

concordium.write_state(location, length, offset) → i32

Write a section of the state to the given location. Return the number of bytes written. The location is assumed to contain enough memory to write the requested length into.

Parameters

  • location (i32) – Pointer to read location

  • length (i32) – Number of bytes to write

  • offset (i32) – Starting offset in the bytes

Returns

The number of written bytes

Return type

i32

concordium.resize_state(new_size) → i32

Resize state to the new value (truncate if new size is smaller). The additional state is initialized to 0.

Parameters

new_size (i32) – New size of contract state in bytes.

Returns

0 if this was unsuccessful (new state too big), or 1 if successful

Return type

i32

Chain data

Functions for reading information about the chain.

concordium.get_slot_time() → i64

Get time in milliseconds at the beginning of this block.

Returns

Time in milliseconds

Return type

i64

concordium.get_slot_number() → i64

Get the slot number of the current block.

Returns

Slot number

Return type

i64

concordium.get_block_height() → i64

Get block height of the current block.

Returns

Block height

Return type

i64

concordium.get_finalized_height() → i64

Get the height of the last finalized block, i.e., block to which the current block has a finalized pointer to.

Returns

Finalized height

Return type

i64

Only in init function

Functions only accessible for smart contract init functions. If called from a receive function execution will abort.

concordium.get_init_origin(start)

Get the address of the account that triggered the init function.

Parameters

start (i32) – Pointer of location to put the address. The address is 32 bytes and the memory must be large enough to contain it.

Only in receive function

Functions only accessible for smart contract receive functions.

concordium.get_receive_invoker(start)

Get the address of the account that initiated the top-level transaction which lead to triggering the receive function.

Parameters

start (i32) – Pointer of location to put the address

concordium.get_receive_sender(start)

Get the address of the account or contract, triggering the receive function.

Parameters

start (i32) – Pointer of location to put the address

concordium.get_receive_self_address(start)

Get the address of the contract instance, running the receive function.

Parameters

start (i32) – Pointer of location to put the address

concordium.get_receive_owner(start)

Get the address of the account, which created the contract instance.

Parameters

start (i32) – Pointer of location to put the address

concordium.get_receive_self_balance() → i64

Get the current balance of the contract instance.

Returns

Current balance of the contract instance

Return type

i64

Action description

The description of actions to execute on the chain, returned by smart contract receive function.

concordium.accept() → i32

Constructs a accept action, indicating the function was successful.

Returns

Identifier of the resulting action.

Return type

i32

concordium.simple_transfer(addr_bytes, amount) → i32

Constructs a simple transfer of GTU action.

Parameters

  • addr_bytes (i32) – Pointer to the address of the receiver

  • amount (i64) – The amount of GTU to send

Returns

Identifier of the resulting action.

Return type

i32

concordium.send(addr_index, addr_subindex, receive_name, receive_name_len, amount, parameter, parameter_len) → i32

Constructs an action for sending a message to another smart contract instance.

Parameters

  • addr_index (i64) – Index of the smart contract instance address to send to

  • addr_subindex (i64) – Subindex of the smart contract instance address to send to

  • receive_name (i32) – Pointer to a memory location containing the name of the receive function to invoke

  • receive_name_len (i32) – Length of the receive function name. Determines how much memory will be read by the host.

  • amount (i64) – The amount of GTU to invoke the receive function with

  • parameter (i32) – Pointer to a memory location containing the parameters to the receive function

  • parameter_len (i32) – Length of the parameters

Returns

Identifier of the resulting action.

Return type

i32

concordium.combine_and(first, second) → i32

Combine two actions using and. Only run the second if the first succeeds. If the given identifiers are not valid, i.e., returned by a previous call to one of the actions functions, this function will abort.

Parameters

  • first (i32) – Identifier of the first action.

  • second (i32) – Identifier of the second action.

Returns

Identifier of the resulting action.

Return type

i32

concordium.combine_or(first, second) → i32

Combine two actions using or. Only runs the second of the first fails. If the given identifiers are not valid, i.e., returned by a previous call to one of the actions functions, this function will abort.

Parameters

  • first (i32) – Identifier of the first action.

  • second (i32) – Identifier of the second action.

Returns

Identifier of the resulting action.

Return type

i32