[][src]Module casperlabs_contract::ext_ffi

Contains low-level bindings for host-side ("external") functions.

Generally should not be used directly. See the contract_api for high-level bindings suitable for writing smart contracts.

Functions

add

This function adds the provided value (read via de-serializing the bytes in wasm memory from offset value_ptr to value_ptr + value_size) to the current value under the provided key (read via de-serializing the bytes in wasm memory from offset key_ptr to key_ptr + key_size) in the global state. This function will cause a Trap if the key or value fail to de-serialize or if adding to that key is not permitted, or no value presently exists at that key.

add_associated_key

This function attempts to add the given public key as an associated key to the current account. Presently only 32-byte keys are supported; it is up to the caller to ensure that the 32-bytes starting from offset public_key represent the key they wish to add. Weights are internally represented by a u8, this function will cause a Trap if the weight is not between 0 and 255 inclusively. The result returned is a status code for adding the key where 0 represents success, 1 means no more keys can be added to this account (only 10 keys can be added), 2 means the key is already associated (if you wish to change the weight of an associated key then used update_associated_key), and 3 means permission denied (this could be because the function was called outside of session code or because the key management threshold was not met by the keys authorizing the deploy).

add_contract_version

Adds new contract version to a contract package.

add_local
call_contract

Calls a contract by its hash. Requires entry point name that has to be present on a specified contract, and serialized named arguments. Returns a standard error code in case of failure, otherwise a successful execution returns zero. Bytes returned from contract execution are set to result_size pointer.

call_versioned_contract

Calls a contract by its package hash. Optionally accepts a serialized Option<u32> as a version that for None case would call most recent version for given protocol version, otherwise it selects a specific contract version. Requires an entry point name registered in a given version of contract. Returns a standard error code in case of failure, otherwise a successful execution returns zero. Bytes returned from contract execution are set to result_size pointer

create_contract_package_at_hash

Creates new contract package at hash. Returns both newly generated casperlabs_types::ContractPackageHash and a casperlabs_types::URef for further modifying access.

create_contract_user_group

Creates new named contract user group under a contract package.

create_purse

This function uses the mint contract to create a new, empty purse. If the call is successful then the casperlabs_types::uref::URef (in serialized form) is written to the indicated place in wasm memory. It is up to the caller to ensure at least purse_size bytes are allocated at purse_ptr, otherwise data corruption may occur. This function causes a Trap if purse_size is not equal to 38.

disable_contract_version

Disables contract in a contract package. Returns non-zero standard error for a failure, otherwise a zero indicates success.

get_balance

This function uses the mint contract's balance function to get the balance of the specified purse. It causes a Trap if the bytes in wasm memory from purse_ptr to purse_ptr + purse_size cannot be de-serialized as a casperlabs_types::uref::URef. The return value is the size of the result in bytes. The result is copied to the host buffer and thus can be obtained by any function which copies the buffer into wasm memory (e.g. get_read). The result bytes are serialized from type Option<U512> and should be interpreted as such.

get_blocktime

This function gets the timestamp which will be in the block this deploy is included in. The return value is always a 64-bit unsigned integer, representing the number of milliseconds since the Unix epoch. It is up to the caller to ensure there are 8 bytes allocated at dest_ptr, otherwise data corruption in the wasm memory may occur.

get_caller

This function returns the public key of the account for this deploy. The result is always 36-bytes in length (4 bytes prefix on a 32-byte public key); it is up to the caller to ensure the right amount of memory is allocated at dest_ptr, data corruption in the wasm memory could occur otherwise.

get_key
get_main_purse
get_named_arg

This function copies the contents of the current runtime buffer into the wasm memory, beginning at the provided offset. It is intended that this function be called after a call to load_arg. It is up to the caller to ensure that the proper amount of memory is allocated for this write, otherwise data corruption in the wasm memory may occur due to this call overwriting some bytes unintentionally. The size of the data which will be written is returned from the load_arg call. The bytes which are written are the those corresponding to the provided argument; it is up to the developer to know how to attempt to interpret those bytes.

get_named_arg_size

This function queries the host side to check for given named argument existence and returns a size in bytes of given argument. Returns zero for success or non-zero value for failure as described in standard error codes.

