Welcome to the Xahau Documentation. This is your comprehensive guide to understanding and working with Xahau. This documentation is divided into three main categories: Features, Infrastructure, and Technical.

Each category is designed to provide you with detailed insights and instructions about different aspects of Xahau.

Features

The Features section is where you'll find information about the unique aspects of Xahau. One of the key areas covered in this section is Developer Tooling.

Our Developer Tooling page covers Hooks Tools and Client Libraries, simplifying the process of interacting with Hooks and the Xahau Ledger. This section is designed to help you understand the functionality and capabilities of Xahau, with practical examples to help illustrate these features in action.

Infrastructure

The Infrastructure section provides detailed instructions for setting up the build environment on both Ubuntu 22.04 and macOS 13.5.2.

In the 'Building Xahau' chapter, you will find a step-by-step guide through the process of establishing environmental variables, installing core and Xahaud dependencies, and compiling the software.

This includes the acquisition and setup of essential components like LLVM, Boost, WasmEdge, and Protobuf. The steps explain why certain versions and configurations are needed to ensure compatibility and optimal performance.

This section ends with cloning the Xahau repository and creating the Xahaud target, setting developers on the path to adding to or deploying the Xahau network.

Technical

The Technical section of Xahau's documentation provides an in-depth look at the platform's unique aspects, including various transaction types like AccountDelete, CheckCancel, and Payment, each with its own specific use and characteristics.

It also covers the different ledger objects integral to the network's operation, such as AccountRoot and Amendments. This comprehensive overview aims to enhance the understanding of Xahau's functionalities and capabilities, ensuring users can fully leverage the network's features.

We hope this documentation provides you with the information you need to understand, use, and contribute to Xahau. Happy exploring!

IOU Token Escrow & PayChannels

Xahau introduces IOU Token Escrow and PayChannels as unique features, enhancing transaction flexibility and security. They facilitate the temporary holding of IOU tokens under predefined conditions (escrow) and the establishment of payment channels for efficient, off-ledger transactions.

URITokens NOT NFTokens

Instead of using NFTokens like XRPL, Xahau employs URITokens. URITokens are a form of non-fungible digital assets with unique identifiers and metadata, offering a novel approach to asset representation on the blockchain.

Different Repo

Xahau and XRPL operate from different repositories, signifying that they are separate protocols with their own development trajectories and documentation. This distinction implies that Xahau may offer unique features and optimizations not found in XRPL.

https://github.com/Xahau/xahaud

Different Build Process (WASM & LLVM)

Xahau's build process incorporates WebAssembly (WASM) and the Low-Level Virtual Machine (LLVM), which is not described in the XRPL build process. Xahau is utilizing these technologies for enhanced smart contract capabilities and to improve the performance and cross-platform compatibility of its codebase.

Different Amendment Time (5 days)

The amendment process in Xahau has a specified time frame of 5 days, differing from XRPL's timeline. Amendments are protocol changes, and the 5-day period refers to the duration validators have to reach a consensus and implement these changes.

Different Starting Sequence

Xahau employs a different starting sequence for accounts than XRPL. The initial sequence on the account is the ripple epoch time when the account was create/imported into Xahau.

Import / Burn 2 Mint

Importing from XRPL to Xahau grants users 2 XAH tokens, indicating an incentive mechanism to encourage asset migration or bridging from XRPL to Xahau, potentially to enhance network adoption and liquidity.

Balance Rewards (Rewards for using XAH)

Xahau offers balance rewards for utilizing XAH, a feature absent in XRPL. This is a reward system for holding or using Xahau's native token, XAH, to promote network engagement and stability.

Hooks

Hooks in Xahau, which are not present in XRPL, are programmable scripts or smart contract-like functions that can be attached to accounts. They add a layer of programmability and automation to the network's operations.

Governance Structure

Xahau's governance structure differs from XRPL's. Xahau has its own approach to decision-making, proposal systems, or validator roles, which could influence the network's evolution.

Node Requirements

Running a Xahau node has different requirements compared to an XRPL node. These differences could be related to the technical specifications needed to support Xahau's unique features and network demands.

Native Token

Xahau's native token is XAH, distinct from XRPL's XRP. As the primary currency within the Xahau network, XAH likely serves as the main medium of exchange and a store of value, central to the network's economic framework.

Versioning (Uses Dates)

Xahau employs a date-based versioning system, unlike XRPL's versioning approach. This method may provide a more intuitive means of tracking the network's updates and historical development.

Please read the introduction of Hooks in this blog.

While working on Hooks we published a number of blogs on our progress, insights & Hooks concepts. You can read all about that in our blogs on Dev.to

Examples (scenarios)

1. Receiving Hook executes additional logic

2. Receiving Hook blocks incoming transaction

3. Sending Hook blocks outgoing transaction

4. Hook controls an institutional account

What are Hooks?

Hooks are small, efficient web assembly modules designed specifically for Xahau. Hooks can be written in any language (compilable to WebAssembly) and most business logic and most smart contract concepts can be implemented in a hook. Typically Hooks are written in C.

Hooks are set onto an Xahau account using a SetHook transaction. Once installed on an account, a hook can:

1. Block or allow incoming and outgoing transactions on the account,

2. Modify and maintain internal state and logic specific to the hook on that account, and

3. Emit new transactions on behalf of the account.

Glossary

This Hooks documentation and the Hooks API use a set of unfamiliar terms. Use the lookup table below if you find yourself lost.

What are guards?

Hooks are deliberately not . This means arbitrary looping is forbidden. Instead you must guard your loops against a hard "maximum iteration" boundary.

A guard is a marker placed in your code at the top of each loop. The marker informs the Xahau what the upper bound of your loop will be in every possible scenario. Thus if your loop usually executes twice but sometimes executes 500 times, then your guard will say 500.

Guards are used by the Xahau to determine the worst case execution time (in instructions) of your Hook before execution. This is the basis for the fee the Xahau charges for the execution of a Hook and makes execution times predictable and controllable.

🚧 Tip

Existing developers migrating from other smart contract platforms may find guards to be annoying at first but once you get used to them they are no harder to use than a normal for-loop.

The guard function

The guard function tells the ledger the maximum number of iterations a loop will make. Specifically the function takes two arguments:

