1 of 100

Xahau Network

Xahau Documentation

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!

XRPL/Xahau: What is Different?

A list of notable differences between the XRP Ledger and Xahau.

Not Documented

accounts on xahau start at a sequence that matches the timestamp of the previous ledger
Pseudo tx docs missing: UNLReport, EmitFailure, Etc
URIToken Size Limit
AccountDelete is still listed as a transaction but is disabled on Xahau

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.

Concepts

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.

Introduction

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.

Please note: you're reading the technical documentation of Hooks. This documentation is highly technical & assumes prior knowledge of programming and the Xahau Ledger. If you are looking for examples on what Hooks are, will bring to the Xahau Ledger and what they could do, please check this page.

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

Example Usage

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

Loops and Guarding

Guards are needed to perform loops in a Hook.

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.

Chaining

Chain multiple hooks together to do more useful tasks

👍 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

In addition to the install-time operations specified in the , Hooks have some runtime control over chain execution:

A Hook may determine its own HookHash by calling .
A Hook may determine its location in the Hook Chain using .
A Hook may skip (or re-enable) another Hook further down the chain using .
A Hook may modify the of a Hook further down the chain using .

Weak Executions

Hook Chains are . However any Hook in any chain may flag that it requires a second, Weak Execution by calling . If all Hook Chains execute successfully then the originating transaction is applied. Once the originating transaction has been applied any Weak Executions may happen, in the following order:

cbak execution if this was an Emitted Transaction.
Weak Transactional Stake Holders who have opted in to allow a . Execution order is first-come first-serve according to the event that caused the TSH to be flagged (such as pathing).
Any Again as Weak (AAW) Hooks. Execution order for AAW is first numerically according to Account ID then numerically according to Hook position.

Collect Call

👍 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

Type of Weak Execution

Fee

Again As Weak - Happens when a Strongly Executed Hook calls

Free (already paid by the Strong Execution).

Callback - Happens when an emitted transaction either makes it into a ledger or is flagged as being impossible to ever make it into a ledger.

Free (already paid during Emission).

Weak Transactional Stakeholder - Happens if a transaction in some way mildly affects your account.

Paid for by your account (not by the originating transaction) if and only if both your account is marked with asfTshCollect flag and your Hook is marked with the hsfCollect flag.

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

Parameters

Install-time parameters allow Hooks to be generic and flexible

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

Prevent state clobbering by using the correct namespace

Namespaces

To avoid two or more Hooks installed on the same account unintentionally clobbering each-other's , 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 .

The configured Namespace a Hook operates under alters the its 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.)

Default Namespace

The first user to defines a HookNamespace which becomes the Default Namespace for that Hook. This means any subsequent users who 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 and for information about how to query the ledger regarding namespaces.

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

Hook Fees

What to expect when your Hook runs.

Hook Creation Fees

SetHook transactions are charged per byte of created webassembly. The rate is 500 drops per byte. Thus a 1kib Hook will cost 0.5 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:

Open a websocket connection to the Hooks node you will be working with.
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.

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.

Execution Metadata

What to expect when your Hook runs.

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:

Field

Description

Emitted Transactions

Your Hook can do a lot more than just block or allow transactions!

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

The Hook API will enforce the following rules on a proposed (to be emitted) transaction.

Emission Rule

Explanation

EmitDetails block

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

Field

Required Value

Description

👍 Check the examples
The , in particular Peggy, Carbon and Doubler, demonstrate how to emit both simple and more complicated transactions.

Serialized Objects

Manipulate raw serialized xahaud objects!

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.

Hook API

at it does

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.

Features

Public Nodes (RPC)

Running your own node: amazing. Hit the ground running? Use the public Xahau RPC nodes.

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

JSHooks-Testnet (network 31338)

Websocket
- wss://jshooks.xahau-test.net
HTTP POST RPC
- https://jshooks.xahau-test.net
Network Definitions (Binary Codec, ...)

Amendments

Amendments represent new features or other changes to transaction processing.

The amendment system uses the consensus process to approve any changes that affect transaction processing on Xahau. Fully-functional, transaction process changes are introduced as amendments; validators then vote on these changes. If an amendment receives more than 80% support for five days, the amendment passes and the change applies permanently to all subsequent ledger versions. Disabling a passed amendment requires a new amendment to do so.

Note: Bug fixes that change transaction processes also require amendments.

Amendment Process

The Contributing Code to Xahau topic walks through the workflow to develop an amendment from an idea to activation on Xahau.

