XLDB is the easiest and most direct way to put blockchain to use. It allows developers and business users alike to utilize blockchain like a regular database without needing to understand or deploy smart contracts.

Create your XLDB by clicking Deploy under XLDB tile and select the ledger you want XLDB to be deployed on. You can straightaway write data to it.

The Xooa Ledger Database (XLDB) is comprised of two databases: A mutable document datastore called the State Database, or World State, and an immutable database called the Transaction Database, or simply the Ledger. The Ledger is append-only and cryptographically protected against modifications using blockchain technology.

When a key-value pair is created or updated, the World State is modified using a transaction. The transaction is appended to the ledger. All changes to key-value pairs (including deletions) are recorded in the ledger and can be queried via the History endpoint.

Key Considerations

The key uniquely identifies the key-value pair within the World State database. The most appropriate method for constructing keys varies by use case. For example, if you are only interested in the append-only nature of the XLDB, and not in the state database, or rich query, it doesn’t matter what you use as a key, and you may find it convenient to use the same key for all transactions. You can use the History endpoint to fetch all transactions and their associated payloads.

If you wish to search based on the content of each transaction (the payload), you will then need a unique key (such as uuid) for each transaction because such a search can run only against the State Database (see Query endpoint for more details).

The XLDB State Database may be used to store different object types (such as cars and people), typically using different JSON document schemas. If this is your use case, it makes sense to combine the object type and the unique object identifier into a single key. Another best practice with multiple object types is to denote the object type within the JSON representation of the value. It will facilitate query filtering by object types.

Value Considerations

It is recommended that values are formatted as JSON objects to effectively utilize the rich query capabilities of the query endpoint.

The XLDB enriches values with metadata fields such as the identity of the token holder that created or modified the key, along with the created and the last-modified date. These metadata fields may be used to filter a query using the Query endpoint.

More details on the XLDB APIs can be read and tried here.

More details about World State, Transactions, and other app-related features can be read here.

Do you prefer video tutorials? Check out the video tutorial for XLDB here.

Write to the XLDB blockchain ledger

Using Xooa console

We can invoke functions directly from the UI. You won’t even need the API token.

  1. Go to the World State tab, and then select Add.

  2. Select Use Sample. It will populate the key and value fields for you.

  3. Click Save.

world state



You have saved data in a blockchain ledger by using Xooa.

Using API Explorer

We can invoke functions from the API documentation, but you will need the API token.

Let’s create an API token first.
  1. Go to the XLDB > Identities tab, and then click Add New.

  2. Enter an identity name and under API Access Permission, select Read+Write.

  3. Click Create. You’ll get a message that the identity has been enrolled and the API token generated.

  4. Before you dismiss the message, click Copy. The token is now in the clipboard.

  5. Store the token somewhere safe. You will need it to authorize every API request.


Xooa does not store the API token. If you lose the token, you will have to generate a new one, invalidating any existing API clients.

id creation

Let’s invoke functions from the API documentation.
  1. Go to the API tab, and then click Explore APIs. The API Explorer, including the API documentation, will open.

  2. At the top left, there is an input field for the API token. Paste the token that you copied earlier here.

  3. From the navigation, go to XLDB > Create.

  4. In the key-value field, enter the data you want to store in the ledger in the format:

    [ "<key>", "<value>" ]

  5. Click TRY.



    If your HTTP response code was 200, you have saved data in a blockchain ledger by using Xooa. Check instructions in the message or the API documentation for other return codes.

Read from the XLDB blockchain ledger

  1. To view transactions, go to Transactions tab inside the app.
  2. Click the tx ID to get additional details about the transaction
  3. To view World State, go to World State.
  4. Expand the row from listed states to get the detailed structure of values.