DEV Community: Ekiserrepe

Learning Xahau: PriceOracle and IOURewardClaim, On-Chain Prices and Custom Reward Programmes

Ekiserrepe — Sun, 28 Jun 2026 17:09:45 +0000

If you've been following this series, you already know that Xahau is more than a ledger, it's a programmable settlement layer. We've explored, and built several things during this series.

The new 2026.06.21 xahaud release shipped two amendments that open up entirely new design space for DeFi builders on Xahau:

PriceOracle — brings the XLS-47d on-chain price feed standard to Xahau
IOURewardClaim — extends the ClaimReward transaction to IOU currencies, enabling any account to run a custom token reward programme

All code in this article targets the Xahau Testnet (wss://xahau-test.net) and requires xahau.js 4.1.0 or later.

Clone the companion repository and install dependencies:

git clone https://github.com/Ekiserrepe/learningxahau20260621.git
cd learningxahau20260621
npm install

Copy .env.example to .env and fill in your testnet seeds:

ISSUER_SEED=your_issuer_seed_here
RESERVE_SEED=your_reserve_seed_here
HOLDER_SEED=your_holder_seed_here
ORACLE_SEED=your_holder_seed_here

Get funded testnet accounts at xahau-test.net.

PriceOracle: On-Chain Price Feeds

The Problem It Solves

DeFi contracts need prices. The naive approach (hard-coding a value or trusting a single off-chain feed) is fragile: stale data or a compromised source can break the whole system. The standard solution is an oracle network: multiple independent providers publish prices on-chain, and consumers aggregate them, discarding outliers.

The PriceOracle amendment ports the XLS-47d standard to Xahau. Any account can become an oracle provider by submitting an OracleSet transaction. Consumers query prices via a single get_aggregate_price RPC call that aggregates across as many providers as they list, with built-in outlier trimming.

Key Concepts

Concept	Description
`OracleDocumentID`	A `uint32` that uniquely identifies one oracle object per account. One account can run multiple oracles (different IDs).
`PriceDataSeries`	Array of `{ BaseAsset, QuoteAsset, AssetPrice, Scale }` entries. One oracle can publish up to 10 trading pairs simultaneously.
`Scale`	Decimal exponent for the price. `AssetPrice: 450000, Scale: 6` means `0.45`.
`LastUpdateTime`	Unix timestamp of the price data. Must be updated each time the price changes.
`Provider`	Hex-encoded UTF-8 string identifying the data source (e.g. your service name).
`AssetClass`	Hex-encoded UTF-8 string classifying the asset type (e.g. `"currency"`, `"commodity"`).

Multiple Oracle Objects per Account

A single account is not limited to one oracle object. By using different OracleDocumentID values you can publish separate feeds, for example, one object for currency pairs and another for commodity prices, each with its own Provider label, AssetClass, and PriceDataSeries. Each oracle object costs XAH in reserve, so the practical limit is determined by your account's available balance.

Each oracle object can hold up to 10 price pairs in its PriceDataSeries array. If you need more pairs than that, split them across additional oracle objects with different OracleDocumentID values on the same account.

Publishing a Price (`01-price-oracle-set.js`)

Any account can publish an oracle object by submitting an OracleSet transaction:

require('dotenv').config()
const { Client, Wallet } = require('xahau')

async function setOraclePrice() {
  const client = new Client('wss://xahau-test.net')
  await client.connect()

  // Set ORACLE_SEED in your .env file. The signing account becomes the
  // oracle provider on the ledger. Get funds at https://xahau-test.net/
  const wallet = Wallet.fromSeed(process.env.ORACLE_SEED, { algorithm: 'secp256k1' })
  console.log(`Oracle account: ${wallet.address}`)

  // OracleSet creates or updates a price feed object on the ledger.
  // Multiple OracleSet transactions from different accounts can be aggregated
  // by consumers using the get_aggregate_price RPC (see 08-price-oracle-query.js).
  const oracleSetTx = await client.autofill({
    TransactionType: 'OracleSet',
    Account: wallet.address,
    OracleDocumentID: 1,  // unique ID per oracle; allows multiple feeds per account

    // Provider and AssetClass must be hex-encoded UTF-8 strings
    Provider:   Buffer.from('MyOracle',  'utf8').toString('hex'),
    AssetClass: Buffer.from('currency', 'utf8').toString('hex'),

    // Ripple-epoch timestamp of the price data (seconds since 2000-01-01)
    LastUpdateTime: Math.floor(Date.now() / 1000),

    // Each entry in PriceDataSeries represents one trading pair.
    // AssetPrice is an integer; divide by 10^Scale to get the real price.
    PriceDataSeries: [
      {
        PriceData: {
          BaseAsset:  'XAH',
          QuoteAsset: 'USD',
          AssetPrice: 450000,
          Scale: 6           // actual price = 450000 × 10⁻⁶ = 0.45 USD
        }
      }
    ]
  })

  const { tx_blob } = wallet.sign(oracleSetTx)
  const result = await client.submitAndWait(tx_blob)
  console.log(`OracleSet: ${result.result.meta.TransactionResult}`)
  console.log(`Oracle object: https://xaman.app/explorer/21338/${result.result.hash}`)

  await client.disconnect()
}

setOraclePrice().catch(console.error)

This is what you should get:

Oracle account: r35gjkjZL4mhqyrabpxVUE9K9T5JW1nng9
OracleSet: tesSUCCESS
Oracle object: https://xaman.app/explorer/21338/5F312C3B5CB2F2D3745D8CE4F4A0EFFFD7770C0C51401DDB52256D28DA019527

To update the price, submit another OracleSet with the same OracleDocumentID and a new LastUpdateTime. Only the fields you include are changed — any price pairs you omit are preserved from the previous submission.

To add a second trading pair to the same oracle object, include both entries in PriceDataSeries:

PriceDataSeries: [
  { PriceData: { BaseAsset: 'XAH', QuoteAsset: 'USD', AssetPrice: 450000, Scale: 6 } },
  { PriceData: { BaseAsset: 'XAH', QuoteAsset: 'EUR', AssetPrice: 410000, Scale: 6 } }
]

Querying the Aggregate Price (`02-price-oracle-query.js`)

Once multiple oracle accounts have published prices for the same pair, any application can request the on-chain aggregate via the get_aggregate_price RPC. This is a read-only query — no transaction fee required:

require('dotenv').config()
const { Client } = require('xahau')

// Oracle accounts to include in the aggregate calculation.
// Each entry must identify the oracle account and the document ID
// of the price feed published by that account (via OracleSet).
// Add or remove entries to include different oracle providers.
const ORACLES = [
  { account: 'rEhZSNh9pVRTcA79tQjYezg9V44HfcToR1', oracle_document_id: 1 },
  { account: 'rD1rh9ffewxVb9QBqkr5ph98QXqCM1xsEP', oracle_document_id: 1 },
  { account: 'r35gjkjZL4mhqyrabpxVUE9K9T5JW1nng9', oracle_document_id: 1 },
]

async function getAggregatePrice() {
  const client = new Client('wss://xahau-test.net')
  await client.connect()

  // get_aggregate_price is a Xahau ledger RPC that reads all listed oracle
  // objects and computes statistical aggregates over their reported prices.
  // No transaction or fee is required — this is a read-only query.
  const response = await client.request({
    command: 'get_aggregate_price',
    ledger_index: 'current',
    base_asset:   'XAH',
    quote_asset:  'USD',
    trim: 20,   // remove the bottom and top 20% of values before averaging
                // to reduce the impact of outlier oracles
    oracles: ORACLES
  })

  const stats = response.result

  // entire_set covers all oracle values before trimming
  // trimmed_set covers only the values remaining after the trim
  console.log('Median:       ', stats.median)
  console.log('Mean:         ', stats.entire_set?.mean)
  console.log('Trimmed mean: ', stats.trimmed_set?.mean)
  console.log('Oracle count: ', stats.entire_set?.size)

  await client.disconnect()
}

getAggregatePrice().catch(console.error)

You should get something like this:

Median:        0.45
Mean:          0.4333333333333334
Trimmed mean:  0.4333333333333334
Oracle count:  3

A few things to know about get_aggregate_price:

You can include up to 200 oracle accounts in the oracles array per request.
The trim parameter removes outliers symmetrically before computing the mean. trim: 20 discards the bottom 20 % and top 20 % of values — useful when you expect a minority of providers to be stale or adversarial. The untrimmed mean and median are always included in the response alongside the trimmed result.
The optional time_threshold field (not shown above) lets you exclude feeds whose LastUpdateTime is older than N seconds relative to the freshest oracle in the set. For example, time_threshold: 60 drops any oracle that hasn't updated in the last minute compared to the most recent provider. In a production environment where stale prices carry real risk, this is worth setting.

Removing an Oracle (`03-price-oracle-delete.js`)

To remove an oracle object from the ledger and recover its XAH reserve, submit an OracleDelete transaction:

require('dotenv').config()
const { Client, Wallet } = require('xahau')

// Must match the OracleDocumentID used when the oracle was created
// (via 01-price-oracle-set.js). Deleting removes the oracle object from
// the ledger entirely and releases the reserve XAH locked by it.
const ORACLE_DOCUMENT_ID = 1

async function deleteOracle() {
  const client = new Client('wss://xahau-test.net')
  await client.connect()

  // Only the account that originally submitted OracleSet can delete it.
  // Set ORACLE_SEED in your .env file.
  const wallet = Wallet.fromSeed(process.env.ORACLE_SEED, { algorithm: 'secp256k1' })
  console.log(`Account:          ${wallet.address}`)
  console.log(`OracleDocumentID: ${ORACLE_DOCUMENT_ID}`)

  // OracleDelete removes the oracle price feed object from the ledger.
  // After deletion, this account's prices will no longer appear in
  // get_aggregate_price responses that list this account.
  const oracleDeleteTx = await client.autofill({
    TransactionType: 'OracleDelete',
    Account: wallet.address,
    OracleDocumentID: ORACLE_DOCUMENT_ID
  })

  const { tx_blob } = wallet.sign(oracleDeleteTx)
  const result = await client.submitAndWait(tx_blob)
  console.log(`OracleDelete: ${result.result.meta.TransactionResult}`)
  console.log(`Explorer: https://xaman.app/explorer/21338/${result.result.hash}`)

  await client.disconnect()
}

deleteOracle().catch(console.error)

Only the account that created the oracle can delete it. After deletion, its prices will no longer appear in get_aggregate_price responses that list this account.

IOURewardClaim: Custom Token Reward Programmes

What Is ClaimReward?

Xahau has a built-in reward mechanism for network participation. Accounts that hold XAH can periodically submit a ClaimReward transaction to receive genesis rewards, a fraction of newly generated XAH, distributed based on how long the account has been staking and participating. This is Xahau's native yield for XAH holders.

Until the IOURewardClaim amendment, this mechanism was exclusive to XAH. If you issued a custom token, a loyalty point, a yield-bearing asset, a staking receipt, there was no native way to tie rewards to it. You'd have to build your own off-chain tracker or use periodic manual payments.

What IOURewardClaim Adds

The IOURewardClaim amendment extends ClaimReward with two new fields:

Issuer — the address of the account running the reward programme
ClaimCurrency — the IOU currency object { currency, issuer } that identifies which reward counter to claim from

This is the full transaction structure:

{
  "TransactionType": "ClaimReward",
  "Account": "rHOLDER...",
  "Issuer": "rRESERVE...",
  "ClaimCurrency": {
    "currency": "RWD",
    "issuer": "rISSUER..."
  }
}

Important: The first Issuer field in this transaction does not refer to the account that created the IOU token. It refers to the account from which you are requesting the reward, the account whose Hook (the reward program) will be triggered. That account can be any Xahau account, completely independent from the token creator. The only requirement is that it has a Hook installed that activates on ttClaimReward transactions. In our setup this is the RESERVE account, which holds the token supply and has the reward Hook installed — but in another programme design it could be a DAO treasury, a smart vault, or any account with the appropriate Hook.

When both fields are present, the ledger looks for a Hook installed on the Issuer account and fires it. The Hook defines all the reward logic: how much to pay, how often, to whom, and under what conditions. This means any account can run its own reward programme for any IOU, all settled natively on-chain via trustlines.

The Three Accounts

This setup involves three distinct accounts, each with a specific role:

Account	Seed in `.env`	Role
ISSUER	`ISSUER_SEED`	Creates and signs the IOU token. Enables `DefaultRipple` so the currency can flow freely through trustlines.
RESERVE	`RESERVE_SEED`	Holds the token supply received from the issuer. Has the reward Hook installed. Is the `Issuer` in ClaimReward transactions.
HOLDER	`HOLDER_SEED`	Any account that wants to claim a reward. Submits the `ClaimReward` transaction.

The separation between ISSUER and RESERVE keeps the token signing key isolated from the operational reward-distribution account. The ISSUER signs the initial token creation; after that, the RESERVE handles all day-to-day reward operations.

Step 1 — Create and Distribute the Token (`04-create-distribute-token.js`)

Before any reward can be paid out, the token must exist on the ledger and the RESERVE account must hold a supply of it. The script 04-create-distribute-token.js does this in three steps.

Before you run it, open the file and set your token details:

const TOKEN_CURRENCY_INPUT = "RWD"; // your 3-char code or a longer name
const TOTAL_SUPPLY         = "1000000";

If your currency name is 3 characters or fewer, Xahau uses it directly (e.g. "RWD"). If it is longer, the script converts it to a 40-character hex representation padded with zeros, the format Xahau uses internally for non-standard currency codes.

require("dotenv").config();
const { Client, Wallet } = require("xahau");

// Required .env variables:
//   ISSUER_SEED  – seed of the account that will create and sign IOU tokens
//   RESERVE_SEED – seed of the account that will hold the supply and distribute rewards
// Get testnet funds at https://xahau-test.net

// Converts a human-readable currency name to the 40-char hex format required
// by Xahau for non-standard (>3 char) currency codes.
// Standard 3-char codes (e.g. "RWD") are returned as-is.
function normalizeCurrency(token_currency) {
  if (typeof token_currency !== "string") return token_currency;

  const cur = token_currency.trim();

  // Standard 3-char currency codes need no conversion
  if (cur.length <= 3) return cur;

  // Convert UTF-8 string to uppercase hex and right-pad to 40 chars (20 bytes)
  const hex = Buffer.from(cur, "utf8").toString("hex").toUpperCase();

  if (hex.length > 40)
    throw new Error(
      `Currency too long: "${cur}" → hex ${hex.length} chars (max 40)`
    );

  return hex.padEnd(40, "0");
}

async function createAndDistributeToken() {
  const client = new Client("wss://xahau-test.net");
  await client.connect();

  // Load both wallets from environment seeds
  const issuer  = Wallet.fromSeed(process.env.ISSUER_SEED,  { algorithm: "secp256k1" });
  const reserve = Wallet.fromSeed(process.env.RESERVE_SEED, { algorithm: "secp256k1" });

  // ── Token configuration ────────────────────────────────────────────────
  // Change TOKEN_CURRENCY_INPUT to your desired currency code or name.
  // Change TOTAL_SUPPLY to the amount you want to mint.
  const TOKEN_CURRENCY_INPUT = "YourTokenName"; // 3-char code or longer name
  const TOTAL_SUPPLY         = "1000000";

  const TOKEN_CURRENCY = normalizeCurrency(TOKEN_CURRENCY_INPUT);

  console.log("=== Token creation ===");
  console.log("Issuer:", issuer.address);
  console.log("Reserve:", reserve.address);
  console.log("Token:", TOKEN_CURRENCY);
  console.log("Supply:", TOTAL_SUPPLY);

  // ── Step 1: Enable DefaultRipple on the issuer ─────────────────────────
  // DefaultRipple (asfDefaultRipple, flag 8) allows the issuer's trustlines
  // to be used for rippling, which is required for IOU tokens to flow
  // between accounts that both trust the same issuer.
  console.log("--- Step 1: DefaultRipple ---");
  const prep1 = await client.autofill({
    TransactionType: "AccountSet",
    Account: issuer.address,
    SetFlag: 8, // asfDefaultRipple
  });
  const result1 = await client.submitAndWait(issuer.sign(prep1).tx_blob);
  console.log("DefaultRipple:", result1.result.meta.TransactionResult);
  if (result1.result.meta.TransactionResult !== "tesSUCCESS") {
    await client.disconnect();
    return;
  }

  // ── Step 2: Reserve account opens a TrustLine toward the issuer ────────
  // A TrustLine must exist before any tokens can be sent. The reserve account
  // signals it is willing to hold up to TOTAL_SUPPLY units of TOKEN_CURRENCY
  // issued by the issuer account.
  console.log("--- Step 2: TrustLine (reserve → issuer) ---");
  const prep2 = await client.autofill({
    TransactionType: "TrustSet",
    Account: reserve.address,
    LimitAmount: {
      currency: TOKEN_CURRENCY,
      issuer: issuer.address,
      value: TOTAL_SUPPLY, // maximum amount the reserve is willing to hold
    },
  });
  const result2 = await client.submitAndWait(reserve.sign(prep2).tx_blob);
  console.log("TrustLine:", result2.result.meta.TransactionResult);
  if (result2.result.meta.TransactionResult !== "tesSUCCESS") {
    await client.disconnect();
    return;
  }

  // ── Step 3: Issuer mints and sends the full supply to the reserve ───────
  // Issuing tokens means sending them from the issuer account to a
  // trustline holder. The issuer never "holds" its own tokens — sending
  // them to the reserve creates them on the ledger for the first time.
  console.log("--- Step 3: Issue tokens (issuer → reserve) ---");
  const prep3 = await client.autofill({
    TransactionType: "Payment",
    Account: issuer.address,
    Destination: reserve.address,
    Amount: {
      currency: TOKEN_CURRENCY,
      issuer: issuer.address,
      value: TOTAL_SUPPLY,
    },
  });
  const result3 = await client.submitAndWait(issuer.sign(prep3).tx_blob);
  console.log("Issuance:", result3.result.meta.TransactionResult);
  if (result3.result.meta.TransactionResult !== "tesSUCCESS") {
    await client.disconnect();
    return;
  }

  console.log("Token created and distributed to the reserve account!");
  console.log("Total supply:", TOTAL_SUPPLY, TOKEN_CURRENCY);

  // ── Verification: query the reserve's trustline balance ────────────────
  // Confirms the tokens arrived correctly by reading account_lines for the
  // reserve and finding the line that matches our currency and issuer.
  console.log("--- Verification ---");
  const lines = await client.request({
    command: "account_lines",
    account: reserve.address,
    ledger_index: "validated",
  });
  const line = lines.result.lines.find(
    (l) => l.currency === TOKEN_CURRENCY && l.account === issuer.address
  );
  if (line) {
    console.log("Reserve balance:", line.balance, TOKEN_CURRENCY);
    console.log("Issuer:", line.account);
    console.log("Limit:", line.limit, TOKEN_CURRENCY);
  }

  await client.disconnect();
}

createAndDistributeToken();

Three concepts worth understanding here:

DefaultRipple (SetFlag: 8) is an account setting that allows the issuer's trustlines to be used for rippling, passing IOU balances through the issuer from one trustline holder to another. Without it, the RESERVE cannot forward tokens to the HOLDER later. This is a one-time setup on the ISSUER account.

TrustLine is a bilateral agreement on the ledger between two accounts for a specific currency. The RESERVE creates a TrustLine toward the ISSUER saying "I am willing to hold up to 1,000,000 RWD issued by this account." Until this line exists, the ISSUER cannot send tokens to the RESERVE.

Issuing tokens on Xahau works by sending them from the issuer account outward. The ISSUER never "holds" its own tokens, sending them to the RESERVE creates them on the ledger for the first time.

Step 2 — The Reward Hook (`iou_reward_hook.c`)

If you're new to Hooks, here's the short version: a Hook is a small WebAssembly program installed on a Xahau account that executes automatically when that account is involved in a transaction. The Hook can accept the transaction, reject it, or, most powerfully, emit new transactions of its own. Think of it as a smart contract that lives on an account rather than at a separate address.

For our reward programme, we install a Hook on the RESERVE account (To simplify the process, I recommend using a separate account for the rewards program on Mainnet). Every time a HOLDER submits a ClaimReward transaction targeting RESERVE, the Hook fires and automatically emits a payment of 1 token back to the claimant, provided all conditions are met.

The Hook (iou_reward_hook.c) receives three configuration parameters set at install time:

Parameter	Key	Size	Description
Currency ticker	`TC`	3 bytes	The ASCII currency code, e.g. `"RWD"`
Issuer AccountID	`IS`	20 bytes	The raw 20-byte AccountID of the ISSUER account
Cooldown	`CD`	4 bytes	Seconds between claims (big-endian uint32)

The Hook logic runs in this order on every ClaimReward:

Filter — if the incoming transaction is not a ClaimReward, accept silently and do nothing.
Read claimant — get the Account field from the transaction (the HOLDER submitting the claim).
Load parameters — read TC, IS, and CD from the hook parameters.
Cooldown check — look up the RippleState (trustline) object between the claimant and the issuer and read the sfLowReward / sfHighReward sub-object to find the timestamp of the last reward claim. If a claim was made within the cooldown window, rollback with an error.
Balance check — look up the RESERVE's trustline to ISSUER and verify it holds at least 1 token. If not, rollback.
Emit payment — serialize 1 token as an IOU STAmount and emit a Payment transaction to the claimant.

#include "hookapi.h"

/*
 * Field definitions for IOURewardClaim fields that may not yet be present
 * in the version of hookapi.h shipped with this hooks-builder release.
 * The guard (#ifndef) ensures they are only defined if missing.
 *
 * sfRewardTime  – UInt32 (type 2, field 98): Ripple-epoch timestamp of the
 *                 last reward claim stored inside the RippleState object.
 * sfHighReward  – STObject (type 14, field 98): reward tracking sub-object
 *                 on the high-balance side of a trustline.
 * sfLowReward   – STObject (type 14, field 99): reward tracking sub-object
 *                 on the low-balance side of a trustline.
 */
#ifndef sfRewardTime
#define sfRewardTime ((2U << 16U) + 98U)
#endif

#ifndef sfHighReward
#define sfHighReward ((14U << 16U) + 98U)
#endif

#ifndef sfLowReward
#define sfLowReward ((14U << 16U) + 99U)
#endif

/*
 * Hook entry point.
 *
 * This hook is installed on the RESERVE account (the one that holds
 * the IOU token supply). It fires on every ClaimReward transaction
 * that targets this account as Issuer, validates a cooldown period
 * and a sufficient token balance, then emits 1 token to the claimant.
 *
 * Hook parameters (set at install time via 12-install-hook.js):
 *   TC (2 bytes)  – 3-char currency ticker, e.g. "RWD"
 *   IS (20 bytes) – AccountID of the IOU issuer (the token creator)
 *   CD (4 bytes)  – big-endian uint32 cooldown in seconds between claims
 */
int64_t hook(uint32_t reserved)
{
    /* Guard call — must be the very first statement.
       The hook guard checker rejects any hook where a loop is reachable
       before _g() / GUARD() has been called at least once.             */
    _g(1, 1);

    /* ── 1. FILTER: only act on ClaimReward transactions ────────────── */
    if (otxn_type() != ttCLAIM_REWARD)
        accept(SBUF("DBG: not ClaimReward"), __LINE__);

    /* ── 2. READ THE CLAIMANT ACCOUNT ────────────────────────────────── */
    /* sfAccount is the originating account of the ClaimReward tx —
       the holder who wants to receive the IOU reward.                   */
    uint8_t claimant[20];
    if (otxn_field(SBUF(claimant), sfAccount) != 20)
        rollback(SBUF("ERR: missing claimant"), __LINE__);

    /* ── 3. READ HOOK PARAMETERS ─────────────────────────────────────── */

    /* TC – 3-byte currency ticker set when the hook was installed */
    uint8_t ticker_key[2] = {'T', 'C'};
    uint8_t ticker[3];
    if (hook_param(SBUF(ticker), SBUF(ticker_key)) != 3)
        rollback(SBUF("ERR: missing TC"), __LINE__);

    /* IS – 20-byte AccountID of the IOU issuer */
    uint8_t issuer_key[2] = {'I', 'S'};
    uint8_t issuer[20];
    if (hook_param(SBUF(issuer), SBUF(issuer_key)) != 20)
        rollback(SBUF("ERR: missing IS"), __LINE__);

    /* CD – cooldown duration in seconds (big-endian uint32) */
    uint8_t cooldown_key[2] = {'C', 'D'};
    uint8_t cooldown_buf[4];
    if (hook_param(SBUF(cooldown_buf), SBUF(cooldown_key)) != 4)
        rollback(SBUF("ERR: missing CD"), __LINE__);

    /* Decode big-endian uint32 from the 4-byte parameter */
    uint32_t cooldown_seconds =
        ((uint32_t)cooldown_buf[0] << 24) |
        ((uint32_t)cooldown_buf[1] << 16) |
        ((uint32_t)cooldown_buf[2] << 8)  |
        ((uint32_t)cooldown_buf[3]);

    /* ── 4. BUILD THE 20-BYTE CURRENCY REPRESENTATION ───────────────── */
    /* XRPL encodes 3-char currency codes as 20 bytes where bytes 12-14
       hold the ASCII characters and all other bytes are 0x00.          */
    uint8_t currency[20] = {
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,
        0,0,0,0,0
    };
    currency[12] = ticker[0];
    currency[13] = ticker[1];
    currency[14] = ticker[2];

    /* ── 5. COOLDOWN CHECK ───────────────────────────────────────────── */
    /*
     * The last reward timestamp is stored inside the RippleState (trustline)
     * object between the claimant and the issuer, under sfLowReward or
     * sfHighReward depending on which side has the numerically lower
     * AccountID. If no RewardTime exists yet, this is a first-time claim
     * and we skip the check.
     *
     * RippleState keylets require the accounts in a canonical order
     * (lower AccountID first), so we compare byte-by-byte first.
     */
    int claim_cmp = 0;
    for (int i = 0; GUARD(20), i < 20; ++i)
    {
        if (claimant[i] < issuer[i]) { claim_cmp = -1; break; }
        if (claimant[i] > issuer[i]) { claim_cmp =  1; break; }
    }

    /* Build the keylet for the claimant↔issuer trustline */
    uint8_t claim_line_keylet[34];
    if (claim_cmp > 0)
    {
        /* claimant is the high-account; pass (claimant, issuer) */
        util_keylet(
            SBUF(claim_line_keylet), KEYLET_LINE,
            (uint32_t)claimant, 20,
            (uint32_t)issuer,   20,
            (uint32_t)currency, 20
        );
    }
    else
    {
        /* issuer is the high-account; pass (issuer, claimant) */
        util_keylet(
            SBUF(claim_line_keylet), KEYLET_LINE,
            (uint32_t)issuer,   20,
            (uint32_t)claimant, 20,
            (uint32_t)currency, 20
        );
    }

    /* Load the trustline into slot 10; if it exists, inspect RewardTime */
    if (slot_set(SBUF(claim_line_keylet), 10) == 10)
    {
        int64_t reward_slot = 0;

        /* Try the LowReward sub-object first, then HighReward */
        reward_slot = slot_subfield(10, sfLowReward, 11);
        if (reward_slot != 11)
            reward_slot = slot_subfield(10, sfHighReward, 11);

        if (reward_slot == 11)
        {
            /* Read sfRewardTime (4-byte Ripple-epoch timestamp) */
            if (slot_subfield(11, sfRewardTime, 12) == 12)
            {
                uint8_t rt_buf[4];
                if (slot(SBUF(rt_buf), 12) == 4)
                {
                    uint32_t last_reward_time =
                        ((uint32_t)rt_buf[0] << 24) |
                        ((uint32_t)rt_buf[1] << 16) |
                        ((uint32_t)rt_buf[2] << 8)  |
                        ((uint32_t)rt_buf[3]);

                    uint32_t now = ledger_last_time();

                    /* Reject if the cooldown window has not elapsed */
                    if (cooldown_seconds > 0 && (now - last_reward_time) < cooldown_seconds)
                        rollback(SBUF("ERR: cooldown active"), __LINE__);
                }
            }
        }
    }

    /* ── 6. BALANCE CHECK ────────────────────────────────────────────── */
    /*
     * Confirm the hook account (the reserve) holds at least 1 token
     * before attempting to emit. This prevents the hook from firing
     * when the reserve is empty, which would cause the emit to fail.
     *
     * reward_amount = 1.0 token (float_set(exponent=0, mantissa=1))
     */
    int64_t reward_amount = float_set(0, 1);

    uint8_t hook_acc[20];
    hook_account(SBUF(hook_acc));

    /* Determine canonical ordering for the hook account ↔ issuer keylet */
    int hook_cmp = 0;
    for (int i = 0; GUARD(20), i < 20; ++i)
    {
        if (hook_acc[i] < issuer[i]) { hook_cmp = -1; break; }
        if (hook_acc[i] > issuer[i]) { hook_cmp =  1; break; }
    }

    uint8_t hook_line_keylet[34];
    if (hook_cmp > 0)
    {
        if (util_keylet(
            SBUF(hook_line_keylet), KEYLET_LINE,
            (uint32_t)hook_acc, 20,
            (uint32_t)issuer,   20,
            (uint32_t)currency, 20
        ) != 34)
            rollback(SBUF("ERR: hook keylet high"), __LINE__);
    }
    else
    {
        if (util_keylet(
            SBUF(hook_line_keylet), KEYLET_LINE,
            (uint32_t)issuer,   20,
            (uint32_t)hook_acc, 20,
            (uint32_t)currency, 20
        ) != 34)
            rollback(SBUF("ERR: hook keylet low"), __LINE__);
    }

    /* Load the hook account's trustline into slot 1 */
    if (slot_set(SBUF(hook_line_keylet), 1) != 1)
        rollback(SBUF("ERR: hook RippleState not found"), __LINE__);

    /* Read the Balance sub-field from slot 1 into slot 2 */
    if (slot_subfield(1, sfBalance, 2) != 2)
        rollback(SBUF("ERR: hook balance not found"), __LINE__);

    /* Convert the slot value to an XLS-17d float */
    int64_t balance = slot_float(2);

    /* RippleState balances are stored from the low-account's perspective.
       If the hook account is on the high side, negate to get its true balance. */
    if (hook_cmp > 0)
        balance = float_negate(balance);

    /* Reject if the reserve does not have at least 1 token left */
    if (float_compare(balance, reward_amount, COMPARE_LESS))
        rollback(SBUF("ERR: insufficient token balance"), __LINE__);

    /* ── 7. EMIT THE REWARD PAYMENT ──────────────────────────────────── */
    /* Reserve one emitted transaction slot */
    etxn_reserve(1);

    /*
     * Serialize the IOU amount into a 48-byte STAmount buffer.
     * float_sto writes the amount starting at (amt_out - 1) with write_len=49
     * so that the field-code prefix byte lands just before amt_out[0],
     * leaving amt_out[0..47] as the raw 48-byte value that
     * PREPARE_PAYMENT_SIMPLE_TRUSTLINE expects as its tlamt argument.
     */
    uint8_t amt_out[48];
    if (float_sto(
        (uint32_t)(amt_out - 1), 49,
        SBUF(currency),
        SBUF(issuer),
        reward_amount,
        sfAmount
    ) < 0)
        rollback(SBUF("ERR: amount serialize failed"), __LINE__);

    /* Build the full Payment transaction using the trustline macro.
       Arguments: output buffer, IOU amount (48 bytes), destination,
       destination tag (0), source tag (0).                          */
    uint8_t txn[PREPARE_PAYMENT_SIMPLE_TRUSTLINE_SIZE];
    PREPARE_PAYMENT_SIMPLE_TRUSTLINE(txn, amt_out, claimant, 0, 0);

    /* Emit the transaction; emit() returns 32 (the hash length) on success */
    uint8_t emithash[32];
    if (emit(SBUF(emithash), SBUF(txn)) != 32)
        rollback(SBUF("ERR: emit failed"), __LINE__);

    accept(SBUF("OK: emitted 1 token"), __LINE__);
}

You can also paste iou_reward_hook.c directly into builder.xahau.network and compile there. Once you have iou_reward_hook.wasm, place it in the project root alongside 05-install-hook.js. You can download iou_reward_hook.wasm from the repository too.

Step 3 — Install the Hook (`05-install-hook.js`)

With the WASM file ready, 05-install-hook.js submits a SetHook transaction on the RESERVE account. Before running it, update these three values at the top of the file to match your setup:

const rewardIssuer   = "rYOUR_ISSUER_ADDRESS_HERE"; // your ISSUER account address
const ticker         = "RWD";                        // must match TOKEN_CURRENCY_INPUT
const cooldownSeconds = 300;                         // seconds between claims (here: 5 min)

require("dotenv").config();
const fs = require("fs");
const crypto = require("crypto");
const { Client, Wallet, classicAddressToXAddress, decodeAccountID } = require("xahau");

const WASM_PATH = "./iou_reward_hook.wasm";

const HOOK_ON = "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFFFFFFFFFFFFFFFBFFFFF";

const HOOK_NAMESPACE = crypto
  .createHash("sha256")
  .update("IOUReward")
  .digest("hex")
  .toUpperCase();

function hex(str) {
  return Buffer.from(str, "utf8").toString("hex").toUpperCase();
}

function uint32ToHex(value) {
  const b = Buffer.alloc(4);
  b.writeUInt32BE(value);
  return b.toString("hex").toUpperCase();
}

function accountToAccountIDHex(address) {
  return Buffer.from(decodeAccountID(address)).toString("hex").toUpperCase();
}

async function installHook() {
  const client = new Client("wss://xahau-test.net");
  await client.connect();

  const hookAccount = Wallet.fromSeed(process.env.RESERVE_SEED, {
    algorithm: "secp256k1",
  });

  const rewardIssuer = "IssuerAddress";
  const ticker = "YourTokenTicker";
  const cooldownSeconds = 300;

  if (ticker.length !== 3) {
    throw new Error("Ticker must be exactly 3 characters");
  }

  const issuerAccountIdHex = accountToAccountIDHex(rewardIssuer);

  console.log("=== Hook installation ===");
  console.log("Hook account:", hookAccount.address);
  console.log("Reward issuer:", rewardIssuer);
  console.log("Reward issuer AccountID:", issuerAccountIdHex);
  console.log("Ticker:", ticker);
  console.log("Cooldown seconds:", cooldownSeconds);
  console.log("Namespace:", HOOK_NAMESPACE);
  console.log("HookOn:", HOOK_ON);

  if (!fs.existsSync(WASM_PATH)) {
    console.error(`WASM file not found: ${WASM_PATH}`);
    await client.disconnect();
    return;
  }

  const wasmHex = fs.readFileSync(WASM_PATH).toString("hex").toUpperCase();

  const setHookTx = await client.autofill({
    TransactionType: "SetHook",
    Account: hookAccount.address,
    Hooks: [
      {
        Hook: {
          CreateCode: wasmHex,
          HookApiVersion: 0,
          HookNamespace: HOOK_NAMESPACE,
          HookOn: HOOK_ON,
          Flags: 1, // hsfOVERRIDE

          HookParameters: [
            {
              HookParameter: {
                HookParameterName: hex("TC"),
                HookParameterValue: hex(ticker), // RWD = 525744
              },
            },
            {
              HookParameter: {
                HookParameterName: hex("IS"),
                HookParameterValue: issuerAccountIdHex, // 20 bytes / 40 hex chars
              },
            },
            {
              HookParameter: {
                HookParameterName: hex("CD"),
                HookParameterValue: uint32ToHex(cooldownSeconds), // 300 = 0000012C
              },
            },
          ],
        },
      },
    ],
  });

  const { tx_blob } = hookAccount.sign(setHookTx);
  const result = await client.submitAndWait(tx_blob);

  console.log("SetHook:", result.result.meta.TransactionResult);
  console.log(`Explorer: https://xaman.app/explorer/21338/${result.result.hash}`);

  await client.disconnect();
}

installHook().catch(console.error);

A few things to note:

HookNamespace is a 32-byte identifier that groups all state entries written by this hook. We derive it deterministically from the string "IOUReward" using SHA-256 so it is always reproducible and unique to this hook.

HookOn is a 64-character hex bitmask where each bit corresponds to a transaction type. A bit set to 1 means the hook does not fire for that transaction. Our value has all bits set to 1 except the bit for ClaimReward, so the hook fires exclusively on that transaction type.

HookParameters passes the three configuration values into the hook at install time. The hook reads these on every execution using hook_param(). Parameters are stored in the ledger as key-value pairs where both key and value are hex-encoded bytes.

Step 4 — Claiming IOU Rewards (`06-claim-reward-iou.js`)

With the hook installed on the RESERVE account and the HOLDER ready to claim, 07-claim-reward-iou.js handles the full claim flow. Set TOKEN_CURRENCY_INPUT to match what you used in 04-create-distribute-token.js.

The script does two things before submitting the ClaimReward:

Checks for a TrustLine between the HOLDER and the ISSUER. The HOLDER needs this line to be able to receive the IOU tokens that the hook will emit.
Creates the TrustLine automatically if it does not already exist, so the holder does not have to do a separate manual step.

require("dotenv").config();
const { Client, Wallet } = require("xahau");

// Required .env variables:
//   ISSUER_SEED  – seed of the IOU token creator (used for TrustLine setup)
//   RESERVE_SEED – seed of the account that holds the supply and has the hook installed
//   HOLDER_SEED  – seed of the account claiming the reward (must have testnet funds)
// Get testnet funds at https://xahau-test.net

// Must match the currency code used in 04-create-distribute-token.js
const TOKEN_CURRENCY_INPUT = "YourTokenAddress";

// Converts a human-readable currency name to the 40-char hex format required
// by Xahau for non-standard (>3 char) currency codes.
function normalizeCurrency(token_currency) {
  if (typeof token_currency !== "string") return token_currency;
  const cur = token_currency.trim();
  // Standard 3-char codes need no conversion
  if (cur.length <= 3) return cur;
  const hex = Buffer.from(cur, "utf8").toString("hex").toUpperCase();
  if (hex.length > 40)
    throw new Error(`Currency too long: "${cur}" → hex ${hex.length} chars (max 40)`);
  return hex.padEnd(40, "0");
}

const TOKEN_CURRENCY = normalizeCurrency(TOKEN_CURRENCY_INPUT);

async function claimIouReward() {
  const client = new Client("wss://xahau-test.net");
  await client.connect();

  // Load all three wallets involved in the flow
  const issuer  = Wallet.fromSeed(process.env.ISSUER_SEED,  { algorithm: "secp256k1" });
  const reserve = Wallet.fromSeed(process.env.RESERVE_SEED, { algorithm: "secp256k1" });
  const holder  = Wallet.fromSeed(process.env.HOLDER_SEED,  { algorithm: "secp256k1" });

  console.log("=== IOU Reward Claim ===");
  console.log("Holder:", holder.address);
  console.log("Issuer:", issuer.address);
  console.log("Token: ", TOKEN_CURRENCY);

  // ── Step 1: Ensure the holder has a TrustLine to the issuer ───────────
  // The holder needs a TrustLine toward the ISSUER (the token creator)
  // in order to receive IOU tokens as the reward payment emitted by the hook.
  // We query existing lines first to avoid submitting a redundant TrustSet.
  const lines = await client.request({
    command: "account_lines",
    account: holder.address,
    peer: issuer.address,   // filter lines between holder and issuer only
    ledger_index: "validated",
  });

  // Check whether a line for this specific currency already exists
  const hasTrustLine = lines.result.lines.some(
    (l) => l.currency === TOKEN_CURRENCY && l.account === issuer.address
  );

  if (!hasTrustLine) {
    // TrustLine does not exist — create it so the holder can receive tokens
    console.log("--- TrustLine not found, creating it ---");
    const trustSetTx = await client.autofill({
      TransactionType: "TrustSet",
      Account: holder.address,
      LimitAmount: {
        currency: TOKEN_CURRENCY,
        issuer: issuer.address,
        value: "1000000", // maximum tokens the holder is willing to hold
      },
    });
    const trustResult = await client.submitAndWait(holder.sign(trustSetTx).tx_blob);
    console.log("TrustSet:", trustResult.result.meta.TransactionResult);
    if (trustResult.result.meta.TransactionResult !== "tesSUCCESS") {
      console.error("TrustLine creation failed, aborting.");
      await client.disconnect();
      return;
    }
  } else {
    console.log("--- TrustLine already exists, skipping ---");
  }

  // ── Step 2: Submit the ClaimReward transaction ─────────────────────────
  // Issuer  – the RESERVE account, which has the reward hook installed.
  //           The ledger fires the hook on this account when it processes
  //           the ClaimReward.
  // ClaimCurrency – identifies which IOU trustline's reward counter to claim.
  //           Both currency and issuer point to the RESERVE account because
  //           that is the account distributing the reward tokens.
  console.log("--- Submitting ClaimReward ---");
  const claimTx = await client.autofill({
    TransactionType: "ClaimReward",
    Account: holder.address,
    Issuer: reserve.address,          // account whose hook fires
    ClaimCurrency: {
      currency: TOKEN_CURRENCY,
      issuer: issuer.address,        // issuer of the reward currency
    },
  });

  const { tx_blob } = holder.sign(claimTx);
  const result = await client.submitAndWait(tx_blob);
  console.log("ClaimReward:", result.result.meta.TransactionResult);
  console.log(`Explorer: https://xaman.app/explorer/21338/${result.result.hash}`);

  await client.disconnect();
}

claimIouReward().catch(console.error);

Let's unpack the ClaimReward transaction fields:

Account — the HOLDER, the account submitting the claim and receiving the reward.
Issuer — the RESERVE address. This tells the ledger which account's Hook to fire. The ledger looks up any Hook installed on this account and executes it with the ClaimReward as the originating transaction.
ClaimCurrency — identifies the specific IOU reward counter to claim from, using the token's currency code and the RESERVE address. This field is what distinguishes an IOU claim from a genesis XAH claim.

When the ledger processes this transaction, it fires the Hook on the RESERVE account. The Hook validates the cooldown and balance, then emits a Payment of 1 RWD token from RESERVE to the HOLDER. Because RESERVE holds RWD on a trustline to ISSUER, and HOLDER also has a trustline to ISSUER, the payment ripples through the ISSUER account, RESERVE's balance decreases, HOLDER's balance increases, and the ISSUER acts as the bridge (which is why DefaultRipple was required in step 1).

The Full Picture

Here is a summary of the complete IOURewardClaim flow from start to finish:

ISSUER account
  └─ AccountSet(DefaultRipple)                  ← one time only
  └─ ← TrustSet from RESERVE                    ← RESERVE opens line to ISSUER
  └─ Payment → RESERVE (1,000,000 RWD)          ← mints and distributes supply

RESERVE account
  └─ SetHook(iou_reward_hook.wasm)              ← install hook with TC/IS/CD params
  └─ holds 1,000,000 RWD from ISSUER

HOLDER account
  └─ TrustSet → ISSUER (auto, via script 07)    ← opens line to receive tokens
  └─ ClaimReward(Issuer: RESERVE, ClaimCurrency: RWD/ISSUER)
       ↓ ledger fires Hook on RESERVE
       ↓ Hook checks cooldown + balance
       ↓ Hook emits Payment(1 RWD → HOLDER)
  └─ receives 1 RWD via rippling through ISSUER

Summary

Feature	Amendment	Transaction Types	What It Adds
PriceOracle	`featurePriceOracle`	`OracleSet`, `OracleDelete` + `get_aggregate_price` RPC	On-chain price feeds, up to 10 pairs per oracle, up to 200 oracles per aggregate query
IOURewardClaim	`featureIOURewardClaim`	`ClaimReward` (extended)	`Issuer` + `ClaimCurrency` fields enable custom IOU reward programmes via Hooks

Resources

If this is your first time here, I recommend starting with What is Xahau? and working your way through the series before diving in.

Have questions about PriceOracle or IOURewardClaim? Leave a comment below or find us in the Xahau Discord.

Learning Xahau: Debunking Common Myths About Xahau

Ekiserrepe — Sun, 10 May 2026 10:50:31 +0000

If you spend enough time reading discussions about Xahau, you’ll quickly notice that many people talk about the blockchain and its capabilities without fully understanding how it actually works.

The rise of AI-generated content, combined with the lack of deep technical research in many online discussions, has created an environment where misinformation spreads extremely fast. Over the last few months, I’ve repeatedly seen the same myths, misunderstandings, and inaccurate comparisons appear across social media.

So I decided to write this article to help clarify some of the most common misconceptions surrounding Xahau.

If you want to learn more about Xahau, I also recommend checking out the rest of the Learning Xahau series, where I share information about the ecosystem, automation concepts, development ideas, and practical use cases for builders interested in working with Xahau.

Today, however, we’re going to focus on breaking down some of the most common myths I’ve encountered online.

1. “Xahau Is an XRP Ledger Sidechain”

This is probably the most repeated myth.

XRP Ledger and Xahau share technological origins, but Xahau is not a native sidechain connected to the XRP Ledger.

Xahau is an independent Layer 1 blockchain built from a fork of XRPL code that evolved in a completely different direction.

That means:

Xahau has its own validators
Xahau has its own native asset: XAH
Xahau has its own governance and technical evolution
XRPL amendments do not automatically appear on Xahau

Both networks may occasionally adopt ideas from one another, but they evolve independently.

There are features available on XRP Ledger that do not exist on Xahau, and there are features on Xahau that do not exist on XRP Ledger.

Part of the sidechain confusion comes from the early history of the project.

In the beginning, Xahau was actually described as a sidechain, including in early versions of its whitepaper. At that time, there was a mechanism where XRP could be burned on the XRP Ledger and converted into XAH on the Xahau blockchain. However, that process was eventually closed. Once that bridge mechanism disappeared, the term “sidechain” no longer made technical sense.

Today, Xahau operates as an independent Layer 1 blockchain, even though it still shares part of its original codebase heritage with XRP Ledger.

2. “Projects Built on Xahau Don’t Actually Use XAH”

This is another claim I’ve seen online that honestly surprised me.

In many blockchain ecosystems, “adoption” often refers to companies using private versions of the technology, centralized services, or additional enterprise services offered by blockchain companies, while still presenting it publicly as if they were directly using the public blockchain itself. In some cases, the public chain or its native asset barely participates in the actual operation behind the scenes. Xahau works differently.

To interact with the network, you need XAH. Because XAH is the native asset required for network operation. XAH is a gas token.

XAH is used for:

Account/Object reserves
Transaction execution
Hook interactions

There is no artificial separation between “the technology” and “the public blockchain.” Xahau only makes sense if the blockchain itself is actively used.

3. “Hooks Are Just Ethereum Smart Contracts”

No. While both systems enable automation, the philosophy behind them is completely different.

In Ethereum, smart contracts are typically full decentralized applications deployed directly on-chain. In Xahau, Hooks are lightweight pieces of logic attached directly to accounts that react to specific ledger events.

This creates a very different model:

Compact logic
Deterministic behavior
Native account integration
Direct financial automation

Hooks were never designed to replicate the EVM.

4. “The XAH You See on XRPL Is Native XAH”

No.

When you see XAH traded on the XRP Ledger DEX, you are usually seeing an IOU representation of XAH, not native XAH itself.

Even worse, multiple fake IOUs using the name “XAH” have appeared over time, created by scammers attempting to mislead users.

At the moment, the main legitimate XAH IOU on XRPL is issued by Gatehub:

Currency Code: XAH
Issuer: rswh1fvyLqHizBS2awu1vs6QcmwTBd9qiv

Native XAH only exists directly on the Xahau blockchain. This is similar to how wrapped versions of BTC or ETH exist on other blockchains without being the native assets themselves.

And this distinction matters because certain features only exist directly on Xahau, such as Balance Adjustment, which currently provides around 4%.

5. “Xahau Is Just XRP Ledger With Smart Contracts”

That explanation is far too simplistic.

Yes, Hooks are one of the biggest innovations introduced by Xahau. But Xahau also introduces new programmable dynamics and a different philosophy around financial automation.

The goal is not simply to “add smart contracts.”

The goal is to allow users to integrate custom business logic directly into the ledger itself. That fundamentally changes how financial systems can be automated.

6. “Hooks Are Dangerous Because They Can Do Anything”

Actually, Hooks were specifically designed with limitations in mind. Strict execution limits and deterministic behavior exist precisely to avoid many of the problems seen in more open smart contract environments. Those limitations are not weaknesses. They are part of the design philosophy.

Instead of allowing infinite complexity, Hooks prioritize:

Predictability
Efficiency
Security
Low operational costs
Native integration

7. “Xahau Depends on Ripple”

Ripple does not own or control Xahau.

Xahau emerged after years of research and development surrounding Hooks technology. Originally, Hooks were expected to become part of XRP Ledger itself. However, after significant pushback, the developers behind the Hooks project decided not to abandon years of work and instead launched an independent blockchain where Hooks could exist natively: Xahau.

Like XRPL, Xahau is built using open-source technology and independent validators. Ripple has no governance control or any type of control over Xahau.

Interestingly, it was later announced that a certain level of programmability would be introduced to the XRP Ledger, beginning with features such as Smart Escrows, expected around late 2025. As of May 2026, those features have still not arrived in production.

8. “Xahau Is Trying to Compete With Every Other Blockchain”

The blockchain industry often frames everything as a constant war between ecosystems:

One chain vs another
One token vs another
One community attacking another

But Xahau does not necessarily need to operate under that mentality. Financial institutions are free to use whatever technologies they consider useful. And in reality, most companies rarely depend on a single infrastructure provider.

An organization may simultaneously use:

Multiple blockchains
Traditional banking systems
Private infrastructure
Internal automation tools

Xahau does not need to “win” a blockchain war to be useful.

There’s also an uncomfortable reality within this industry:

Many blockchain companies directly or indirectly pay for institutional pilots and demonstrations through:

PoCs
Pilot programs
Corporate demos
Marketing partnerships

And in many cases, those institutions never end up using the public blockchain or native token at all. Yet the announcements are still heavily promoted to generate speculation and marketing narratives. That creates enormous confusion within crypto communities.

Xahau is attempting to follow a different philosophy. The goal is not to manufacture headlines. The goal is to build tools that can actually function in real regulatory and financial environments. And if institutions choose to combine Xahau with other technologies, they can. Because the objective is not to “win a competition.” The objective is to build useful technology.

Final Thoughts

Understanding Xahau requires looking beyond the usual blockchain narratives. Too often, people try to categorize every project using the same labels: Ethereum competitor, XRPL sidechain, smart contract platform, or DeFi chain. But Xahau was not designed to fit neatly into those categories. Its philosophy is different.

Instead of chasing maximum complexity, Xahau focuses on making financial automation more integrated, predictable, and usable directly at the ledger level.

Whether Xahau succeeds long term will ultimately depend on real adoption, real builders, and real utility, not marketing narratives or social media speculation.

And that is probably the most important thing to understand about Xahau: the goal is not to imitate what already exists, but to explore a different way of building programmable financial systems.

Learning Xahau: Building an Automatic NFT Factory with Hooks

Ekiserrepe — Sat, 14 Mar 2026 20:36:05 +0000

Welcome to a new chapter of Learning Xahau, where we explore the theoretical and practical aspects of the Xahau blockchain. If you are new to the series, I recommend starting with the first article to understand what Xahau is and what makes it different.

Today we are going to build something concrete: an automatic NFT factory. A Hook that turns a Xahau account into a URIToken vending machine: the user pays, the Hook mints. No marketplace. No backend. No servers. Just on-chain logic.

The source code is available at: https://github.com/Ekiserrepe/auto_nft_factory_xahau

The problem we want to solve

Imagine you are an artist, a project, or simply someone who wants to distribute an NFT collection on Xahau. You have your images uploaded to IPFS, your metadata prepared, and you know exactly how much you want to charge for each piece. Now what?

The usual options are:

Registering on a marketplace and giving control of the process to a third-party platform.
Building your own backend: a server that listens for incoming payments, mints the corresponding NFT, and sends it to the buyer. This means infrastructure, maintenance, costs, and a centralized point of failure.

None of these options are ideal if what you want is autonomy and simplicity. This is where Xahau, with its Hook system, offers a completely different alternative.

The solution: a Hook as an automatic factory

The NFT Factory Hook is a smart contract written in C that is installed directly on a Xahau account. From that moment on, every time someone sends an exact payment of XAH to that account, the Hook:

Validates that the received amount exactly matches the configured price.
Reads the minted NFT counter from the Hook state.
Increments the counter and verifies that the collection limit has not been exceeded.
Builds the final URI: base path + zero-padded number + extension.
Emits a URIToken Remit transaction that mints the NFT and sends it directly to the buyer.
Stores the new counter in the Hook state for the next mint.

All of this happens in a single atomic process, without external servers and without human intervention.

What is a URIToken?

Before diving into the technical details, it is worth clarifying what URITokens are, which is the native NFT standard of Xahau.

URITokens are simple and unique objects directly linked to an account. Each URIToken has:

A URI pointing to the content (image, metadata, etc.), typically stored on IPFS.
A single owner at any given time.
The ability to be transferred or burned.

They are easy to index and manage, and thanks to Hooks you can implement custom logic such as royalties or transfer restrictions.

If you need to find information about NFTs on Xahau for your projects, here are a couple of APIs you can use:

The Xahau Remit transaction allows you, in a single operation, to mint a new URIToken and transfer it to the recipient without requiring the recipient to authorize receiving it, as happens with URITokenCreateSellOffer. This is exactly what we use in this Hook.

How the Hook works internally

Configuration parameters

When installing our Hook, we must prepare the following parameters. The Hook is configured at installation time using these four parameters:

Parameter	Type	Size	Description
`AMOUNT`	uint64 big-endian	8 bytes	Exact price in XAH drops
`URI`	ASCII	1–200 bytes	Base IPFS content path (with trailing slash)
`EXT`	ASCII	1–16 bytes	File extension: `.json`, `.png`, etc.
`NUM`	uint32 big-endian	4 bytes	Maximum number of NFTs in the collection

For example, for a collection of 100 NFTs priced at 10 XAH each:

AMOUNT → 0000000000989680   (10,000,000 drops = 10 XAH)
NUM    → 00000064            (100 NFTs)
URI    → ipfs://bafybei.../  (your IPFS CID)
EXT    → .json

You can encode your own values here:
https://transia-rnd.github.io/xrpl-hex-visualizer/

Example parameters

To make it easier for you to practice with this exercise, I have uploaded two test NFT collections to IPFS: one with 100 NFTs and another with 10 NFTs.

100 NFTs (Includes files XXX.json)

ipfs://bafybeig5t3mn2s2mv6ns7o65ee4qz6gw7w47hdovjtmq54qz6fsiv2ctfu/

10 NFTs (Includes files XX.json)

ipfs://bafybeifhquw7q5wsd3h5t6r5j6mjtvroivfv3du7wbqgl6jbdgyrmbn6vq/

The generated URI format

Each NFT receives a unique URI constructed as follows:

<URI> + <zero-padded counter> + <EXT>

The counter width is automatically calculated from the number of digits in NUM:

NUM	Width	Resulting URI example
25	2	`ipfs://.../01.json`
1000	4	`ipfs://.../0001.json`
100000	6	`ipfs://.../000001.json`

This guarantees that NFTs are correctly ordered in any system that indexes by URI.

The Hook state

We need to store the number of NFTs minted so far in memory so that the hook does not mint the same NFT twice or skip any. The hook stores this counter value in the variable CNT:

Key	Size	Content
`CNT`	4 bytes	Number of the last minted NFT, big-endian uint32

The state is only updated after a successful emission, so a failed transaction never advances the counter. The first mint starts from 0 and mints number 1. This ensures the hook does not skip NFTs.

The minting flow

Incoming XAH payment
       │
       ▼
Is it exactly AMOUNT drops?  ──No──▶ rollback (payment rejected)
       │ Yes
       ▼
Is CNT + 1 ≤ NUM?  ──No──▶ rollback (collection sold out, payment rejected)
       │ Yes
       ▼
Build URI: base + counter + extension
       │
       ▼
Emit URIToken Remit → NFT minted and sent to buyer
       │
       ▼
Store new CNT in state
       │
       ▼
accept ✓

An important detail: when the collection is sold out or the payment does not match, the Hook calls rollback, which rejects the entire transaction. The buyer does not lose their XAH because the payment never gets executed.

Another detail is that the Remit transaction used to send the URIToken will send 0.20 XAH to the user so they can accept the NFT in case their balance reaches zero when purchasing the NFT. Therefore you will need to take this into account when setting the NFT price.

How to install the Hook

There are two ways to activate the Hook on your account.

Option A: Deploy from your own `.wasm`

Use create_hook_nft_factory.js to deploy the Hook from the .wasm binary you compiled yourself. This option gives you full control over the code running on-chain.

To compile the source code you need the hook-toolkit:

hooks-cli init c nft_factory
cd nft_factory
yarn install
yarn run build

Option B: Install using the already deployed HookHash

If you prefer not to compile, use install_hook_nft_factory.js to reference the binary that is already deployed on the network. The script points directly to the Hook by its hash, without uploading new code.

The HookHash corresponding to the source code in this repository is:

6786DE24C37FFCDEED643CED581793D4E47BC54FA0D796D35FEA0CBF1338C19B

This hash is valid on both Xahau Testnet and Xahau Mainnet.

You will need to edit each HookParameterValue with the values that define your collection. In this code, the order is IPFS, EXT, NUM, AMOUNT. Check the Configuration parameters section aboce to see how to fill them using https://transia-rnd.github.io/xrpl-hex-visualizer/

"TransactionType": "SetHook",
      "Account": my_wallet.address,
      "Flags": 0,
      "Hooks": [
        {
          "Hook": {
            "HookHash": "6786DE24C37FFCDEED643CED581793D4E47BC54FA0D796D35FEA0CBF1338C19B",
            "HookOn": 'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFE', //Only Payments https://richardah.github.io/xrpl-hookon-calculator/
            "HookCanEmit": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFFFFFFFFFFFFBFFFFF", //Can emit remits
            "HookNamespace": crypto.createHash('sha256').update('nft_factory').digest('hex').toUpperCase(),
            "Flags": 1,
            "HookParameters": [
              {
              "HookParameter": {
              "HookParameterName": "555249", //URI base
              "HookParameterValue": stringToHex("ipfs://bafybeig5t3mn2s2mv6ns7o65ee4qz6gw7w47hdovjtmq54qz6fsiv2ctfu/"),
              }
              },
              {
              "HookParameter": {
              "HookParameterName": "455854", //EXTENSION
              "HookParameterValue": "2E6A736F6E" //.json
              }
              },
              {
              "HookParameter": {
              "HookParameterName": "4E554D", //NUMBER OF NFTS
              "HookParameterValue": "00000064" //100
              }
              },
                            {
              "HookParameter": {
              "HookParameterName": "414D4F554E54", //AMOUNT XAH
              "HookParameterValue": "0000000000989680" // 10000000
              }
              }
              ]
          }
        }
      ],

Warning: This Hook is provided as-is. The author is not responsible for any problems it may cause. It is strongly recommended that you compile and audit your own version. Community forks and improvements are welcome.

Practical considerations

Always test on testnet first

Before installing the Hook on mainnet, deploy it on testnet:

const network = 'wss://xahau-test.net'; // Testnet
// const network = 'wss://xahau.network'; // Mainnet

You can obtain a testnet account at https://xahau-test.net/

The business layer perspective

This project is a very direct example of what Xahau enables: turning an account into an autonomous service. There is no database, no API, no server to maintain. The business logic lives on the blockchain and runs by itself.

This opens the door to scenarios that previously required complex infrastructure:

Digital art collection launches where the artist only needs an account and a folder on IPFS.
Credential or ticket distribution as on-chain verifiable URITokens.
Generative collections where metadata for each number is pre-generated and stored on IPFS.
Membership systems where each NFT represents an access level.
Game unlockables where each NFT represents parts of a game, characters, or items.

The NFT factory is a building block. From here, combining it with additional Hooks, CronSet, adapting it for marketplaces or any other logic is simply a matter of imagination.

Web Service for Non-Coders

Not everyone has, or wants to have, the technical knowledge required to manage a hook. For this reason, I have created a front-end that allows users to generate collections and have a minting page for anyone who wants to experiment with the hook. The address is: https://nft.xahau.love/

The Xahau NFT Pop-Up Shop allows users, through a simple form, to install, modify, or remove a Hook on a Xahau Mainnet/Testnet account provided through Xaman. This means you don’t have to deal with servers or password management within them.

The website also generates a unique page, based on the Xahau address and the selected network, where others can mint NFTs from the collection through Xaman.

This project is purely educational. I am aware that some members of the Xahau community are working on a marketplace for URITokens on Xahau, and I hope to see and enjoy it soon.

Conclusion

The NFT Factory Hook demonstrates that you do not need a marketplace or a backend to launch an NFT collection on Xahau. With a properly configured Hook, your account becomes an autonomous vending machine: it receives the exact payment, mints the NFT, and delivers it, all within the same transaction and without human intervention. Of course, a marketplace offers additional services beyond minting third-party tokens, such as visibility and marketing. Marketplaces on Xahau can also be managed by Hooks.

The code for this exercise is open and available at
https://github.com/Ekiserrepe/auto_nft_factory_xahau

I invite you to test it on testnet, audit it, and most importantly, build better versions.

As always: we are still in the early days of Xahau. The tools are there. What is missing are the ideas—and those are up to you.

Possible improvements and ideas

Mientras estaba escribiendo este artículo se me han ocurrido los siguientes puntos de mejoras o ideas:

Create a front-end to give other people the ability to mint their own collections.
Add improvements to the Hook for error handling. For example, stopping the collection emission if an error is detected or resetting the minted NFT counter.
Generate a version with time-based bidding. Users send their bids to the minting account, and when the time period ends, the NFT is issued to the highest bidder while the funds are returned to the non-winning bidders.
A middleman version. Improve the Hook and add a service fee for minting NFTs on behalf of others.
Static or dynamic blacklisting, for example: once an address receives an NFT, it is no longer allowed to purchase another NFT from that collection.
Handle PreAuth cases

Acknowledgements

Thanks to Handy_4ndy for his library XahauHooks101, which made this project possible.

Learning Xahau: Automating Reward Claims with Hooks and CronSet

Ekiserrepe — Sat, 22 Nov 2025 13:21:02 +0000

Introduction

If you've been following the Xahau blockchain, you know that claiming rewards is a fundamental part of participating in the ecosystem. Every account that opts in can claim rewards approximately every 30 days. But here's the thing: manually tracking when to claim and executing transactions every month can become tedious. The closest thing that exists today is the fantastic Balance Adjustment app for Xaman, which sends you a push notification as the date approaches so you can claim your XAH. What if we could automate this entire process?

Today, I'm excited to share a complete example solution that automates reward claiming on Xahau using Hooks and CronSet transactions. This tutorial covers the entire lifecycle of reward automation. Of course, it's an example meant to inspire others to build better solutions.

Update: I created a wizard to help you configure the entire process in an easy way using Xaman: https://claim.xahau.love. They guys from XahauExplorer also have one: https://xahauexplorer.com/services/reward-auto-claim

The Problem We're Solving

Let me paint you a picture. You have multiple Xahau accounts, each eligible for rewards every 30 days, 2 hours, and 13 minutes (precisely 2,599,980 seconds). Missing a claim means delaying your rewards. Tracking multiple accounts manually? That's a recipe for mistakes and missed opportunities.

The traditional approach requires:

Remembering when each account last claimed
Calculating the next eligible time
Being available to submit transactions at the right moment
Repeating this process indefinitely

There has to be a better way, right?

The Solution: Combining Hooks with CronSet

You can find the repository with the entire process at this link: https://github.com/Ekiserrepe/cron-claimreward-xahau

Our automated reward claiming system leverages two powerful Xahau features:

Hooks: Smart contracts that execute automatically on transactions
CronSet: Scheduled transactions that run at predetermined intervals

By combining these technologies, we create a "set it and forget it" system that claims your rewards automatically for months or even years ahead.

Understanding the Architecture

The system consists of several interconnected components:

Account Setup → Hook Installation → Cron Scheduling → Automated Execution

Each component plays a crucial role:

1. The ClaimReward Hook (C Code)

The heart of our automation is a Hook written in C that executes ClaimReward transactions automatically. This hook is a simplified copy of the TreasuryHook which I recommend checking out.

The Hook hash (805351CE26FB79DA00647CEFED502F7E15C2ACCCE254F11DEFEDDCE241F8E9CA) is consistent across both testnet and mainnet, ensuring reliability and trustworthiness.

#include "hookapi.h"

// Macro to flip endianness for 32-bit values
#define FLIP_ENDIAN(x) ((((x) & 0xFF000000) >> 24) | \
                        (((x) & 0x00FF0000) >> 8)  | \
                        (((x) & 0x0000FF00) << 8)  | \
                        (((x) & 0x000000FF) << 24))