After the code for an amendment is built into a software release, the process to enable it happens within the Xahau network, which checks the status of amendments every flag ledger (typically about 15 minutes apart).

Every 256th ledger is called a flag ledger. The flag ledger doesn't have special contents, but the amendment process happens around it.

Flag Ledger -1: When xahaud validators send validation messages, they also submit their amendment votes.
Flag Ledger: Servers interpret the votes from trusted validators.
Flag Ledger +1: Servers insert an EnableAmendment pseudo-transaction and flag based on what they think happened:
- The tfGotMajority flag means the amendment has more than 80% support.
- The tfLostMajority flag means support for the amendment has decreased to 80% or less.
- No flag means the amendment is enabled.
Note: It's possible for an amendment to lose 80% support on the same ledger it reaches the required five day period to be enabled. In these cases, an EnableAmendment pseudo-transactions is added for both scenarios, but the amendment is ultimately enabled.
Flag Ledger +2: Enabled amendments apply to transactions on this ledger onwards.

Amendment Voting

Each version of xahaud is compiled with a list of known amendments and the code to implement those amendments. Operators of xahaud validators configure their servers to vote on each amendment and can change it at any time. If the operator doesn't choose a vote, the server uses a default vote defined by the source code.

Note: The default vote can change between software releases. [Updated in: rippled 1.8.1][]

Amendments must maintain five days of support from more than 80% of trusted validators to be enabled. If support drops below 80%, the amendment is temporarily rejected, and the two week period restarts. Amendments can gain and lose a majority any number of times before they become permanently enabled.

Amendments that have had their source code removed without being enabled are considered Vetoed by the network.

Amendment Blocked Servers

Amendment blocking is a security feature to protect the accuracy of Xahau's data. When an amendment is enabled, servers running earlier versions of xahaud without the amendment's source code no longer understand the rules of the network. Rather than guess and misinterpret ledger data, these servers become amendment blocked and can't:

Determine the validity of a ledger.
Submit or process transactions.
Participate in the consensus process.
Vote on future amendments.

The voting configuration of a xahaud server has no impact on it becoming amendment blocked. A xahaud server always follows the amendments enabled by the rest of the network, so blockages are based solely on having the code to understand rule changes. This means you can also become amendment blocked if you connect your server to a parallel network with different amendments enabled. For example, the Xahau Testnet typically has experimental amendments enabled. If you are using the latest production release, your server likely won't have the code for those experimental amendments.

You can unblock amendment blocked servers by upgrading to the newest version of xahaud.

Retiring Amendments

When amendments are enabled, the source code for pre-amendment behaviors remain in xahaud. While there are use-cases for keeping old code, such as reconstructing ledger outcomes for verification, tracking amendments and legacy code adds complexity over time.

The defines a process for retiring old amendments and associated pre-amendment code. After an amendment has been enabled on the Mainnet for two years, it can be retired. Retiring an amendment makes it part of the core protocol unconditionally; it's no longer tracked or treated as an amendment, and all pre-amendment code is removed.

Transaction Fees

Xahau smart contracts (Hooks) need transaction & destination specific fees. You can easily get the required fee from the `fee` RPC command.

While libraries may deal with fee determination for you (see ), when building your own integrations with the Xahauy ledger, you may have to implement dynamic fee determination based on the transaction, source & destination account.

As the sender of a transaction will have to pay for the fees required for the invoked Hooks for the specific transaction type, where Hooks can live both on the source & destination account, you can send a TX Blob (signed with a dummy account) to the fee command, after which Xahau will return the specific fees required for the specific transaction.

Fee RPC Helper

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:

Open a websocket connection to the Hooks node you will be working with.
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.

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

For HTTP POST RPC submit it as follows:

The response should look something like

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.

Source:

Developer Tooling

Our Developer Tooling page covers Hooks Tools and Client Libraries, simplifying interacting with Hooks and the Xahau Ledger.

Curated Tooling

These tools simplify some of the common work of accessing and processing Hooks.

Tool

Reference Link

Client Libraries

These client libraries simplify some of the common work of accessing and processing XAH Ledger data and present it in a form that matches the native conventions of their respective programming languages.

For other programming languages, you can access the XAH Ledger through the HTTP APIs.

Language

Library Name

Get Started

Protocol

Source Code

Tip: To add a client library not listed here, please suggest changes to this page!

Developer Tricks

Wildcard signing

To easily test & replay, use NetworkID with value 65535 (config: [network_id]) to disable signature verification.

Added:

Server Definitions

Server definitions can eas

Request Formatting Guide

Public Servers

