Grants

Hook Grants

❗️

Warning

Most Hook Developers will rarely need to use HookGrants, and should exercise extreme caution when granting state mutation permission to foreign Hooks and accounts.

While a HookGrant cannot be used to directly steal funds, intentional external modification of a Hook's State may lead a Hook to behave in an unintended way, which in some cases could lead to a theft.

If you think you need to use a Grant then please re-check your design first to ensure you actually need to use one before continuing.

Grants

Grants provide a way for a Hook Installer to assign State Management permissions to a foreign Hook or XRPL account.

A SetHook Transaction may specify a HookGrants array within any Hook object in its Hooks array. The HookGrants array contains one or more HookGrant objects (up to 8).

A HookGrant permits a foreign XRPL account or Hook to modify the Hook State within the namespace of the specific Hook for which the HookGrant is defined.

The HookGrant may specify either (or both of):

  • HookHash
  • Authorize

If HookHash is specified then the Hook specified by HookHash may modify the Hook State within the namespace of the Hook for which the HookGrant is specified, irrespective of which account it runs on.

If Authorize is specified then any Hook running on the account specified by Authorized may modify the Hook State within the namespace of the Hook for which the HookGrant is specified.

If both HookHash and Authorize are specified then the Hook specified by HookHash running on the account specified by Authorized may modify the Hook State within the namespace of the Hook for which the HookGrant is specified.

Example

Account: "rALicebv3hMYNBWtu1VEEWkToArgYsYERs",
TransactionType: "SetHook",
Hooks:
[   
    {   
        Hook: {
            ...,
            HookNamespace: "3963ADEB1B0E8934C0963680531202FD511FF1E16D5864402C2DA63861C420A8",
            HookGrants:
            [   
                {   
                    HookGrant:     // first grant
                    {   
                        Authorize:  "rBobg6BSXPm8DLTGfqub7JbEPPk9AsyBX2"
                    },
                    HookGrant:    // second grant
                    {   
                        HookHash:  "78CAF69EEE950A6C55A450AC2A980DE434D624CD1B13148E007E28B7B6461CC8"
                    },
                    HookGrant:    // third grant
                    {   
                        Authorize: "rCLairev2ma2gNZdcHJeTk7fCQ1ki84vr9",
                        HookHash:  "A5B8D62154DA1C329BE13582086B52612476720CEBD097EB85CEE1455E1C70A6"
                    },
                },  
            ]   
        }   
    }   
],  
... 

The first grant above allows:

  • any Hook
  • executing on account rBobg6BSXPm8DLTGfqub7JbEPPk9AsyBX2
  • to modify the Hook State of account rALicebv3hMYNBWtu1VEEWkToArgYsYERs
  • inside the Namespace 3963ADEB1B0E8934C0963680531202FD511FF1E16D5864402C2DA63861C420A8

The second grant above allows:

  • any instance of the Hook whose code that hashes to 9BE43A0058FF4C358015CD89CE754AFEF201A6FF3D7E2C868B8C7E61DB00BD68
  • executing on any account
  • to modify the Hook State of account rALicebv3hMYNBWtu1VEEWkToArgYsYERs
  • inside the Namespace 3963ADEB1B0E8934C0963680531202FD511FF1E16D5864402C2DA63861C420A8

The third grant above allows:

  • any instance of the Hook whose code that hashes to A5B8D62154DA1C329BE13582086B52612476720CEBD097EB85CEE1455E1C70A6
  • executing on account rCLairev2ma2gNZdcHJeTk7fCQ1ki84vr9
  • to modify the Hook State of account rALicebv3hMYNBWtu1VEEWkToArgYsYERs
  • inside the Namespace 3963ADEB1B0E8934C0963680531202FD511FF1E16D5864402C2DA63861C420A8

Using the Grant

To make use of a grant, a Hook modifies State objects on a foreign account by calling state_foreign_set.


What’s Next