// ClaimReward transaction template
uint8_t ctxn[251] =
{
/* size,upto */
/* 3,    0, tt = ClaimReward      */   0x12U, 0x00U, 0x62U,
/* 5,    3  flags                 */   0x22U, 0x00U, 0x00U, 0x00U, 0x00U,
/* 5,    8, sequence              */   0x24U, 0x00U, 0x00U, 0x00U, 0x00U,
/* 6,   13, firstledgersequence   */   0x20U, 0x1AU, 0x00U, 0x00U, 0x00U, 0x00U,
/* 6,   19, lastledgersequence    */   0x20U, 0x1BU, 0x00U, 0x00U, 0x00U, 0x00U,
/* 9,   25, fee                   */   0x68U, 0x40U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x00U,
/* 35,  34, signingpubkey         */   0x73U, 0x21U, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
/* 22,  69, account               */   0x81U, 0x14U, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
/* 22,  91, issuer                */   0x84U, 0x14U, 0xB5U, 0xF7U, 0x62U, 0x79U, 0x8AU, 0x53U, 0xD5U, 0x43U, 0xA0U, 0x14U, 0xCAU, 0xF8U, 0xB2U, 0x97U, 0xCFU, 0xF8U, 0xF2U, 0xF9U, 0x37U, 0xE8U,
/* 138, 113  emit details          */  0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
                                       0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
                                       0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
/* 0,  251                        */ 
};