wss://xahau.network or https://xahau.network (Mainnet)
wss://xahau-test.net or https://xahau-test.net (Testnet)

Sample Requests

To send a sample request to the API, use the following commands.

Websocket

{
  "id": 3,
  "command": "account_info",
  "account": "rhBDFMmr3jSjgsWMqBAYaATLy3PuXy395y",
  "strict": true,
  "ledger_index": "validated",
  "api_version": 1
}

WebSocket Request Structure

Once you establish a WebSocket connection to the xahaud server, you can send commands as JSON objects with these fields:

Field

Type

Description

command

String

The name of the API method

(Multiple)

(Optional) Unique identifier for the request.

api_version

Number

(Optional) Specifies the API version.

JSON-RPC

POST https://xahau.network/
Content-Type: application/json

{
    "method": "account_info",
    "params": [
        {
            "account": "rhBDFMmr3jSjgsWMqBAYaATLy3PuXy395y",
            "strict": true,
            "ledger_index": "validated",
            "api_version": 1
        }
    ]
}

JSON-RPC Request Structure

Field

Type

Description

method

String

The name of the API method

params

Array

(Optional) A one-item array containing a JSON object with the parameters of the method.

Comandline

xahaud account_info rhBDFMmr3jSjgsWMqBAYaATLy3PuXy395y validated strict

Commandline Request Structure

Field

Description

xahaud

Start calling the service xahaud

method

The name of the API method

params

(Optional)

Response Formatting Guide

Responses are structured differently based on whether the request is made through the WebSocket, JSON-RPC, or Commandline interfaces. The JSON-RPC and Commandline interfaces share the same format, as the Commandline interface internally uses JSON-RPC.

Fields

Field

Type

Description

(Varies)

(For WebSocket) The ID from the original request.

status

String

(For WebSocket) Indicates success when the request was received and processed correctly.

result.status

String

(For JSON-RPC and Commandline) Indicates success when the request was successfully processed.

type

String

(For WebSocket) The value response is used for direct replies to API requests. Asynchronous notifications use other values, such as ledgerClosed or transaction.

result

Object

Contains the query result, with content that varies by command.

warning

String

(Optional) If present, the value is load, indicating the client is nearing the rate limit threshold where the server may disconnect.

warnings

Array

(Optional) A list of Warning Objects with important server warnings. For more details, see API Warnings.

forwarded

Boolean

(Optional) true indicates the request was forwarded from a Reporting Mode server to a P2P server to fulfill the request. Default is false.

API Warnings

When a response contains a warnings array, each entry represents a specific warning from the server. Each Warning Object includes the following fields:

Field

Type

Description

Number

A unique numeric code identifying this warning message.

message

String

A human-readable explanation of the warning. Avoid writing code that relies on the content of this field; use the id (and details, if available) to interpret the warning instead.

details

Object

(Optional) Additional context about the warning. The content varies by warning type.

Considerations

Markers

Some methods return more data than can fit efficiently into a single response. When the results exceed the response limit, a marker field is included in the response. This field allows you to retrieve additional pages of data through subsequent requests. To continue fetching data, include the marker value from the previous response in your next request. If a response does not include a marker, it means you have reached the end of the data set.

The format of the marker field is intentionally unspecified. Each server can define the marker as needed, meaning it could be a string, a nested object, or another type. The marker format may vary between servers and even between methods on the same server. Each marker is temporary and may become invalid after approximately 10 minutes.

Rate Limit

The xahaud server enforces rate limits on API clients using public APIs to prevent excessive requests. Rate limiting is applied based on the client’s IP address, meaning multiple clients sharing a network address translation (NAT) will share the same rate limit associated with their public IP.

When a client is nearing the rate limit, the server includes a "warning": "load" field at the top level of an API response. This warning does not appear on every response but may be sent several times before the server disconnects the client. Clients connected as an admin are exempt from rate limiting.

If a client exceeds the rate limit, the server disconnects the client and temporarily blocks further requests from that IP address. The WebSocket and JSON-RPC APIs handle disconnects differently, as described below.

Admin API Methods

These methods are intended exclusively for trusted personnel responsible for maintaining xahaud server operations.

Key Generation Methods

Method

Description

Logging and Data Management Methods

Method

Description

Server Control Methods

Method

Description

Signing Methods

Method

Description

Peer Management Methods

Method

Description

Status/Debugging Methods

Method

Description

Network Features

Account Managment

The Account Management features in the Xahau network are a crucial component for users to manage their accounts effectively.

This includes several transaction types that enable users to perform various operations on their accounts.

Transaction Types

AccountSet

