What a Hook is

Picture a doorman at your account. Every transaction that touches the account walks past him. He checks it against a short list of rules you wrote. Then he lets it through or turns it away.

That doorman is a Hook. It is a small program attached to one account.

Examples from the Xahau docs:

• Refuse incoming payments below an amount you choose.
• Send a share of every outgoing payment to a savings account.
• Keep a small list, such as approved senders, that other Hooks can check.
• Start a new transaction from the account, such as a refund.

Hooks are limited on purpose. Every loop has a fixed maximum number of rounds. A Hook cannot run forever, and the network knows its worst-case cost before it runs.

A rejected transaction still costs its sender the fee. So a Hook that refuses spam does not make spam free.

Hooks run on Xahau, a separate network. They do not run on the XRP Ledger. See Xahau, a separate network.

A Hook is a WebAssembly module. Developers write it in C or another language that compiles to WebAssembly. A JavaScript option, JSHooks, is in testing.

Installing. The SetHook transaction creates, installs, updates or deletes Hooks. Each entry in its Hooks array can carry:

• CreateCode: the compiled WebAssembly.
• HookHash: the hash of code already on the ledger, to reuse it.
• HookOn: the transaction types that fire the Hook.
• HookNamespace: a 256-bit value that scopes the Hook's state.

The chain. One account holds up to 10 Hooks, in positions 0 to 9. They run in order. The chain is strongly executed: every Hook must call accept for the transaction to succeed.

Ending. A Hook ends with accept or rollback. After rollback, the originating transaction fails with tecHOOK_REJECTED. The sender is still charged a fee. The Hook's state changes and emitted transactions are discarded.

State. Hook State is a per-account key-value map with 32-byte keys. It belongs to the Hook's account, not the sender.

Emitted transactions. A Hook can create new transactions during execution. A common use is sending funds back to the originating account.

Guards. Every loop starts with a call to _g(id, maxiter). maxiter is the most rounds that loop may run. Hooks are deliberately not Turing complete. Recursion is not allowed. If a loop passes its cap, the Hook rolls back with GUARD_VIOLATION. The network rejects a SetHook whose guards are wrong. The worst-case count sets the fee.

Ledger objects on Xahau: Hook (an account's chain), HookDefinition (shared code) and HookState (stored values).