The first argument id is the identifier for this guard. This is a unique constant chosen by the developer, typically the line number in the source file is used.

The second argument maxiter is a promise the developer makes to the ledger that this guard will not be hit more than maxiter times during the execution of the Hook. If the guard call is executed more than this many times the Hook will automatically rollback with a GUARD_VIOLATION (). Because the guard will be hit before the loop condition is checked, it is important to add one to the total number of expected iterations. (Note: The GUARD() macro already adds one).

❗️ Pay Attention

Guards must be set using numerical literals. You cannot use a variable or runtime value in a Guard.

Guard enforcement

Consider the following for-loop in C:

In C, the comma operator executes each expression in a list of expressions (e.g. A, B, C) and returns the last expression (e.g. C). Thus the condition above is still i < 3, but the guard is called before the condition is checked. This is the only way to satisify the guard rule when using a for-loop in C.

👍 The Guard Rule

A call to _g (the guard function) is must be the first branch instruction after a loop instruction.

Below appears the webassembly output when the above is compiled. Note the guard function being called at the start of the loop. The only instructions allowed before this call are non-branch instructions (typically manipulating constants.)

Nested Loops

When using nested loops the maxiter argument must reflect the total number of times the guard will be hit. This means you must multiply the nestings together.

Consider the example below:

Notice the inner-loop's guard is set to 15. You must multiply the loops together to compute the maximum number of times an inner guard will be hit during Hook execution.

No recursion

Calls to non-Hook API functions are disallowed in the Hooks ammendment. All user code must fit within the two allowed Hook functions cbak and hook.

❗️ Warning

Failure to use guards correctly will cause an attempted SetHook transaction to be rejected.

👍 Hook Design Philosophy

Every party affected by a transaction should have the opportunity to have their Hooks executed.

Transactional Stake Holders (TSH) are parties that somehow have a stake in or are otherwise affected by a transaction. Their particular stake may be a weak or strong. The degree of connection with the transaction dictates whether the party has the right to have their Hooks executed and who has to pay for that execution.

For example:

• In a conventional direct XAH Payment transaction the two TSH are the originating account and the destination account.

• In a SetSignerList transaction the TSH are the originating account and each account whose address appears in the signer list, where such accounts are active on the ledger.

• In an OfferCreate transaction, other account's offers which are crossed by the originating transaction are all weak TSH and may opt for weak execution.

Due to the heterogenous nature of transactions on Xahau, TSH come in all shapes and sizes and can be exotic and non-intuitive. This becomes more true as time passes and more transaction types are added to the Ledger.

Weak and Strong

Each TSH has either a weak or a strong connection to the transaction.

A Strong connection means:

1. The originating transaction must pay the fee for the execution of the TSH Hook Chain

2. The TSH has the right to rollback the whole transaction by calling rollback() from their Hook during execution.

A Weak connection means:

1. The originating transaction does not pay for the execution of the TSH Hook Chain.

2. The TSH pays for the execution of their own Hook Chain through a feature called .

3. The TSH must have set an account flag asfTshCollect prior to the execution of the originating transaction.

4. The TSH does not have the right to rollback the whole transaction by calling rollback() from their Hook during execution (but can still modify their own Hook state and Emit transactions.)

Before or After

📘 Hint

Execution Context

The uint32_t parameter in hook(uint32_t) and cbak(uint32_t) carries important context information from the Hooks Amendment to your Hook.

During the execution of hook:

• 0 means the Hook is being executed strongly

• 1 means the Hook is being executed weakly

During the execution of cbak:

• 0 means the Hook is being called back after a transaction it emitted was successfully accepted into a ledger.

• 1 means the Hook is being called back after a transaction it emitted was marked as never able to be applied to any ledger (EmitFailure).

Reference Table

If a Transaction Type does not appear in the table then it has no TSHes other than its originating account.

AccountSet

AccountDelete

Check

ClaimReward

DepositPreauth

Escrow

GenesisMint

Import

Invoke

Offer

Payment

PaymentChannel

SetHook

SetRegularKey

SignersListSet

Ticket

TrustSet

URIToken

👍 Hook Design Philosophy

Each Hook should do one thing, and do it really well.

History

In the early days of Hooks it was only possible to install one Hook per account. This meant users were forced to produce omnibus Hooks if they wanted to do more than one thing: for example offset carbon and firewall at the same time.

This was counter to the Hook Design Philosophy, so Hook Chaining was introduced.

Chaining

A Hook Chain is a sequence of up to 10 Hooks installed on an Xahau account.

• A Hook Chain executes successfully when every Hook in the chain has been individually executed and subsequently calls .

• Each chain's execution starts at chain position 0 and ends at chain position 9. If a position is blank (because it was never filled or because the hook that was installed there has been removed) then that position is skipped and treated as successful.

• In order for a transaction to succeed, both ends of the transaction (sending side and receiving side) must have executed successfully. This means if there is a Hook Chain installed on both sides, then both Hook Chains must execute successfully for the transaction to succeed.

Hooks are installed into the chain using the . When they are installed, the installer may specify install-time which may change the behaviour of the installed Hook.

Chain Manipulation

Weak Executions

1. cbak execution if this was an Emitted Transaction.

3. Any Again as Weak (AAW) Hooks. Execution order for AAW is first numerically according to Account ID then numerically according to Hook position.

Parameters

Hook developers may opt to use install-time parameters (called Hook Parameters) in their Hook. This allows subsequent installers of the Hook to change certain behaviours the programmer defines without recompiling or re-uploading the Hook (assuming at least one account still references the existing Hook Definition.)

Hook Parameters are a set of Key-Value pairs set during the SetHook Transaction and retrievable by the Hook during runtime. Both the ParameterName (key) and the ParameterValue are set as hex blobs, and have a maximum length of 32 bytes and 256 bytes respectively.

A SetHook Transaction may define up to 16 Hook Parameters per installed Hook.

Setting Parameters

The HookParameters array is optionally defined inside each Hook in the Hooks array as shown below:

TransactionType: "SetHook",
Hooks:
[   
    {   
        Hook: {
            ...,
            HookParameters:
            [   
                {   
                    HookParameter:
                    {   
                        HookParameterName:  "ABCDEF12",
                        HookParameterValue: "12345678"
                    }   
                },  
                ...  // optionally up to 15 more Hook Parameters
            ]   
        }   
    }   
],  
... 