#define CFLS_OUT (ctxn + 15U)
#define CLLS_OUT (ctxn + 21U)
#define CFEE_OUT (ctxn + 26U)
#define CACCOUNT_OUT (ctxn + 71U)
#define CEMIT_OUT (ctxn + 113U)

#define BE_DROPS(drops)\
{\
        uint64_t drops_tmp = drops;\
        uint8_t* b = (uint8_t*)&drops;\
        *b++ = 0b01000000 + (( drops_tmp >> 56 ) & 0b00111111 );\
        *b++ = (drops_tmp >> 48) & 0xFFU;\
        *b++ = (drops_tmp >> 40) & 0xFFU;\
        *b++ = (drops_tmp >> 32) & 0xFFU;\
        *b++ = (drops_tmp >> 24) & 0xFFU;\
        *b++ = (drops_tmp >> 16) & 0xFFU;\
        *b++ = (drops_tmp >>  8) & 0xFFU;\
        *b++ = (drops_tmp >>  0) & 0xFFU;\
}

// Callback function
int64_t cbak(uint32_t reserve)
{
    accept((uint32_t)"Callback completed", 18, __LINE__);
    return 0;
}

// Main hook function using state_foreign for custom namespace
int64_t hook(uint32_t reserved)
{
    // Proceed with ClaimReward emission
    uint32_t current_ledger = ledger_seq();
    uint32_t fls = current_ledger + 1;
    uint32_t lls = fls + 4;

    etxn_reserve(1);
    uint8_t emithash[32];

    hook_account((uint32_t)CACCOUNT_OUT, 20);
    *((uint32_t *)(CFLS_OUT)) = FLIP_ENDIAN(fls);
    *((uint32_t *)(CLLS_OUT)) = FLIP_ENDIAN(lls);
    etxn_details((uint32_t)CEMIT_OUT, 138U);

    int64_t fee = etxn_fee_base((uint32_t)ctxn, sizeof(ctxn));
    BE_DROPS(fee);
    *((uint64_t*)(CFEE_OUT)) = fee;

    if (emit(SBUF(emithash), (uint32_t)ctxn, sizeof(ctxn)) != 32)
        rollback((uint32_t)"AutoReward: Failed to emit claim transaction.", 45, __LINE__);

    accept((uint32_t)"AutoReward: Claim emitted successfully.", 39, __LINE__);
    _g(1, 1);
    return 0;
}