The AccountSet transaction type allows users to modify the properties of their accounts. This includes settings such as transfer rate, account flags, and more.

AccountDelete

The AccountDelete transaction type enables users to delete their accounts from the Xahau network. This operation is irreversible and should be used with caution.

SetRegularKey

The SetRegularKey transaction type allows users to set a regular key pair for their account. This key pair can be used as an alternative to the master key pair for signing transactions.

SignersListSet

The SignersListSet transaction type enables users to set a list of signers for their account. This is particularly useful for multi-signature accounts where multiple parties are required to sign off on transactions.

Import

The Import transaction type is used to import transactions from other networks. This feature is especially useful for issuers who need to import transactions for their asset holders. It's recommended to key your accounts first before attempting to import transactions.

Please note that the process of importing for the issuer involves specific transaction types and requires careful configuration. Always ensure that the hooks are correctly set up and that the transactions are valid for the intended operations.

These transaction types provide users with a comprehensive set of tools for managing their accounts on the Xahau network. As with all operations, users should ensure they understand the implications of each transaction type before use.

Balance Rewards

The Balance Rewards feature is a unique aspect of the Xahau network that allows users to accumulate and claim rewards based on their account balance. This feature is implemented through a combination of native code (BalanceRewards Amendment) and hook code (Genesis Account's Reward Hook).

Transaction Types

ClaimReward

A ClaimReward transaction allows an account to claim the rewards it has accumulated. The rewards can be claimed by the account owner or by a specified issuer. The account can also opt-out of rewards by setting the Flags field to 1.

GenesisMint

The GenesisMint transaction type is also associated with the Balance Rewards feature. This is an Emitted transaction that is executed through the Reward Hook every time a user claims balance rewards.

Check

The Check feature in the Xahau network is a deferred payment system that allows for the creation, cancellation, and cashing of checks within the ledger. This feature is designed to facilitate secure and efficient transactions between parties.

Transaction Types

CheckCreate

The CheckCreate transaction is used to create a Check object in the ledger. This represents a deferred payment that can be cashed by its intended destination.

CheckCancel

The CheckCancel transaction is used to cancel a Check that has been created but not yet cashed. This allows the sender to stop the payment from being processed if necessary.

CheckCash

The CheckCash transaction is used to cash a Check that has been created. This allows the recipient to receive the funds that have been deferred.

Escrow

The Escrow feature is a crucial part of the Xahau network. It provides a secure and trustless method for transactions between parties. The Escrow feature ensures that the assets involved in a transaction are held securely until all the conditions of the transaction are met.

Transaction Types

The Escrow feature includes three types of transactions:

EscrowCreate

The EscrowCreate transaction is used to create a new escrow agreement. This transaction specifies the terms of the escrow, including the parties involved, the assets to be held in escrow, and the conditions under which the assets will be released.

EscrowFinish

The EscrowFinish transaction is used to complete an escrow agreement. This transaction is executed when all the conditions of the escrow are met. Upon execution, the assets held in escrow are released to the appropriate party.

EscrowCancel

The EscrowCancel transaction is used to cancel an escrow agreement. This transaction can be executed if the conditions of the escrow are not met within a specified time frame. Upon cancellation, the assets held in escrow are returned to the party that initiated the escrow.

Hooks

Hooks are a powerful feature of the XRPL network, providing robust smart contract functionality. They are small, efficient WebAssembly modules designed specifically for the XRPL, and can be referred to as Smart Contracts for the XRP Ledger Protocol. Hooks can be written in any language that is compilable with WebAssembly, allowing for a wide range of business logic and smart contract concepts to be implemented.

Transaction Types

The Hooks feature includes two types of transactions:

SetHook

This transaction type is used to set up a hook on an account.

Invoke

This transaction type is used to call or invoke the functionality of a hook.

Offer

The Offer feature in the Xahau network is a crucial component of the decentralized exchange system. It allows users to create and cancel offers, facilitating a dynamic and responsive trading environment.

Transaction Types

OfferCreate

The OfferCreate transaction is used to place an offer in the decentralized exchange.

OfferCancel

The OfferCancel transaction is used to cancel an existing offer. The documentation for this transaction type is referenced in the Xahau Documentation but not provided in the given context.

Payments

The Payments feature in the Xahau network is a crucial component that enables the transfer of assets and funds within the network. This feature is designed to facilitate seamless transactions, ensuring a smooth and efficient operation of the network.

Transaction Types

The Payments feature comprises several transaction types, each serving a unique purpose in the network. Here's a brief overview of each transaction type:

DepositPreauth

This transaction type allows an account to preauthorize incoming transactions from a specified source. It's a way to whitelist accounts, ensuring that only authorized transactions are processed.

TrustSet

This transaction type allows users to create a trust line with another account. It's a way to establish trust between two accounts, enabling them to transact with each other.

Payment

This is the basic transaction type that allows the transfer of assets between accounts. It's the fundamental transaction type for any payment operation in the network.

PaymentChannelCreate

This transaction type allows the creation of a payment channel between two accounts. Payment channels are off-ledger scalability solutions that enable high-frequency, low-cost transactions between two parties.

PaymentChannelFund

This transaction type allows an account to fund an existing payment channel. It's a way to add more assets to a payment channel, enabling more transactions to take place.

PaymentChannelClaim

This transaction type allows an account to claim the funds from a payment channel. It's a way to close a payment channel and retrieve the remaining assets.

URIToken

URITokens are the Non-Fungible Token (NFT) implementation native to the Xahau network. They exist as first-class on-ledger objects, uniquely identified by the hash of their issuer and Uniform Resource Identifier (URI). URITokens can point to any digital content, with only one object per URI per account existing on the ledger.

The issuer has the ability to set a flag to enable the burning of the object in the future. Each owner's reserve is locked up as well upon ownership of the URIToken.

Transaction Types

URITokenMint

The URITokenMint transaction mints a new URIToken and assigns ownership to the specified account. The minted URIToken represents a unique digital asset that can be used in various applications. The issuer can choose to allow the minted URIToken to be destroyed in the future.

URITokenBurn

The URITokenBurn transaction is used to burn a URIToken in Xahau. Burning a URIToken permanently removes it from circulation. The transaction does not have any special transaction cost requirements. The account that owns the URIToken to be burned is required for this transaction.

URITokenBuy

The URITokenBuy transaction allows a user to buy a URIToken from the issuer. This transaction is used to transfer ownership of a URIToken from the issuer to the buyer. The buyer's account, the unique identifier of the URIToken to be bought, and the amount of currency to pay for the URIToken are required for this transaction.

Faucet & Explorers

The Xahau Faucet & Explorers can be found here:

Testnet

Faucet:
- To automate funding accounts on testnet, HTTP POST to: Empty body: new account (prefunded) JSON body with destination property: fund the mentioned destination account.
Explorers:
- Xahauexplorer:
- XRPLF:
- XRPL.org:
- XRPLWin:

Mainnet

Homepage:
Explorers:
- Xahauexplorer:
- Xahscan:
- XRPLF:
- XRPL.org:
- XRPLWin:

Data API's

Nice API's to fetch Xahau ledger information

XRPLF Data API

@nixerFFM ()

Infrastructure

Node Requirements

Hardware requirements for nodes (RPC, validator, ...) should be generally along the lines of the specs outlined below.

For specific node use cases (e.g. full history) specs may differ (and grow) over time.

Nodes should run (reasonably) well for own use with:

CPU: 6+ cores
Memory: 16GB+ (32GB advised)
Disk IO: 10k random RW
Disk size: 100GB+
Filesystem: EXT4/XFS/...
Network IO: 100Mbit+

Nodes for future (network growth) production use:

Minimum

Preferred

Ideal

Building Xahau (Dev)

A Guide to Setting Up the Development Environment.

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

The building Xahau chapter will guide you through the process of establishing environmental variables, installing core and Xahaud dependencies, and compiling the software, including 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. Ending with cloning the Xahau repository and creating the Xahaud target, which sets developers on the path to adding to or deploying the Xahau network.

Technical

Hooks Functions

Overview

Hook API Conventions

Naming conventions

All Hook APIs follow a standard naming convention:

namespace

[ _ noun #1 ]

[ _ verb ]

[ _ noun #2 ]

This may look confusing at first but is actually quite simple:

If the first noun is missing then it is implicitly the same as the namespace
If the verb is missing then it is implicitly get

Thus:

state() means: fetch a hook state.
state_set() means: set a hook.
state_foreign() means: fetch a foreign hook state.

Memory model

Each Hook executes as a singular stack frame. All working memory must exist within this stackframe. There is no heap and no dynamic memory.

When Hooks communicate with xahaud they can only pass integer values. Typically these integers are pointers within the Hook's memory. Since the Hook runs within xahaud, these points can then be resolved by xahaud and written to or read from as needed to perform the Hook API function.

Allowed functions

Only two functions are allowed within a Hook: hook() and cbak(). Read about this here

Parameters

All parameters passed to a Hook API must be one of: uint32_t, int32_t, uint64_t, int64_t. Typically these are pointers and lengths of buffers within the Hook's stack frame. Sometimes they are Integer Encoded Floating Point Numbers (XFL) or other data.

The parameters to a Hook API are always in the following order:

Writing pointer if any
Writing length if any
Reading pointer if any
Reading length if any
Specifics / other fields if any

Some Hook APIs may only write or may only read from memory, and some might not do either and return a value only by return code.

All parameters passed to a Hook API must be one of: string, number[], bigint(xfl), object(json). Typically these are pointers and lengths of buffers within the Hook's stack frame. Sometimes they are Integer Encoded Floating Point Numbers (XFL) or other data.

The parameters to a Hook API are always in the following order:

Writing variable if any
Reading variable if any
Specifics / other fields if any

Some Hook APIs may only write or may only read from memory, and some might not do either and return a value only by return code.

Return codes

All Hook APIs return a signed integer. Read about return codes here: Return codes

Developer Defined

cbak / Callback

The callback function of your hook

Concepts

Compiling Hooks

Behaviour

cbak is a user defined function called by xahaud in order to inform your hook about the status of a previously emitted transaction
State changes and further emit calls can be made from cbak but it cannot rollback a transaction.
When cbak is executed the emitted transaction to which the callback relates is now the originating transaction.

Definition

type Callback = (reserved: number) => number

Example

const Callback = (reserved: number) => {
  return 0
}

Parameters

Name

Type

Description

reserved

uint32_t

if 0: - the emittted transaction to which this callback relates was successfully accepted into a ledger. If 1 - the emitted transaction to which the callback relates was NOT successfully accepted into a ledger before it expired.

Name

Type

Description

reserved

number

Return Code

Type

Description

int64_t

An arbitrary return code you wish to return from your hook. This will be present in the metadata of the originating transaction.

Type

Description

number

An arbitrary return code you wish to return from your hook. This will be present in the metadata of the originating transaction.

Control

accept

Accept the originating transaction and commit any changes the hook made.

Concepts

Execution Order

Behaviour

End the execution of the hook with status: success.

Record a return string and return code in transaction metadata.
Commit all state changes.
Submit all emit() transactions.
Allow originating transaction to continue.

🚧Caution
If the originating transaction is stopped for some other reason then this accept becomes a rollback. See: Execution Order.

Definition

Example

Parameters

Name

Type

Description

Name

Type

Description

Return Code

Type

Description

Type

Description

rollback

Concepts

Execution Order

Behaviour

End the execution of the hook with status: reject.

Record a return string and return code in transaction metadata.
Discard all state changes.
Discard all emit() transactions.
Disallow originating transaction to continue.

❗️Warning
The originating transaction will fail with tecHOOK_REJECTED and a fee will be charged. See: Execution Order.

Definition

Example

Parameters

Name

Type

Description

Name

Type

Description

Return Code

Type

Description

Type

Description

Utilities

Serialization

sto_to_json

Format an STO object (binary encoded ledger data) as JSON format.

Concepts

Serialized Objects

Behaviour

Format an STO object (binary encoded ledger data) as JSON format.
This function takes a serialized transaction blob and converts it into a human-readable JSON format.
Returns Decoded JSON representation of the STO object, or an error code if the conversion fails.

Definition

function sto_to_json(
    blob: ByteArray | HexString
  ): ErrorCode | Record<string, any> | Transaction

Example

const jsonSto = sto_to_json(stoBlob)

Parameters

Name

Type

Description

blob

ByteArray | HexString

The blob (e.g. serialized transaction) to be converted.

Return Code

Type

Description

ErrorCode | Record<string, any> | Transaction

Decoded JSON representation of the STO object, or an error code if the conversion fails.

sto_from_json

Format JSON as an STO object (binary encoded ledger data).

Concepts

Serialized Objects

Behaviour

Takes a JSON object and converts it into a binary encoded ledger data format.
Returns STO Object in binary encoded ledger data format, or an error code if the conversion fails.

Definition

function sto_from_json(
    jsonobj: Record<string, any> | Transaction
  ): ErrorCode | ByteArray

Example

const stoBlob = sto_from_json(stoJson)

Parameters

Name

Type

Description

jsonobj

Record<string, any> | Transaction

JSON object to be converted into an STO object.

Return Code

Type

Description

ErrorCode | ByteArray

STO Object in binary encoded ledger data format, or an error code if the conversion fails.

sto_erase

Remove a field from an STObject

Concepts

Behaviour

Parse an STObject pointed to by read_ptr
Write a new STObject to write_ptr but without field_id if it was present in the original object.

It will look for the STO object (binary encoded ledger data) from which the field will be removed.
It will look for the ID of the field to be erased.
Returns the updated STO object in binary encoded ledger data format, or an error code if the operation fails.

Definition

🚧Field ID encoding
The sto_ apis accept a field_id parameter encoded as follows: (type << 16U) + field Thus type 1 field 2 would be 0x10002U.

Example

📘Emplace equivalence
sto_erase is the same as sto_emplace with 0,0 for field_ptr, field_len parameters.

Parameters

Name

Type

Description

Name

Type

Description

Return Code

Type

Description

Type

Description

Emitted Transaction

etxn_burden

Get the burden of a hypothetically emitted transaction

Concepts

Emitted Transactions

Behaviour

Return the burden an emitted transaction will carry.

Definition

function etxn_burden(): ErrorCode | number

Example

const burden = etxn_burden()

Parameters

None

Return Code

Type

Description

int64_t

The burden an emitted transaction will need in order to be successfully passed to emit()

Type

Description

number

An ErrorCode if there is an error, or the current burden value on success.

etxn_fee_base

🚧 Warning
Fees on a Hooks-enabled ledger are non trivial. See: for details.

Concepts

Behaviour

Return the amount of the fee in drops recommended for a to-be emitted transaction.

Definition

Example

Parameters

Name

Type

Description

Name

Type

Description

Return Code

Type

Description

Type

Description

etxn_reserve

Estimate the required fee for a txn to be emitted successfully

Concepts

Emitted Transactions

Behaviour

Specifies a number of emitted transactions this hook might emit during execution.

Definition

function etxn_reserve(count: number): ErrorCode | number

Example

etxn_reserve(2)

Parameters

Name

Type

Description

count

uint32_t

The largest number of transactions this hook might emit during the course of one execution.

Name

Type

Description

count

number

The maximum amount of transactions this Hook is allowed to emit.

Return Code

Type

Description

int64_t

The maximum number of emitted transactions this hook may emit. This will always be the same as the count parameter or an error as below. If negative, an error: ALREADY_SET - The hook already called this function earlier. TOO_BIG - The specified number of emitted transactions is too large.

Type

Description

number

An ErrorCode if there is an error, or the configured transaction count on success.

etxn_generation

Get the generation of a hypothetically emitted transaction

Concepts

Behaviour

Return the generation an emitted transaction will carry.

Definition

Example

Parameters

None

Return Code

Type

Description

Type

Description

prepare

Prepares a JSON transaction for emission.

Concepts

Behaviour

This function takes a transaction JSON object and prepares it for emission.
The transaction must be complete except for the Account field, which should always be the Hook account.

Definition

Example

Parameters

Name

Type

Description

Return Code

Type

Description

Float

float_set

Create a float from an exponent and mantissa

Concepts

Behaviour

Compute an XFL (xls17) floating point from the provided exponent and mantissa
Return that XFL as an int64_t

Sets the exponent and mantissa for a float representation.
Returns an error code or a new XFL as a bigint.

Definition

Example

Parameters

Name

Type

Description

🚧Caution
When setting a mantissa that is greater or fewer than 16 decimal digits the exponent will be adjusted to ensure the mantissa is exactly 16 digits. This adjustment may result in an INVALID_FLOAT in some circumstances.

📘Special case
XFL canonical 0 is also 0 in the enclosing number. Thus there is never a need to call float_set(0,0);

Name

Type

Description

Return Code

Type

Description

Type

Description

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,
            }
        }
    ]
}

