These docs are for v2.0. Click to read the latest docs for v3.0.

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

Behaviour

  • Read a 20 byte Account ID from the aread_ptr
  • Read a 32 byte Hook State key from the kread_ptr
  • Write the data (value) at that key at that Account ID to the buffer pointed to by write_ptr

Definition

int64_t state_foreign (
    uint32_t write_ptr,
    uint32_t write_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  
);

Example

#define SBUF(str) (uint32_t)(str), sizeof(str)
uint8_t ns[32] = {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0};
int64_t lookup =
    state_foreign(SBUF(blacklist_status), SBUF(otxn_accid), SBUF(ns), SBUF(blacklist_accid));
if (lookup < 0)
     rollback(SBUF("Error: could not find key on foreign state."), 1);

Parameters

NameTypeDescription
write_ptruint32_tA pointer to the buffer to write the data in the Hook State into.
write_lenuint32_tThe length of the write buffer.
kread_ptruint32_tPointer to a buffer containing the Hook State key.
kread_lenuint32_tThe length of the Hook State key. (Should be 32.)
nread_ptruint32_tA pointer to the buffer containing the 32 byte Namespace to lookup the state on
nread_lenuint32_tThe length of the namespace buffer (Should be 32).
aread_ptruint32_tA pointer to a buffer containing the 20 byte Account ID to look up state on.
aread_lenuint32_tThe length of the Account buffer. (Should always be 20).

📘

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

TypeDescription
int64_tThe 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.

INVALID_ACCOUNT
- the account specified at aread_ptr is invalid or does not exist.