Welcome to Hooks ๐Ÿ‘‹

What are Hooks?

Hooks are small, efficient web assembly modules designed specifically for the XRPL. Hooks can be written in any language (compilable to WebAssembly) and most business logic and most smart contract concepts can be implemented in a hook. Typically Hooks are written in C.

Hooks are set onto an XRPL account using a SetHook transaction. Once installed on an account, a hook can:

  1. Block or allow incoming and outgoing transactions on the account,
  2. Modify and maintain internal state and logic specific to the hook on that account, and
  3. Emit new transactions on behalf of the account.


This Hooks documentation and the Hooks API use a set of unfamiliar terms. Use the lookup table below if you find yourself lost.

HookThis term refers to a range of things depending on context
1. A webassembly binary uploadable to the XRPL with the SetHook Transaction type.
2. A webassembly binary already uploaded to and set or configured onto an XRPL account.
3. The source code of such a binary.
Originating TransactionThe transaction that triggered the Hook to fire. This could be either a transaction sent out of or into an account with a Hook set on it.
Originating AccountThe account that sent an Originating Transaction.
Hook AccountThe account where the currently executing Hook lives. This is the account that owns the Hook, the account that performed the SetHook Transaction which created the Hook and the account to whom belongs the Hook State for the currently executing Hook.
InstallerThe account which is currently installing a Hook using the SetHook transaction.
Emitted TransactionA new transaction created by a Hook during the Hook's execution that is not the Originating Transaction. These are typically used for sending funds back to the Originating Account. See: Emitted Transactions.
StateA per-account key-value map of 32 byte keys to arbitrary data. All Hooks present on an account have access to the same Hook State and can modify it. Note that the Hook State lives on the Hook Account not on the Originating Account. See: State Management.
SetHookA new Transaction Type introduced in the Hooks ammendment which sets a Hook onto an XRPL account. See: SetHook Transaction.
GuardsA special control mechanism you need to use if you write a loop into in a Hook. See: Loops and Guarding.
GrantsSpecial permission a Hook Installer can give another account or a specific Hook (regardless of where it is installed) to modify Hook State on the Installer's account.
NamespaceA unique 32 byte code delineating one set of state keys from another. The same state key may be used by two different Hooks without interfering with each-other if the namespaces set on the Hooks are different.
ParametersInstall-time parameters that can be optionally set on a Hook.
Reference CountingAn unowned object on the ledger may be reference counted, meaning it is deleted when the final account which referenced (used) it removes their reference to it.
XFL or Floating PointA way to do high precision math in Hooks such as for exchange rate computation. See: Floating Point Numbers (XFL).
Serialized Objects (STO)The way xrpld transmits and stores ledger objects. See: Serialized Objects.
Slots and KeyletsSlots can contain ledger objects and keylets identify those objects. See: Slots and Keylets.
TraceA way to print a log line to the xrpld output from a Hook. See: Debugging Hooks.

Whatโ€™s Next