Module casper_contract::ext_ffi
source · [−]Expand description
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
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.
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).
Adds new contract version to a contract package.
Returns a 32-byte BLAKE2b hash digest from the given input bytes
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.
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
Creates new contract package at hash. Returns both newly generated
casper_types::ContractPackageHash
and a casper_types::URef
for further
modifying access.
Creates new named contract user group under a contract package.
This function uses the mint contract to create a new, empty purse. If the
call is successful then the 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.
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 dictionary.
The value at that dictionary is read from the global state, serialized and
buffered in the runtime. This result can be obtained via the casper_read_host_buffer
function.
The bytes in wasm memory from offset key_ptr
to key_ptr + key_size
will be used together with the passed URef’s seed to form a dictionary.
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 dictionary in the global state. This function will cause a Trap
if
the value fails to de-serialize.
Disables contract in a contract package. Returns non-zero standard error for a failure, otherwise a zero indicates success.
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.
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.
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.
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.
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.
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).
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
URef
s). 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
.
Creates new URef that points to a dictionary partition of global state.
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
.
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.
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.
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.
Records era info. Can only be called from within the auction contract. Needed to support system contract-based execution.
Records a transfer. Can only be called from within the mint contract. Needed to support system contract-based execution.
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.
Removes group from given contract package.
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.
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 URef
s of the calling context are augmented with the
URef
s 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 URef
s are invalid in the current
context.
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.
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).
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 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 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).
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 URef
.
The target is also a serialized 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 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).
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).
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).
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.