Xahau Network
Testnet FaucetExplorerHooks API Docs
Xahau Network
Xahau Network
  • 🪝Xahau Documentation
    • XRPL/Xahau: What is Different?
  • 🪝Hooks
  • 🚨Concepts
    • Introduction
      • Example Usage
      • Xahau Testnet
      • Xahau Testnet Explorer
      • Examples (source code)
      • Blogs (concepts)
    • Terminology
    • Loops and Guarding
    • Compiling Hooks
    • Chaining
    • Weak and Strong
    • Collect Call
    • SetHook Transaction
    • Parameters
    • Namespaces
    • Grants
    • HookOn Field
    • Reference Counted Hook Definitions
    • Hook Fees
    • Execution Metadata
    • Debugging Hooks
    • State Management
    • Slots and Keylets
    • Floating Point Numbers (XFL)
    • Emitted Transactions
    • Serialized Objects
  • Features
    • Public Nodes (RPC)
    • Amendments
    • Transaction Signing
      • Transaction Fees
    • Developer Tooling
      • Curated Tooling
      • Client Libraries
      • Developer Tricks
    • HTTP / WebSocket APIs
      • Request Formatting Guide
      • Response Formatting Guide
      • Considerations
      • Public API Methods
      • Admin API Methods
    • Network Features
      • Account Managment
      • Balance Rewards
      • Check
      • Escrow
      • Hooks
      • Offer
      • Payments
      • URIToken
    • Faucet & Explorers
    • Data API's
  • Infrastructure
    • Node Requirements
    • Running a Node
      • Running a Mainnet Node
      • Running a Testnet Node
    • Building Xahau (Dev)
      • Ubuntu - 22.04
      • Mac OS - 15.3.2 (24D81)
  • Technical
    • 📐Hooks Functions
      • Overview
        • Hook API Conventions
        • Return Codes
      • Developer Defined
        • hook
        • cbak / Callback
      • Control
        • accept
        • rollback
      • Utilities
        • util_raddr
        • util_accid
        • util_verify
        • util_sha512h
        • util_keylet
      • Serialization
        • sto_subfield
        • sto_to_json
        • sto_from_json
        • sto_subarray
        • sto_emplace
        • sto_erase
        • sto_validate
      • Emitted Transaction
        • etxn_burden
        • etxn_details
        • etxn_fee_base
        • etxn_nonce
        • etxn_reserve
        • etxn_generation
        • prepare
        • emit
      • Float
        • float_set
        • float_multiply
        • float_mulratio
        • float_negate
        • float_compare
        • float_sum
        • float_sto
        • float_sto_set
        • float_invert
        • float_divide
        • float_one
        • float_exponent
        • float_mantissa
        • float_sign
        • float_int
        • float_root
        • float_log
      • Ledger
        • fee_base
        • ledger_seq
        • ledger_last_hash
        • ledger_last_time
        • ledger_nonce
        • ledger_keylet
      • Hook Context
        • hook_account
        • hook_hash
        • hook_param
        • hook_param_set
        • hook_skip
        • hook_pos
        • hook_again
      • Slot
        • slot
        • slot_clear
        • slot_count
        • slot_set
        • slot_size
        • slot_subarray
        • slot_subfield
        • slot_type
        • xpop_slot
        • slot_float
      • State
        • state
        • state_set
        • state_foreign
        • state_foreign_set
      • Trace (Debug)
        • trace
        • trace_num
        • trace_float
      • Originating Transaction
        • otxn_burden
        • otxn_field
        • otxn_generation
        • otxn_id
        • otxn_type
        • otxn_slot
        • otxn_param
        • otxn_json
        • meta_slot
      • Websocket APIs
        • account_info
        • account_namespace
    • Protocol Reference
      • Transactions
        • Transaction Common Fields
        • Transaction Types
          • AccountDelete
          • AccountSet
          • CheckCancel
          • CheckCash
          • CheckCreate
          • ClaimReward
          • DepositPreauth
          • EscrowCancel
          • EscrowCreate
          • EscrowFinish
          • GenesisMint - (Emitted Txn)
          • Import
          • Invoke
          • OfferCancel
          • OfferCreate
          • Payment
          • PaymentChannelClaim
          • PaymentChannelCreate
          • PaymentChannelFund
          • Remit
          • SetHook
          • SetRegularKey
          • SignerListSet
          • TicketCreate
          • TrustSet
          • URITokenBurn
          • URITokenBuy
          • URITokenCancelSellOffer
          • URITokenCreateSellOffer
          • URITokenMint
        • Pseudo Transaction Types
          • EmitFailure
          • UNLReport
          • UNLModify
          • SetFee
          • EnableAmendment
        • Transaction Results
          • TES Codes
          • TER Codes
          • TEM Codes
          • TEL Codes
          • TEF Codes
          • TEC Codes
        • Transaction Metadata
      • Ledger Data
        • Ledger Objects Types
          • AccountRoot
          • Amendments
          • Check
          • Deposit Pre Auth
          • Directory Node
          • Emitted Txn
          • Escrow
          • Fee Settings
          • Hook
          • Hook Definition
          • Hook State
          • Import VL Sequence
          • Ledger Hashes
          • Negative UNL
          • Offer
          • Pay Channel
          • Ripple State
          • Signers List
          • Ticket
          • UNL Report
          • URIToken
        • Ledger Header
        • Ledger Object IDs
      • Data Types
        • Currency Formats
        • Base 58 Encodings
      • Binary Format
    • Balance Adjustments
    • Governance Game
    • Burn 2 Mint (B2M)
    • Versioning Process
  • Compliance
    • Security Audits
      • Responsible Disclosure
  • Support
    • Help Us
Powered by GitBook
On this page
  • Grants
  • Example
  • Using the Grant

Was this helpful?

Edit on GitHub
Export as PDF
  1. Concepts

Grants

Hook Grants

Last updated 4 months ago

Was this helpful?

❗️ 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 permissions to a foreign Hook on other Xahau accounts.

A 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).

Unlike , the HookGrants array is always set exactly as specified in the . Therefore if you wish to update a particular HookGrant whilst retaining multiple other HookGrant entires that were previously set, you must first obtain the old HookGrants array, modify it, and then resubmit the entire array in an .

To delete all Grants submit an empty HookGrants array.

🚧 Important

Unlike , the HookGrants array is always set exactly as specified in the .

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

The HookGrant must specify at least:

  • HookHash And may also specify an account:

  • Authorize

Only the Hook specified by HookHash may modify the Hook State within the namespace of the Hook for which the HookGrant is specified. If Authorize is specified then this permission is tightened further to only the Hook specified by the HookHash when it is installed on the account specified by Authorize.

📘 Tip

Grants only apply to external Hooks and never limit the operation of Hooks with respect to the Hook State on the account they are installed on.

Example

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

The first grant above allows:

  • any instance of the Hook whose code that hashes to 78CAF69EEE950A6C55A450AC2A980DE434D624CD1B13148E007E28B7B6461CC8

  • executing on any account

  • 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 A5B8D62154DA1C329BE13582086B52612476720CEBD097EB85CEE1455E1C70A6

  • but only when executed 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 Management
SetHook Transaction
Parameters
SetHook Transaction
Update Operation
Parameters
SetHook Transaction
state_foreign_set