HookOn Field

Understanding the HookOn field

Each bit in this unsigned 256-bit integer indicates whether the Hook should execute on a particular transaction type. All bits are active low except bit 22 which is active high. Since 22 is ttHOOK_SET this means the default value of all 0’s will not fire on a SetHook transaction but will fire on every other transaction type. This is a deliberate design choice to help people avoid bricking their Xahau account with a misbehaving hook.

Bits are numbered from right to left:

• bit 0 - right most, i.e. the least significant bit.
• bit 63 - the left-most, i.e. the most significant bit.

Examples (assuming a 256-bit unsigned integer type):

1. If we want to completely disable the hook:

~(1ULL << 22) /* every bit is 1 except bit 22 which is 0 */

2. If we want to disable the hook on everything except ttPAYMENT:

~(1ULL << 22) & ~(1ULL)

3. If we want to enable the hook on everything except ttHOOK_SET

0

4. If we want to enable hook firing on ttHOOK_SET (dangerous) and every other transaction type:

(1ULL << 22)

HookOn Calculator

HookOn Calculator

HookCanEmit Field

(Added by the HookCanEmit amendment.)

HookCanEmit uses the same 256-bit bitmask syntax as HookOn but controls which transaction types a Hook is allowed to emit, rather than which types trigger it.

• Uses the same active-low semantics as HookOn, with bit 22 (ttHOOK_SET) being active high.
• If HookCanEmit is absent, the Hook may emit any transaction type, including SetHook.

HookOnIncoming and HookOnOutgoing Fields

(Added by the HookOnV2_1 amendment, which replaces the unsupported HookOnV2 amendment.)

Instead of specifying a single HookOn field, Hooks may optionally replace it with two separate fields that differentiate the direction of the triggering transaction:

• HookOnIncoming — triggers the Hook on transactions originating from another account (the Hook account is not the initiator).
• HookOnOutgoing — triggers the Hook on transactions originating from the Hook account itself.

Both fields use the same bit-field syntax as HookOn. The following rules apply, on both install and update operations:

• HookOn and HookOnIncoming/HookOnOutgoing are mutually exclusive in a Hook entry. You must use either HookOn alone or the HookOnIncoming/HookOnOutgoing pair, not both.
• HookOnIncoming and HookOnOutgoing must be supplied together. Supplying only one of them makes the entry invalid.
• The two values must differ. If they would be equal, use HookOn instead.
• Without the amendment, HookOn remains mandatory when creating a Hook.

Valid example:

{ "Hook": { "CreateCode": "...", "HookOnIncoming": "FFFF...FFBF", "HookOnOutgoing": "FFFF...FFFE", "HookNamespace": "...", "HookApiVersion": 0 } }

Invalid: HookOn together with HookOnIncoming; only HookOnOutgoing; or HookOnIncoming equal to HookOnOutgoing.

Using HookOn alone continues to work exactly as before.