Xahau Hooks Docs

Appearance

Xahau Hooks: C/WASM API Documentation ​

Xahau Hooks are small WebAssembly programs attached to accounts. They run on-ledger whenever a transaction touches the account they are installed on, and they can read the originating transaction, read and write persistent state, read ledger objects, emit new transactions, and ultimately accept (apply) or rollback (reject) the transaction.

This doc set describes the C / WebAssembly Hook API as it exists in this repository (branch dev). Every claim here is grounded in repository source — primarily hook/extern.h, hook/error.h, hook/macro.h, hook/hookapi.h, the Hook execution engine, and the example hooks embedded in the test suite.

Who this is for: developers writing Hook smart contracts in C, and anyone who needs an accurate reference for the 75 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.
sethook-fields/SetHook fields that control hook triggering and permissions: HookOn, HookOnIncoming, HookOnOutgoing, HookCanEmit, HookName.
tshTransactional Stake Holders: strong vs. weak TSH, the two-condition gate for weak-TSH ("collect call") execution, and a per-transaction-type TSH table.
glossaryAlphabetical glossary of Hook terminology (Slot, Keylet, XFL, Namespace, Grant, Burden, TSH, and more).
xflXFL concept page: the fixed-precision floating-point format's bit encoding, valid range, and relationship to the ledger's Amount format.
nop-bytesThe 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.
macros/Helper macros from hook/macro.h: control flow, guards, buffer helpers, integer conversion, comparison.
tools/Community tooling for building Hooks, including the Transaction Builder code generator and the Binary Visualizer.
best-practicesPractical guidance: guarding loops, buffer sizing, state and reserve management, error handling.

API reference, by group ​

GroupDescription
api-reference/control/Control functions: _g, accept, rollback, hook_account, hook_hash, hook_param, hook_param_set, hook_again, hook_skip, hook_pos.
api-reference/transaction/Originating-transaction functions: otxn_field, otxn_id, otxn_type, otxn_slot, otxn_param, otxn_burden, otxn_generation.
api-reference/state/Hook state: state, state_set, state_foreign, state_foreign_set.
api-reference/slot/The slot system: slot_set, slot*, meta_slot, xpop_slot.
api-reference/ledger/Ledger info: ledger_*, fee_base.
api-reference/emit/Emitting transactions: etxn_*, prepare, emit.
api-reference/float/XFL floating-point math and amount serialization: float_*.
api-reference/utility/Cryptography, address conversion, and keylet computation: util_*.
api-reference/sto/Serialized-object (STO) inspection/editing: sto_*.
api-reference/trace/Debug tracing: trace*.

Worked examples ​

DocumentDescription
examples/payment-filterWorked example: inspect an incoming Payment and accept or rollback.
examples/state-counterWorked example: read/increment/write a counter in hook state.
examples/emitted-transactionWorked example: reserve, prepare, and emit a transaction.
examples/foreign-stateWorked example: read another account's state via state_foreign.
examples/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. api-reference/control/ — how a hook starts, guards loops, and terminates.
  3. api-reference/transaction/ — how to read the transaction that triggered the hook.
  4. api-reference/state/ — how to persist data.
  5. The examples/ — end-to-end hooks that tie it together.

Keep glossary and 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 75 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.