Appearance
SetHook Fields
This directory documents all 12 fields of the sfHook inner object used by SetHook (ttHOOK_SET) transactions — HookHash, CreateCode, HookGrants, HookNamespace, HookParameters, HookOn, HookOnIncoming, HookOnOutgoing, HookCanEmit, HookApiVersion, HookName, and Flags — plus a page mapping which of them are required, optional, or forbidden for each of the six operations (hsoCREATE/hsoINSTALL/hsoUPDATE/hsoDELETE/hsoNSDELETE/hsoNOOP) a sfHook object can represent. All fields and rules described here exist on this branch (dev); this branch has no HookApiVersion 1 (gas-metered) ABI, so HookApiVersion accepts only 0.
Start with operations-field-matrix if you want the per-operation required/optional/forbidden table first — the individual field pages below go deeper on the runtime and validation semantics of each field but assume familiarity with the six operations.
Where these fields live
A SetHook transaction carries sfHooks (required), an array of sfHook objects (HookSetObject). Each sfHook entry describes one operation (hsoCREATE/hsoINSTALL/hsoDELETE/hsoNSDELETE/hsoUPDATE/hsoNOOP, inferred from which fields are present) applied to one position in the account's hook chain. See ../overview.md for the lifecycle table.
| Field | SField type (code) | Where it can appear | Required/optional |
|---|---|---|---|
HookHash | UINT256 (31) | sfHook; sfHookGrant (as sfHookGrant's own HookHash); ltHOOK_DEFINITION (identifies the definition itself) | soeOPTIONAL on sfHook, soeREQUIRED on sfHookGrant and ltHOOK_DEFINITION |
CreateCode | VL (11) | sfHook, ltHOOK_DEFINITION | soeOPTIONAL on sfHook, soeREQUIRED on ltHOOK_DEFINITION |
HookGrants | ARRAY (20) | sfHook only — never ltHOOK_DEFINITION | soeOPTIONAL |
HookNamespace | UINT256 (32) | sfHook, ltHOOK_DEFINITION | soeOPTIONAL on sfHook, soeREQUIRED on ltHOOK_DEFINITION |
HookParameters | ARRAY (19) | sfHook, ltHOOK_DEFINITION (default set) | soeOPTIONAL on sfHook, soeREQUIRED on ltHOOK_DEFINITION |
HookOn | UINT256 (20) | sfHook, ltHOOK_DEFINITION | soeOPTIONAL in both |
HookOnIncoming | UINT256 (94) | sfHook, ltHOOK_DEFINITION | soeOPTIONAL in both |
HookOnOutgoing | UINT256 (93) | sfHook, ltHOOK_DEFINITION | soeOPTIONAL in both |
HookCanEmit | UINT256 (96) | sfHook, ltHOOK_DEFINITION | soeOPTIONAL in both |
HookApiVersion | UINT16 (20) | SetHook create input (sfHook); ltHOOK_DEFINITION only | soeOPTIONAL on create input, soeREQUIRED on ltHOOK_DEFINITION |
HookName | VL (97) | sfHook only (never ltHOOK_DEFINITION); also a common field on every transaction type | soeOPTIONAL |
Flags | UINT32 (2) | sfHook; auto-attached to every ltHOOK_DEFINITION/ledger entry (not listed explicitly in its macro); also a distinct, unrelated top-level field on every transaction | soeOPTIONAL |
HookOn, HookApiVersion, and HookGrants all show a numeric code of 20 above — this is not a collision. An SField code is only unique within its SerializedTypeID (UINT256, UINT16, ARRAY respectively here), not globally.
The exact field declarations (name, storage type, and numeric code) match the table above.
ltHOOK_DEFINITION carries sfHookHash, sfHookNamespace, sfHookParameters, sfHookApiVersion, sfCreateCode, sfHookSetTxnID, sfReferenceCount, and sfFee as required fields, and sfHookOn, sfHookOnIncoming, sfHookOnOutgoing, sfHookCanEmit, sfHookCallbackFee, sfPreviousTxnID, and sfPreviousTxnLgrSeq as optional fields.
Neither sfHookGrants nor sfHookName appear on ltHOOK_DEFINITION — grants and the display name are per-account (sfHook-entry-only) concepts, never part of the shared, hash-addressed definition (see HookGrants and HookName). sfFlags also doesn't appear in this list, but is not per-account-only — it is one of the fields auto-attached to every LEDGER_ENTRY (alongside sfLedgerIndex, sfLedgerEntryType, sfRemarks), so ltHOOK_DEFINITION does carry it in practice (see flags).
sfHookName is instead a common field on every transaction type, alongside sfHookParameters. This lets a caller target one named hook in a chain when submitting any transaction (Payment, Invoke, TrustSet, ...) — see the HookName section.
Index
Start here: operations-field-matrix — the full per-operation (CREATE/INSTALL/UPDATE/DELETE/NSDELETE/NOOP) required/optional/forbidden table for all 12 fields, with inferOperation explained and every rule cited.
| Field | Purpose |
|---|---|
| HookHash | Installs an already-uploaded WASM by hash; drives ltHOOK_DEFINITION reference counting. |
| CreateCode | Uploads new WASM (hsoCREATE) or, if empty, marks the slot for deletion (hsoDELETE). |
| HookGrants | Authorizes specific hooks to write into this hook's namespace via state_foreign_set. |
| HookNamespace | Selects the Hook State key-space a hook reads/writes; also the target of hsoNSDELETE. |
| HookParameters | Per-install/update overrides of a hook's named parameters, three-way-merged against the definition's defaults. |
| HookOn | Selects which transaction types cause a hook to fire. |
| HookOnIncoming / HookOnOutgoing | Splits HookOn into independent incoming/outgoing bit fields. |
| HookCanEmit | Restricts which transaction types a hook is permitted to emit(). |
| HookApiVersion | Declares the Hook API ABI version; on this branch, must be 0, and is stored only on ltHOOK_DEFINITION after create. |
| HookName | Names one installed hook so any transaction can target it directly. |
| flags | The hsf* control/persistent bits (hsfOVERRIDE, hsfNSDELETE, hsfCOLLECT) carried in each sfHook object's own Flags. |
| operations-field-matrix | Per-operation field legality matrix (see "Start here" above). |
Related documents
- ../overview — SetHook lifecycle, operations/flags, and the general error-code table (
EMISSION_FAILUREand others). - ../api-reference/control/README —
hook_pos,hook_skip, and other chain-position/control functions referenced by the execution model here. - ../api-reference/emit/README —
emit,etxn_reserve, and the rest of the emission API thatHookCanEmitgates. - ../glossary — definitions of
SetHook,HookOn, TSH, and other terms used throughout this page.