Slot APIs

This page documents the seventeen slot Hook APIs: the slot family (an efficient handle system for transaction and ledger-object data), the metadata/XPOP slot loaders, and the ledger info family (sequence, times, hashes, nonces, and keylet enumeration). The slot family is documented here; the ledger-info family has its own page, Ledger APIs.

All signatures are copied verbatim from hook/extern.h. Return codes reference the shared error table in ../../glossary; values come from hook/error.h. The implementation is split between core lookup/read logic and the WASM-facing wrappers that marshal arguments across the guest boundary.

---

The slot system

Serialized ledger objects and transactions can be large. Rather than copy a whole object into WASM memory to read one field, a hook loads the object into a slot — a numbered, server-side handle — and then drills into it.

• A slot holds a parsed serialized object (an STObject, STArray, or a leaf field). There are at most max_slots = 255 slots per hook execution. Requesting a slot when none are free returns NO_FREE_SLOTS (-6).
• Slot 0 is special as an argument: passing 0 for a destination slot means "allocate any free slot for me", and the chosen slot number is returned. Passing a specific number targets that slot (overwriting whatever was there).
• Typical lifecycle:
  1. slot_set loads an object from a keylet (34 bytes) or a transaction id (32 bytes) into a slot.
  2. slot_subfield / slot_subarray drill into that slot, placing a subfield or array element into another slot.
  3. slot, slot_size, slot_count, slot_type, and slot_float read the slotted data.
  4. slot_clear frees a slot when you are done (or you simply let execution end).

Keylets for slot_set are usually built with util_keylet, which produces the 34-byte serialized keylet these functions expect.

---

Index

Function	Purpose
slot_set	Load a ledger object or transaction into a slot.
slot	Write a slot's serialized contents to memory (or return as int64_t).
slot_size	Byte size of the data in a slot.
slot_clear	Free a slot.
slot_count	Number of elements in a slotted array.
slot_subfield	Expand a subfield of a slotted object into a new slot.
slot_subarray	Expand an array element of a slotted array into a new slot.
slot_type	Return the field type of a slot (and whether an amount is XAH).
slot_float	Interpret a slotted amount as an XFL value.
meta_slot	Load the originating transaction's metadata into a slot.
xpop_slot	Load an XPOP's inner transaction and metadata into two slots.

Related documents

• ../../README — documentation index.
• ../../overview — hook execution model and lifecycle.
• ../../glossary — full error-code and term reference.
• ../../macros — SBUF, GUARD, and buffer helpers.
• ../../best-practices — slot budgets and iterating ledger objects.
• Ledger APIs — fee_base, ledger_seq, ledger_nonce, and the rest of the ledger-info family.
• control — hook_again and the strong/weak execution model.
• transaction — otxn_slot, otxn_field, and originating-txn access.
• state — persistent state read/write.
• emit-and-etxn — etxn_fee_base, etxn_nonce, and emission.
• float-and-amount — XFL math for slot_float values.
• utility — util_keylet for building the keylets slot_set/ledger_keylet consume.
• ../../examples/emitted-transaction — reading slots and emitting.
• ../../examples/memo-routing — drilling arrays and subfields.