2. Account Configuration Scripts

Before automating, we need to prepare the account properly:

accountSet.js: Configures basic account settings
checkAccount.js: Analyzes account status and calculates optimal claiming times
installHook.js: Deploys the ClaimReward Hook to your account

3. The CronSet Orchestrator

This is where the magic happens. The CronSet transaction schedules automatic executions with these key parameters:

StartTime: When to begin automated claiming
DelaySeconds: The interval between claims (2,603,580 seconds with safety margin)
RepeatCount: How many times to repeat (up to 256, covering over 21 years!)

The Technical Deep Dive

Let's explore the critical timing calculations that make this system reliable:

Understanding Xahau Time

Xahau uses its own epoch, starting 946,684,800 seconds after Unix epoch. This means we need to convert between Unix timestamps and Xahau time:

const RIPPLED_EPOCH_OFFSET = 946684800;
const xahauTime = unixTime - RIPPLED_EPOCH_OFFSET;

The Safety Margin Philosophy

The official reward delay is 2,599,980 seconds (30 days, 2 hours, 13 minutes). However, our system adds a 1-hour safety margin, resulting in 2,603,580 seconds. Why?

Network conditions, ledger closing times, and transaction queues can introduce minor delays. By adding this buffer, we ensure our automated claims always execute successfully rather than failing due to timing edge cases. (Feel free to remove or edit it)

