state_foreign_set

Behaviour

C

• Read a 32 byte Hook State key from the kread_ptr
• Read an arbitrary amount of data from read_ptr (the value)
• Read a 32 byte Namespace from the nread_ptr
• Read a 20 byte Account ID from aread_ptr
• Update the Hook State key on the specified account within the specified namespace with the value
• But only if a Grant on that account allows this.
• If the Hook Account is specified in aread_ptr then the behaviour is that of state_set but still allows specification of namespace through nread_ptr

JavaScript

• Sets the Foreign Hook State with the specified value, key, namespace, and account ID.
• This operation requires authorization and a Grant to allow this action.
• Returns the number of bytes written to Hook State (the length of the data), negative on error.

Definition

C

int64_t state_foreign_set (
    uint32_t read_ptr,
    uint32_t read_len,
    uint32_t kread_ptr,
    uint32_t kread_len,
    uint32_t nread_ptr,
    uint32_t nread_len,
    uint32_t aread_ptr,
    uint32_t aread_len
);

JavaScript

function state_foreign_set(
    value: ByteArray | HexString | undefined | null,
    key: ByteArray | HexString,
    namespace: ByteArray | HexString | undefined | null,
    accountid: ByteArray | HexString | undefined | null
  ): ErrorCode | number

Example

C

#define SBUF(str) (uint32_t)(str), sizeof(str)
if (state_foreign_set(SBUF(vault), SBUF(vault_key), SBUF(namespace), SBUF(account)) < 0)
    rollback(SBUF("Error: could not set foreign state!"), 1);

JavaScript

if (state_foreign_set(vault, vault_key, namespace, account) < 0)
    rollback("Error: could not set foreign state!", 1);

Parameters

C

Name	Type	Description
read_ptr	uint32_t	Pointer to the data (value) to write into Hook State. If this is 0 (null) then delete the data at this key. May be null.
read_len	uint32_t	The length of the data. If this is 0 (null) then delete the data at this key. May be null.
kread_ptr	uint32_t	A pointer to the Hook State key at which to store the value.
kread_len	uint32_t	The length of the key. (Should always be 32.)
nread_ptr	uint32_t	A pointer to the namespace which the key belongs to.
nread_len	uint32_t	The length of the namespace. (Should always be 32.)
aread_ptr	uint32_t	A pointer to the Account ID whose state we are trying to modify.
aread_len	uint32_t	The length of the Account ID. (Should always be 20.)

Caution

Xahau sets internally a maximum hook data size. At time of writing and for public testnet this is hard coded at 128 bytes, however in future it will be a validator-votable number.

JavaScript

Name	Type	Description
value	ByteArray or HexString	The value of data to persist.
key	ByteArray or HexString	The key of the Hook State to set the value for.
namespace	ByteArray or HexString	The Hook namespace to look in.
accountid	ByteArray or HexString	The owner of the state.

Return Code

C

Type

Description

int64_t

The number of bytes written to Hook State (the length of the data.) If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_BIG - kread_len was greater than 32, or - read_len was greater than the maximum hook data size. TOO_SMALL - kread_len was 0. NOT_AUTHORIZED - no appropriate HookGrant was present on the foreign account to allow this state mutation. PREVIOUS_FAILURE_PREVENTS_RETRY - during this execution a previous state_foreign_set failed with NOT_AUTHORIZED, and consequently no further calls to this API are allowed during this execution.

JavaScript

Type	Description
number or ErrorCode	Returns the number of bytes written to Hook State (the length of the data), negative on error.