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(i) i32#

Get the byte size of the i-th parameter to the call. The 0-th parameter is always the original parameter that the method was invoked with. Invoking other contracts with invoke adds additional parameters to the stack.

Parameters

i (i32) – Index of the parameter.

Returns

Byte size of the i-th parameter or -1 if the parameter doesn’t exist.

Return type

i32

concordium.get_parameter_section(i, location, length, offset) i32#

Read a section of the i-th 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
  • i (i32) – Index of the parameter.

  • 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). Returns -1 if the parameter does not exist.

Return type

i32

Smart contract instance state#

concordium.state_create_entry(key_start, key_length) i64#

Create an empty entry with the given key. If an entry at that key already exists it is set to the empty entry.

Parameters
  • key_start (i32) – Pointer to a key, represented as a bytearray in the Wasm memory.

  • key_length (i32) – The length of the key.

Returns

The return value is either 2^64 - 1 if creating the entry failed because of an iterator lock on the part of the tree, or else the first bit is 0, and the remaining bits are an entry identifier that maybe used in subsequent state-related calls.

Return type

i64

concordium.state_lookup_entry(key_start, key_length) i64#

Lookup an entry with the given key.

Parameters
  • key_start (i32) – Pointer to key, represented as a bytearray in the Wasm memory.

  • key_length (i32) – The length of the key.

Returns

The return value is either 2^64 - 1 if creating the entry failed because of an iterator lock on the part of the tree, or else the first bit is 0 and the remaining bits are an entry identifier that maybe used in any of the entry calls.

Return type

i64

concordium.state_delete_entry(key_start, key_length) i32#

Delete the entry.

Parameters
  • key_start (i32) – Pointer to a key, represented as a byte array in the Wasm memory.

  • key_length (i32) – The length of the key.

Returns

Returns 0 if the part of the tree this entry was in is locked by an iterator (see the state_iterate_prefix for details) and the deletion thus failed. Returns 1 if the entry didn’t exist. Return 2 if the entry was successfully deleted.

Return type

i32

concordium.state_delete_prefix(key_start, key_length) i32#

Delete a prefix in the tree, that is, delete all parts of the tree that have the given key as a prefix.

Parameters
  • key_start (i32) – Pointer to a key, represented as a byte array in the Wasm memory.

  • key_length (i32) – The length of the key.

Returns

Returns 0 if the tree is locked by an iterator (see the state_iterate_prefix for details) and the deletion thus failed. Returns 1 if the tree was not locked, but the key points to an empty part of the tree. Returns 2 if a part of the tree was successfully deleted.

Return type

i32

concordium.state_iterate_prefix(prefix_start, prefix_length) i64#

Construct an iterator over a part of the tree. This locks the part of the tree that has the given prefix. Locking means that no deletions or insertions of entries may occur in that subtree.

Parameters
  • key_start (i32) – Pointer to a prefix, represented as a byte array in the Wasm memory.

  • key_length (i32) – The length of the prefix.

Returns

Returns all 1 bits if too many iterators already exist with this key. Returns all but second bit set to 1 if there is no value in the state with given prefix. Otherwise, the first bit is 0, and the remaining bits are the iterator identifier that may be used in subsequent calls to advance it, or to get its key.

Return type

i64

concordium.state_iterator_next(iterator) i64#

Return the next entry along the iterator, and advance the iterator.

Parameters

iterator (i64) – An iterator identifier, as returned by state_iterate_prefix.

Returns

Returns all 1 bits if the iterator does not exist (it was deleted, or the identifier was invalid). Returns all but the second bit set to 1 if no more entries are left, i.e., the iterator is exhausted. All further calls will yield the same value until the iterator is deleted. Otherwise, the first bit is 0, and the remaining bits encode an entry identifier that may be with any of the entry methods.

Return type

i64

concordium.state_iterator_delete(iterator) i32#

Delete the iterator, unlocking the subtree.

Parameters

iterator (i64) – An iterator identifier, as returned by state_iterate_prefix.

Returns

Returns 2^64 - 1 if the iterator does not exist. Returns 0 if the iterator was already deleted. Returns 1 if the iterator was successfully deleted.

Return type

i32

concordium.state_iterator_key_size(iterator) i32#

Get the length of the key that the iterator is currently pointing at.

Parameters

iterator (i64) – An iterator identifier, as returned by state_iterate_prefix.

Returns

2^64 - 1 if the iterator does not exist. Otherwise, it returns the length of the key in bytes.

Return type

i32

concordium.state_iterator_key_read(iterator, start, length, offset) i32#

Read a section of the key the iterator is currently pointing at. Before the first call to the state_iterator_next function this returns (sections of) the key that was used to create the iterator. After the iterator is exhausted, this method returns (sections of) the key at the first node returned by the iterator.

Parameters
  • iterator (i64) – An iterator identifier, as returned by state_iterate_prefix.

  • start (i32) – A pointer to a location in the Wasm memory where the key section be written to.

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

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