Calculating Next Claim Time

The checkAccount.js script performs sophisticated calculations:

Checks current RewardTime from account data
Adds the delay period (2,599,980 seconds)
Converts to human-readable format
Suggests both exact time and safety-margin time

This dual approach lets users choose between aggressive timing (exact) or conservative timing (with 1 hour buffer).

Real-World Implementation

Let me walk you through setting up automated claiming for a real account:

Step 1: Initial Setup

First, clone the repository and install dependencies:

git clone https://github.com/Ekiserrepe/cron-claimreward-xahau.git
cd cron-claimreward-xahau
npm install

Step 2: Configure Your Account

Edit the seed in accountSet.js and run:

const xahau = require('xahau');
const { derive, utils, signAndSubmit } = require("xrpl-accountlib");

const seed = 'sYourSeedHere'; // Replace with your actual seed, get one at https://xahau-test.net/
const network = "wss://xahau-test.net";

async function setAccountFlag() {
  const client = new xahau.Client(network);
  const account = derive.familySeed(seed, { algorithm: "secp256k1" });
  console.log(`Account: ${account.address}`);

  try {
    await client.connect();
    console.log('Connected to Xahau');

    const networkInfo = await utils.txNetworkAndAccountValues(network, account);

    const prepared = {
      "TransactionType": "AccountSet",
      "Account": account.address,
      "SetFlag": 11, // asfTshCollect - Enable Transaction Signature Hook Collection
      ...networkInfo.txValues,
    };

    console.log("Prepared AccountSet transaction:", JSON.stringify(prepared, null, 2));

    const tx = await signAndSubmit(prepared, network, account);
    console.log("Transaction result:", JSON.stringify(tx, null, 2));

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
    console.log('Disconnected from Xahau');
  }
}

setAccountFlag();

This prepares your account for Hook installation. Setting the flag 11 'asfTshCollect' allows you to interact with cron transactions and hook executions.

Step 3: Install the Hook

Deploy the ClaimReward Hook to your account:

const xahau = require('xahau');
const { derive, utils, signAndSubmit } = require("xrpl-accountlib");

const seed = 'sYourSeedHere'; // Replace with your actual seed, get one at https://xahau-test.net/
const network = "wss://xahau-test.net";

async function installHook() {
  const client = new xahau.Client(network);
  const account = derive.familySeed(seed, { algorithm: "secp256k1" });
  console.log(`Account: ${account.address}`);

  try {
    await client.connect();
    console.log('Connected to Xahau');

    const networkInfo = await utils.txNetworkAndAccountValues(network, account);

    const prepared = {
      "TransactionType": "SetHook",
      "Account": account.address,
      "Hooks": [
        {
          "Hook": {
            "HookHash": "805351CE26FB79DA00647CEFED502F7E15C2ACCCE254F11DEFEDDCE241F8E9CA",
            "HookNamespace": "0000000000000000000000000000000000000000000000000000000000000000",
            "HookOn": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFFFBFFFFF",
            "HookCanEmit": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFFFFFFFFFFFFFFFBFFFFF", //Can emit ClaimReward
            "Flags": 4
          }
        }
      ],
      ...networkInfo.txValues,
    };

    console.log("Prepared SetHook transaction:", JSON.stringify(prepared, null, 2));

    const tx = await signAndSubmit(prepared, network, account);
    console.log("Transaction result:", JSON.stringify(tx, null, 2));

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
    console.log('Disconnected from Xahau');
  }
}

installHook();

The Hook is now ready to execute claims when triggered. The Flag 4 is needed to allow the cron transaction to trigger the hook execution.

Step 4: Analyze Your Account

Run the account checker to get precise timing information:

const { Client } = require('xahau');

// Constants
const RIPPLED_EPOCH_OFFSET = 946684800;
const REWARD_DELAY_SECONDS = 2599980; // 30 days, 2 hours, 13 minutes

async function checkAccount() {
  const client = new Client('wss://xahau-test.net');
  const address = 'yourAddress';

  try {
    await client.connect();
    console.log('Connected to Xahau Testnet\n');

    const { result } = await client.request({
      command: 'account_info',
      account: address,
      ledger_index: 'validated'
    });

    console.log('=== ACCOUNT INFO ===\n');
    console.log('Address:', address);
    console.log('Balance:', result.account_data.Balance, 'drops');
    console.log('Balance (XAH):', (parseInt(result.account_data.Balance) / 1000000).toFixed(6), 'XAH');
    console.log('Sequence:', result.account_data.Sequence);
    console.log('RewardTime:', result.account_data.RewardTime || 'Not set (not opted in)');
    console.log('RewardLgrFirst:', result.account_data.RewardLgrFirst || 'Not set');
    console.log('RewardLgrLast:', result.account_data.RewardLgrLast || 'Not set');
    console.log('\nAccount exists:', true);
    console.log('Is opted in to rewards:', !!result.account_data.RewardTime);

    // Calculate next claim time if opted in
    if (result.account_data.RewardTime) {
      const rewardTime = parseInt(result.account_data.RewardTime);
      const nextClaimTime = rewardTime + REWARD_DELAY_SECONDS;
      const nextClaimDate = new Date((nextClaimTime + RIPPLED_EPOCH_OFFSET) * 1000);

      // Calculate with 1 hour safety margin
      const nextClaimTimeSafe = nextClaimTime + 3600; // +1 hour (3600 seconds)
      const nextClaimDateSafe = new Date((nextClaimTimeSafe + RIPPLED_EPOCH_OFFSET) * 1000);

      // Format date as YYYY/MM/DD, time as 12-hour format
      const formatDate = (date) => {
        const year = date.getFullYear();
        const month = String(date.getMonth() + 1).padStart(2, '0');
        const day = String(date.getDate()).padStart(2, '0');
        const timeString = date.toLocaleTimeString('en-US', {
          hour: 'numeric',
          minute: '2-digit',
          second: '2-digit',
          hour12: true
        });
        return `${year}/${month}/${day}, ${timeString}`;
      };

      console.log('\n=== NEXT CLAIM INFO ===\n');
      console.log('Next Claim Date:', formatDate(nextClaimDate));
      console.log('\n⭐ For cronSet.js:');
      console.log('StartTime:', nextClaimTime);
      console.log('StartTime + 1 hour (for safety):', nextClaimTimeSafe, '-', formatDate(nextClaimDateSafe));

      // Calculate DelaySeconds for 30 days, 3 hours, 13 minutes
      const delaySeconds = (30 * 24 * 60 * 60) + (3 * 60 * 60) + (13 * 60);
      console.log('\nDelaySeconds (30d 3h 13m):', delaySeconds);
    }

  } catch (error) {
    console.error('Error:', error.message);
  } finally {
    await client.disconnect();
  }
}

checkAccount();

You'll see output like:

=== NEXT CLAIM INFO ===
Next Claim Date: 2025/12/21, 1:09:41 PM
⭐ For cronSet.js:
StartTime: 819634181
StartTime + 1 hour (for safety): 819637781

Step 5: Schedule Automation

Edit cronSet.js with the calculated StartTime from last code (or 0 if its the first time you are opt-in your rewards) and run:

const xahau = require('xahau');
const { derive, utils, signAndSubmit } = require("xrpl-accountlib");

const seed = 'sYourSeedHere'; // Replace with your seed
const network = "wss://xahau-test.net";

async function createCronSet() {
  const client = new xahau.Client(network);
  const account = derive.familySeed(seed, { algorithm: "secp256k1" });
  console.log(`Account: ${account.address}`);

  try {
    await client.connect();
    console.log('Connected to Xahau');

    const networkInfo = await utils.txNetworkAndAccountValues(network, account);

    // Convert current time to Ripple Epoch (seconds since January 1, 2000 00:00 UTC)
    const RIPPLE_EPOCH_OFFSET = 946684800;
    const currentUnixTime = Math.floor(Date.now() / 1000);
    const startTimeRippleEpoch = currentUnixTime - RIPPLE_EPOCH_OFFSET + 60; // Start in 1 minute

    const prepared = {
      "TransactionType": "CronSet",
      "Account": account.address, // Your Hook address
      "StartTime": 0,//Check checkAccount.js to get your StartTime number if you already opt-in, Or use 0 for immediate start if you didn't top-in yet.
      "RepeatCount": 256, // Max number of times to repeat the task
      "DelaySeconds": 2603580, // 30 days, 3 hours, 13 minutes (Regular claim interval + 1 hour safety margin)
      ...networkInfo.txValues,
    };

    console.log("Prepared CronSet transaction:", JSON.stringify(prepared, null, 2));

    const tx = await signAndSubmit(prepared, network, account);
    console.log("Transaction result:", JSON.stringify(tx, null, 2));

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
    console.log('Disconnected from Xahau');
  }
}

createCronSet();

Congratulations! Your rewards will now be claimed automatically.

Advanced Considerations

Handling First-Time Users

If you've never opted into rewards before, use StartTime: 0 in your CronSet configuration. This triggers an immediate first claim and starts your reward cycle.

Choosing RepeatCount Wisely

Each repeat covers approximately 30 days. Here's a quick reference:

12 repeats = ~1 year of automation
24 repeats = ~2 years
256 repeats (maximum) = ~21 years

Consider your long-term commitment to the network when choosing this value.

Network Selection

Always test on testnet first:

const network = 'wss://xahau-test.net'; // Testing
// const network = 'wss://xahau.network'; // Production

Monitoring Your Automation

Even with automation, periodic checks are wise:

Verify CronSet transactions are executing
Check account balance for fees
Monitor Hook execution logs
Validate reward accumulation

The Business Layer Perspective

This automated reward system exemplifies what I discussed in my previous article about building business layers on Xahau. By abstracting the complexity of reward claiming into an automated system, we're creating infrastructure that enables:

Portfolio Management: Manage multiple accounts efficiently
Institutional Adoption: Enterprises can automate treasury operations
User Experience: Remove friction from reward claiming
Scalability: Handle hundreds of accounts without manual intervention

Security Considerations

Hook Verification

The provided Hook hash is public and verifiable. If you prefer maximum security, compile the claimReward.c file yourself and verify the hash matches or create a new one!

Transaction Fees

Ensure your account maintains sufficient XAH balance for:

CronSet execution fees
ClaimReward transaction fees

Troubleshooting Common Issues

"Account not eligible for rewards yet"

Solution: Wait for the exact RewardTime + delay period, or use the safety margin suggestion.

"Insufficient balance for fees"

Solution: Maintain at least 10 XAH for fee reserves.

"Hook is not being triggered"

Solution: Ensure account is properly configured with accountSet.js first and you installed your hook with proper HookOn and HookCanEmit and Flags values.

The Bigger Picture

This automated reward system represents more than just convenience, it's a glimpse into the future of blockchain automation. By combining Hooks (smart contracts) with CronSet (scheduled execution), we're creating autonomous financial systems that operate without human intervention.

Imagine scaling this concept:

Automated DeFi strategies
Scheduled payment distributions
Autonomous treasury management
Self-executing compliance operations

The infrastructure we're building today lays the foundation for tomorrow's decentralized autonomous organizations.

Future Enhancements

While the current system is production-ready, several enhancements could add value:

Multi-account Management: Handle multiple accounts from a single interface
Notification System: Alert users when claims execute
Analytics Dashboard: Track reward accumulation over time
Dynamic Optimization: Adjust timing based on network conditions
Integration APIs: Connect with existing portfolio management tools

Conclusion

Automating reward claims on Xahau isn't just about saving time, it's about building reliable, scalable infrastructure for the future of finance solutions. By combining Hooks and CronSet transactions, we've created a system that runs autonomously for years, ensuring you never miss a reward claim again.

The code is open source and available at github.com/Ekiserrepe/cron-claimreward-xahau. I encourage you to explore it, test it on testnet, and create new improvements.

Remember: the best automation is the one you set up once and forget about. With this system, your Xahau rewards practically claim themselves.

Acknowledgments

Special thanks to Denis Angell and Satish from XRPL Labs for their pioneering work on Hooks and assistance in developing this solution.

Learning Xahau: Automating Hook Execution with Cron Transactions

Ekiserrepe — Fri, 14 Nov 2025 20:09:16 +0000

Welcome to a new chapter of Learning Xahau, where we explore the theoretical and practical aspects of the Xahau blockchain. If you're new to Xahau, I recommend checking out the first article in the series to understand the basics.

Today, we're diving into Cron Transactions—a powerful feature that brings scheduled automation to the Xahau blockchain. If you've ever wondered how to make your Hooks execute automatically at specific intervals without manual intervention, this article is for you.

What Are Cron Transactions?

If you're familiar with Unix/Linux systems, you've probably heard of cron jobs—scheduled tasks that run automatically at specified times. Xahau brings this concept to the blockchain with CronSet transactions, allowing you to schedule Hook callbacks at regular intervals.

Think of Cron Transactions as your blockchain alarm clock. Instead of waking you up, they wake up your Hooks and tell them: "Hey, it's time to execute your logic!" This happens automatically, on-chain, without needing external triggers or services.

Why Do We Need Cron Transactions?

In traditional blockchain environments, smart contracts typically react to external transactions. Someone or something needs to call them. This creates several challenges:

