Xahau Network
Testnet FaucetExplorerHooks API Docs
Xahau Network
Xahau Network
  • 🪝Xahau Documentation
    • XRPL/Xahau: What is Different?
  • 🪝Hooks
  • 🚨Concepts
    • Introduction
      • Example Usage
      • Xahau Testnet
      • Xahau Testnet Explorer
      • Examples (source code)
      • Blogs (concepts)
    • Terminology
    • Loops and Guarding
    • Compiling Hooks
    • Chaining
    • Weak and Strong
    • Collect Call
    • SetHook Transaction
    • Parameters
    • Namespaces
    • Grants
    • HookOn Field
    • Reference Counted Hook Definitions
    • Hook Fees
    • Execution Metadata
    • Debugging Hooks
    • State Management
    • Slots and Keylets
    • Floating Point Numbers (XFL)
    • Emitted Transactions
    • Serialized Objects
  • Features
    • Public Nodes (RPC)
    • Amendments
    • Transaction Signing
      • Transaction Fees
    • Developer Tooling
      • Curated Tooling
      • Client Libraries
      • Developer Tricks
    • HTTP / WebSocket APIs
      • Request Formatting Guide
      • Response Formatting Guide
      • Considerations
      • Public API Methods
      • Admin API Methods
    • Network Features
      • Account Managment
      • Balance Rewards
      • Check
      • Escrow
      • Hooks
      • Offer
      • Payments
      • URIToken
    • Faucet & Explorers
    • Data API's
  • Infrastructure
    • Node Requirements
    • Running a Node
      • Running a Mainnet Node
      • Running a Testnet Node
    • Building Xahau (Dev)
      • Ubuntu - 22.04
      • Mac OS - 15.3.2 (24D81)
  • Technical
    • 📐Hooks Functions
      • Overview
        • Hook API Conventions
        • Return Codes
      • Developer Defined
        • hook
        • cbak / Callback
      • Control
        • accept
        • rollback
      • Utilities
        • util_raddr
        • util_accid
        • util_verify
        • util_sha512h
        • util_keylet
      • Serialization
        • sto_subfield
        • sto_to_json
        • sto_from_json
        • sto_subarray
        • sto_emplace
        • sto_erase
        • sto_validate
      • Emitted Transaction
        • etxn_burden
        • etxn_details
        • etxn_fee_base
        • etxn_nonce
        • etxn_reserve
        • etxn_generation
        • prepare
        • emit
      • Float
        • float_set
        • float_multiply
        • float_mulratio
        • float_negate
        • float_compare
        • float_sum
        • float_sto
        • float_sto_set
        • float_invert
        • float_divide
        • float_one
        • float_exponent
        • float_mantissa
        • float_sign
        • float_int
        • float_root
        • float_log
      • Ledger
        • fee_base
        • ledger_seq
        • ledger_last_hash
        • ledger_last_time
        • ledger_nonce
        • ledger_keylet
      • Hook Context
        • hook_account
        • hook_hash
        • hook_param
        • hook_param_set
        • hook_skip
        • hook_pos
        • hook_again
      • Slot
        • slot
        • slot_clear
        • slot_count
        • slot_set
        • slot_size
        • slot_subarray
        • slot_subfield
        • slot_type
        • xpop_slot
        • slot_float
      • State
        • state
        • state_set
        • state_foreign
        • state_foreign_set
      • Trace (Debug)
        • trace
        • trace_num
        • trace_float
      • Originating Transaction
        • otxn_burden
        • otxn_field
        • otxn_generation
        • otxn_id
        • otxn_type
        • otxn_slot
        • otxn_param
        • otxn_json
        • meta_slot
      • Websocket APIs
        • account_info
        • account_namespace
    • Protocol Reference
      • Transactions
        • Transaction Common Fields
        • Transaction Types
          • AccountDelete
          • AccountSet
          • CheckCancel
          • CheckCash
          • CheckCreate
          • ClaimReward
          • DepositPreauth
          • EscrowCancel
          • EscrowCreate
          • EscrowFinish
          • GenesisMint - (Emitted Txn)
          • Import
          • Invoke
          • OfferCancel
          • OfferCreate
          • Payment
          • PaymentChannelClaim
          • PaymentChannelCreate
          • PaymentChannelFund
          • Remit
          • SetHook
          • SetRegularKey
          • SignerListSet
          • TicketCreate
          • TrustSet
          • URITokenBurn
          • URITokenBuy
          • URITokenCancelSellOffer
          • URITokenCreateSellOffer
          • URITokenMint
        • Pseudo Transaction Types
          • EmitFailure
          • UNLReport
          • UNLModify
          • SetFee
          • EnableAmendment
        • Transaction Results
          • TES Codes
          • TER Codes
          • TEM Codes
          • TEL Codes
          • TEF Codes
          • TEC Codes
        • Transaction Metadata
      • Ledger Data
        • Ledger Objects Types
          • AccountRoot
          • Amendments
          • Check
          • Deposit Pre Auth
          • Directory Node
          • Emitted Txn
          • Escrow
          • Fee Settings
          • Hook
          • Hook Definition
          • Hook State
          • Import VL Sequence
          • Ledger Hashes
          • Negative UNL
          • Offer
          • Pay Channel
          • Ripple State
          • Signers List
          • Ticket
          • UNL Report
          • URIToken
        • Ledger Header
        • Ledger Object IDs
      • Data Types
        • Currency Formats
        • Base 58 Encodings
      • Binary Format
    • Balance Adjustments
    • Governance Game
    • Burn 2 Mint (B2M)
    • Versioning Process
  • Compliance
    • Security Audits
      • Responsible Disclosure
  • Support
    • Help Us