get_phase

This function writes bytes representing the current phase of the deploy execution to the specified pointer. The size of the result is always one byte, it is up to the caller to ensure one byte of memory is allocated at dest_ptr, otherwise data corruption in the wasm memory could occur. The one byte is interpreted as follows: 0 means a system phase (should never be encountered by user deploys), 1 means the payment phase, 2 means the session phase and 3 means the finalization phase (should never be encountered by user code).

get_system_contract
has_key
is_valid_uref

This function checks if all the keys contained in the given Value are valid in the current context (i.e. the Value does not contain any forged casperlabs_types::uref::URefs). This function causes a Trap if the bytes in wasm memory from offset value_ptr to value_ptr + value_size cannot be de-serialized as type Value.

load_named_keys
new_uref

This function causes the runtime to generate a new casperlabs_types::uref::URef, with the provided value stored under it in the global state. The new casperlabs_types::uref::URef is written (in serialized form) to the wasm linear memory starting from the key_ptr offset. Note that data corruption is possible if not enough memory is allocated for the casperlabs_types::uref::URef at key_ptr. This function will cause a Trap if the bytes in wasm memory from offset value_ptr to value_ptr + value_size cannot be de-serialized into a Value.

provision_contract_user_group_uref

Requests host to provision additional casperlabs_types::URef to a specified group identified by its label. Returns standard error code for non-zero value, otherwise zero indicated success.

put_key
read_host_buffer

This function copies the contents of the current runtime buffer into the wasm memory, beginning at the provided offset. It is intended that this function be called after a call to a function that uses host buffer. It is up to the caller to ensure that the proper amount of memory is allocated for this write, otherwise data corruption in the wasm memory may occur due to this call overwriting some bytes unintentionally. The size of the data which will be written is stored on the host. The bytes which are written are those corresponding to the value returned by the called contract; it is up to the developer to know how to attempt to interpret those bytes.

read_value

The bytes in the span of wasm memory from key_ptr to key_ptr + key_size must correspond to a valid global state key, otherwise the function will fail. If the key is de-serialized successfully, then the result of the read is serialized and buffered in the runtime. This result can be obtained via the read_host_buffer function. Returns standard error code.

read_value_local

The bytes in wasm memory from offset key_ptr to key_ptr + key_size will be used together with the current context’s seed to form a local key. The value at that local key is read from the global state, serialized and buffered in the runtime. This result can be obtained via the read_host_buffer function.

remove_associated_key

This function attempts to remove the given public key from the associated keys of the current account. Presently only 32-byte keys are supported; it is up to the caller to ensure that the 32-bytes starting from offset public_key represent the key they wish to remove. The result returned is a status code for adding the key where 0 represents success, 1 means the key was not associated to begin with, 2 means means permission denied (this could be because the function was called outside of session code or because the key management threshold was not met by the keys authorizing the deploy), and 3 means this key cannot be removed because otherwise it would be impossible to meet either the deploy or key management thresholds.

remove_contract_user_group

Removes group from given contract package.

remove_contract_user_group_urefs

Removes user group urefs. Accepts a contract package hash, label name of a group, and a list of urefs that will be removed from the group.

remove_key
ret

This function causes a Trap, terminating the currently running module, but first copies the bytes from value_ptr to value_ptr + value_size to a buffer which is returned to the calling module (if this module was invoked by call_contract or call_versioned_contract). Additionally, the known casperlabs_types::uref::URefs of the calling context are augmented with the casperlabs_types::uref::URefs de-serialized from wasm memory offset extra_urefs_ptr to extra_urefs_ptr + extra_urefs_size. This function will cause a Trap if the bytes at extra_urefs_ptr cannot be de-serialized as type Vec<URef>, or if any of the extra casperlabs_types::uref::URefs are invalid in the current context.

revert

This function causes a Trap which terminates the currently running module. Additionally, it signals that the current entire phase of execution of the deploy should be terminated as well, and that the effects of the execution up to this point should be reverted. The error code provided to this function will be included in the error message of the deploy in the block in which it is included.

set_action_threshold

