Prevent state clobbering by using the correct namespace


To avoid two or more Hooks installed on the same account unintentionally clobbering each-other's Hook State, a 32 byte namespace must be provided when creating or installing each Hook.

The namespace may be any arbitrary 32 byte value the developer chooses. Provided the namespace is unique in the Hook chain no state clobbering will occur.

We strongly recommended using SHA256 over the developer's working name for the Hook. SHA256 is one of the two hashing algorithms used in the derivation of XRPL addresses (from an account master key), and, as such, it should be readily available to the developer.

The HookNamespace field is supplied as a 32 byte hex blob inside each Hook object in a Hooks array when executing a SetHook transaction.

The configured Namespace a Hook operates under alters the Keylets its State is stored under. Therefore two Hooks under two different Namespaces installed on the same XRPL account may use the same state key to refer to different state objects. Conversely, two different Hooks using the same Namespace on the same XRPL account can access and modify eachother's state objects using the same state keys.


In javascript, importing the ripple-address-codec yields access to SHA256.
(It is also possible to use crypto.subtle in browser, or crypto.createHash in node to access this hash algorithm.)

HookNamespace: addr.codec.sha256('carbon').toString('hex')

Default Namespace

The first user to set a novel Hook defines a HookNamespace which becomes the Default Namespace for that Hook. This means any subsequent users who reference the same HookDefinition will receive this originally set Namespace by default.

The subsequent user may specify their own Namespace, overriding the Default Namespace for their installation only.

Hook APIs Affected

Choice of HookNamespace affects the behaviour of the following Hook APIs:

Namespace API Helper

See account_info and account_namespace for information about how to query the ledger regarding namespaces.

What’s Next