Module casper_contract::ext_ffi[][src]

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

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

casper_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 casper_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).

casper_add_contract_version

Adds new contract version to a contract package.

casper_blake2b

Returns a 32-byte BLAKE2b hash digest from the given input bytes

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

casper_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

casper_create_contract_package_at_hash

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

casper_create_contract_user_group

Creates new named contract user group under a contract package.

casper_disable_contract_version

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

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

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

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

casper_get_key
casper_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.

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

casper_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).

casper_get_system_contract
casper_has_key
casper_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 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.

casper_load_named_keys
casper_new_uref

This function causes the runtime to generate a new URef, with the provided value stored under it in the global state. The new 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 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.

casper_provision_contract_user_group_uref

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

casper_put_key
casper_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.

casper_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 casper_read_host_buffer function. Returns standard error code.

casper_record_era_info

Records era info. Can only be called from within the auction contract. Needed to support system contract-based execution.

casper_record_transfer

Records a transfer. Can only be called from within the mint contract. Needed to support system contract-based execution.

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

casper_remove_contract_user_group

Removes group from given contract package.

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

casper_remove_key
casper_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 casper_call_contract or casper_call_versioned_contract). Additionally, the known URefs of the calling context are augmented with the 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 URefs are invalid in the current context.

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

casper_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).

casper_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).

casper_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).

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