This function changes the threshold to perform the specified action. The action index is interpreted as follows: 0 means deployment and 1 means key management. Thresholds are represented internally as a u8, this function will cause a Trap if the new threshold is not between 0 and 255 inclusively. The return value is a status code where 0 means success, 1 means the key management threshold cannot be set lower than the deploy threshold, 2 means the deployment threshold cannot be set higher than the key management threshold, 3 means permission denied (this could be because the function was called outside of session code or because the key management threshold was not met by the keys authorizing the deploy), and 4 means the threshold would be set higher than the total weight of associated keys (and therefore would be impossible to meet).

transfer_from_purse_to_account

This function uses the mint contract’s transfer function to transfer tokens from the specified purse to the main purse of the target account. If the target account does not exist then it is automatically created, and the tokens are transferred to the main purse of the new account. The source is a serialized casperlabs_types::uref::URef. The target is a serialized PublicKey (i.e. 36 bytes where the first 4 bytes are the number 32 in little endian encoding, and the remaining 32-bytes are the public key). The amount must be a serialized 512-bit unsigned integer. This function causes a Trap if the source cannot be de-serialized as a casperlabs_types::uref::URef, or the target cannot be de-serialized as a PublicKey or the amount cannot be de-serialized into a U512. The return value indicated what occurred, where 0 means a successful transfer to an existing account, 1 means a successful transfer to a new account, and 2 means the transfer failed (this could be because the source purse had insufficient tokens or because there was not valid access to the source purse).

transfer_from_purse_to_purse

This function uses the mint contract’s transfer function to transfer tokens from the specified source purse to the specified target purse. If the target account does not exist then it is automatically created, and the tokens are transferred to the main purse of the new account. The source is a serialized casperlabs_types::uref::URef. The target is also a serialized casperlabs_types::uref::URef. The amount must be a serialized 512-bit unsigned integer. This function causes a Trap if the source or target cannot be de-serialized as a casperlabs_types::uref::URef or the amount cannot be de-serialized into a U512. The return value indicated what occurred, where 0 means a successful transfer, 1 means the transfer failed (this could be because the source purse had insufficient tokens or because there was not valid access to the source purse or target purse).

transfer_to_account

This function uses the mint contract’s transfer function to transfer tokens from the current account’s main purse to the main purse of the target account. If the target account does not exist then it is automatically created, and the tokens are transferred to the main purse of the new account. The target is a serialized PublicKey (i.e. 36 bytes where the first 4 bytes are the number 32 in little endian encoding, and the remaining 32-bytes are the public key). The amount must be a serialized 512-bit unsigned integer. This function causes a Trap if the target cannot be de-serialized as a PublicKey or the amount cannot be de-serialized into a U512. The return value indicated what occurred, where 0 means a successful transfer to an existing account, 1 means a successful transfer to a new account, and 2 means the transfer failed (this could be because the current account’s main purse had insufficient tokens or because the function was called outside of session code and so does not have access to the account’s main purse).

update_associated_key

This function attempts to update the given public key as an associated key to the current account. Presently only 32-byte keys are supported; it is up to the caller to ensure that the 32-bytes starting from offset public_key represent the key they wish to add. Weights are internally represented by a u8, this function will cause a Trap if the weight is not between 0 and 255 inclusively. The result returned is a status code for adding the key where 0 represents success, 1 means the key was not associated to the account (to add a new key use add_associated_key), 2 means means permission denied (this could be because the function was called outside of session code or because the key management threshold was not met by the keys authorizing the deploy), and 3 means this key cannot be changed to the specified weight because then it would be impossible to meet either the deploy or key management thresholds (you may wish to try again with a higher weight or after lowering the action thresholds).

write

This function writes the provided value (read via de-serializing the bytes in wasm memory from offset value_ptr to value_ptr + value_size) under the provided key (read via de-serializing the bytes in wasm memory from offset key_ptr to key_ptr + key_size) in the global state. This function will cause a Trap if the key or value fail to de-serialize or if writing to that key is not permitted.

write_local

The bytes in wasm memory from offset key_ptr to key_ptr + key_size will be used together with the current context’s seed to form a local key. This function writes the provided value (read via de-serializing the bytes in wasm memory from offset value_ptr to value_ptr + value_size) under that local key in the global state. This function will cause a Trap if the value fails to de-serialize.