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 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 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

Support & Feedback

If you have questions or feedback, join us on Discourse, or contact us at support@concordium.software.