Returns

2^64 - 1 if the iterator does not exist. Otherwise, it returns the length of the key in bytes.

Return type

i32

concordium.state_entry_size(entry) i32#

Get the byte size of the entry.

Parameters

i64 (entry) – Entry identifier.

Returns

Byte size of the entry. Or 2^32 - 1 if the entry does not exist.

Return type

i32

concordium.state_entry_read(entry, location, length, offset) i32#

Read a section of the entry 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
  • entry (i64) – Entry identifier.

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

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

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

Returns

The number of read bytes. Or 2^32 - 1 if the entry does not exist.

Return type

i32

concordium.state_entry_write(entry, location, length, offset) i32#

Write a section of the memory to the entry at a given offset. Return the number of bytes written. The offset must be less than or equal to the current entry size.

Parameters
  • entry (i64) – Entry identifier.

  • location (i32) – Pointer to read location in Wasm linear memory.

  • length (i32) – Number of bytes to write.

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

Returns

The number of written bytes. Or 2^32 - 1 if the entry does not exist.

Return type

i32

concordium.state_entry_resize(entry, new_size) i32#

Resize entry to the new value (truncate if new size is smaller). If the new size is bigger, the additional state is initialized with 0.

Parameters
  • entry (i64) – Entry identifier.

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

Returns

0 if this was unsuccessful (new entry too big), 1 if successful, or 2^32 - 1 if the entry does not exist.

Return type

i32

Cryptographic primitives#

concordium.verify_ed25519_signature(public_key, signature, message, message_len) i32#

Verify an ed25519 signature.

Parameters
  • public_key (i32) – Pointer to a public key in linear memory. The public_key must point to a 32-byte array.

  • signature (i32) – Pointer to the claimed signature. The signature must point to a 64-byte array.

  • message (i32) – Pointer to the beginning of the message.

  • message_len (i32) – Length of the message in bytes.

Returns

1 if the signature check is successful, 0 if not.

Return type

i32

concordium.verify_ecdsa_secp256k1_signature(public_key, signature, message) i32#

Verify an ecdsa over secp256k1 signature with the bitcoin-core implementation.

Parameters
  • public_key (i32) – Pointer to a public key in linear memory. The public_key must point to a 33-byte array.

  • signature (i32) – Pointer to the claimed signature. The signature must point to a 64-byte array, serialized in compressed format.

  • message (i32) – Pointer to the beginning of the message. The message must be exactly 32-bytes long.

Returns

1 if the signature check is successful, 0 if not.

Return type

i32

concordium.hash_sha2_256(data, data_len, output)#

Compute the SHA2-256 digest of the data.

Parameters
  • data (i32) – Pointer to the beginning of the data.

  • data_len (i32) – Length of the data in bytes.

  • output (i32) – Pointer to a memory location where the digest will be written.

concordium.hash_sha3_256(data, data_len, output)#

Compute the SHA3-256 digest of the data.

Parameters
  • data (i32) – Pointer to the beginning of the data.

  • data_len (i32) – Length of the data in bytes.

  • output (i32) – Pointer to a memory location where the digest will be written.

concordium.hash_keccak_256(data, data_len, output)#

Compute the Keccak-256 digest of the data.

Parameters
  • data (i32) – Pointer to the beginning of the data.

  • data_len (i32) – Length of the data in bytes.

  • output (i32) – Pointer to a memory location where the digest will be written.

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.invoke(tag, start, length) i64#

Invoke a host instruction which is either a transfer to an account or a call to a contract.

Parameters
  • tag (i32) – 0 for transfer to an account or 1 for call to a contract.

  • start (i32) – Pointer to the start of the invoke payload.

  • length (i32) – Length of the invoke payload.

Returns

If the last five bytes are 0 then the call succeeded. In this case, the first bit of the response indicates whether state (of the invoking contract) has changed (1) or not (0) and the remaining 23 bits are the index of the return value that can be used in a call to get_parameter_size and get_parameter_section. Otherwise, the call failed and only the forth byte is set. With the value:

1 if the call failed because of insufficient funds.

2 if the account to transfer to did not exist.

3 if the contract to call did not exist.

4 if the entrypoint did not exist on contract to call.

5 if it called a V0 contract that failed.

6 if it called a contract that failed with a runtime error.

Return type

i64

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

concordium.get_receive_entrypoint_size() i32#

Get the size of the entrypoint that was named. See get_receive_entrypoint for more information on the use of this host function.

Returns

The size of the entrypoint that was named.

Return type

i32

concordium.get_receive_entrypoint(start)#

Write the receive entrypoint name into the given location. It is assumed that the location contains enough space to write the name. For regular receive methods, the entrypoint name will always be the same as the receive method’s entrypoint name. But for fallback entrypoints, it might differ.

Parameters

start (i32) – Pointer to the location to put th entrypoint name.