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, include/xrpl/hook/Enum.h, include/xrpl/hook/hook_api.macro, the Hook execution engine under src/xrpld/app/hook/, and the example hooks embedded in src/test/app/SetHook_test.cpp.

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

Document	Description
overview.md	Conceptual 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.
glossary.md	Alphabetical glossary of Hook terminology (Slot, Keylet, XFL, Namespace, Grant, Burden, TSH, and more).
macros/	Helper macros from hook/macro.h: control flow, guards, buffer helpers, integer conversion, comparison.
best-practices.md	Practical guidance: guarding loops, buffer sizing, state and reserve management, error handling.

API reference, by group

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

Document	Description
examples/payment-filter.md	Worked example: inspect an incoming Payment and accept or rollback.
examples/state-counter.md	Worked example: read/increment/write a counter in hook state.
examples/emitted-transaction.md	Worked example: reserve, prepare, and emit a transaction.
examples/foreign-state.md	Worked example: read another account's state via state_foreign.
examples/memo-routing.md	Worked example: route behavior based on transaction memos/parameters.

Suggested reading order

For newcomers, read in this order:

1. overview.md — 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.md 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.md and is repeated per function where relevant.

Source of truth

These documents were derived from the following repository sources (repo root /Users/tequ/projects/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.
• include/xrpl/hook/Enum.h — hook_return_code enum, limits, keylet codes, exit types, HookSet log codes, SetHook operations/flags.
• include/xrpl/hook/hook_api.macro — WasmEdge registration and amendment gating (featureHooksUpdate1, featureHooksUpdate2).
• include/xrpl/hook/Guard.h — guard validation rules.
• src/xrpld/app/hook/applyHook.h and src/xrpld/app/hook/detail/applyHook.cpp — the Hook execution engine.
• src/test/app/SetHook_test.cpp — real example hooks (between the R"[test.hook]( and )[test.hook]" markers).
• src/test/app/build_test_hooks.sh — the test-hook compilation pipeline.

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

Related documents

• overview.md
• sethook-fields/
• glossary.md
• macros/
• best-practices.md
• api-reference/control/
• api-reference/transaction/
• api-reference/state/
• api-reference/slot/
• api-reference/ledger/
• api-reference/emit/
• api-reference/float/
• api-reference/utility/
• api-reference/sto/
• api-reference/trace/
• examples/payment-filter.md
• examples/state-counter.md
• examples/emitted-transaction.md
• examples/foreign-state.md
• examples/memo-routing.md