Default Parameters

The first user to set a novel Hook may define Hook Parameters which then become the Default Parameters for that Hook. This means any subsequent users who references the same HookDefinition will receive these originally set Hook Parameters by default.

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

To erase a Parameter in a subsequent installation, specify the ParameterName key without specifying a ParameterValue key.

Using Parameters in Hooks

Parameters can be read by the Hooks they are set on using hook_param.

If more than one Hook is installed in a Hook Chain, then hook_param_set can be used in limited circumstances to modify the Hook Parameters of a Hook further down the chain on the same account.

Runtime Parameters

On Xahau and the Xahau testnet, HookParameters may also be included at the top level of any transaction type according to the foregoing rules and size limits. These parameters can be accessed inside a hook using the otxn_param API.

Namespaces

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 Xahau 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 Xahau account may use the same state key to refer to different state objects. Conversely, two different Hooks using the same Namespace on the same Xahau account can access and modify eachother's state objects using the same state keys.

Example

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:

• state

• state_set

Namespace API Helper

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

❗️ 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 on other Xahau accounts.

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

Unlike Parameters, the HookGrants array is always set exactly as specified in the SetHook Transaction. 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 Update Operation.

To delete all Grants submit an empty HookGrants array.

🚧 Important

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

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_foreign_set.

Hooks add smart contract functionality to Xahau: 'layer one' custom code to influence the behaviour and flow of transactions. Hooks are small, efficient pieces of code being defined on an Xahau account, allowing logic to be executed before and/or after Xahau transactions.

Xahau is known and is being appreciated for its transaction throughput, speed and the low fees. Combined with available advanced transaction types like multi sign, escrows, payment channels and even a decentralized exchange (all on ledger, out of the box, without requiring smart contracts) the Xahau has a lot to offer businesses and (creative) developers.

Constraints

All Hooks are compiled to a single webassembly module before they can be set onto an Xahau account.

A Hook always implements and exports exactly one or both of the following functions:

int64_t hook(uint32_t ctx) { ... } required

• Executed whenever a transaction comes into or leaves from the account the Hook is set on (ctx = 0) or

• Executed when executed as a Weak Transactional Stakeholder (ctx > 0).

int64_t cbak(uint32_t ctx) { ... } optional

• Executed when an emitted transaction is successfully accepted into a ledger (ctx = 0) or

• Executed when an emitted transaction cannot be accepted into any ledger (ctx = 1).

Hooks are not allowed to specify other functions. Instead they must make clever use of macros to do all their computation within these two functions. This is part of a computational restriction on hooks to keep their runtime predictable.

Additionally Hooks are afforded no heap memory. All required memory must be reserved and used on the stack.

Example

Here is an example Hook written in C. The Hook prints 0...3 to the trace log before accepting the originating transaction.

#include <stdint.h>
#define GUARD(maxiter) _g(__LINE__, (maxiter)+1)
extern int32_t _g (uint32_t id, uint32_t maxiter);
extern int64_t accept (uint32_t read_ptr, uint32_t read_len, int64_t error_code);
extern int64_t trace_num (uint32_t read_ptr, uint32_t read_len, int64_t number);

int64_t hook(uint32_t ctx)
{
    for (int i = 0; GUARD(3), i < 3; ++i)
    {
        trace_num("test", 4, i);
    }
    accept (0,0,0); 
    return 0;
}

📘 Hint

For educational purposes the above example deliberately does not include hookapi.h (which developers would typically use.)

Compilation

A variety of compilers will generate valid webassembly from a C source file. Once compiled, a Hook exists as a binary .wasm file. This contains a webassembly module. Using wasmcc to compile and the wasm2wat tool to convert to human readable webassembly this binary form can be rendered to the human readable form. Below appears the compilation result of the above example.

(module
  (type (;0;) (func (param i32 i32) (result i32)))
  (type (;1;) (func (param i32 i32 i64) (result i64)))
  (type (;2;) (func))
  (type (;3;) (func (param i32) (result i64)))
  (import "env" "_g" (func $_g (type 0)))
  (import "env" "trace_num" (func $trace_num (type 1)))
  (import "env" "accept" (func $accept (type 1)))
  (func $__wasm_call_ctors (type 2))
  (func $cbak (type 3) (param i32) (result i64)
    (local i32 i32 i32 i64)
    global.get 0
    local.set 1
    i32.const 16
    local.set 2
    local.get 1
    local.get 2
    i32.sub
    local.set 3
    i64.const 0
    local.set 4
    local.get 3
    local.get 0
    i64.store offset=8
    local.get 4
    return)
  (func $hook (type 3) (param i32) (result i64)
    (local i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i32 i64 i32 i32 i32 i64 i32 i32 i32)
    global.get 0
    local.set 1
    i32.const 16
    local.set 2
    local.get 1
    local.get 2
    i32.sub
    local.set 3
    local.get 3
    global.set 0
    i32.const 0
    local.set 4
    local.get 3
    local.get 0
    i64.store offset=8
    local.get 3
    local.get 4
    i32.store offset=4
    block  ;; label = @1
      loop  ;; label = @2
        i32.const 3
        local.set 5
        i32.const 14
        local.set 6
        i32.const 4
        local.set 7
        local.get 6
        local.get 7
        call $_g
        drop
        local.get 3
        i32.load offset=4
        local.set 8
        local.get 8
        local.set 9
        local.get 5
        local.set 10
        local.get 9
        local.get 10
        i32.lt_s
        local.set 11
        i32.const 1
        local.set 12
        local.get 11
        local.get 12
        i32.and
        local.set 13
        local.get 13
        i32.eqz
        br_if 1 (;@1;)
        i32.const 1024
        local.set 14
        i32.const 4
        local.set 15
        local.get 3
        i32.load offset=4
        local.set 16
        local.get 16
        local.set 17
        local.get 17
        i64.extend_i32_s
        local.set 18
        local.get 14
        local.get 15
        local.get 18
        call $trace_num
        drop
        local.get 3
        i32.load offset=4
        local.set 19
        i32.const 1
        local.set 20
        local.get 19
        local.get 20
        i32.add
        local.set 21
        local.get 3
        local.get 21
        i32.store offset=4
        br 0 (;@2;)
      end
    end
    i64.const 0
    local.set 22
    i32.const 0
    local.set 23
    local.get 23
    local.get 23
    local.get 22
    call $accept
    drop
    i32.const 16
    local.set 24
    local.get 3
    local.get 24
    i32.add
    local.set 25
    local.get 25
    global.set 0
    local.get 22
    return)
  (table (;0;) 1 1 funcref)
  (memory (;0;) 2)
  (global (;0;) (mut i32) (i32.const 66576))
  (global (;1;) i32 (i32.const 1029))
  (global (;2;) i32 (i32.const 1024))
  (global (;3;) i32 (i32.const 66576))
  (global (;4;) i32 (i32.const 1024))
  (export "memory" (memory 0))
  (export "__wasm_call_ctors" (func $__wasm_call_ctors))
  (export "__data_end" (global 1))
  (export "__global_base" (global 2))
  (export "__heap_base" (global 3))
  (export "__dso_handle" (global 4))
  (export "cbak" (func $cbak))
  (export "hook" (func $hook))
  (data (;0;) (i32.const 1024) "test\00"))

