state_set

Set the Hook State for a given key and value

Behaviour

C

• Read a 32 byte Hook State key from the kread_ptr

• Read an arbitrary amount of data from read_ptr (the value)

• Update the Hook State key with the value

Javascript

• Sets the Hook State with the specified value and key.

• Returns the number of bytes written to Hook State (the length of the data), negative on error.

Definition

C

int64_t state_set (
    uint32_t read_ptr,
    uint32_t read_len,
    uint32_t kread_ptr,
    uint32_t kread_len  
);

Javascript

function state_set(
    value: ByteArray | HexString | undefined | null,
    key: ByteArray | HexString
  ): ErrorCode | number

Example

C

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

📘Hint

To delete the state use state_set(0, 0, SBUF(key);.

Javascript

const result = state_set(vault, vault_key)
if (result < 0)
    rollback("Error: could not set state!", 1);

📘Hint

To delete the state use state_set(null, key);.

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

🚧 Caution

Xahaud sets internally a maximum hook data size. At time of writing and for mainnet this is hard coded at 256 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.

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.

Javascript

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