Xahau Hooks Docs

Appearance

Xahau HooksC / WebAssembly API Documentation

Small WebAssembly programs attached to accounts. They run on-ledger when a transaction touches the account, read the originating transaction and ledger, keep persistent state, emit transactions, and accept or rollback.

Start with the overview
API reference
Examples

Grounded in source

Every claim is traced to the xahaud repository (branch dev) - hook/extern.h, hook/error.h, hook/macro.h, the execution engine, and the test-suite example hooks.

Every API function

Exact C signatures, parameters, return conventions, and error codes for every host function a hook can import, grouped by purpose.

Worked examples

End-to-end hooks for payment filtering, state counters, memo routing, foreign state, and emitted transactions.

Who this is for: developers writing Hook smart contracts in C, and anyone who needs an accurate reference for the Hook API functions, their error codes, and the execution model.

Table of contents ​

DocumentDescription
OverviewConceptual foundation: what Hooks are, entry points, execution modes, environment limits, and the typical processing flow.
Execution OrderHook chains and the order hooks run in for one transaction: strong, weak, and callback passes, the reserved argument, and the chain-control APIs.
TSHTransactional Stake Holders: strong vs. weak TSH, the two-condition gate for weak-TSH ("collect call") execution, and a per-transaction-type TSH table.
Hook FeesDeployment, reserve, execution, and emitted-transaction costs in one place: what you pay, when, and who pays it.
XFLXFL concept page: the fixed-precision floating-point format's bit encoding, valid range, and relationship to the ledger's Amount format.
NOP Bytes (0x99)The 0x99 NOP byte Xahau's deserializer skips: its rules and limits, which Hook APIs honor it, and how to use it for optional and variable-length fields in an emitted-transaction template.
Compiling HooksFrom C to an installable WASM module: what the SetHook validator enforces, the recommended hooks-compiler toolchain, and the install-rejection log codes.
Validating HooksCheck a compiled module with the hook_validate RPC before installing it: availability, request and response, and reading the guard checker's log.
Best PracticesPractical guidance: guarding loops, buffer sizing, state and reserve management, error handling.
SetHook FieldsSetHook fields that control hook triggering and permissions: HookOn, HookOnIncoming, HookOnOutgoing, HookCanEmit, HookName.
Helper MacrosHelper macros from hook/macro.h: control flow, guards, buffer helpers, integer conversion, comparison.
ToolsCommunity tooling for building Hooks: the hooks-compiler build tool, the Transaction Builder code generator, and the Binary Visualizer.
Other LanguagesWriting hooks in Rust, Zig, AssemblyScript, or hand-written WAT: how to satisfy the validator's contract from a non-C toolchain.
GlossaryAlphabetical glossary of Hook terminology (Slot, Keylet, XFL, Namespace, Grant, Burden, TSH, and more).

API reference, by group ​

GroupDescription
Control APIsControl functions: _g, accept, rollback, hook_account, hook_hash, hook_param, hook_param_set, hook_again, hook_skip, hook_pos.
Transaction APIsOriginating-transaction functions: otxn_field, otxn_id, otxn_type, otxn_slot, otxn_param, otxn_burden, otxn_generation.
State APIsHook state: state, state_set, state_foreign, state_foreign_set.
Slot APIsThe slot system: slot_set, slot*, meta_slot, xpop_slot.
Ledger APIsLedger info: ledger_*, fee_base.
Emit APIsEmitting transactions: etxn_*, prepare, emit.
Float & Amount APIsXFL floating-point math and amount serialization: float_*.
Utility APIsCryptography, address conversion, and keylet computation: util_*.
STO APIsSerialized-object (STO) inspection/editing: sto_*.
Trace APIsDebug tracing: trace*.

Worked examples ​

DocumentDescription
Payment FilterWorked example: inspect an incoming Payment and accept or rollback.
State CounterWorked example: read/increment/write a counter in hook state.
Emitted TransactionWorked example: reserve, prepare, and emit a transaction.
Foreign StateWorked example: read another account's state via state_foreign.
Memo RoutingWorked example: route behavior based on transaction memos/parameters.

Suggested reading order ​

For newcomers, read in this order:

  1. Overview — the model and vocabulary.
  2. Control APIs — how a hook starts, guards loops, and terminates.
  3. Transaction APIs — how to read the transaction that triggered the hook.
  4. State APIs — how to persist data.
  5. The Examples — end-to-end hooks that tie it together.
  6. Compiling Hooks and Validating Hooks — build the module, check it with hook_validate, and install it.

Keep Glossary and Helper Macros open alongside the above; both are lookup references rather than linear reading.

Reference use ​

Experienced developers can jump straight to the relevant api-reference/* page. Each function is documented with its exact C signature from hook/extern.h, its parameters, return convention, and error codes. The full error-code table lives in Overview and is repeated per function where relevant.

Source of truth ​

These documents were derived from the developer-facing Hook API headers (repo root https://github.com/Xahau/xahaud):

  • hook/extern.h — canonical developer-facing declarations of all API functions.
  • hook/error.h — developer-facing error #defines.
  • hook/macro.h — helper macros.
  • hook/hookapi.h — top-level include; KEYLET_* and COMPARE_* constants.
  • hook/sfcodes.h, hook/tts.h, hook/ls_flags.h, hook/tx_flags.h — field, transaction-type, and flag codes.

The hook_return_code enum, limits, keylet codes, exit types, HookSet log codes, SetHook operations/flags, guard-validation rules, amendment gating (featureHooksUpdate1, featureHooksUpdate2), and the Hook execution engine itself round out the picture, and the example hooks referenced throughout this doc set come from the project's own test suite.

The consolidated, cross-checked inventory these docs build on is .claude/plans/hook-docs/api-inventory.md.