The average Hook developer will never need to examine webassembly directly. However it is a useful conceptual exercise to review the contents of the sample Hook.

Above we can see:

• Three functions are imported from the Hooks API (_g, accept, trace_num)

• Two functions are defined by the hook (cbak, hook)

• Two functions are exported by the hook (again: cbak, hook)

• Some static (constant) data is recorded in the hook (see data at the bottom).

It is very important to note that a Hook must only import functions available to it from the Hooks API and must only export the cbak and hook functions. In additional all hooks must import _g from the Hooks API, which is the guard function.

📘 Hint

Webassembly is a platform-independent general computation bytecode language. It has a one-to-one mapping with a human readable equivalent. These are used interchangeably.

Unwanted Exports

Most webassembly compilers (including the one above) produce additional exports for their own linking purposes. In many cases the generation of these is difficult or impossible to disable.

Unwanted exports will lead to an otherwise valid Hook being rejected. Therefore after compilation developers should use the Hook Cleaner Utility to strip out these out. Failure to do so will lead to your Hook being rejected.

❗️ Important

Don't forget to use the Hook Cleaner Utility or your Hooks will be rejected.

What is Hook State?

State in computer science describes information held by a system between executions (as distinct from inputs and outputs.) For example your browser leaves you logged in to a website even after you close and reopen it. The login cookie is held in the browser's state.

Hook State refers to a key-value mapping that logically exists for each account on Xahau whether or not any keys are currently present. The keys are always 32 bytes (unsigned 256 bit integer) and the values are variable length with a maximum size determined by validator voting, at time of writing 256 bytes.

State Management is achieved using

• state

• state_set

• state_foreign

Storing and fetching

The below example uses the state_set Hook API to assign the value 0xC001CAFE to the key 0x0..000001 (uint256 = 1) in the Hook State of the Hook Account.

uint8_t key[32] = {
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U,
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U,
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U,
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x01U
};
uint8_t value[4] = { 0xC0U, 0x01U, 0xCAU, 0xFEU };
if (state_set(value, 4, key, 32) == 4)
{
    // ... state successfully saved
}

In a subsequent Hook execution this value can now be retrieved using the same key:

uint8_t value[4];
uint8_t key[32] = {
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U,
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U,
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U,
    0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x01U
};
if (state(value, 4, key, 32) < 0)
{
    // ... state fetch failed
}

After the above code has run the value buffer will be populated with the value found at the key.

📘 Hint

The buffer state() reads into (writeptr) must be large enough to store the value currently held at that key. If it isn't the Hook API returns with a TOO_SMALL error.

Foreign state

From time to time it may be advantageous for one Hook running on one account to read the Hook State of another Hook running on another account. The state_foreign Hook API does exactly this. Because the ledger is public there is no reasonable expectation of privacy anyway. Any Hook may therefore read (but not write) the Hook State of any other Hook.

Namespaces and querying

Please see Namespaces

Hook Creation Fees

SetHook transactions are charged per byte of created webassembly. The rate is 10000 drops per byte. Thus a 1kib Hook will cost 10 XAH to create.

Hook Execution Fees

When Hooks are Strongly Executed the originating transaction must pay for the Strong Executions in the originating transaction's fee.

Hook Execution fees are charged at a rate of 1 drop per web assembly instruction in the worst-case execution of the function hook (or cbak in the case of a callback). Thus a small Hook with a lot of looping may end up attracting high runtime fees.

Fee RPC Helper

Transaction fees on a ledger with the Hooks Amendment enabled become non-trivial to compute for end-users and/or wallet applications. This is because strong hooks must be paid for by the originator of a transaction, and there may be as many as 4 strong hooks on the sending account and 4 on the receiving account, as well as any other strong transactional stakeholders involved (as can be the case with some exotic transaction types). Further, if the transaction is a SetHook then the size of the parameters, the size of the code and whether it is a create operation or an install operation all determine the size of the fee.

Therefore it is highly recommended that all transactions be run through the updated fee RPC call before they are submitted to the ledger.

To invoke the RPC call:

1. Open a websocket connection to the Hooks node you will be working with.

2. Compose the serialized transaction you wish to know the fee for with the following:

• Fee: "0"

• SigningPubKey: "" (That is: 0 byte VL of type 0x73. In hex:0x7300.)

• Do not sign the transaction.

1. Submit it as a hex blob to the RPC as follows:

{"command":"fee", "tx_blob":"<hex blob>"}

For HTTP POST RPC submit it as follows:

{"method":"fee", "params": [{"tx_blob":"<hex blob>"}] }

The response should look something like

{
  result: {
    drops: {
      base_fee: '130520',
    },
  //...
  },
  type: 'response'
}

Take the base fee and set it as the Fee field in the transaction. Now sign and submit it as per the normal transaction submission process.

If there is an invalid value for tx_blob or tx_blob is missing, a regular JSON result will be returned with a base_fee of 10.

Emission Fees

Hooks have access to the same computation the Fee RPC Helper does. To use this simply call etxn_fee_base with a buffer containing the serialised transaction as the arguments. As with the RPC call, you must ensure that the Fee field is present in the serialised transaction. The value is irrelevant.

