1 of 5

State

state

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.

state_set

Set the Hook State for a given key and value

Behaviour

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

Definition

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

Example

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

Parameters

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

Return Code

Type

Description

int64_t

state_foreign

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

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

nread_ptr

uint32_t

A pointer to the buffer containing the 32 byte Namespace to lookup the state on

nread_len

uint32_t

The length of the namespace buffer (Should be 32).

aread_ptr

uint32_t

A pointer to a buffer containing the 20 byte Account ID to look up state on.

aread_len

uint32_t

The 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

Type

Description

int64_t

state_foreign_set

Set the Hook State on another account for a given key, value and namespace

Behaviour

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

Definition

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

Example

#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);

Parameters

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

Return Code

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.

state_foreign

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

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

nread_ptr

uint32_t

A pointer to the buffer containing the 32 byte Namespace to lookup the state on

nread_len

uint32_t

The length of the namespace buffer (Should be 32).

aread_ptr

uint32_t

A pointer to a buffer containing the 20 byte Account ID to look up state on.

aread_len

uint32_t

The 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

Type

Description

int64_t

state_foreign_set

Set the Hook State on another account for a given key, value and namespace

Behaviour

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

Definition

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

Example

#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);

Parameters

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

Return Code

Type

Description

int64_t

state_set

Set the Hook State for a given key and value

Behaviour

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

Definition

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

Example

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

Parameters

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

Return Code

Type

Description

int64_t