Manual Intervention: Regular tasks require someone to trigger them manually
External Dependencies: You need off-chain services (bots, servers) to trigger on-chain actions
Cost Inefficiency: Each manual trigger costs transaction fees
Reliability Issues: External services can fail, forget, or experience downtime

Cron Transactions solve these problems by moving the scheduling logic on-chain. Your Hook can be programmed to execute at specific intervals, creating truly autonomous on-chain processes.

Real-World Use Cases

Before diving into the technical implementation, let's explore practical scenarios where Cron Transactions shine:

1. Automated Reward Distribution

Imagine a staking system where rewards need to be calculated and distributed daily. Instead of running an external bot, a Cron Transaction can trigger your Hook every 24 hours to process rewards automatically.

2. Regular Data Updates

If you're using Remarks (as discussed in my previous article) to create a price oracle, Cron Transactions can update prices at regular intervals without external intervention.

3. Subscription Management

For subscription-based services, Cron Transactions can automatically check and process payments, update subscription statuses, or trigger access revocations when subscriptions expire.

4. Automated Maintenance Tasks

Hooks that need to perform cleanup operations, reset counters, or archive old data can use Cron Transactions to execute these tasks periodically.

How Cron Transactions Work

The workflow for implementing Cron Transactions involves several steps:

Install a Hook with the hsfCOLLECT flag enabled
Enable Transaction Signature Hook Collection on your account
Create a CronSet transaction with your scheduling parameters
Let Xahau handle the rest—your Hook will execute automatically

Let's break down each component:

The CronSet Transaction Structure

{
  "TransactionType": "CronSet",
  "Account": "rYourAccountAddress",
  "StartTime": 816348759,      // When to start (Ripple Epoch)
  "RepeatCount": 3,             // How many times to execute
  "DelaySeconds": 120           // Interval between executions
}

StartTime: When the first execution should occur (0 for immediate start)
RepeatCount: Total number of times the Hook should be triggered
DelaySeconds: Time interval between each execution

Important: Ripple Epoch Time

Xahau uses Ripple Epoch time, which counts seconds from January 1, 2000 (not Unix time which starts from 1970). Here's how to convert:

const RIPPLE_EPOCH_OFFSET = 946684800;
const rippleEpochTime = Math.floor(Date.now() / 1000) - RIPPLE_EPOCH_OFFSET;

Hands-On Implementation

Now let's get practical. The cron-transaction-xahau repository provides ready-to-use examples for implementing Cron Transactions.

Step 1: Prerequisites

First, you'll need a Xahau testnet account. Get one at https://xahau-test.net which will provide you with:

An account address (starts with 'r')
A seed/secret (starts with 's')

Security Note: Never share your seed! It's your private key. The examples use testnet seeds, but in production, use environment variables or secure key management.

Step 2: Install a Hook with Collection Enabled

The Hook must be installed with the hsfCOLLECT flag (value: 4) to enable callback functionality:

const xahau = require('xahau');
const { derive, utils, signAndSubmit } = require("xrpl-accountlib");

const seed = 'yourSeed'; // Replace with your actual seed, get one at https://xahau-test.net/
const network = "wss://xahau-test.net";

async function installHook() {
  const client = new xahau.Client(network);
  const account = derive.familySeed(seed, { algorithm: "secp256k1" });
  console.log(`Account: ${account.address}`);

  try {
    await client.connect();
    console.log('Connected to Xahau');

    const networkInfo = await utils.txNetworkAndAccountValues(network, account);

    const prepared = {
      "TransactionType": "SetHook",
      "Account": account.address,
      "Hooks": [
        {
          "Hook": {
            "HookHash": "83A41BE45166B33E66EF653512396409E1BF9FA85A7C15D0ABC81C24E2890CB3",
            "HookNamespace": "0000000000000000000000000000000000000000000000000000000000000000",
            "HookOn": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFFFBFFFFF",
            "Flags": 4
          }
        }
      ],
      ...networkInfo.txValues,
    };

    console.log("Prepared SetHook transaction:", JSON.stringify(prepared, null, 2));

    const tx = await signAndSubmit(prepared, network, account);
    console.log("Transaction result:", JSON.stringify(tx, null, 2));

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
    console.log('Disconnected from Xahau');
  }
}

installHook();

Step 3: Enable Account Collection

Your account needs the asfTshCollect flag enabled:

const xahau = require('xahau');
const { derive, utils, signAndSubmit } = require("xrpl-accountlib");

const seed = 'yourSeed'; // Replace with your actual seed, get one at https://xahau-test.net/
const network = "wss://xahau-test.net";

async function setAccountFlag() {
  const client = new xahau.Client(network);
  const account = derive.familySeed(seed, { algorithm: "secp256k1" });
  console.log(`Account: ${account.address}`);

  try {
    await client.connect();
    console.log('Connected to Xahau');

    const networkInfo = await utils.txNetworkAndAccountValues(network, account);

    const prepared = {
      "TransactionType": "AccountSet",
      "Account": account.address,
      "SetFlag": 11, // asfTshCollect - Enable Transaction Signature Hook Collection
      ...networkInfo.txValues,
    };

    console.log("Prepared AccountSet transaction:", JSON.stringify(prepared, null, 2));

    const tx = await signAndSubmit(prepared, network, account);
    console.log("Transaction result:", JSON.stringify(tx, null, 2));

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
    console.log('Disconnected from Xahau');
  }
}

setAccountFlag();

Step 4: Schedule Your Cron Job

Once your Hook is installed and your account is configured, create the CronSet transaction:

const xahau = require('xahau');
const { derive, utils, signAndSubmit } = require("xrpl-accountlib");

const seed = 'yourSeed'; // Replace with your seed
const network = "wss://xahau-test.net";

async function createCronSet() {
  const client = new xahau.Client(network);
  const account = derive.familySeed(seed, { algorithm: "secp256k1" });
  console.log(`Account: ${account.address}`);

  try {
    await client.connect();
    console.log('Connected to Xahau');

    const networkInfo = await utils.txNetworkAndAccountValues(network, account);

    // Convert current time to Ripple Epoch (seconds since January 1, 2000 00:00 UTC)
    const RIPPLE_EPOCH_OFFSET = 946684800;
    const currentUnixTime = Math.floor(Date.now() / 1000);
    const startTimeRippleEpoch = currentUnixTime - RIPPLE_EPOCH_OFFSET + 60; // Start in 1 minute

    const prepared = {
      "TransactionType": "CronSet",
      "Account": account.address, // Your Hook address
      "StartTime": startTimeRippleEpoch, // Or use 0 for immediate start
      "RepeatCount": 3, // Number of times to repeat the task
      "DelaySeconds": 120, // 2 minutes
      ...networkInfo.txValues,
    };

    console.log("Prepared CronSet transaction:", JSON.stringify(prepared, null, 2));

    const tx = await signAndSubmit(prepared, network, account);
    console.log("Transaction result:", JSON.stringify(tx, null, 2));

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
    console.log('Disconnected from Xahau');
  }
}

createCronSet();

This schedules your Hook to execute based on your specified parameters.

Step 5: Monitor and Manage

You can check your scheduled executions on explorers like XRPLWin. To stop a scheduled Cron job:

const xahau = require('xahau');
const { derive, utils, signAndSubmit } = require("xrpl-accountlib");

const seed = 'yourSeed'; // Replace with your seed
const network = "wss://xahau-test.net";

async function removeCronSet() {
  const client = new xahau.Client(network);
  const account = derive.familySeed(seed, { algorithm: "secp256k1" });
  console.log(`Account: ${account.address}`);

  try {
    await client.connect();
    console.log('Connected to Xahau');

    const networkInfo = await utils.txNetworkAndAccountValues(network, account);

    const prepared = {
      "TransactionType": "CronSet",
      "Account": account.address, // Your Hook address
      "Flags": 1, // tfCronUnset - this removes the cron job
      ...networkInfo.txValues,
    };

    console.log("Prepared CronUnset transaction:", JSON.stringify(prepared, null, 2));

    const tx = await signAndSubmit(prepared, network, account);
    console.log("Transaction result:", JSON.stringify(tx, null, 2));

  } catch (error) {
    console.error('Error:', error);
  } finally {
    await client.disconnect();
    console.log('Disconnected from Xahau');
  }
}

removeCronSet();

The No-Code Alternative: HookStore

For Non-Technical Users

Not everyone is comfortable working with code, and that's perfectly fine! The Xahau ecosystem provides user-friendly alternatives for those who want to leverage the power of Cron Transactions without diving into technical implementation.