Powered by GitBook
On this page
  • Background
  • What are slots?
  • What are keylets?
  • Example

Was this helpful?

Edit on GitHub
Export as PDF
  1. Concepts

Slots and Keylets

Inspect and manipulate on-ledger objects.

Last updated 4 months ago

Was this helpful?

Background

Xahau contains numerous heterogenous object types which a Hook has read-access to. For example: transactions, accounts, ledgers, and the subcomponents of each of these, to name just a few.

It is very easy to carelessly program a computer to do a lot of needless copy operations when disciplined access to the same underlying data (i.e. through a view) would suffice. The deliberate avoidance of copy operations in programming is referred to as in programming.

With Hooks the same principle applies. We want to avoid copying where possible. In particular we want to avoid as much as possible needlessly copying large objects such as whole ledgers, we also want to avoid serializaing and unserializing these where possible.

What are slots?

Slots are part of the Hook API and provide a zero-copy heterogenous access system for on-ledger objects and transactions.

  • Each Hook has access to 255 slots during runtime.

  • Each slot may be empty or may contain a slotted object.

  • The slot API allows traversal into inner objects, and allows these inner objects themselves to be slotted.

  • The slot API allows slotted objects to be dumped to a buffer or otherwise read by the Hook.

The avilable slot APIs are:

Hook API
What it does

Serialize and output a slotted object

Free up a currently occupied slot

Count the elements of an array object in a slot

slot_id

Compute the canonical hash of the slotted object and return it

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

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

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

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

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

Compute the serialized size of an object in a slot

What are keylets?

Keylets are used to locate (point to) on-ledger objects. In brief they are a hash of identifying information from the object, which is the canonical handle for that object.

🚧 Tip

The Hook APIs which accept a 34 byte keylet will also generally accept a 32 byte canonical transaction hash.

Example

In the following example a 34 byte keylet for a signers object is used to slot that object.

uint8_t keylet[34];
if (util_keylet(SBUF(keylet), KEYLET_SIGNERS, SBUF(hook_accid), 0, 0, 0, 0) != 34)
    rollback(SBUF("Notary: Internal error, could not generate keylet"), 10);

// then requesting XRPLD slot that keylet into a new slot for us
int64_t slot_no = slot_set(SBUF(keylet), 0);
if (slot_no < 0)
   rollback(SBUF("Notary: Could not set keylet in slot"), 10);

Hooks use a serialized 34 byte keylet format which can be derrived using the important function. Without this looking up and slotting objects would be generally impossible.

🚨
Zero copy
util_keylet
slot
slot_clear
slot_count
slot_set
slot_subarray
slot_subfield
slot_type
slot_float
slot_size