When etxn_fee_base returns the recommended fee you may use sto_emplace to emplace it into the serialised transaction before emission. The relevant field is sfFee.

SetHook Transaction

Hook web assembly bytecode is installed onto an Xahau account using the SetHook transaction.

An example appears below:

{ 
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Fee: "2000000",
    Hooks:
    [        
        {                        
            Hook: {                
                CreateCode: fs.readFileSync('accept.wasm').toString('hex').toUpperCase(),
                HookOn: '0000000000000000',
                HookNamespace: addr.codec.sha256('accept').toString('hex').toUpperCase(),
                HookApiVersion: 0
            }
        }
    ]
}

The transaction is deceptively simple, but hides significant complexity, described below.

Hooks Array

The main body of the SetHook transaction is the hooks array:

{
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Hooks:                         // This is the Hooks Array
    [            
          {  Hook: { ... }  },     // HookSet Object (position 0)
          {  Hook: { ... }  },  
          {  Hook: { ... }  },  
          {  Hook: { ... }  }.     // HookSet Object (position 3)
    ]
}

This array mirrors the Hook Chain installed on the account:

• Position 0 in the array corresponds to position 0 in the Hook Chain.

• Position 3 in the array corresponds to position 3 in the Hook Chain, etc.

HookSet Object and Corresponding Hook

Each entry in the Hooks Array (in the SetHook Transaction) is called a HookSet Object, and its corresponding Hook in the account's Hook Chain is called the Corresponding Hook.

HookDefinition

Each Corresponding Hook is an object containing a reference (pointer) to a HookDefinition object.

The HookDefinition object is an unowned reference-counted ledger object that provides for de-duplication of identical web assembly bytecode. Two users using an identical hook will both point to the same HookDefinition.

For more information see: Reference Counting

Hook Defaults

When a HookDefinition is created it contains the initial Parameters, Namespace and Grants supplied by the user. These become the Hook Defaults. Any Hook referencing this Hook Definition will use these defaults unless the SetHook Transaction that creates that reference explicitly overrides those defaults, or a subsequent Update Operation overrides them.

HookSet Operations

There are six possible operations: No Operation, Create, Update, Delete, Install and Namespace Delete

Each operation is specified by the inclusion or omission of certain HookSet Object fields. This might seem confusing at first but by working through a few examples the reader should find it intuitive; Essentially HookSet operations are a type of diff between a specific Hook's defaults, existing and newly specified fields.

Achieving each type of operation is explained in a subsection below.

No Operation

Occurs when:

• The HookSet Object is empty

Behaviour:

• No change of any kind is made.

Example:

{ 
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Fee: "2000000",
    Hooks:
    [        
        {                        
            Hook: {}
        }
    ]
}

Create Operation

Occurs when:

All of the following conditions are met:

• The Corresponding Hook does not exist orFLAG_OVERRIDE is specified.

• CreateCode field is specified and is not blank and contains the valid web assembly bytecode for a valid Hook.

• No instance of the same web assembly bytecode already exists on Xahau. (If it does and all other requirements are met then interpret as an Install Operation — see below.)

Behaviour:

• A reference counted HookDefinition object is created on Xahau containing the fields in the HookSet Object, with all specified fields (Namespace, Parameters, HookOn) becoming defaults (but not Grants.)

• A Hooks array is created on the executing account, if it doesn't already exist. (This is the structure that contains the Corresponding Hooks.)

• A Hook object is created at the Corresponding Hook position if one does not already exist.

• The Hook object points at the HookDefinition.

• The Hook object contains no fields except HookHash which points at the created HookDefinition.

• If hsfNSDELETE flag is specified then any HookState entires in the destination namespace are deleted if they currently exist.

Example:

{ 
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Fee: "2000000",
    Hooks:
    [        
        {                        
            Hook: {                
                CreateCode: fs.readFileSync('accept.wasm').toString('hex').toUpperCase(),
                HookOn: '0000000000000000',
                HookNamespace: addr.codec.sha256('accept').toString('hex').toUpperCase(),
                HookApiVersion: 0
            }
        }
    ]
}

Install Operation

Occurs when:

All of the following conditions are met:

• The Corresponding Hook does not exist orFLAG_OVERRIDE is specified.

• HookHash field is specified and is not blank and contains the hash of a Hook that already exists as a HookDefinition on the ledger or CreateCode field is specified and is not blank and contains the valid web assembly bytecode for a valid hook that already exists on the ledger as a HookDefinition.

Behaviour:

• The reference count of the HookDefinition object is incremented.

• A Hooks array is created on the executing account, if it doesn't already exist. (This is the structure that contains the Corresponding Hooks.)

• A Hook object is created at the Corresponding Hook position if one does not already exist.

• The Hook object points at the HookDefinition.

• The Hook object contains all the fields in the HookSet Object, except and unless:

• A field or key-pair within a field is identical to the Hook Defaults set on the HookDefinition, in which case it is omitted due to defaults.

• If hsfNSDELETE flag is specified then any HookState entires in the destination namespace are deleted if they currently exist.

Example:

{ 
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Fee: "2000000",
    Hooks:
    [        
        {                        
            Hook: {                
                HookHash: "A5663784D04ED1B4408C6B97193464D27C9C3334AAF8BBB4FA5EB8E557FC4A2C",
                HookOn: '0000000000000000',
                HookNamespace: addr.codec.sha256('accept').toString('hex').toUpperCase(),
            }
        }
    ]
}

Update Operation

Occurs when:

All of the following conditions are met:

• The Corresponding Hook exists.

• HookHash is absent.

• CreateCode is absent.

• One or more of HookNamespace, HookParameters or HookGrants is present.

General Behaviour:

• The Corresponding Hook is updated in such a way that the desired changes are reflected in the Corresponding Hook.

Specific Behaviour:

If HookNamespace is specified and differs from the Corresponding Hook's Namespace:

• the Corresponding Hook's HookNamespace is updated, and

• if the hsfNSDELETE flag is specified all HookState entires in the old namespace are deleted.

If HookParameters is specified, then for each entry:

• If HookParameterName exists but HookParameterValue is absent and the Corresponding Hook's Parameters (either specifically or via defaults) contains this HookParameterName then the parameter is marked as deleted on the Corresponding Hook.

• If HookParameterName exists and HookParameterValue exists then the Corresponding Hook's Parameters are modified to include the new or updated parameter.