The HookStore (https://hookstore.xahau.network) is a public marketplace where developers publish their Hooks, making them accessible to everyone through a simple interface. Think of it as an "app store" for Xahau Hooks.

Using Ping-Cron Through Xaman

Our process is available on the HookStore as Ping-Cron, which you can find at:
👉 https://hookstore.xahau.network/hooks/ping-cron

This process is specifically designed for implementing Cron functionality without writing a single line of code. Here's what makes it special:

Xaman Integration: The entire process is managed through the Xaman wallet app—no terminal, no coding required
Visual Interface: Configure your scheduling parameters through an intuitive interface
One-Click Installation: Install the Hook directly to your account with proper configuration
Automatic Setup: The HookStore handles all the technical details, including flags and parameters

How It Works for End Users

The process is remarkably simple:

Open the HookStore link in your browser
Review the Hook details including what it does
Click on Install below the README notes
Configure your schedule using the provided interface:
- Set when you want it to start
- Choose how many times it should run
- Define the interval between executions
Sign the transactions in Xaman
Done! Your example is installed and working!

Benefits of Using HookStore

No Technical Knowledge Required: Perfect for business users, traders, and anyone who needs automation without coding
Verified Hooks: Hooks on the HookStore are reviewed and documented
Community Support: Each Hook has its own page with descriptions and usage instructions
Safe Testing: You can try Hooks on testnet before using them on mainnet

When to Choose HookStore vs. Custom Implementation

Use HookStore when:

You need a quick solution without development time
You're not comfortable with coding
You want to test functionalities before building custom solutions
You need standard automation patterns that already exist

Build custom implementations when:

You need specific business logic not available in existing Hooks
You want complete control over the Hook's behavior
You're building a unique application with proprietary features
You need to optimize for specific performance requirements

The beauty of Xahau is that both approaches are valid and serve different audiences. The HookStore democratizes access to blockchain automation, while custom development enables innovation and specialized solutions.

The Bigger Picture

Cron Transactions represent a significant step toward truly autonomous blockchain applications. Combined with Xahau's other features like Hooks, Remarks, and URITokens, developers can build sophisticated decentralized applications that operate independently.

This automation capability opens doors for:

DeFi protocols with automated rebalancing
Gaming systems with scheduled events
Supply chain solutions with periodic updates
Governance mechanisms with automated proposal processing

As I mentioned in my article about building your own business layer, Xahau empowers developers to create their own logic without permission. Cron Transactions extend this freedom by adding the dimension of time-based automation.

Final Thoughts and Resources

Cron Transactions showcase Xahau's commitment to providing developers with powerful, practical tools. By moving scheduling on-chain, Xahau eliminates external dependencies and creates truly autonomous applications.

The complete working code for this article is available at:
👉 https://github.com/Ekiserrepe/cron-transaction-xahau

Remember, we're still in the early days of Xahau. If you have ideas for using Cron Transactions in innovative ways, now is the perfect time to experiment and potentially become a pioneer in this space.

Feel free to reach out with questions, or join the Xahau Contributors Discord server, where we'll be happy to help you implement your automated Hook solutions.

HookCanEmit, an Extra Step Towards Making Xahau a Safer Place

Ekiserrepe — Sat, 14 Jun 2025 11:24:01 +0000

Welcome to a new chapter of Learning Xahau, a space where you’ll find in-depth articles about Xahau—both theoretical and practical—designed for all audiences. If this is your first time here and you want to learn the basics, I recommend checking out the first article in the Learning Xahau series.

Today we’re talking about HookCanEmit, a new optional parameter we can use when installing Hooks. If you’re not familiar with Hooks or Xahau, I’ll start with a brief introduction.

Xahau is an independent decentralized blockchain based on the XRP Ledger codebase. What makes Xahau special is the introduction of innovations not available on the XRP Ledger, such as Hooks—a technology that enables the creation of smart contracts in a simpler, safer, and regulation-friendly way compared to the EVM vision.

Hooks are pieces of code you can write yourself or use from other users on the network. To make your Hook available on Xahau, you must first go through a process called Create, where the Hook is uploaded to Xahau for the first time. This creates a HookHash, an ID that you can share if you want others to install it. Once a Hook is created, any further use of it is considered an Install operation. Both Create and Install operations use the SetHook transaction, but it’s important to distinguish between them if you ever need help or need to explain where you're stuck.

Since we're talking about Hooks, it’s worth noting that Hooks do not exist independently in Xahau—they are installed on Xahau accounts. Each account can have up to 10 Hooks installed. Think of Hooks as plug-ins that give Xahau accounts new behaviors—they gain “superpowers” that let them react to specific transaction types in ways they normally wouldn’t.

Back to installing Hooks: you may have guessed that to install a third-party Hook, you’ll need its HookHash. HookHashes look something like this: 610F33B8EBF7EC795F822A454FB852156AEFE50BE0CB8326338A81CD74801864.

Although some developers may publish their source code and you can compile the file to see if you get the same HookHash to confirm that it is the same code the developer shows you, it may happen that a user does not have access to the source code of a Hook they want to install. This could occur for many reasons: it's impossible to locate the hook's creator or their repository, the creator does not want someone to copy the hook's logic because it is part of their business or they charge a fee and don't want others to remove the commission request from the business. Contractually, the developed hook is not allowed to be published, and many other reasons. So it is possible that a user finds themselves in the dilemma of whether or not to install a hook. They could be guided by the creator's reputation or the popularity of the hook, but they can never be 100% sure that the code does what it says or that the code only does what it claims to do.

HookCanEmit, the reason for this article, adds an extra optional security step for when you need to install a Hook. HookCanEmit is one of the latest improvements added in Xahau in the 2025.5.1-release+1762 release of the xahaud software. HookCanEmit allows the user to decide what type of transactions they want to allow when this Hook is executed. It is similar to the HookOn parameter, which indicates what type of transactions the Hook should be triggered by. More info: https://docs.xahau.network/concepts/hookon-field

If I want to install a hook (whose code I cannot verify or do not understand the source code) that automates NFT minting processes, what I do not expect (or want) is for the hook to send payments out of my account without me knowing, or create buy or sell offers for tokens, which are other types of transactions the account can generate. Therefore, if we use the HookCanEmit field, we could block these types of transactions and only allow NFT creation. This avoids erroneous or malicious behaviors that someone could introduce into their hooks.

You can generate a HookCanEmit value using Richard Holland’s calculator: https://richardah.github.io/xrpl-hookon-calculator/

As we can see in the image, if we want our Hook to only be able to emit transactions of the Payment type, we should check the option and copy the result provided by the page. In this case, we click PAYMENT and the result is this code: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFE (ignore 0x part)

If we want it to only work with the NFT minting transaction, we select URITOKEN_MINT and it results in the following code: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFDFBFFFFF (ignore 0x part)

Time to Get Hands-On

First Test, blocking all types of transactions that can be emitted

Let's confirm that what we say is true. For this, I will use my Forwarder Hook that serves to forward a payment that enters the account where this hook is installed. We use this hook because by its nature it will have to emit a Payment transaction if it receives funds and has configured addresses to which to forward this money. In the Xahau Testnet, I created the account rMLRy72cWuPgCBxjni7e84ThuwRsBDta9p and install the hook adding the HookCanEmit FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFF to prevent the hook from emitting, since with this code we do not allow any type of emission.

"TransactionType": "SetHook",
      "Account": your_address,
      "Flags": 0,
      "Hooks": [
        {
          "Hook": {
            "HookHash": "319E16820BAEF9A08C51F52C97338D4CF09E6E53991B4131820A079721C64EA1",
            "HookNamespace": "0000000000000000000000000000000000000000000000000000000000000000",
            "HookOn": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFFFFFFF7FFFFFBFFFFE",
            "HookCanEmit": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFF",
          }
        }
      ],
      ...networkInfo.txValues,

We confirm that the transaction has been successful in XRPLWin: https://xahau-testnet.xrplwin.com/tx/31F8C8948C678347CDFC25CC2C59608BD413778BEDDB9B61435F7F6B3111D90C#overview

The Forwarder Hook needs to pre-configure an address to which we want to forward what enters the account where we are installing the hook, so we are going to configure this one: rf1NrYAsv92UPDd8nyCG4A3bez7dhYE61r which using the XRPL Hex Visualizer tells us that in Hex it would be 4B50699E253C5098DEFE3A0872A79D129172F496. We can use this transaction:

TransactionType: "Invoke",
      Account: your_address,
      Flags: 0,
      HookParameters: [
        {
          HookParameter: {
            HookParameterName: "414444",
            HookParameterValue: "D53F733E54B866B9FBDB85762071832B03A56C76",
          },
        },
        {
          HookParameter: {
            HookParameterName: "4E554D",
            HookParameterValue: "00",
          },
        },
      ],
      ...networkInfo.txValues,

We execute the transaction and check that everything went well; we should receive a message that the address has been added like this: https://xahau-testnet.xrplwin.com/tx/4F8B247877BFC44B033C14ED1C5945B395F95C38261AB2FA2067D782BAD94043

Now the acid test: let's check that HookCanEmit works as expected. The account rMLRy72cWuPgCBxjni7e84ThuwRsBDta9p should not allow the Forwarder Hook to emit an outgoing transaction from the account. Let's see. The account receives a payment of 1 XAH from the account rBHk1ekqaVkKzkrsivbajrw5ZE3omR23Ax but was not able to emit the money forwarding to the account rf1NrYAsv92UPDd8nyCG4A3bez7dhYE61r as the hook was expected to do.

In fact, the hook believes that the execution was correct, emitting the forwarding transaction and returning a success message, but our "firewall" HookCanEmit stopped the transaction. Here you can see how the hook thinks everything went fine.

Second test, let's allow it to emit payments.

In this case, we are going to delete the hook and reinstall it. That way we learn more operations with this test. Here would be the transaction that uninstalls the hook:

      "TransactionType": "SetHook",
      "Account": your_address,
      "Flags": 0,
      Hooks:
    [        
        {                        
            Hook: {
                CreateCode: "",
                Flags: 1,
            }
        }
    ],
      ...networkInfo.txValues,

Here we can confirm that the hook has been uninstalled: https://xahau-testnet.xrplwin.com/tx/B8E94645D10E403ABA60525372208BDA90248C14118231E7047174AA7E233533

Now we are going to install the hook again but granting permission for Payment transactions. To do this, we go to the calculator https://richardah.github.io/xrpl-hookon-calculator/ and activate the Payment button, which results in this code: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFE. Remember to ignore the 0x.

We generate a SetHook transaction to install the hook with permission in HookCanEmit for Payment emissions:

"TransactionType": "SetHook",
      "Account": your_address,
      "Flags": 0,
      "Hooks": [
        {
          "Hook": {
            "HookHash": "319E16820BAEF9A08C51F52C97338D4CF09E6E53991B4131820A079721C64EA1",
            "HookNamespace": "0000000000000000000000000000000000000000000000000000000000000000",
            "HookOn": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFFFFFFF7FFFFFBFFFFE",
            "HookCanEmit": "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFE",
          }
        }
      ],
      ...networkInfo.txValues,

Once installed, we can go check the transaction on XRPLWin and confirm that we have done it correctly. https://xahau-testnet.xrplwin.com/tx/0A2F2243963533F716A1D11C08786B41AE366E7CD5753AA7EB4B9D7EEF0555D9. If we click on the Information block in the Summary, we see the "Allowed emission types" section where the transaction type ttPayment is marked as valid.

Everything is ready, let's send a transaction to the hook's account to see if now it is able to forward it. If you deleted the namespace, remember you will have to repeat the process of adding a forwarding account for the forwarder hook. If you followed the steps just like I did, you won’t have to do it.

This time, HookCanEmit allows us to perform payment emissions from the hook, so the operation was completed.

Final words and code

As you can see, HookCanEmit is an extra step that all Xahau users can use to avoid surprises or unexpected behavior. Just as we should have digital hygiene with our passwords on the Internet, we must also make responsible use of the configuration of the hooks we install in order to work more securely and enjoy the opportunities Xahau offers us.

The code used in this article is available at: https://github.com/Ekiserrepe/Xahau-HookCanEmit-Example in case you need it.

Feel free to reach out with questions, or join the Xahau Contributors Discord server, where we’ll be happy to help.

Links

Official Website
Official Docs
Hooks Builder
Discord Server
Xahaud
X Account

Learning Xahau: Storing On-Chain Data with Remarks

Ekiserrepe — Mon, 09 Jun 2025 20:03:50 +0000

Welcome to Learning Xahau, a series of articles designed to help you better understand the Xahau blockchain from both theoretical and practical perspectives—accessible to all audiences.

Xahau is an independent blockchain based on the XRP Ledger codebase, enriched with many new features, such as Hooks—a new, simpler, and more secure vision for implementing smart contracts that diverges from the traditional EVM concept.
If you're eager to learn more about Xahau, be sure to explore the other articles in the Learning Xahau series.

Introduction to Remarks

In this article, we’ll cover Remarks, a new feature introduced for the first time in version 2025.5.1-release+1762 of xahaud (the software that powers the Xahau network).
Remarks are a form of annotation that can be added to Xahau objects. These annotations follow a key-value format. This means you use one variable to identify a field (the key) and assign it a desired value. For example: "Name (key): Jose (value)".
Each Xahau object can store up to 32 Remarks.

Depending on the object, either the owner or the issuer has permission to write Remarks to it. Additionally, each Remark can be set as mutable or immutable using the tfInmutable flag. This is especially useful for dynamic objects like NFTs.

You can check the list of object types and who is allowed to write Remarks to them in the official documentation:

If you'd like to dive deeper into the technical side of Remarks, we recommend the dedicated SetRemarks transaction documentation on Xahau Docs.

Here’s an example of a SetRemarks transaction:

{
  "TransactionType": "SetRemarks",
  "Account": "rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm",
  "Flags": 0,
  "ObjectID": "AABBCCDDEEFF00112233445566778899AABBCCDDEEFF00112233445566778899",
  "Remarks": [
    {
      "Remark": {
        "RemarkName": "CAFE",
        "RemarkValue": "DEADBEEF",
        "Flags": 0
      }
    }
  ]
}

In all SetRemarks transactions, you must specify the target object in the ObjectID field. Then, define the Remarks you wish to include. The Flags field determines whether the Remark is mutable (0 for mutable, 1 for immutable).
Both RemarkName (key) and RemarkValue (value) must be written in hexadecimal.
If you leave the RemarkValue empty, the Remark will be deleted.

Practical Use Cases for Remarks

Remarks are ideal for storing small pieces of data on-chain, removing the need to manage databases.
By eliminating the dependency on external connections and storing data directly on Xahau, processes become easier—just remember the 32-entry limit per object.

Here are a few practical examples of how Remarks can be used (feel free to share your ideas to include them in this article):

Tagging Accounts or Indicating Status

Xahau addresses aren’t user-friendly by default. That’s why apps like Xaman let you assign aliases to Xahau addresses to improve usability. With Remarks, you can now tag your accounts on-chain, and view them in an explorer.
Note: This data is public, so avoid storing private or sensitive information for security reasons.

Another use case is indicating a status.
Let’s say one of your Xahau accounts has several Hooks installed that power a complex process. If you need to update or replace one or more of these Hooks, the process might go offline temporarily. A Status Remark like "Active", "Closed", or "Under Maintenance" can notify others of the current state.
If properly documented, third-party services can use this information to avoid interacting with an inactive account.

For example, I’ve set "Status": "Open" for the account rMLVXQxGXWrYnJXgEDL2qDqC48gMs4bJv on the Xahau Testnet.
You can check it here:

NFTs and On-Chain Metadata

Xahau supports the URIToken object for NFTs.
If you're coming from the XRP Ledger ecosystem, you'll know that most NFT metadata is stored off-chain in a JSON file linked via IPFS. This means additional infrastructure is needed to retrieve and interpret that JSON file—something that can be tedious and error-prone.

Here’s an example from my Power Zerps collection on the XRP Ledger. It’s a series of tokusatsu-inspired warriors, each with unique attributes like attack, defense, and health stats used in gameplay.
Most metadata is stored off-chain in the JSON file, accessible through the URI field:

Opening the JSON reveals details such as "Helmet", "Body Armor", "Color", "Attack", "Defense", "Health", and "Magic":

Before Remarks, if I wanted to use this data in a game, I couldn’t do it purely on-chain. I’d have to maintain a database, detect the NFT via blockchain queries, and cross-reference that with the metadata.

With Remarks, the entire process is simpler. I can store this data on-chain, with no need for a database.
As the issuer, I can embed attributes into each NFT as I mint them, and they’ll always be available. Since Remarks can also be mutable, I can make dynamic attributes for my NFTs—such as leveling up in an RPG game, or evolving traits.

You could even use Remarks to indicate fallback sources for metadata or other explorer-friendly enhancements.

Here’s an example of how the Power Zerp’s attributes appear in a test URIToken, viewable on XRPLWin.

We focused on a gaming use case, but this can be applied to any environment where annotations or object tagging is needed.
Imagine financial products that need identifiers, real-world assets represented on-chain with updatable traits, open or closed loans, new or used cars, or even a price oracle whose value is updated every few seconds.

As I always say: your imagination is the limit.

Update: Price Oracle

Here’s a new example with code for a Price Oracle.
In this case, it’s a URIToken where we update the price and last update timestamp using Remarks.
Repo: https://github.com/Ekiserrepe/xahaupriceoracle-remarks

You can check the updates live: https://xahau-testnet.xrplwin.com/account/rsPUkjW4ukdwKEP6EqhRfsUN9cqqQr9rkr

Final Thoughts & Sample Code

As you can see, Remarks are a simple yet powerful addition to Xahau with great potential for tagging or storing small amounts of on-chain information.

If you want to experiment with Remarks but aren’t sure where to start, here’s a GitHub repository with sample code to help you begin:
👉 https://github.com/Ekiserrepe/setRemarks-example-Xahau

Feel free to reach out with questions, or join the Xahau Contributors Discord server, where we’ll be happy to help.

Links

Official Website
Official Docs
Hooks Builder
Discord Server
Xahaud
X Account

Learning Xahau: Time as a Variable for Your Business

Ekiserrepe — Fri, 06 Jun 2025 19:10:53 +0000

In this Learning Xahau article, we’ll talk about how we can use time as a variable in our project or business without being forced to use an Escrow-type transaction, thanks to the many features of Hooks, the smart contract technology used by Xahau.

If you're new here and don’t yet know what the Xahau blockchain is, it’s a fork of the XRP Ledger base code that includes some improvements not available in the XRP Ledger—like Hooks, which allow Xahau users to implement complex logic easily (smart contracts). If you want more information, I recommend checking out the first article in this series: "Learning Xahau 1".

If you're coming from the XRP Ledger world, you know that you can’t implement custom logic directly on-chain. The only native transaction that allows the use of time in XRP Ledger (and also in Xahau) would be Escrow. Escrows allow locking amounts of the native token (in XRP Ledger) or any token (in Xahau), based on two possible conditions: time-based (lock these funds until a specific date/time), or conditional release, which is somewhat inaccurately named—it essentially unlocks when a "secret" is submitted. Escrows can also combine both conditions. One could argue that the Check transaction type is also time-based since you can add an expiration condition, but that’s not the focus of this article.

In XRP Ledger, if you want to create time-based (or any custom logic) for your transactions, events, accounts, etc., you must build your own backend outside the blockchain. This means you need:

A server and configure it.
A backend that stays connected and doesn't fail at critical moments.
To store secret keys of your accounts on your own or someone else’s server—with all the risks that entails.

In short:

Server management.
Persistent connection to the network.
Private key storage risk.

In Xahau, however, you can create all the conditional logic you want inside a hook, deploy it to your own Xahau account, and everything works on Xahau. The hook can always listen to relevant transactions and execute your desired logic—without your interaction.

This means:

You don’t need a server.
You don’t need backend knowledge.
Your secret keys are never exposed.
Your service only stops if Xahau stops working.

Given these advantages, it makes sense to think of use cases or businesses where time is an important or necessary variable. Some examples:

An event happens on a specific date (or multiple).
An event is triggered only after some delay.
An event occurs only during a defined window of time.
An event stops after a certain period or date.

Time isn’t just a useful variable—it can be combined with other conditions, such as:

Triggering different transactions depending on the amount.
Allowlisting or blocklisting sender or recipient addresses.
Requiring a fee for acting as an intermediary.
Creating custom rules or constraints.

The possibilities are nearly endless.

How to test time in Xahau?

You can start using the Xahau Hooks Builder, an online IDE to develop and test hooks. There’s also the Hooks Toolkit, a desktop SDK.

Let’s create a hook in the Xahau Hooks Builder and try the ledger_last_time() function, which returns the timestamp at the moment the hook is called.

Here’s the full hook code so you can copy, paste, and modify it in the Xahau Hooks Builder:

//Get timestamp from the last ledger
    int64_t ts = ledger_last_time();
    TRACEVAR(ts);

As you can see, we've created a variable called ts that stores the execution timestamp (technically of the last closed ledger, but we’ll keep it simple). The timestamp is the number of seconds since a reference date. In our example, the timestamp is 802547943, which corresponds to June 6, 2025.

If we go to XRPL Time Visualizer by Denis Angell, enter the timestamp, and click "From XRPL Time", it will return the current date.

Note: The Xahau/XRPL timestamp is not the same as Unix time. To convert it to Unix time, you must add 946684800 to your timestamp, since Xahau’s base date is Jan 1, 2000, while Unix time starts on Jan 1, 1970 at 00:00:00 UTC.

Let’s create a variable representing 2 minutes. Since the timestamp is in seconds, we can set it to 120 seconds or 2 * 60. We can use this variable later to add it to other timestamp variables and create conditions.

//Set a variable representing 2 minutes
    int64_t two_min = 2*60;
    TRACEVAR(two_min);

We can also declare a fixed timestamp for use as a base. In this case, we assign the value 802549410 to my_ts.

    //Set my own ts
    int64_t my_ts = 802549410;
    TRACEVAR(my_ts);

You can also save a timestamp in a namespace—"simple key-value tables where we store data on Xahau". For example:

    //Save my_ts in a namespace
    state_set(SVAR(my_ts), SBUF(dest_param));

You can verify on the Xahau Testnet de XRPLWin that your account has a declared namespace where the timestamp was saved:

As you can see, the stored value is A2EED52F00000000, which we need to convert from HEX to a readable format. Using the XRPL Hex Visualizer, enter the value and click "From Hex". You’ll see it returns 802549410, just like the value we saved in the hook.

Of course, we can also retrieve our timestamp from the namespace later, using this code:

    //Get my_ts from my namespace
    int64_t get_ts;
    state(SVAR(get_ts), SBUF(dest_param));
    TRACEVAR(get_ts);

From here on, with these tools, your imagination is the limit. If you want to continue building and have any questions you can join to the Discord Xahau Builders server.

Links

Official Website
Official Docs
Hooks Builder
Discord Server
Xahaud
X Account

Learning Xahau: Inflation and Deflation as Core Elements of Its Design

Ekiserrepe — Wed, 21 May 2025 15:42:09 +0000

In today's world, the word "inflation" sparks fear wherever it is mentioned.

It is felt on supermarket shelves, in transportation, energy and gas bills, in the consumption and acquisition of services and properties, in life expectancy, and even in birth rates. Inflation is part of our daily lives due to a variety of national and international factors. It has reshaped our routines and the way we work.

Inflation is the sustained and widespread increase in the prices of goods and services within an economy over time.

This means that, as time goes by, the purchasing power of money decreases, as more money is required to buy the same products or services.

When we bring inflation into the blockchain world, it becomes a topic of interest and concern for users.

Blockchains are designed for different purposes, and understanding the specific use case of the blockchain we intend to use is essential for the project, business, or service we want to build on it. When we talk about inflation in the context of blockchain, we are usually referring to whether the protocol can generate new tokens—potentially increasing the supply—or whether there are mechanisms in place that may result in a certain level of inflation.

Take Bitcoin as an example.

Initially introduced as a peer-to-peer electronic payment system, it has evolved into a store of value for many of its users. Observing the market, Bitcoin’s price behavior, and its most common use cases, we can conclude that users have largely chosen to treat it as an investment asset due to its non-inflationary nature. There will only ever be 21 million bitcoins, and some of these will be permanently inaccessible due to lost private keys or forgotten passwords. For many, this effectively makes Bitcoin deflationary.

Xahau, on the other hand, is currently inflationary.

This feature was deliberately included in the blockchain’s design from the outset, and this article aims to explain why.

Xahau excels as a robust payment system—it is extremely fast, efficient, and highly cost-effective.

It also features a decentralized exchange at its core, allowing users to trade assets with each other in real time. The technology behind Xahau has been tested in real-world environments for over a decade, which reinforces its reliability.

What and Why was Xahau created?

Xahau is an evolution of the XRP Ledger, enhanced with smart logic features known as Hooks. Hooks are programmable rules that can be attached to user accounts, enabling anything from simple to highly complex automated processes—similar to what other networks refer to as smart contracts. Hooks open up new possibilities on Xahau, allowing users to accept or reject incoming or outgoing transactions, automate tasks, and help enforce regulations and laws across multiple jurisdictions.

Most simple actions on Xahau consume (or temporarily reserve) XAH, the network’s native token.

These fees and reserves are typically negligible and barely noticeable in users' balances. This mechanism gives value to the requested transactions and the computational resources required to execute them, while also protecting the network from high-frequency transaction attacks. However, when it comes to Hooks, transactions can become significantly more complex. They may generate additional transactions, queue processes, store data on-chain, and require more processing power. Therefore, it is reasonable for these more complex Hooks to carry a higher cost.

This brings us back to the question of inflation on Xahau.

To make the execution of more sophisticated processes sustainable, Xahau allows users to claim a monthly balance adjustment (always positive), currently amounting to approximately 4% annually. This balance adjustment provides users with additional XAH to continue their ongoing processes and execute complex logic on the network, without the risk of depleting their balance due to Hook-related fees—while still upholding the principle that everything comes at a cost.

This mild inflation also influences other aspects of Xahau beyond Hooks.

Users are encouraged to actively use their XAH instead of letting it sit idle—unlike in many other blockchains. For example, Bitcoin could be described as a value network where users are incentivized to hold rather than spend, undermining its original purpose as a payment system. Similarly, on the XRP Ledger, the average user often prefers to hold XRP in hopes of appreciation, rather than using it for transactions or services. This limits overall network activity. Xahau, by contrast, is a system built for active use, where network participation is incentivized. Its mild inflation encourages users to make continuous use of their balance, as it will gradually lose value if left untouched. This mechanism is a brilliant part of Xahau’s design, ensuring steady engagement and avoiding the network becoming dormant during off-peak periods.

It would not be fair to discuss inflation on Xahau without mentioning the deflationary mechanisms that introduce scarcity.

Some actions in Xahau require users to reserve or lock portions of their XAH, which are excluded from inflation adjustments. Examples of such deflationary actions include the creation of URITokens (NFTs), setting up trustlines, configuring multi-signature lists, placing offers on the decentralized exchange, issuing checks, creating escrows, and other protocol features currently available or to be introduced in the future.

Deflationary pressure doesn’t come only from the protocol itself.

Users developing their own applications and businesses within or based on Xahau also contribute to deflation, at varying rates and scales. Some processes or services may consume more XAH than is gained through inflation, whether continuously or sporadically. This dynamic can have a positive impact on the valuation of XAH: as the circulating supply decreases, the value of each unit may increase, enabling more transactions with fewer tokens.

In conclusion, Xahau’s inflation mechanism is an intelligent way to encourage network engagement and the creation of complex logic using Hooks—without users fearing that their balances will be exhausted too quickly.

At the same time, it incentivizes making these processes as efficient as possible to avoid excessive fees. If poorly optimized, Hooks could consume users’ balances too rapidly, rendering the inflationary support insufficient and preventing abuse of the mechanism.

How do I claim the balance adjustment to receive my monthly XAH?

To claim the XAH corresponding to your account, you must first opt in with a ClaimReward transaction of type Opt-In: https://docs.xahau.network/technical/protocol-reference/transactions/transaction-types/claimreward. You will be able to claim your XAH every 30 days, 2 hours, and 13 minutes by calling this type of transaction again.
If you're not comfortable managing the transaction yourself, you can always use the Balance Adjustment xApp from Xaman by following this tutorial: https://help.xaman.app/app/all-about-xapps/xahau-xapps/balance-adjustment.

Learning Xahau Articles

Learning Xahau: The importance of building your own business layer
Learning Xahau: What is Xahau?
Learning Xahau: Inflation and Deflation as Core Elements of Its Design

Links

Official Website
Official Docs
Hooks Builder
Discord Server
Xahaud
X Account

Learning Xahau: The importance of building your own business layer.

Ekiserrepe — Wed, 14 May 2025 08:30:47 +0000

In the previous article Learning Xahau: What is Xahau?, we described what Xahau is and what it is not in general terms. The article defined Xahau as an independent blockchain based on the original XRP Ledger code, with several added features—one of the most important being Hooks, a new way to implement advanced logic within Xahau. Compared to other popular blockchain networks, we could say that Hooks are like smart contracts in EVM-based networks, but with a completely different philosophy and approach, tailored to Xahau’s technology.

The previous article also pointed out the need to add “smart contract” technology to Xahau, since it was not originally available in the XRP Ledger. But we should not reduce Xahau to a simple XRP Ledger + smart contracts formula. Let’s dive deeper into why this addition is necessary and how it benefits all network participants—from individual users to large corporations.

The Pre-Xahau Days

In my talk at APEX 2024, I discussed the current state of the XRP Ledger, where different proposals must compete for the same slice of the pie. Whenever a new feature is introduced to the XRP Ledger, different entities try to build interfaces around it, which forces these actors to compete to offer the best service to the end user. Clear examples include the many NFT marketplaces or services that enable interaction with AMMs.

Due to the lack of advanced logic in the XRP Ledger, every new feature must be integrated directly into its core code and go through a validator consensus process, requiring more than 80% agreement for at least 14 consecutive days. So, every update to the XRP Ledger becomes a difficult and prolonged process. Furthermore, not just anyone can propose, develop, and have their code accepted into the XRP Ledger. Contributions from the community have been rare. It’s usually much easier for Ripple, as a major actor in the network, to propose and implement changes. This greatly speeds up development but clearly highlights the lack of decentralization. Independent developers can’t afford to invest months or years (and money) developing improvements without guarantees that their code will be accepted and included in the XRP Ledger. (This is precisely what happened with the original Hooks proposal, which eventually became the Xahau blockchain.)

Another issue with the XRP Ledger is that every feature aims to be as efficient as possible, which is great for the end user, but makes it nearly impossible for companies and businesses to monetize their use of the XRP Ledger—unless they create interfaces or interpretations that simplify things for thousands of users. And not only do they have to focus on interfaces, but they must also compete in that narrow niche with others, since there are very few ways to build on the XRP Ledger. If a development such as NFTs or the AMM has already been implemented, it is very unlikely that another proposal with similar characteristics from an external team will be approved—especially considering that the original implementation is already optimized to run on the XRP Ledger without third-party fees. And even if the new proposal is more efficient, it can be argued that the new logic could jeopardize the blockchain itself and prevent it from reaching the end user. A dead end.

The importance of building your own business layer

For all these reasons, it’s time to take a close look at Xahau. For the first time in a blockchain based on XRP Ledger technology, anyone can create advanced logic thanks to Hooks—what I like to call “The Business Layer”. Why is this insteresting? Because those interested in building businesses don’t need to ask anyone for permission to build on Xahau. Thanks to Hooks, anyone can implement their own business logic and charge for it (if they want). Major actors in Xahau can’t stop you—they can’t block your business layer from working or prevent you from charging for it. You can create new features or processes and profit from them. There’s no need to wait to submit a proposal, hope it gets approved, and pray validators support your amendment—Hooks eliminate that entire process.

The business layer doesn’t just let you create exclusive logic for your own operations. You can share your Hooks with others, and each time your Hook runs, it can include a fee (optional) that is sent to your account. And if you don’t have ideas of your own, you can always earn money by coding Hooks for clients who don’t have the time to do it themselves.

If you don’t like the publicly available Hooks, you can always create a new version with your own improvements. If you see that a third party is running a business using Hooks and you don’t agree with their approach, you can always offer better Hooks. In other blockchains with smart contracts (such as the boom of Uniswap clones), this is a common practice. But in an XRP Ledger ecosystem, this is the first time we’re allowed to run our own business layer directly on the blockchain itself—Xahau.

The Xahau era begins

Xahau created its first ledger on Mainnet on October 30, 2023. This makes Xahau a newborn blockchain. If something in this post caught your attention, I forgot to mention that Xahau is the perfect ground to plant your ideas. Since it has only been live for a short time, very few projects have dared to take the leap. This gives those eager to build the opportunity to become pioneers in Xahau and set the path for others to follow. If you have an idea, now is the time. It doesn’t have to be innovative or revolutionary—even simple projects are viable options, as they’ve likely never been brought to Xahau before. From here, I encourage you to take action.

Learning Xahau Articles

Learning Xahau: The importance of building your own business layer
Learning Xahau: What is Xahau?
Learning Xahau: Inflation and Deflation as Core Elements of Its Design

Links

Official Website
Official Docs
Hooks Builder
Discord Server
Xahaud
X Account

Learning Xahau: What is Xahau?

Ekiserrepe — Mon, 12 May 2025 17:27:02 +0000

Welcome to Learning Xahau, a series of posts where we’ll try to explain the Xahau blockchain, its features, how it works, and even build our own examples in a way that’s accessible to everyone.

In today’s article, we’ll broadly discuss what Xahau is — and what it isn’t — debunk some common misconceptions, and dive into a few basic concepts.

What is Xahau?

Xahau is a layer 1 blockchain built from the XRP Ledger codebase, enhanced with features and improvements that are not present in the original XRP Ledger. Its native token is called XAH, and the blockchain has been live on mainnet since October 30, 2023.

Xahau shines for its speed, low cost and efficiency already proven for more than ten years based on the original XRP Ledger code.

Xahau is perfect for moving and exchanging value. Organizations, financial institutions and individuals can benefit from its features.

Why Xahau?

Xahau was not planned to exist but fate decided that it would. For several years, the XRPL-Labs team decided to devise and implement a smart-contracts solution for the XRP Ledger blockchain under the name Hooks. The solution was never merged into the XRP Ledger blockchain, so the work of years was going to be forgotten as it would not fulfill its ultimate goal. That is why, a modification of the XRP Ledger code base was made, new features were added and the Hooks solution was implemented, which would allow to see advanced logic in a blockchain based on XRP Ledger technology under a new name, Xahau.

Xahau was able to see the light of day thanks to the work of the Xahau Launch Alliance, a now disbanded organization to which several players who supported the launch of Xahau belonged.

What features does Xahau have—and what doesn’t it have?

As mentioned above, Xahau is not a simple copy of the XRP Ledger with smart contract capabilities added via Hooks. Although the codebases share similarities in how they operate, there are clear differences that, at the time of writing, can be summarized as follows:

URITokens: A new concept of NFTs, different from what’s available on the XRP Ledger. These are simpler to manage and index, but do not natively support royalties like XRP Ledger NFTs. However, thanks to Hooks, you can create your own custom royalty logic.
Hooks: Advanced pieces of code created by yourself or third parties, installable on Xahau accounts (up to 10 per account). Hooks are autonomous and don’t require network consensus to be activated. As long as a Hook has no errors and compiles correctly, it can be installed on Xahau. Hooks enable a business logic layer not possible on the XRP Ledger.
Governance Game: Different committees vote on decisions within the Xahau network, allowing for greater democratization.
Claim Reward: Xahau has an annual inflation rate of 4%, which benefits all Xahau users. The XAH you hold determines the share of monthly rewards you can claim, if desired.
Faster amendment approval: XRP Ledger requires 14 days of positive votes above threshold to activate an amendment. Xahau only requires 5 days.
Different supply: Xahau launched with 600 million XAH and has an annual growth close to 4%. As of May 12, 2025, there are 627,711,384 XAH in circulation. You can check the current supply at this API: Xahau API Supply Info
Escrows for IOUs: In addition to creating escrows for XAH, you can also manage escrows for other tokens of any kind (this is not possible on the XRP Ledger).
Remits: A transaction type that allows users to send multiple payment types, mint a URIToken, transfer a list of URITokens, and activate an account—all at once.

In addition to these unique features, Xahau shares the following characteristics with the XRP Ledger:

Token creation (IOUs): Xahau allows users to issue tokens representing real or fictional assets.
DEX: A native decentralized exchange that allows creating offers for tokens, XAH, or URITokens.
Multisigning: Xahau supports multi-signature account control.
Payment Channels

Some native XRP Ledger implementations like the AMM haven’t been adopted by Xahau yet, though alternative approaches are being developed as seen in the proposal XAS-1 or in XRPLWin Xahau Testnet Explorer.

The base codes of Xahau and XRP Ledger are diverging, as both chains are following different paths. New features in XRP Ledger won’t automatically appear in Xahau, since the code is no longer the same. However, thanks to Hooks, many features that would take months to be introduced into the XRP Ledger core and require validator approval can be implemented in Xahau within days or weeks—without requiring validator consensus.

What is Xahau not?

Xahau is not a Layer 2 of the XRP Ledger. Xahau is an independent blockchain with its own token. There is no connectivity between Xahau and the XRP Ledger, so it’s not a sidechain either.

While Xahau did initially launch with a mechanism called Burn2Mint—which allowed users to burn XRP in exchange for XAH on the Xahau network—this mechanism has been disabled. Therefore, it's incorrect to consider Xahau a sidechain of the XRP Ledger (or vice versa).

The XAH available on the XRP Ledger DEX is not native XAH—just as the BTC or ETH on XRP Ledger are not real BTC or ETH. They are IOUs issued within XRP Ledger. XAH on the XRP Ledger is not eligible for ClaimReward. To benefit, you must move that XAH to the Xahau network. There is a xApp in Xaman called XAH Teleport that allows you to transfer XAH from XRP Ledger to your Xahau account.

Learning Xahau Articles

Learning Xahau: The importance of building your own business layer
Learning Xahau: What is Xahau?
Learning Xahau: Inflation and Deflation as Core Elements of Its Design

Links

Official Website
Official Docs
Hooks Builder
Discord Server
Xahaud
X Account

DEV Community: Ekiserrepe

Learning Xahau: PriceOracle and IOURewardClaim, On-Chain Prices and Custom Reward Programmes

PriceOracle: On-Chain Price Feeds

The Problem It Solves

Key Concepts

Multiple Oracle Objects per Account

Publishing a Price (01-price-oracle-set.js)

Querying the Aggregate Price (02-price-oracle-query.js)

Removing an Oracle (03-price-oracle-delete.js)

IOURewardClaim: Custom Token Reward Programmes

What Is ClaimReward?

What IOURewardClaim Adds

The Three Accounts

Step 1 — Create and Distribute the Token (04-create-distribute-token.js)

Step 2 — The Reward Hook (iou_reward_hook.c)

Step 3 — Install the Hook (05-install-hook.js)

Step 4 — Claiming IOU Rewards (06-claim-reward-iou.js)

The Full Picture

Summary

Resources

Learning Xahau: Debunking Common Myths About Xahau

1. “Xahau Is an XRP Ledger Sidechain”

2. “Projects Built on Xahau Don’t Actually Use XAH”

3. “Hooks Are Just Ethereum Smart Contracts”

4. “The XAH You See on XRPL Is Native XAH”

5. “Xahau Is Just XRP Ledger With Smart Contracts”

6. “Hooks Are Dangerous Because They Can Do Anything”

7. “Xahau Depends on Ripple”

8. “Xahau Is Trying to Compete With Every Other Blockchain”

Final Thoughts

Learning Xahau: Building an Automatic NFT Factory with Hooks

The problem we want to solve

The solution: a Hook as an automatic factory

What is a URIToken?

How the Hook works internally

Configuration parameters

Example parameters

The generated URI format

The Hook state

The minting flow

How to install the Hook

Option A: Deploy from your own .wasm

Option B: Install using the already deployed HookHash

Practical considerations

Always test on testnet first

The business layer perspective

Web Service for Non-Coders

Conclusion

Possible improvements and ideas

Acknowledgements

Links

Learning Xahau: Automating Reward Claims with Hooks and CronSet

Introduction

The Problem We're Solving

The Solution: Combining Hooks with CronSet

Understanding the Architecture

1. The ClaimReward Hook (C Code)

2. Account Configuration Scripts

3. The CronSet Orchestrator

The Technical Deep Dive

Understanding Xahau Time

The Safety Margin Philosophy

Calculating Next Claim Time

Real-World Implementation

Step 1: Initial Setup

Step 2: Configure Your Account

Step 3: Install the Hook

Step 4: Analyze Your Account

Step 5: Schedule Automation

Advanced Considerations

Handling First-Time Users

Choosing RepeatCount Wisely

Network Selection

Monitoring Your Automation

The Business Layer Perspective

Security Considerations

Hook Verification

Transaction Fees

Troubleshooting Common Issues

"Account not eligible for rewards yet"

Publishing a Price (`01-price-oracle-set.js`)

Querying the Aggregate Price (`02-price-oracle-query.js`)

Removing an Oracle (`03-price-oracle-delete.js`)

Step 1 — Create and Distribute the Token (`04-create-distribute-token.js`)

Step 2 — The Reward Hook (`iou_reward_hook.c`)

Step 3 — Install the Hook (`05-install-hook.js`)

Step 4 — Claiming IOU Rewards (`06-claim-reward-iou.js`)

Option A: Deploy from your own `.wasm`