state

Retrieve the data pointed to by a Hook State key and write it to an output buffer

Behaviour

C

• Read a 32 byte Hook State key from the kread_ptr

• Write the data (value) at that key to the buffer pointed to by write_ptr

Javascript

• Retrieves the Hook State value associated with the specified key.

• Returns an error code or the Hook State value for the key.

Definition

C

int64_t state (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t kread_ptr,
    uint32_t kread_len  
);

Javascript

function state(key: ByteArray | HexString): ErrorCode | ByteArray

Example

C

#define SBUF(str) (uint32_t)(str), sizeof(str)
if (state(SBUF(vault), SBUF(vault_key)) != 16)
    rollback(SBUF("Error: could not read state!"), 1);

Javascript

const value = state(SBUF(vault), SBUF(vault_key))
if (typeof value === 'number' || value.length != 16)
    rollback("Error: could not read state!", 1);

Parameters

C

Name	Type	Description
write_ptr	uint32_t	A pointer to the buffer to write the data in the Hook State into.
write_len	uint32_t	The length of the write buffer.
kread_ptr	uint32_t	Pointer to a buffer containing the Hook State key.
kread_len	uint32_t	The length of the Hook State key. (Should be 32.)

📘Hint

Ensure you check the return value. A state lookup can fail of a range of reasons and the buffer will then contain whatever it did before the call (typically all zeros).

Javascript

Name	Type	Description
key	ByteArray or HexString	The key of the Hook State to retrieve the value from.

Return Code

C

Type

Description

int64_t

The number of bytes written to the write buffer. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. DOESNT_EXIST - the specified Hook State key doesn't have an associated value on the ledger at the time of the call. TOO_BIG - the key specified by read_ptr and read_len was larger than 32 bytes. TOO_SMALL - the output buffer was too small to store the Hook State data.

Javascript

Type	Description
ByteArray or ErrorCode	Returns an error code or the Hook State value for the key.