If HookGrants is specified then:

• The Corresponding Hook's HookGrants array is replaced with the array.

Example:

{ 
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Fee: "2000000",
    Hooks:
    [        
        {                        
            Hook: {
                HookNamespace: addr.codec.sha256('new_accept').toString('hex').toUpperCase(),
            }
        }
    ]
}

Delete Operation

Occurs when:

All of the following conditions are met:

• The Corresponding Hook exists.

• hsfOVERRIDE is specified.

• optionally hsfNSDELETE is also specified.

• HookHash is absent.

• CreateCode is present but empty.

Behaviour:

• The reference count of the HookDefinition object is decremented.

• If the reference count is now zero the HookDefintion is removed from the ledger.

• The Hook object in the Corresponding Hook position is deleted, leaving an empty position.

• If hsfNSDELETE is specified the namespace and all HookState entries are also deleted.

Example:

{ 
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Fee: "2000000",
    Hooks:
    [        
        {                        
            Hook: {
                CreateCode: "",
                Flags: 1,
            }
        }
    ]
}

Namespace Reset

Occurs when:

All of the following conditions are met:

• flags is present and hsfNSDELETE is set. hsfOVERRIDE can optionally also be specified if the Hook at this position is to be deleted.

• HookNamespace is specified.

• CreateCode is absent.

• HookHash is absent.

• HookGrants, HookParameters, HookOn and HookApiVersion are absent.

Behaviour:

• If the Corresponding Hook exists, it remains, nothing happens to it.

• A subset of HookState objects and the HookState directory for the specified namespace are removed from the ledger, up to the defined limit of 512. Further transactions are needed to continue the deletion process until all relevant records are removed.

Example:

{ 
    Account: "r4GDFMLGJUKMjNhhycgt2d5LXCdXzCYPoc",
    TransactionType: "SetHook",
    Fee: "2000000",
    Hooks:
    [        
        {                        
            Hook: {
              	HookNamespace: addr.codec.sha256('accept').toString('hex').toUpperCase(),
                Flags: 3,
            }
        }
    ]
}

How can I debug a Hook?

The Hook API provides a set of functions in the namespace trace which write output to the xrpld log file when xrpld is configured with the trace log-level. These functions, generally speaking, allow you to see the value of variables, buffers and otherwise trace the execution and state of a Hook at runtime.

📘 Hint

At time of writing there is no interactive Hook Debugger. You must use the trace functions.

Trace APIs

The following trace functions are available in the Hooks API

Example

The following code will print a single trace line then accept the Originating Transaction.

#include "../hookapi.h"
int64_t hook(int64_t reserved)
{
  trace_num(SBUF("A number"), 10);
  accept(0,0,0);
  return 0;
}

An example of the log-line produced by xahaud when a payment is sent out of or into the Hook Account:

2021-Apr-13 13:59:11.083700726 UTC View:TRC
    HookTrace[rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh-rE3SfnjwfzZFL3JK9cLVfJuy8Ar1XnCqPw]:
        A number 10

The above appears in the log as all-one-line, but split here for visibility.

👍 Use testnet

The Xahau Testnet is the perfect place to test your Hooks.

Log format

A breakdown of the log format appears in the table below

🚧 Tip

Xahaud produces a lot of output. It is therefore generally advisible to grep logs for the account/s you are interested in. For example use: tail -f log | grep HookTrace | grep <account>

👍 Hook Design Philosophy

Every party affected by a transaction should have the opportunity to have their hooks executed.

When hooks are not Strongly Executed it is unfair to bill the originating transaction for their execution. For example an OfferCreate which crosses 20 offers on the DEX should not be forced to pay for the execution of each of those account's Hooks.

Therefore during typical Weak execution the fee for the execution is collected from the owner of the Hook. To enable this:

• The Hook owner must have set asfTshCollect on their Xahau account using the AccountSet transaction.

• The Hook owner must have set hsfCollect on the specific Hook they wish to be called as a Weak TSH.

Fee Responsibility Table

🚧 Warning

This is an advanced feature most Hook Developers will probably not use.

Hooks add smart contract functionality to the Xahau: layer one custom code to influence the behaviour and flow of transactions. Hooks are small, efficient pieces of code being defined on an Xahau account, allowing logic to be executed before and/or after Xahau transactions.

Xahau is known and is being appreciated for its transaction throughput, speed and the low fees. Combined with available advanced transaction types like multi sign, escrows, payment channels and even a decentralized exchange (all on ledger, out of the box, without requiring smart contracts) Xahau has a lot to offer businesses and (creative) developers.

Hooks add smart contract functionality to Xahau: layer one custom code to influence the behaviour and flow of transactions. Hooks are small, efficient pieces of code being defined on an Xahau account, allowing logic to be executed before and/or after Xahau transactions. These Hooks can be really simple, like: “reject payments < 10 XAH”, or “for all outgoing payments, send 10% to my savings account” or more advanced.

By allowing Hooks to not only execute efficient logic but also to store small, simple data objects, one could define a Hook like: “for incoming payments transactions, check if the sending account is in a list maintained by another Hook, and if present: reject the transaction”.

Hooks are deliberately not Turing-Complete. While often touted as the holy grail of smart contracts, Turing-Completeness is actually inappropriate for smart contracts. (See Blog 2.)

Hooks are currently live on a public testnet. It's time for testing, coding, having fun & breaking things, so a future amendment to add Hooks to Xahau livenet can be drafted with confidence.

Resources

• Xahau Testnet

• Xahau Testnet Explorer

• Examples (source code)

• Blogs (concepts)

What are Hooks?

Hooks allow the creation of customized logic and automation within the XRPL, making transactions smarter and more convenient. These small, efficient modules add custom on-ledger functionality, such as creating custom triggers for specific events on the ledger.

These triggers can be used to send on-ledger actions or execute other actions in response to the specified event. Hooks are currently available on the Xahau network.

There is a Hooks Builder site where you can develop, test, debug, and deploy your own Hooks on testnet in your browser, using our examples or building your own from scratch.

Why are Hooks a Big Deal?

Simply put, Hooks add a robust smart contract functionality to the XRPL, empowering you to construct and deploy applications with bespoke functionalities aligning with your specific needs and requirements.

