1 of 95

📐 Hooks C-Functions

Overview

Hook API Conventions

Naming conventions

All Hook APIs follow a standard naming convention:

namespace

[ _ noun #1 ]

[ _ verb ]

[ _ noun #2 ]

This may look confusing at first but is actually quite simple:

If the first noun is missing then it is implicitly the same as the namespace
If the verb is missing then it is implicitly get

Thus:

state() means: fetch a hook state.
state_set() means: set a hook.
state_foreign() means: fetch a foreign hook state.

Memory model

Each Hook executes as a singular stack frame. All working memory must exist within this stackframe. There is no heap and no dynamic memory.

When Hooks communicate with xahaud they can only pass integer values. Typically these integers are pointers within the Hook's memory. Since the Hook runs within xahaud, these points can then be resolved by xahaud and written to or read from as needed to perform the Hook API function.

Allowed functions

Only two functions are allowed within a Hook: hook() and cbak(). Read about this here

Parameters

All parameters passed to a Hook API must be one of: uint32_t, int32_t, uint64_t, int64_t. Typically these are pointers and lengths of buffers within the Hook's stack frame. Sometimes they are Integer Encoded Floating Point Numbers (XFL) or other data.

The parameters to a Hook API are always in the following order:

Writing pointer if any
Writing length if any
Reading pointer if any
Reading length if any
Specifics / other fields if any

Some Hook APIs may only write or may only read from memory, and some might not do either and return a value only by return code.

Return codes

All Hook APIs return a signed integer. Read about return codes here: Return codes

Return Codes

Return code design

Web assembly allows for exceptions (traps) however this language feature is not used for Hooks. Instead there is only one way to return from any Hook API (you may think of every Hook API as being noexcept).

To provide for efficient error handling:

All Hook API functions return a signed integer.
All negative return codes are an error.
All return codes 0 or greater are a function specific output, usually but not always the number of bytes read or written.

Error codes

Error codes are global across all Hook APIs and may be found in the table below.

Name

Value

Description

SUCCESS

>= 0

Non-negative return codes refer always to success and usually indicate the number of bytes written or events performed, depending on the specific API.

OUT_OF_BOUNDS

-1

A pointer or buffer length provided as a parameter described memory outside of the Hook's allowed memory region.

INTERNAL_ERROR

-2

Reserved for internal invariant trips, generally unrelated to inputs. These should be reported with an issue.

TOO_BIG

-3

Attempted to set a parameter or value larger than the allowed space.

TOO_SMALL

-4

The API was unable to produce output to the write_ptr because the specified write_len was too small.

DOESNT_EXIST

-5

The requested object or item wasn't found.

NO_FREE_SLOTS

-6

The Hook attempted to allocate an item into a slot, but there were no slots free. To avoid ensure re-use of existing slots. The maximum number of slots is 255.

INVALID_ARGUMENT

-7

One or more of the parameters to the API were invalid according to the individual API's specification.

ALREADY_SET

-8

Some APIs allow for a once-per-execution parameter to be set. A second attempt to set a once-per-execution parameter results in this error.

PREREQUISITE_NOT_MET

-9

An API required the Hook to do something before the API is allowed to be called. Check the API's documentation.

FEE_TOO_LARGE

-10

During fee calculation if an absurdly large fee is calculated this error is returned.

EMISSION_FAILURE

-11

An attempt to emit() a TXN was unsccessful for any of a number of reasons. Check the trace log of the rippled to which you are submitting the originating TXN.

TOO_MANY_NONCES

-12

A Hook may only use up to 256 calls to nonce() per execution. Further calls result in this error code.

TOO_MANY_EMITTED_TXN

-13

A Hook must declare ahead of time how many TXN it intends to emit(). If it emits fewer than this many, this is allowed. If it emits more than this many this error is returned.

NOT_IMPLEMENTED

-14

While Hooks is/was in development an API may return this if some or all of that API is planned but not yet implemented.

INVALID_ACCOUNT

-15

An API which accepts a 20 byte Account ID may return this if, in its opinion, the Account ID was not valid for any reason.

GUARD_VIOLATION

-16

All loops inside a Hook must declare at the top of the loop, as the first non trivial instruction, before any branch instruction, the promised maximum number of iterations of the loop. If this promise is violated the hook terminates immediately with this error code.

INVALID_FIELD

-17

The requested serialized field could not be found in the specified object.

PARSE_ERROR

-18

While parsing serialized content an error was encountered (typically indicating an invalidly serialized object).

RC_ROLLBACK

-19

Used internally to communicate a rollback event.

RC_ACCEPT

-20

Used internally to communicate an accept event.

NO_SUCH_KEYLET

-21

Specified keylet could not be found, or keylet is invalid

NOT_AN_ARRAY

-22

API was asked to assume object under analysis is an STArray but it was not.

NOT_AN_OBJECT

-23

API was asked to assume object under analysis is an STObject but it was not.

INVALID_FLOAT

-10024

A floating point operation resulted in Not-A-Number or API call attempted to specify an XFL floating point number outside of the expressible range of XFL.

DIVISION_BY_ZERO

-25

API call would result in a division by zero, so API ended early.

MANITSSA_OVERSIZED

-26

When attempting to create an XFL the mantissa must be 16 decimal digits.

MANTISSA_UNDERSIZED

-27

When attempting to create an XFL the mantissa must be 16 decimal digits.

EXPONENT_OVERSIZED

-28

When attempting to create an XFL the exponent must not exceed 80.

EXPONENT_UNDERSIZED

-29

When attempting to create an XFL the exponent must not be less than -96.

OVERFLOW

-30

A floating point operation done on an XFL resulted in a value larger than XFL format is able to represent.

NOT_IOU_AMOUNT

-31

An API assumed an STAmount was an IOU when in fact it was XRP.

NOT_AN_AMOUNT

-32

An API assumed an STObject was an STAmount when in fact it was not.

CANT_RETURN_NEGATIVE

-33

An API would have returned a negative integer except that negative integers are reserved for error codes (i.e. what you are reading.)

NOT_AUTHORIZED

-34

Hook attempted to set foreign state but was not authorized to do so (grant was missing or invalid.)

PREVIOUS_FAILURE_PREVENTS_RETRY

-35

Hook previously received a NOT_AUTHORIZED return code and is not allowed to retry.

TOO_MANY_PARAMS

-36

Attempted to set a hook parameter for a later hook in the chain, but there are now too many parameters.

INVALID_TXN

-37

Serialized transaction was not a valid transaction (usually because of a missing required field or data corruption / truncation.)

RESERVE_INSUFFICIENT

-38

Setting an additional state object on this account would cause the reserve requirements to exceed the account's balance.

COMPLEX_NOT_SUPPORTED

-39

Hook API would be forced to return a complex number, which it cannot do.

DOES_NOT_MATCH

-40

Two arguments were required to be of the same type but are not.

INVALID_KEY

-41

The provided public key was not valid.

NOT_A_STRING

-42

The buffer did not contain a nul terminated string.

MEM_OVERLAP

-43

The writing pointer points to a buffer that overlaps with the reading pointer.

TOO_MANY_STATE_MODIFICATIONS

-44

More than 5000 modified state entries in the combined hook chains

TOO_MANY_NAMESPACES

-45

More than 256 namespaces on this account

Developer Defined

hook

The main function of your hook

Concepts

Compiling Hooks

Behaviour

hook is a user defined function called by xahaud in order to fire your hook.
Your hook function calls either accept or reject to pass or reject the originating transaction.
If execution reaches the end of the function it is implicitly an accept.

Definition

int64_t hook (
    uint32_t reserved
)

Example

int64_t hook(uint32_t reserved)
{
  return 0;
}

Parameters

Name

Type

Description

reserved

uint32_t

Reserved for future use.

Return Code

Type

Description

int64_t

An arbitrary return code you wish to return from your hook. This will be present in the metadata of the originating transaction.

cbak

The callback function of your hook

Concepts

Compiling Hooks

Behaviour

cbak is a user defined function called by xahaud in order to inform your hook about the status of a previously emitted transaction
State changes and further emit calls can be made from cbak but it cannot rollback a transaction.
When cbak is executed the emitted transaction to which the callback relates is now the originating transaction.

Definition

int64_t cbak (
    uint32_t what
)

Example

int64_t cbak(uint32_t what)
{
    return 0;
}

Parameters

Name

Type

Description

what

uint32_t

if 0: - the emittted transaction to which this callback relates was successfully accepted into a ledger. If 1 - the emitted transaction to which the callback relates was NOT successfully accepted into a ledger before it expired.

Return Code

Type

Description

int64_t

An arbitrary return code you wish to return from your hook. This will be present in the metadata of the originating transaction.

Control

accept

Accept the originating transaction and commit any changes the hook made.

Concepts

Introduction
Execution Order

Behaviour

End the execution of the hook with status: success.

Record a return string and return code in transaction metadata.
Commit all state changes.
Submit all emit() transactions.
Allow originating transaction to continue.

🚧Caution
If the originating transaction is stopped for some other reason then this accept becomes a rollback. See: Execution Order.

Definition

int64_t accept (
    uint32_t read_ptr,
    uint32_t read_len,
    uint64_t error_code
);

Example

accept("Success", 7, 100);

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to a return string to be stored in execution metadata. This is any string the hook-developer wishes to return with the acceptance. May be null.

read_len

uint32_t

The length of the return string. At most 32. May be null.

error_code

uint64_t

A return code specific to this hook to be stored in execution metadata. Similar to the return code of an application on a *nix system. By convention success is zero.

Return Code

Type

Description

int64_t

Accept ends the hook, therefore no value is returned to the caller. By convention all Hook APIs return int64_t, but in this case nothing is returned.

rollback

Concepts

Introduction
Execution Order

Behaviour

End the execution of the hook with status: reject.

Record a return string and return code in transaction metadata.
Discard all state changes.
Discard all emit() transactions.
Disallow originating transaction to continue.

❗️Warning
The originating transaction will fail with tecHOOK_REJECTED and a fee will be charged. See: Execution Order.

Definition

int64_t rollback (
    uint32_t read_ptr,
    uint32_t read_len,
    uint64_t error_code
);

Example

rollback("Rejected!", 9, 100);

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to a return string to be stored in execution metadata. This is any string the hook-developer wishes to return with the acceptance. May be null.

read_len

uint32_t

The length of the return string. At most 32. May be null.

error_code

uint64_t

A return code specific to this hook to be stored in execution metadata. Similar to the return code of an application on a *nix system. By convention non-success is non-zero.

Return Code

Type

Description

int64_t

Rollback ends the hook, therefore no value is returned to the caller. By convention all Hook APIs return int64_t, but in this case nothing is returned.

Utilities

util_raddr

Convert a 20 byte Account ID to an r-address

Behaviour

Read a 20 byte Account ID from the read_ptr
Write the equivalent r-address for that Account ID to write_ptr

Definition

int64_t util_raddr (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len
);

Example

uint8_t raddr_out[40];
uint8_t acc_id[20] =
{
    0x2dU, 0xd8U, 0xaaU, 0xdbU, 0x4eU, 0x15U,               
    0xebU, 0xeaU,  0xeU, 0xfdU, 0x78U, 0xd1U, 0xb0U,
    0x35U, 0x91U,  0x4U, 0x7bU, 0xfaU, 0x1eU,  0xeU
};
int64_t bytes_written = 
    util_raddr(raddr_out, sizeof(raddr_out), acc_id, 20);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the output r-address. Recommend at least 35 bytes.

write_len

uint32_t

Length of the output buffer.

read_ptr

uint32_t

Pointer to the Account ID.

read_len

uint32_t

The length of the input. Always 20.

Return Code

Type

Description

int64_t

util_accid

Convert an r-address into a 20 byte Account ID

Behaviour

Read an r-address from the read_ptr
Write a 20 byte Account ID to the write_ptr

Definition

int64_t util_accid (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len
);

Example

uint8_t accid_out[20];
uint8_t raddr_in[] = "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh";

int64_t bytes_written = 
    util_accid(accid_out, 20, raddr_in, sizeof(raddr_in)-1);
// NB: if specified as a c-string as above, account for the nul char

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the output Account ID. Must be at least 20 bytes.

write_len

uint32_t

Length of the output buffer.

read_ptr

uint32_t

Pointer to the r-address.

read_len

uint32_t

The length of the r-address.

Return Code

Type

Description

int64_t

The number of bytes written (the length of the output r-address). If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. INVALID_ARGUMENT - read_ptr pointed at something which wasn't a valid r-address. TOO_SMALL - write_len was not large enough to store produced Account ID. (Should be 20 bytes). TOO_BIG - read_len was longer than an r-address can be.

util_verify

Verify a cryptographic signature

Behaviour

Verify a cryptographic signature

If the public key is prefixed with 0xED then use ED25519
Otherwise assume SECP256k1

Definition

int64_t util_verify (
    uint32_t dread_ptr,
    uint32_t dread_len,
    uint32_t sread_ptr,
    uint32_t sread_len,
    uint32_t kread_ptr,
    uint32_t kread_len
);

Example

if (!util_verify(payload_ptr,    payload_len,
                 signature_ptr,  signature_len,
                 publickey_ptr,  publickey_len))
	rollback("Invalid Signature", 17, 60);

Parameters

Name

Type

Description

dread_ptr

uint32_t

Pointer to the signed data

dread_len

uint32_t

Length of the signed data

sread_ptr

uint32_t

Pointer to the signature

sread_len

uint32_t

Length of the signature

kread_ptr

uint32_t

Pointer to the public key

kread_len

uint32_t

Length of the public key

Return Code

Type

Description

int64_t

0 - validation failed, the signature is invalid. 1 - validation succeeded, the signature is valid. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory.

util_sha512h

Compute an sha512-half over some data

Behaviour

Compute an SHA512 hash over the data pointed to by read_ptr
Write the first half of the hash to write_ptr

Definition

int64_t util_sha512h (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len
);

Example

uint8_t hash_out[32];
if (util_sha512h(hash_out, 32, data_in_ptr, data_in_len) < 0)
	rollback("Could not generate Hash", 23, 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer the hash will be written to

write_len

uint32_t

Length of output buffer, should be at least 32.

read_ptr

uint32_t

Pointer to the buffer data will be read from (to compute the hash over)

read_len

uint32_t

Length of input data

Return Code

Type

Description

int64_t

The number of bytes written, should always be 32. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Output buffer isn't large enough

util_keylet

Compute a serialized keylet of a given type

Concepts

Slots and Keylets

📘Tip
Not every Keylet type is supported by this utility function. If you need another Keylet type you can derive it yourself using util_sha512h and by checking the required fields here. A further Keylet tool may assist you.

Behaviour

Compute a keylet of the specified keylet_type according to the parameters a through f depending on type.
Write the serialized 34 byte keylet into write_ptr

Definition

int64_t util_keylet (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t keylet_type,
    uint32_t a,
    uint32_t b,
    uint32_t c,
    uint32_t d,
    uint32_t e,
    uint32_t f
);

Example

uint8_t keylet[34];
if (util_keylet(keylet, 34, KEYLET_LINE,
              hook_accid, 20,
              account_field, 20,
              currency_code, 20) != 34)
	rollback("Keylet Failed.", 14, 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer the serialized keylet will be written to

write_len

uint32_t

Length of output buffer, should be at least 34.

keylet_type

uint32_t

One of the keylet types as defined in hookapi.h e.g. KEYLET_LINE for a trustline.

uint32_t

See keylet table below

uint32_t

See keylet table below

uint32_t

See keylet table below

uint32_t

See keylet table below

uint32_t

See keylet table below

uint32_t

See keylet table below

Keylet Table

Keylet Type

Parameters

KEYLET_HOOK_STATE

a points to an Account ID b is the length of the Account ID (should be 20) c points to a hook state key d is the length of the key (should be 32) e points to a hook state namespace f is the length of the namespace (should be 32)

KEYLET_AMENDMENTS KEYLET_FEES KEYLET_NEGATIVE_UNL KEYLET_EMITTED_DIR

a, b, c, d, e, f must all be zero

KEYLET_SKIP

Either: a, b, c, d, e, f all zero Or: a is a LedgerIndex b is 1 c, d, e, f must all be zero

KEYLET_LINE

a points to the High Account ID b is the length of the above (should be 20) c points to the Low Account ID d is the length of the above (should be 20) e points to the Currency Code f is the length of the above (should be 20)

KEYLET_QUALITY

a points to a serialized keylet b is the length of the above (should be 34) c is the high 32 bits of the uint64 to pass d is the low 32 bits of the uint64 to pass e, f must all be zero

KEYLET_DEPOSIT_PREAUTH

a points to an Account ID b is the length (should be 20) c points to an Account ID d is the length (should be 20) e, f must all be zero

KEYLET_UNCHECKED KEYLET_CHILD KEYLET_EMITTED_TXN

a points to a key. b is the length of the key (should be 32.) c, d, e, f must both be zero

KEYLET_OWNER_DIR KEYLET_SIGNERS KEYLET_ACCOUNT KEYLET_HOOK

a points to an Account ID. b is the length (should be 20.) c, d, e, f must all be zero.

KEYLET_PAGE

a points to a key. b is the length of the key (should be 32.) c is the high 32 bits of the uint64 to pass d is the low 32 bits of the uint64 to pass e, f must both be zero

KEYLET_OFFER KEYLET_CHECK KEYLET_ESCROW KEYLET_NFT_OFFER

a points to an Account ID. b is the length (should be 20.) And Either: c is a 32bit unsigned integer (sequence) d is 0 Or: c points to a 32 byte key d is the length of the key (32). In both cases: e and f must be 0.

KEYLET_PAYCHAN

a points to an Account ID b is the length (should be 20) c points to an Account ID d is the length (should be 20) And Either: e 32bit unsigned int to pass f is zero Or: e points to a 32 byte key f is the length of the key (32)

Return Code

Type

Description

int64_t

The number of bytes written, should always be 34. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. INVALID_ARGUMENT - Call didn't comply with the above table. TOO_SMALL - Writing buffer was smaller than 34 bytes.

Serialization

sto_subfield

Index into a xahaud serialized object and return the location and length of a subfield

Concepts

Serialized Objects

Behaviour

Parse a STObject pointed to by read_ptr
Find the field specified by field_id
If the field is found, and:
1. It is an array, then return the start and length of the array including the leadin/leadout bytes, or
1. It is not an array, then return the start and length of the PAYLOAD of the field (excluding the leadin bytes).

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Definition

int64_t sto_subfield (
    uint32_t read_ptr,
  	uint32_t read_len,
  	uint32_t field_id
);

Example

#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))
int64_t memo_lookup =
    sto_subfield(memo_ptr, memo_len, sfMemo);
if (memo_lookup < 0)
{
    // sfMemo was not found in the STObject pointed at by memo_ptr
}
else
{
    // sfMemo was found and its location is as follows:
	  uint8_t* memo_ptr = SUB_OFFSET(memo_lookup) + memo_ptr;
	  int64_t  memo_len = SUB_LENGTH(memo_lookup);
}

📘
hookmacro.h already contains the SUB_OFFSET and SUB_LENGTH macros.

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to the buffer containing the STObject

read_len

uint32_t

Length of STObject

field_id

uint32_t

The sf code of the field you are searching for. To compute this manually take the serialized type and shift it into the 16 highest bits of uint32_t, then take the field and place it in the 16 lowest bits. For example: sfEmitNonce has type 5 and field 11 thus its value is 0x050BU

Return Code

Type

Description

int64_t

The location of the field within the specified buffer: - The high 32 bits are the offset location. - The low 32 bits are the length. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Input buffer isn't large enough to possibly contain a valid STObject. DOESNT_EXIST - The searched for field isn't present in the supplied STObject. PARSE_ERROR - The supplied STObject is malformed or not an STObject.

sto_subarray

Index into a xahaud serialized array and return the location and length of an index

Concepts

Serialized Objects

Behaviour

Parse a STArray pointed to by read_ptr
Find the array index specified by array_id
Return the byte offset and length of the serialized field within the STObject, if it is found

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.
In the case of this array field ID is array_id.

Definition

int64_t sto_subfield (
    uint32_t read_ptr,
  	uint32_t read_len,
  	uint32_t array_id
);

Example

#define SUB_OFFSET(x) ((int32_t)(x >> 32))
#define SUB_LENGTH(x) ((int32_t)(x & 0xFFFFFFFFULL))

  int64_t memo_lookup =
    sto_subarray(memos, memos_len, 0);

if (memo_lookup < 0)
{
    // sfMemo was not found in the STObject pointed at by memo_ptr
}
else
{
    // 0th index of the STArray was found and its location is as follows:
    uint8_t*  memo_ptr = SUB_OFFSET(memo_lookup) + memos;
    uint32_t  memo_len = SUB_LENGTH(memo_lookup);
}

📘
hookmacro.h already contains the SUB_OFFSET and SUB_LENGTH macros.

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to the buffer containing the STArray

read_len

uint32_t

Length of STArray

array_id

uint32_t

The index of the entry within the STArray you are seeking. Starts from 0.

Return Code

Type

Description

int64_t

The location of the field within the specified buffer: - The high 32 bits are the offset location. - The low 32 bits are the length. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Input buffer isn't large enough to possibly contain a valid STArray. DOESNT_EXIST - The searched for index isn't present in the supplied STArray. PARSE_ERROR - The supplied STArray is malformed or not an STArray.

sto_emplace

Emplace a field into an existing STObject at its canonical placement

Concepts

Serialized Objects

Behaviour

Parse an STObject S (source object) pointed to by sread_ptr
Parse an STObject F (to inject/emplace) pointed to by fread_ptr
Write a new STObject to write_ptr which places F into S at the canonical position field_id

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Definition

int64_t sto_emplace (
    uint32_t write_ptr,
  	uint32_t write_len,
    uint32_t sread_ptr,
    uint32_t sread_len,
    uint32_t fread_ptr,
    uint32_t fread_len,
  	uint32_t field_id
);

Example

uint8_t tx_out[1024];

int64_t tx_len =
    sto_emplace(tx_out, sizeof(tx_out),
                tx_in, tx_len,
                sequence_field, 5, sfSequence);

if (tx_len <= 0)
    rollback("Emplacing failed.", 17, 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

The buffer to write the modified STObject to

write_len

uint32_t

The length of the output buffer

sread_ptr

uint32_t

The buffer to read the source STObject from

sread_len

uint32_t

The Length of the source object

fread_ptr

uint32_t

The buffer to read the field to be emplaced/injected from

fread_len

uint32_t

The length of the field to be emplaced/injected

field_id

uint32_t

The sf code (location) to form the emplacement. If this already exists in the source object then the existing field is overriden. If it doesn't exist it is inserted.

Return Code

Type

Description

int64_t

The number of bytes written to write_ptr If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Output buffer must be at least as large as the source object + the injected field, even if the field is only being overriden. TOO_BIG - Field you are attempting to emplace is too large PARSE_ERROR - The supplied STObject is malformed or not an STObject.

sto_erase

Remove a field from an STObject

Concepts

Serialized Objects

Behaviour

Parse an STObject pointed to by read_ptr
Write a new STObject to write_ptr but without field_id if it was present in the original object.

Definition

int64_t sto_erase (
    uint32_t write_ptr,
  	uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len,
  	uint32_t field_id
);

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Example

int64_t result = 
  sto_erase(tx_out, sizeof(tx_out),
            tx_in, tx_len, sfSigners);

if (tx_len <= 0)
    rollback("Erasing failed.", 15, 1);

📘Emplace equivalence
sto_erase is the same as sto_emplace with 0,0 for field_ptr, field_len parameters.

Parameters

Name

Type

Description

write_ptr

uint32_t

The buffer to write the modified STObject to

write_len

uint32_t

The length of the output buffer

read_ptr

uint32_t

The buffer to read the source STObject from

read_len

uint32_t

The Length of the source object

field_id

uint32_t

The sf code (location) to erase

Return Code

Type

Description

int64_t

The number of bytes written to write_ptr If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Output buffer must be at least as large as the source object. TOO_BIG - Field you are attempting to erase from is too large PARSE_ERROR - The supplied STObject is malformed or not an STObject. DOESNT_EXIST - The specified field_id isn't present in the STObject.

sto_validate

Validate an STObject

Concepts

Serialized Objects

Behaviour

Parse an STObject pointed to by read_ptr
Return 1 if the serialization is valid, 0 otherwise.

Definition

int64_t sto_validate (
    uint32_t read_ptr,
    uint32_t read_len
);

Example

int64_t result = 
  sto_validate(tx_out, sizeof(tx_out));

if (tx_len <= 0)
    rollback("Invalid STO.", 12, 1);

Parameters

Name

Type

Description

read_ptr

uint32_t

The buffer to read the source STObject from

read_len

uint32_t

The Length of the source object

Return Code

Type

Description

int64_t

1 if the STObject pointed to by read_ptr is a valid STObject. 0 if it isn't. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory.

Emitted Transaction

etxn_burden

Get the burden of a hypothetically emitted transaction

Concepts

Emitted Transactions

Behaviour

Return the burden an emitted transaction will carry.

Definition

int64_t etxn_burden (
    void
);

Example

int64_t burden = 
  etxn_burden();

Parameters

None

Return Code

Type

Description

int64_t

The burden an emitted transaction will need in order to be successfully passed to emit()

etxn_details

Produce an sfEmitDetails suitable for a soon-to-be emitted transaction

Concepts

Emitted Transactions

Behaviour

Generate and write a 105 byte sfEmitDetails object into the write_ptr if cbak is not defined
Generate and write a 127 byte sfEmitDetails object into the write_ptr if cbak is defined.

Definition

int64_t etxn_details (
    uint32_t write_ptr,
  	uint32_t write_len
);

Example

uint8_t emitdet[105];
int64_t result =
    etxn_details(emitdet, 105);
if (result != 105)
    rollback("Etxndetails failed.", 19, 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to the buffer receiving the sfEmitDetails record

write_len

uint32_t

Length of the buffer

Return Code

Type

Description

int64_t

The number of bytes written. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL - Buffer isn't large enough to receive record PREREQUISITE_NOT_MET - The hook failed to call etxn_reserve(n) first FEE_TOO_LARGE - The burden would be too high for the network to allow. INTERNAL_ERROR - A generic error in which rippled had trouble generating the required field.

etxn_fee_base

🚧 Warning
Fees on a Hooks-enabled ledger are non trivial. See: Hook Fees for details.

Concepts

Emitted Transactions

Behaviour

Return the amount of the fee in drops recommended for a to-be emitted transaction.

Definition

int64_t etxn_fee_base (
    uint32_t read_ptr,
  	uint32_t read_len
);

Example

int64_t fee_to_pay =
    etxn_fee_base(tx_blob, tx_blob_len);

Parameters

Name

Type

Description

read_ptr

uint32_t

Pointer to the buffer containing the serialized transaction you intend to emit. The fee field is required but ignored (you may use zero). Use the output of this function to populate the fee field correctly.

read_len

uint32_t

The length of the tx blob.

Return Code

Type

Description

int64_t

The smallest number of drops that an emitted txn would need to be accepted. If negative, an error: OUT_OF_BOUNDS - The provided buffer is not validly within the hook memory. PREREQUISITE_NOT_MET - etxn_reserve has not been called first. INVALID_TXN - The provided buffer did not contain a valid serialized transaction. (Deserialization failed, or a required field was missing.)

etxn_nonce

Generate a 32 byte nonce for use in an emitted transaction

Concepts

Behaviour

Write the 32 byte Hash to the write_ptr

Definition

Example

Parameters

Return Code

etxn_reserve

Estimate the required fee for a txn to be emitted successfully

Concepts

Emitted Transactions

Behaviour

Specifies a number of emitted transactions this hook might emit during execution.

Definition

int64_t etxn_fee_base (
    uint32_t count
);

Example

int64_t result = 
    etxn_fee_base(2);
if (result < 2)
    rollback("Error reserving!", 16, 1);

Parameters

Name

Type

Description

count

uint32_t

The largest number of transactions this hook might emit during the course of one execution.

Return Code

Type

Description

int64_t

The maximum number of emitted transactions this hook may emit. This will always be the same as the count parameter or an error as below. If negative, an error: ALREADY_SET - The hook already called this function earlier. TOO_BIG - The specified number of emitted transactions is too large.

etxn_generation

Get the generation of a hypothetically emitted transaction

Concepts

Emitted Transactions

Behaviour

Return the generation an emitted transaction will carry.

Definition

int64_t etxn_generation (
    void
);

Example

int64_t burden = 
  etxn_generation();

Parameters

None

Return Code

Type

Description

int64_t

The generation an emitted transaction will need in order to be successfully passed to emit()

emit

Emit a new transaction from the hook

Concepts

Behaviour

Read a transaction from read_ptr
Validate the transaction against the emission rules
Emit the transaction into consensus when valid
Write canonical transaction hash to write_ptr

Definition

Example

Parameters

Return Code

Float

float_set

Create a float from an exponent and mantissa

Concepts

Floating Point Numbers (XFL)

Behaviour

Compute an XFL (xls17) floating point from the provided exponent and mantissa
Return that XFL as an int64_t

Definition

int64_t float_set (
    int32_t exponent,
    int64_t mantissa
);

Example

int64_t small_amount =
  float_set(-81, 1);

Parameters

Name

Type

Description

exponent

int32_t

An exponent in the range -96 to 80

mantissa

int64_t

A mantissa. If negative then the sign of the float is negative.

🚧Caution
When setting a mantissa that is greater or fewer than 16 decimal digits the exponent will be adjusted to ensure the mantissa is exactly 16 digits. This adjustment may result in an INVALID_FLOAT in some circumstances.

📘Special case
XFL canonical 0 is also 0 in the enclosing number. Thus there is never a need to call float_set(0,0);

Return Code

Type

Description

int64_t

The XFL (xls17) enclosing number If negative, an error: INVALID_FLOAT - The adjustment of the mantissa to 16 digits produced an under or overflow.

float_multiply

Multiply two XFL numbers together

Concepts

Behaviour

Compute the multiplication of two XFL (xls17) floating point numbers
Return a new XFL as an int64_t

Definition

Example

Parameters

🚧Caution
Certain multiplications may overflow, which return with an INVALID_FLOAT error. However an underflow returns as XFL Canonical Zero (i.e. enclosing number = 0).

Return Code

float_mulratio

Multiply an XFL floating point by a non-XFL numerator and denominator

Concepts

Floating Point Numbers (XFL)

Behaviour

Compute the multiplication of an XFL (xls17) floating point number and the quotient of two integers
Return a new XFL as an int64_t

Definition

int64_t float_multiply (
    int64_t float1,
    uint32_t round_up,
    uint32_t numerator,
    uint32_t denominator
);

Example

int64_t max_vault_pusd =
    float_mulratio(max_vault_pusd, 0,
        COLLATERALIZATION_NUMERATOR, COLLATERALIZATION_DENOMINATOR);

Parameters

Name

Type

Description

float1

int64_t

An XFL floating point enclosing number representing the first operand to the multiplication

round_up

uint32_t

If non-zero all computations will be rounded up

numerator

uint32_t

The numerator of the quotient that the float will be multiplied by

denominator

uint32_t

The denominator of the quotient that the float will be multiplied by

🚧Caution
Certain multiplications may overflow, which return with an INVALID_FLOAT error. However an underflow returns as XFL Canonical Zero (i.e. enclosing number = 0).

Return Code

Type

Description

int64_t

The XFL (xls17) enclosing number If negative, an error: INVALID_FLOAT - one of the supplied parameters was not a valid XFL enclosing number OVERFLOW - the result of the multiplication was too large to store in an XFL. DIVISION_BY_ZERO - the supplied denominator was zero.

float_negate

Negate an XFL floating point number

Concepts

Floating Point Numbers (XFL)

Behaviour

Multiply an XFL by -1
Return a new XFL as an int64_t

Definition

int64_t float_negate (
    int64_t float1
);

Example

int64_t negative_one =
    float_negate(float_one());

📘Special case
The negation of Canonical Zero is Canonical Zero. Unlike some floating point standards (such as IEEE) there is no "negative zero" in XFL.

Parameters

Name

Type

Description

float1

int64_t

An XFL floating point enclosing number

Return Code

Type

Description

int64_t

The XFL (xls17) enclosing number If negative, an error: INVALID_FLOAT - one of the supplied parameters was not a valid XFL enclosing number

float_compare

Perform a comparison on two XFL floating point numbers

Concepts

Behaviour

Evaluate a comparison of two XFL floating point numbers
Return the result of the comparison as a boolean encoded in an int64_t.

Definition

Example

Parameters

🚧Caution
Always verify the function returned 1 rather than non-zero, as negative error codes will be classed as non-zero.

Return Code

float_sum

Add two XFL numbers together

Concepts

Floating Point Numbers (XFL)

Behaviour

Compute the addition of two XFL (xls17) floating point numbers
Return a new XFL as an int64_t

Definition

int64_t float_sum (
    int64_t float1,
    int64_t float2
);

Example

int64_t two =
    float_sum(float_one(), float_one());

Parameters

Name

Type

Description

float1

int64_t

An XFL floating point enclosing number representing the first operand to the addition

float2

int64_t

An XFL floating point enclosing number representing the second operand to the addition

📘Hint
To subtract two floats use float_negate on the second float then use float_sum.

Return Code

Type

Description

int64_t

The XFL (xls17) enclosing number If negative, an error: INVALID_FLOAT - one of the supplied parameters was not a valid XFL enclosing number OVERFLOW - the result of the addition was too large to store in an XFL.

float_sto

Output an XFL as a serialized object

Concepts

Behaviour

Read an XFL floating point number and optionally a field code and currency code
Write a serialized amount to write_ptr according to the parameters provided

Definition

int64_t float_sto (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t cread_ptr,
    uint32_t cread_len,  
    uint32_t iread_ptr,
    uint32_t iread_len,  
    int64_t float1,
    uint32_t field_code
);

Example

#define SBUF(str) (uint32_t)(str), sizeof(str)
uint8_t amt_out[48];
if (float_sto(SBUF(amt_out),
    SBUF(currency), SBUF(hook_accid), pusd_to_send, -1) < 0)
        rollback(SBUF("Peggy: Could not dump pusd amount into sto"), 1);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the serialized amount field. Recommend at least 48 bytes.

write_len

uint32_t

The length of the output buffer.

cread_ptr

uint32_t

Pointer to a buffer contianing the currency code to serialize into the output. May be null.

cread_len

uint32_t

The length of the currency code. This must be 20 or 3 or 0 (null).

iread_ptr

uint32_t

Pointer to a buffer containing the issuer's Account ID to serialize into the output. May be null.

iread_len

uint32_t

The length of the issuer's Account ID. This must be either 20 or 0 (null).

float1

int64_t

An XFL floating point enclosing number to serialize.

field_code

uint32_t

The sf field code to prefix the serialized amount with. E.g. sfAmount. If this field is 0xFFFFFFFFU (i.e. (uint32_t)(-1)) then no field code is prepended to the output, and no issuer or currency code is appended, but serialization proceeds as a floating point amount. If this field is 0 no field code is prepended to the output, and no issuer or currency code is appended, but serialization proceeds as though the amount is an XRP native amount rather than a floating point.

📘Hint
To output an XAH amount prepopulate the field code in the output buffer then pass the output buffer incremented to the new start and 0 as field_code

Return Code

Type

Description

int64_t

The number of bytes written to the output buffer. If negative, an error: INVALID_FLOAT - the supplied float was not a valid XFL enclosing number OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. INVALID_ARGUMENT - If instructed to output as XRP or without field code then all non-write pointers and lengths should be 0 (null). TOO_SMALL - The output buffer was too small to receive the serialized object. XFL_OVERFLOW - Expressing the output caused an overflow during normalization.

float_sto_set

Read a serialized amount into an XFL

Concepts

Behaviour

Read a serialized floating point number.
If there are more fields/data after the serialized floating pointer number then ignore them.
Return it as an XFL enclosing number

Definition

Example

Parameters

Return Code

float_invert

Divide one by an XFL floating point number

Concepts

Behaviour

Divide 1 by an XFL
Return a new XFL as an int64_t

Definition

Example

Parameters

Return Code

float_divide

Divide an XFL by another XFL floating point number

Concepts

Behaviour

Divide an XFL by another XFL
Return a new XFL as an int64_t

Definition

Example

Parameters

Return Code

float_one

Return the number 1 represented in an XFL enclosing number

Concepts

Behaviour

Return one(1) as an XFL int64_t

Definition

Example

Parameters

This function has no parameters.

Return Code

float_exponent

Get the exponent of an XFL enclosing number

🚧 Replaced by macro
This function was replaced by a macro. Please use the macro below in your code instead. To check the validity of the XFL please use float_mantissa in conjunction with this macro.

Concepts

Behaviour

Return the exponent part of an XFL as a signed integer

Definition

Because exponents can be negative, and because negatives are reserved for error states, exponents cannot be returned from functions. Therefore this function has become a macro as shown below.

Example

Parameters

float_mantissa

Get the mantissa of an XFL enclosing number

Concepts

Behaviour

Return the mantissa part of an XFL as an unsigned integer

Definition

Example

📘Hint
The mantissa of a negative XFL is positive. Use float_sign to get the sign.

Parameters

Return Code

float_sign

Get the sign of an XFL enclosing number

Concepts

Behaviour

Return 1 if the XFL is negative, otherwise return 0

Definition

Example

📘Hint
The sign bit inside the XFL is the 0 when the XFL is negative, however this function follows the standard computing convention to return 1 if it is negative.

Parameters

Return Code

float_int

Convert an XFL floating point into an integer (floor)

Concepts

Behaviour

Left shift (multiply by 10) the XFL by the number of specified decimal places
Convert the resulting XFL to an integer, discarding any remainder
Return the integer

Definition

Example

Parameters

📘Hint
Negative return values are reserved for error codes. Therefore if you need to execute this function against a negative XFL you should use absolute = 1

Return Code

float_root

Compute the nth root of an XFL

Concepts

Behaviour

Compute a the nth root of an XFL number
Return the new XFL

❗️Warning
Due to speed constraints,float_root converts the argument to an IEEE base-2 double precision floating point before applying n-th root. Therefore the returned result will often contain less precision than expected. If you need better precision you should consider dividing your XFL into a high and a low product then individually take the square roots of those products and multiply the results together.

Definition

Example

🚧Warning
If a negative number is passed the function will return COMPLEX_NOT_SUPPORTED if the root is an even root.

Parameters

Return Code

float_log

Compute the decimal log of an XFL

Concepts

Behaviour

Compute a the decimal logarithm of an XFL number
Return the new XFL

❗️Warning
Due to speed constraints,float_log converts the argument to an IEEE base-2 double precision floating point before applying base 10 log. Therefore the returned result will often contain less precision than expected.

Definition

Example

🚧Warning
If a negative number is passed the function will return COMPLEX_NOT_SUPPORTED if the root is an even root.

Parameters

Return Code

Ledger

fee_base

Fetch the fee base of the current ledger

Concepts

Behaviour

Return the fee base from the current ledger

Definition

Example

Parameters

This API takes no parameters.

Return Code

ledger_seq

Fetch the current ledger sequence number

Behaviour

Return the sequence number from the current ledger

Definition

int64_t ledger_seq ();

Example

int64_t seq =
    ledger_seq();

Parameters

This API takes no parameters.

Return Code

Type

Description

int64_t

The sequence number of the current ledger

ledger_last_hash

Retreive the 32 byte namespace biased SHA512H of the last closed ledger

Behaviour

Write the 32 byte Hash to the write_ptr

Definition

int64_t ledger_last_hash (
    uint32_t write_ptr,
    uint32_t write_len
);

Example

uint8_t hash[32];
int64_t bytes_written = 
    ledger_last_hash(hash, 32);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the output. Should be at least 32 bytes.

write_len

uint32_t

Length of the output buffer.

Return Code

Type

Description

int64_t

The number of bytes written If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory.

ledger_last_time

Fetch the last closed ledger's timestamp

Behaviour

Return the Xahau Timestamp from the last closed ledger.

📘Tip
Xahau timestamps are identical to a unix timestamps except that they are offset by -946684800.
The equivalent unix timestamp is: ledger_last_time() + 946684800;

Definition

int64_t ledger_last_time ();

Example

int64_t ts =
    ledger_last_time();

Parameters

This API takes no parameters.

Return Code

Type

Description

int64_t

The XRPL timestamp of the last closed ledger

ledger_nonce

Generate a 32 byte nonce for use in an emitted transaction

Behaviour

Write a 32 byte random value to the write_ptr

Definition

int64_t ledger_nonce (
    uint32_t write_ptr,
    uint32_t write_len
);

Example

uint8_t n[32];
int64_t bytes_written = 
    ledger_nonce(n, 32);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the output. Should be at least 32 bytes.

write_len

uint32_t

Length of the output buffer.

Return Code

Type

Description

int64_t

The number of bytes written If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory.

ledger_keylet

Search for a keylet within a specified range on the current ledger

Behaviour

Read a 34 byte Keylet from the lread_ptr
Read a 32 byte Keylet from the hread_ptr
Search the ledger for the first (lowest) Keylet of this type in this range.
If any matching Keylet is found, write it to write_ptr.

Definition

int64_t ledger_keylet (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t lread_ptr,
    uint32_t lread_len,
    uint32_t hread_ptr,
    uint32_t hread_len
);

Example

//TODO

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer to store the output serialised Keylet. .

write_len

uint32_t

Length of the output buffer. Must be 34 bytes

lread_ptr

uint32_t

Pointer to the 34 byte serialised Keylet that represents the lower boundary of the Keylet range to search.

lread_len

uint32_t

Always 34 bytes

hread_ptr

uint32_t

Pointer to the 34 byte serialised Keylet that represents the upper boundary of the Keylet range to search.

hread_len

uint32_t

Always 34 bytes

Return Code

Type

Description

int64_t

The number of bytes written (34 bytes) on success. If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. TOO_SMALL / TOO_BIG - write_len, lread_len or hread_len was not 34 bytes INVALID_ARGUMENT - One or more of the provided Keylets was not a valid serialised Keylet DOES_NOT_MATCH - The two provided Keylets were not of the same Keylet Type. DOESNT_EXIST - No matching Keylet was found in the specified range.

Hook Context

hook_account

Retreive the 20 byte Account ID the Hook is executing on

Behaviour

Write the 20 byte Account ID to the write_ptr

Definition

int64_t hook_account (
    uint32_t write_ptr,
    uint32_t write_len
);

Example

uint8_t hook_acc_id[20];
int64_t bytes_written = 
    hook_account(hook_acc_id, 20);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the output. Should be at least 20 bytes.

write_len

uint32_t

Length of the output buffer.

Return Code

Type

Description

int64_t

The number of bytes written If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory.

hook_hash

Retreive the 32 byte namespace biased SHA512H of the currently executing Hook

Behaviour

Look up the hash of the hook installed on hook account at position hook_no
Write the 32 byte hash to write_ptr

Definition

int64_t hook_hash (
    uint32_t write_ptr,
    uint32_t write_len,
  	int32_t  hook_no
);

Example

uint8_t hash[32];
int64_t bytes_written = 
    hook_hash(hash, 32, -1);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the output. Should be at least 32 bytes.

write_len

uint32_t

Length of the output buffer.

hook_no

int32_t

The position in the hook chain the hook is located at, or -1 for the currently executing hook.

Return Code

Type

Description

int64_t

The number of bytes written If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. DOESNT_EXIST - The specified hook sequence number doesn't exist in the hook chain.

hook_param

Retrieve the parameter value for a named hook parameter

Behaviour

Look up the value for a named parameter specified in read_ptr
Write the parameter's value to write_ptr

Definition

int64_t hook_param (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t read_ptr,
    uint32_t read_len
);

Example

uint8_t pname[] = {0xCAU, 0xFEU};
uint8_t pvalue[32];
int64_t value_len = 
    hook_param(pvalue, 32, pname, 2);

Parameters

Name

Type

Description

write_ptr

uint32_t

Pointer to a buffer of a suitable size to store the output. Should be at least 32 bytes.

write_len

uint32_t

Length of the output buffer.

read_ptr

uint32_t

Pointer to a buffer containing the parameter's name

read_len

uint32_t

Length of the parameter's name

Return Code

Type

Description

int64_t

The number of bytes written If negative, an error: OUT_OF_BOUNDS - pointers/lengths specified outside of hook memory. DOESNT_EXIST - The specified paramater doesn't exist or is null TOO_SMALL - The parameter name can't be null TOO_BIG - The parameter name is greater than 32 bytes

hook_param_set

Set or delete a parameter on a hook on the same account further down the execution chain

Behaviour

Search the hook chain on the hook account for a 32 byte hash indicated by hread_ptr
If found: set a parameter:
With the parameter name indicated by kread_ptr and
The parameter value indicated by read_ptr

Definition

Example

Parameters

Return Code

hook_skip

Skip a hook that appears later in the hook chain on the hook account

Behaviour

Search the hook chain for a hook identified by the hook hash at read_ptr
Mark it as disabled for this chain execution

Definition

Example

Parameters

Return Code

hook_pos

Returns the position in the hook chain the currently executing hook occupies

Behaviour

Returns the position in the hook chain the currently executing hook occupies

Definition

Example

Parameters

This API has no parameters

Return Code

Type

Description

hook_again

Returns the position in the hook chain the currently executing hook occupies

Behaviour

If the hook is being strongly executed then flag this specific hook in the chain for .
If the originating transaction successfully is applied then the hook will be called again in a second, Weak Execution.

Definition

Example

Parameters

This API has no parameters

Return Code

Type

Description

Slot

slot

Serialize and output a slotted object

Behaviour

Serialize the object currently occupying the specified slot
Write the serialized version of the object to the output buffer

👍 Alternative use
For small objects you may avoid using a buffer. Specify 0, 0 for write_ptr, write_len to attempt to return the slotted object as big endian packed data in the int64_t return code. Up to 63 bits of data may be returned this way.

Definition

Example

Parameters

Return Code

slot_clear

Free up a currently occupied slot

Behaviour

Free the specified slot, releasing any object that was slotted there

Definition

Example

Parameters

Name

Type

Description

Return Code

Type

Description

slot_count

Count the elements of an array object in a slot

Behaviour

Count the elements of an array in the specified slot
Return the count

Definition

Example

Parameters

Name

Type

Description

Return Code

Type

Description

slot_set

Locate an object based on its keylet and place it into a slot

Behaviour

Locate an object given the Keylet provided in read_ptr
Emplace the located object into the slot specified or into a new slot if no slot (zero) is specified

Definition

Example

Parameters

Name

Type

Description

Return Code

slot_size

Compute the serialized size of an object in a slot

Behaviour

Return the number of bytes the object in the specified slot occupies when serialized

Definition

Example

Parameters

Name

Type

Description

Return Code

Type

Description

slot_subarray

Index into a slotted array and assign a sub-object to another slot

Behaviour

Look up the array in slot parent_slot
Retrieve the sub-object at the index specified in array_id
Place sub-object into the slot new_slot or the next available slot if new_slot is 0.
Return the new slot number.

Definition

Example

Parameters

Return Code

slot_subfield

Index into a slotted object and assign a sub-object to another slot

Behaviour

Look up the object in slot parent_slot
Retrieve the sub-object at field_id
Place sub-object into the slot new_slot or the next available slot if new_slot is 0.
Return the new slot number.

Definition

Example

Parameters

Return Code

slot_type

Retrieve the field code of an object in a slot and, optionally, some other information

Behaviour

Locate the object pointed to by the specified slot_no
Determine its sf field code and return this, or some other information (see below) if flags are used

Definition

Example

Parameters

Name

Type

Description

Return Code

xpop_slot

Serialize and output the xpop transaction blob and metadata

Behaviour

Locate the xpop blob on the Import transaction
Emplace the located tx and meta objects into the slots specified

Definition

Example

Parameters

Name

Type

Description

Return Code

slot_float

Parse the STI_AMOUNT in the specified slot and return it as an XFL enclosed number

Behaviour

Parse the STI_AMOUNT in the specified slot and return it as an XFL enclosed number

Definition

Example

Parameters

Name

Type

Description

Return Code

Type

Description

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

Example

Parameters

📘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

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

Example

Parameters

📘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

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

Example

Parameters

🚧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

Trace (Debug)

trace_num

Write an integer to the Xahaud trace log

Behaviour

Write an integer to the trace log along with a message (if any)

Definition

Example

Parameters

Name

Type

Description

Return Code

trace_float

Write a XFL float to the Xahaud trace log

Behaviour

Write a XFL floating point to the trace log along with a message (if any)

Definition

Example

Parameters

Name

Type

Description

Return Code

Originating Transaction

otxn_burden

Get the burden of the originating transaction

Behaviour

Return the burden of the originating transaction or 1 if no burden field is present.

Definition

Example

Parameters

None

Return Code

Type

Description

otxn_field

Serialize and output a field from the originating transaction

Behaviour

Find the specified sf field in the originating transaction
Write the serialized version of the field to the output buffer

Definition

Example

Parameters

Name

Type

Description

❗️Important
The field code is not written to the output buffer, only the payload of the field is.
At time of writing for Hooks Public Testnet, STI_ACCOUNT fields like sfAccount are returned without the leading variable length byte.

Return Code

otxn_generation

Get the generation of the originating transaction

Behaviour

Return the generation of the originating transaction or 1 if no generation field is present.

Definition

Example

Parameters

None

Return Code

Type

Description

otxn_id

Output the canonical hash of the originating transaction

Behaviour

Write the canonical hash of the originating transaction to the output buffer.
If flags = 1 and the transaction is an EMIT_FAILURE transaction then write the canonical hash of the originating transaction that caused the emission.

Definition

Example

Parameters

Return Code

otxn_type

Get the Transaction Type of the originating transaction

Behaviour

Return the Transaction Type of the originating transaction

Definition

Example

Parameters

None

Return Code

Type

Description

Known Transaction Types

otxn_slot

Load the originating transaction into a slot

Behaviour

Emplace the originating transaction into the slot specified or into a new slot if no slot is specified

Definition

Example

Parameters

Name

Type

Description

Return Code

Type

Description

otxn_param

Retrieve the parameter value for a named Invoke transaction parameter

Behaviour

Look up the value for a named parameter specified in read_ptr on the originating transaction (ttINVOKE only).
Write the parameter's value to write_ptr

Definition

Example

Parameters

Return Code

meta_slot

Load the metadata of the originating transaction into a slot

Behaviour

If the Hook is being then emplace the metadata of the originating transaction into the slot specified or into a new slot if no slot is specified

Definition

Example

Parameters

Name

Type

Description

Return Code

Type

Description

account_namespace

Use the account_namespace websocket API to query the Hook State Objects on a particular account in a particular namespace.

Usage:

JSON

Example query:

JSON

Example result:

JSON