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) → i32

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 the start of the item in Wasm linear memory.
length (i32) – Number of bytes in the item.

Returns:

-1 if logging failed because the message was too long. 0 if the log is already full. 1 if the data was successfully logged.

Return type:

i32

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 in Wasm linear memory. Return the number of bytes read. 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 the write location in Wasm linear memory.
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 in Wasm linear memory.
length (i32) – Number of bytes to read.
offset (i32) – Starting offset in the state bytes.

Returns:

The number of read bytes.

Return type:

i32

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

Write a section of the memory to the state at a given offset. Return the number of bytes written. The offset must be less than or equal to the current state size. The state is assumed to be large enough to write the requested length into.

Parameters:

location (i32) – Pointer to read location in Wasm linear memory.
length (i32) – Number of bytes to write.
offset (i32) – Starting offset in the state 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

Identity data#

Functions for reading identity information.

concordium.get_policy_section(policy_bytes, length, offset) → i32

Read a section of the policy to the given location. Return the number of bytes read. Assumes the location has enough memory to write the requested length into.

Parameters:

policy_bytes (i32) – Pointer to write location in Wasm linear memory.
length (i32) – Number of bytes to read.
offset (i32) – Starting offset in the policy bytes.

Returns:

The number of bytes read.

Return type:

i32

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 to the 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 to the 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 to the 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 to the 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 to the 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 CCD action.

Parameters:

addr_bytes (i32) – Pointer to the address of the receiver.
amount (i64) – The amount of CCD 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 CCD 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 if 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