Hooks provide a versatile platform as they can be used for implementing a broad spectrum of business logic and smart contract paradigms. Once a hook is set up on an account, it enables you to do the following:

• Block or allow transactions to and from the account.

• Change and keep track of the hook’s internal state and logic to inform programmatic choices.

• Autonomously initiate new transactions on the account’s behalf.

Hooks can be written in C or any other preferred language and then compiled into WebAssembly.

The Hooks Builder serves as an integrated development environment, facilitating the crafting, testing, debugging, and deployment of your Hooks on our testnet.

Whether you're utilizing our examples or building from scratch, Hooks Builder provides a helpful environment for honing and deploying your smart contract solutions.

Some Examples of specific Hooks and Use Cases

Showcasing the potential of Hooks with these concrete examples, each illustrating a unique application of smart contract functionality on the XRPL:

• Auto-Savings Hook: Automate savings by configuring a Hook to transfer a set amount of XRP to a separate savings account on the ledger. This could be done to help save a portion of XRP and build up savings at specified intervals—daily, weekly, or monthly. This recurring transfer mechanism can be a base for developing personal finance applications or subscription-based models.

• Carbon-Offset Hook: Each transaction triggers an additional transfer of 1% of the amount to a carbon offset account managed by a trusted non-governmental organization (NGO) using the money for a good cause. This feature can be used as a base for building applications that contribute to environmental sustainability with every transaction made.

• Firewall Hook: By filtering incoming and outgoing transactions. The Firewall Hook can block malicious transactions originating from known scam accounts or containing suspicious memos. By retrieving an updated blocklist from a Hook on a different account, the firewall maintains a robust defense against fraud without the need for manual intervention. Additionally, implementing spending limits to deny high-value unauthorized withdrawals could be a crucial feature for financial applications.

Distinguishing Hooks from Ethereum Virtual Machine (EVM)

XRPL Hooks and the EVM allow developers to build and deploy custom logic and automation within their platforms. However, some key differences between these two technologies set them apart.

• Platform Compatibility: Hooks are tailored for the XRP Ledger, while EVM smart contracts are designed for Ethereum-based blockchains.

• Execution Efficiency: Hooks utilize WebAssembly (WASM), outperforming the bytecode used by the EVM in terms of speed and efficiency.

• Predictable Execution Time: XRPL Hooks use guards to ensure maximum execution time is well-bounded and known ahead of time, improving efficiency.

Alternatives to Hooks on the XRPL

Ripple and Peersyst announced that an EVM-compatible sidechain is now live on the company's devnet. This sidechain functions as an autonomous blockchain, complete with its unique consensus protocol and transaction rules. The EVM sidechain is an alternative to Hooks, adding smart contract functionality to the ecosystem.

However, it's essential to note that EVM sidechain contracts function on Layer 2, which requires a two-step process where XRP is transitioned onto the sidechain for contract execution and then back to the main ledger. Once on the sidechain, then again on the XRPL, meaning Layer 2 smart contracts cannot influence the flow. Hooks can decide if a transaction is allowed in the first place. Layer 2 can make a retroactive decision, but the initial transaction has already happened.

Hooks are more closely integrated with XRPL, operating directly on Layer 1 of the XRPL, so they are more tightly integrated with the underlying blockchain technology than the EVM-compatible sidechain to take advantage of the specific features and capabilities of the XRPL platform. With the inherent scalability and performance of WebAssembly, Hooks are optimal to enhance XRPL's functionality.

Hooks Will Expand the On-ledger Functionality and Help XRPL Grow

Hooks add native smart contract capabilities to the XRPL, enabling the crafting of custom applications that meet the unique needs of users, bringing new functionalities, and opening up whole new domains of functionality. With Hooks, the possibilities are virtually unlimited.

As the XRPL continues to grow, there is no doubt that Hooks will play a significant role in driving further innovation and adoption of the platform by retail and enterprise users.

When a novel Hook's web assembly byte-code is uploaded to Xahau, a significant storage burden is imposed on the network. This storage burden is reflected in the Hook Fees charged by the network.

To avoid this burden (and high fees for end users) reference counting is used:

• The first time a novel Hook is installed, the SetHook Transaction must provide a significant fee.

• The Hook's web assembly byte-code becomes an unowned and reference counted object on the ledger (called a HookDefinition).

• Subsequent installations by the same or other users for an identical Hook (i.e. with identical byte-code) increment the reference count. These installations point at the same object on the ledger. These transactions are billed in a similar way to setting a Trust Line, as the storage burden for the Hook was already paid for in the original Set Hook transaction.

• While the reference count on the Hook Definition is greater than zero (meaning one or more accounts still have the Hook installed) the object remains on the ledger.

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 */

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

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

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

0

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

(1ULL << 22)

HookOn Calculator

Mainnet (network 21337)

• Websocket

  • wss://xahau.network

  • wss://xahau.org (alias, some ad-blockers block .network)

• HTTP POST RPC

  • https://xahau.network

  • https://xahau.org (alias, some ad-blockers block .network)

• Network Definitions (Binary Codec, ...)

Testnet (network 21338)

• Websocket

  • wss://xahau-test.net

• HTTP POST RPC

  • https://xahau-test.net

• Network Definitions (Binary Codec, ...)

Background

Xahau contains numerous heterogenous object types which a Hook has read-access to. For example: transactions, accounts, ledgers, and the subcomponents of each of these, to name just a few.

It is very easy to carelessly program a computer to do a lot of needless copy operations when disciplined access to the same underlying data (i.e. through a view) would suffice. The deliberate avoidance of copy operations in programming is referred to as in programming.

With Hooks the same principle applies. We want to avoid copying where possible. In particular we want to avoid as much as possible needlessly copying large objects such as whole ledgers, we also want to avoid serializaing and unserializing these where possible.

What are slots?

Slots are part of the Hook API and provide a zero-copy heterogenous access system for on-ledger objects and transactions.

• Each Hook has access to 255 slots during runtime.

• Each slot may be empty or may contain a slotted object.

• The slot API allows traversal into inner objects, and allows these inner objects themselves to be slotted.

• The slot API allows slotted objects to be dumped to a buffer or otherwise read by the Hook.

The avilable slot APIs are:

What are keylets?

Keylets are used to locate (point to) on-ledger objects. In brief they are a hash of identifying information from the object, which is the canonical handle for that object.

