Learning Xahau: Storing On-Chain Data with Remarks

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