Weak and Strong

Which Hooks are allowed to run and when?

👍 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:

The originating transaction must pay the fee for the execution of the TSH Hook Chain
The TSH has the right to rollback the whole transaction by calling rollback() from their Hook during execution.

A Weak connection means:

The originating transaction does not pay for the execution of the TSH Hook Chain.
The TSH pays for the execution of their own Hook Chain through a feature called Collect Call Hooks.
The TSH must have set an account flag asfTshCollect prior to the execution of the originating transaction.
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

Strong TSHes have their hooks executed before the originating transaction is applied to the ledger. This means they have the ability to rollback the transaction (because it hasn't yet been applied.) This gives strongly executed hooks the ability to completely block a transaction from occurring.

Weak TSHes have their hooks executed after the originating transaction has been applied to the ledger. This means they have access to the transaction metadata but cannot prevent the transaction from occurring.

📘 Hint
Strongly executed hooks can call hook_again to be executed a second time as a weak execution after the originating transaction has been applied.

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
2 means the Hook is being executed weakly after being executed strongly due to a hook_again call.

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.

Transaction Type

TSH Type

Who is the TSH

AccountDelete

Strong

Destination account funds are paid out to after deletion

AccountSet

None

N/A

CheckCancel

Weak

Destination account

CheckCash

None

N/A

CheckCreate

Strong

Destination account

ClaimReward

Strong

Issuer Account

DepositPreauth

Strong

Authorized account

EscrowCancel

Weak

Destination account

EscrowCreate

Strong

Destination account

EscrowFinish

Strong

Destination account

GenesisMint

Weak

Each Destination in the GenesisMints Array

Import

Strong

Issuer Account

Invoke

Strong

Destination account

OfferCancel

None

N/A

OfferCreate

Weak

Accounts whose offers were crossed by this action.

Payment

Strong + Weak

Strong: Destination account. Weak: Any non-issuer the payment is rippled through.

PaymentChannelClaim

Weak

Destination account

PaymentChannelCreate

Strong

Destination account

PaymentChannelFund

Weak

Destination account

SetHook

None

N/A

SetRegularKey

Strong

The account whose address is being set as the key.

SignerListSet

Strong

Accounts whose addresses are set as signing keys (if they exist and have Hooks set on them).

TicketCreate

None

N/A

TrustSet

Weak

Issuer account

URITokenCancelSellOffer

None

N/A

URITokenCreateSellOffer

Strong

Destination account, Issuer if tfBurnable Flag is set

URITokenBurn

Strong

Issuer if tfBurnable Flag is set

URITokenBuy

Strong

Owner account, Issuer if tfBurnable Flag is set

URITokenMint

None

N/A

AccountSet

OTXN

TSH

AccountSet

Account

Strong

AccountDelete

OTXN

TSH

AccountDelete

Account

None

Account

Beneficiary

Strong

Check

OTXN

TSH

CheckCancel

CheckCreate

CheckCash

Account

Strong

None

Account

Destination

Weak

Strong

None

Destination

Strong

None

Strong

Destination

Account

Weak

None

Weak

ClaimReward

OTXN

TSH

ClaimReward

Account

Strong

Account

Issuer

Strong

DepositPreauth

OTXN

TSH

DepositPreauth

Account

Strong

Account

Authorized

Strong

Escrow

OTXN

TSH

EscrowCancel

EscrowCreate

EscrowFinish

Account

Strong

Account

Destination

Weak

Strong

Weak

Destination

Strong

None

Strong

Destination

Account

Weak

None

Weak

GenesisMint

OTXN

TSH

GenesisMint

Account

Strong

Account

Destination

Strong

Account

Beneficiary

Weak

Import

OTXN

TSH

Import

Account

Strong

Account

Issuer

Strong

Invoke

OTXN

TSH

Invoke

Account

Strong

Account

Destination

Weak

Offer

OTXN

TSH

OfferCancel

OfferCreate

Account

Strong

Account

Crossed

None

Weak

Payment

OTXN

TSH

Payment

Account

Strong

Account

Destination

Strong

Account

Crossed

Weak

PaymentChannel

OTXN

TSH

PaymentChannelClaim

PaymentChannelCreate

PaymentChannelFund

Account

Strong

Account

Destination

Weak

Strong

Weak

Destination

Strong

None

Destination

Account

Weak

None

SetHook

OTXN

TSH

SetHook

Account

Strong

SetRegularKey

OTXN

TSH

SetRegularKey

Account

Strong

Account

RegularKey

Strong

SignersListSet

OTXN

TSH

SignerListSet

Account

Strong

Account

Signer

Strong

Ticket

OTXN

TSH

TicketCreate

Account

Strong

TrustSet

OTXN

TSH

TrustSet

Account

Strong

Account

Issuer

Weak

URIToken

OTXN

Burnable

TSH

Mint

Burn

Buy

Sell

Cancel

Owner

False

Owner

None

Strong

Owner

False

Issuer

None

Weak

None

Owner

False

Buyer

None

Strong

Weak

Owner

True

Buyer

None

Strong

Weak

Owner

True

Owner

None

Strong

Owner

True

Issuer

None

Weak

Strong

None

Issuer

False

Owner

None

Issuer

False

Issuer

Strong

None

Issuer

False

Buyer

Weak

None

Issuer

True

Owner

None

Weak

None

Issuer

True

Issuer

Strong

None

Issuer

True

Buyer

Weak

None

Buyer

True

Buyer

None

Strong

None

Buyer

True

Owner

None

Weak

None