🚧 Tip

The Hook APIs which accept a 34 byte keylet will also generally accept a 32 byte canonical transaction hash.

Example

In the following example a 34 byte keylet for a signers object is used to slot that object.

What are Serialized Objects?

The XRP Ledger has canonical forms of all objects subject to consensus. When writing a Hook it is inevitable you will come across serialized objects. These manifest as buffers containing what might appear to the developer as opaque binary blobs. In fact you can read these with the .

For example an sfAmount field serializes to a collection of bytes like 61D50F26109A32B7EC

Serialized Object API

To assist Hook developers in working with serialized objects the sto namespace was created within the Hooks API. These functions manipulate pointers within a Hook-provided buffer. See table below.

Where applicable these APIs return an offset and a length encoded into a single int64_t. See individual documentation for details.

Example

At typical scenario in which you would use the STO API is in processing memos on an Originating Transaction. Since you will likely need access to the whole memo anyway, an efficient way to process a set of memos is simply to dump the whole sfMemos field into a buffer then index around within it. While it is also possible to use the slot API to do this by slotting the Originating Transaction it would result in additional code and additional copying.

Overlap with slots

You may notice some overlap between slot APIs and STO APIs. The key difference here is who owns the underlying data:

• If you are using slots then xrpld owns the object you are interacting with.

• If you are using the STO API then the Hook owns the buffer you are interacting with.

Both sets of functions index into a Serialized Object without unnecessary copying.

Background

All changes made to Xahau must be the result of applying a valid transaction to the ledger. Thus if some change X is made then some transaction Y is responsible.

When designing the Hooks API we needed a way for Hooks to make changes to the ledger beyond simply accepting or rejecting a transaction. However attaching these changes to the Originating Transaction was confusing and resulted in a large increase in the general complexity of the system.

Suppose for example that a Hook needs to send you some funds... the send operation would be effectively enacted onto the ledger by the Originating Transaction which might have been something completely unrelated such as an Account Set transaction. Additionally this send operation would need to be able to potentially trigger another Hook on the receiving end of a payment.

The solution: Emitted Transactions. We allow the Originating Transaction to do exactly what the contents of the Transaction say it will do. If our Hook needs to make an additional change to the ledger such as sending a payment, it creates and then emits a brand new transaction.

What are Emitted Transactions?

Emitted Transactions are new transactions created by the execution of a Hook and entered into consensus for processing in the next ledger. The transaction may be of any Transaction Type but must follow strict emission rules.

To emit a transaction the Hook first prepares the serialized transaction then calls .

Because emitted transactions can trigger Hooks in the next ledger which in turn may emit more transactions, all emitted transactions carry a burden and a generation field in their EmitDetails block. The EmitDetails block replaces the signature field in a traditional transaction.

The burden and generation fields collectively prevent attacks on the ledger by exponentially increasing the cost of exponentially expanding emtited transactions.

It is important to note that the Hooks API follows the strict rule of no rewriting. You must present an emitted transaction in full, valid and canonically formed to xahaud for emission or it will be rejected. It is not xahaud's job to build your transaction for you. The Hook must do this itself.

Callbacks

As introduced in emitted transactions trigger callbacks when they are accepted into a ledger. Due to the decentralised nature of consensus acceptance into a ledger of an emitted transaction is not a guarantee, although it is usually all-but guaranteed.

If an emitted transaction expires before it can be accepted into a ledger (for any number of reasons: the ledgers may be full, the fee may be too high for the emitted transaction or the emitted transaction may be somehow invalid) then a pseudo transaction is created in the ledger to clean up the emitted transaction. This pseudo transaction also calls the callback of your hook, with parameter = 1 to indicate the emitted transaction indeed failed.

Emission Rules

EmitDetails block

All emitted transactions must contain an sfEmitDetails object correctly populated with the fields in the table below.

👍 Check the examples

Background

are widely used in computer science to do calculation of finite precision but arbitrary scale numbers.

Most modern CPUs are capable of performing fast floating point operations using the however xahaud does not use this format. Instead Xahau uses a .

This custom format has three basic properties:

1. The format is inherently decimal, expressed as a decimal mantissa multipled by 10 to the power of an exponent.

2. All values expressed have 16 significant (decimal) figures.

3. The range of exponents is -96 to +80

When serialized the mantissa is 54 bits, and the exponent is 8 bits, with a final sign bit bringing the total size of the serialized floating point to 63 bits.

What is XFL?

is an XRPL standards proposal that defines an efficient way to pack and store xrpld floating point numbers (as described above).

XFLs store the bits of the floating point number within an enclosing number. This is always an int64_t. Negative enclosing numbers represent invalid XFLs (for example as a result of division by zero.)

📘 Hint

Use the XFL-tool to compose and decompose XFLs in your browser!

Some example XFLs follow

This format is very convenient for Hooks, as Hooks can only exchange integer values with xrpld. By enclosing the floating point inside an integer in a well defined way it becomes possible to do complex floating point computations from a Hook. This is useful for computing exchange rates.

Canonical Zero

Floating point regimes typically have a number of different ways to express zero, which can be a problem for testing for zero. For example 0 x 10 ^ 1 is zero and 0 x 10 ^ 2 is also zero. For this reason there is a canonical zero enforced by the standard and the Hook API. The canonical zero is also enclosing number zero (0).

Hook Float API

Once you have an XFL you can use the Float API to do various computations. The Float API appears in the table below. Each API takes one or more XFL enclosing numbers and returns an XFL enclosing number. Negative return values always represent a computational error (such as division by zero). There are no valid negative enclosing numbers.

❗️ Warning

You should never do any direct math or comparison on the enclosing number. This will almost always result in incorrect computations.

The sole exception is checking for canonical zero.

Example

In the below example an exchange rate conversion is performed, followed by a high precision fraction multiplication.

🚧 Tip

If a float API returns a negative value and you do no check for negatives then feeding that negative value into another float API will also produce a negative value. In this way errors are propagated much as NaN (not a number) is propagated in other languages.

If you ever end up with a negative enclosing number an error occured somewhere in your floating point calculations.

When Hooks execute they leave behind information about the status of that execution. This appears in the Originating Transaction metadata as an sfHookExecutions block. This block contains the following fields: