TXO Transaction Object Format

• Ty Everett ([e-mail])

• _unwriter

Abstract

This document presents the technical standard for the TXO (Transaction Object) format, a structured representation of Bitcoin transactions that enables powerful queries, processes, and filters. The TXO format captures transaction data in a hierarchical structure, facilitating its storage in document databases (e.g., MongoDB) and enabling real-time filtering with JSON filter libraries (e.g., JQ).

Motivation

Traditional raw one-dimensional Bitcoin transactions, as described in BRC-12, are challenging to process and filter, which hinders the development of applications that rely on transaction data. The TXO format overcomes these limitations by transforming raw Bitcoin transactions into a structured, queryable, and hierarchical format, thereby enabling developers to build powerful applications and services using transaction data.

Specification

The TXO format represents a Bitcoin transaction as a JSON object with the following high-level structure:

{
  "tx": {
    "h": [TRANSACTION HASH],
    "r": [RAW TRANSACTION]
  },
  "blk": {
    "i": [BLOCK INDEX],
    "h": [BLOCK HASH],
    "t": [BLOCK TIME]
  },
  "in": [
    INPUT1,
    INPUT2,
    ...
  ],
  "out": [
    OUTPUT1,
    OUTPUT2,
    ...
  ],
  "coinbase": [COINBASE]
}

Level 1: Transaction

At the top level, the TXO format includes two objects: tx and blk.

• tx (transaction): contains:

  • h (transaction hash)

  • r (raw transaction)

• blk (block): contains:

  • i (block index)

  • h (block hash)

  • t (block time)

Level 2: Script

The next level of the TXO format includes two arrays: in (input scripts) and out (output scripts).

Each input and output is essentially a Bitcoin script. Attributes for each script include:

• i: the index of the current script within the in (input) or out (output) array.

• b0, b1, b2, ...: the script's push data.

  • Opcodes: stored as a JSON object with a single key op and the Bitcoin opcode value (e.g., {"op": 106} for the 'return' opcode).

  • Non-Opcodes: stored as a base64 encoded string.

• lb0, lb1, lb2, ...: base64 encoded string, used when the push data size is larger than 512 bytes.

• s0, s1, s2, ...: UTF8 encoded representation of the push data, used for full-text search and simple string matching.

• ls0, ls1, ls2, ...: UTF8 encoded representation, used when the push data size is larger than 512 bytes.

• str: full string representation of the script.

• e: contains the graph structure of each transaction.

Level 3: Graphs

The third level of a TXO interpreted transaction focuses on the graphs that represent the relationships between transactions. Graphs play a crucial role in understanding the flow of transactions in the Bitcoin network. Each item in the in and out arrays has an attribute called e (edge), which represents the graph structure of each transaction. The edge attribute helps in connecting the inputs and outputs of a transaction, as well as tracking the flow of satoshis between addresses.

For inputs, the edge is an "incoming edge" that represents the outputs from the previous linked transaction. It contains the following fields:

• h: The hash of the transaction that contains the previous output.

• i: The index of the previous output within its transaction output set.

• a: The sender address if it can be parsed into an address.

For outputs, the edge is an "outgoing edge" that represents the outputs to the next linked transaction. It contains the following fields:

• v: The amount of satoshis sent.

• i: The output index within the transaction.

• a: The receiver address if the output is linking to an address.

Implementation

To implement the TXO format, follow these steps:

1. Deserialize the raw Bitcoin transaction into its input and output scripts.

2. Parse the input and output scripts into a JSON object following the TXO schema described in the specification section. This includes constructing the transaction, script, and graph levels for each transaction.

3. If applicable, store the TXO JSON object in a document database (such as MongoDB) to enable powerful queries, or filter the transactions in real-time using JSON filter libraries (such as JQ).

4. Ensure compatibility with the TXO format by including all specified fields and adhering to the defined structure.

The reference implementation was written by _unwriter of the 21st Century Motor Company and is available on NPM.