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

Behaviour

  • 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

Definition

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

Example

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

Parameters

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

Return Code

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.