TXHO - Transaction Hoisted Object
TXHO translates raw bitcoin transaction into JSON format while hoisting larger data so you can easily:
- Store context information and content information separately
- Filter in realtime using JSON filter libraries (such as JQ)
TXHO can be used in the browser, as a module for node, from the CLI to make sense of a raw bitcoin transaction or as a processing unit when piping data.
Installation
For CLI
npm install txho -g
As module for node
yarn add txho
Usage
CLI
Provide one of the following combinations of parameters
> txid <txid (64 char long string in hex)>
> rawtx <raw tx data>
For txid see "fromHash" section for configuration of how to contact a bitcoin node.
You can also pipe in data from a file having one txid or rawtx per line. The output will default to a nldjson format (= one json object per line):
txho rawtx < lostOfRawTxs.txt > output.nldjson cat lostOfTxids.txt | txho txid > output.nldjson
The sequence of the output is not guaranteed to be the same as the input. If this is needed xargs is suggested:
cat lostOfTxids.txt | xargs txho txid >> output.nldjson
Node
There are two methods:
- txho.from.rawtx() generates JSON from raw transaction data (Local operation and doesn't require a bitcoin node)
- txho.from.txid() generates JSON from a transaction hash. (requires a bitcoin node for JSON-RPC)
from.rawTx
Generate JSON from raw transaction string.
Example
let result = txhofrom;console;from.txid
The txho.from.txid method needs to contact a bitcoin node to use JSON-RPC, therefore you need to have access to a JSON-RPC endpoint.
For the JSON-RPC endpoint the first step is to make a .env file
BITCOIN_USERNAME=[Bitcoin Node Username]BITCOIN_PASSWORD=[Bitcoin Node Password]BITCOIN_IP=[Bitcoin Node IP]BITCOIN_PORT=[Bitcoin Node Port]Then, we can get the JSON representation of the transactoin like this:
let result = txhofrom;console;The output
TXHO outputs a JSON object that represents a transaction. Large data is hoisted from the main structure and placed next to it so that it's easy to manage large data in different ways while still keeping the references to ensure consistency.
Please note that the structure of the default JSON output from TXHO is similar but not equal to the output from the TXO library or the related MOM notations. You can, however, get the original TXO structure by providing the config variable txo with the configuration you normally provide TXO. The TXO functionality has been included to leverage the ability of TXHO to pipe data.
High level format of the output:
Configuration of the output
The output can be adjusted with the following configuration. For CLI you need to prepend -- to the name. In node you provide a config object.
and following configuration via node:
network: string // main or test maxDataSize: number // What is the max size of data not hosted. Defaults to 512. If 0 no data is hoisted cellB64: flag; // Aways add a base 64 representation of data to each cell. Default true cellStr: flag; // Aways add a string representation of data to each cell. Default false cellHex: flag; // Aways add a hex representation of data to each cell. Default false cellHash: flag; // Aways add a buffer containing a data to each cell. Default false cellAuto: flag; // Try to guess the most human readable format of str/hex/b64. Will add iso representatoin of utc if string looks like a timestamp cellAll: flag; // Same as setting cellB64, cellStr, cellHex, cellHash and cellAuto to true cellBuf: flag; // Aways add a buffer containing raw data to each cell. Default false compress: boolean; // Compress the output to one line. Default false. If data is piped: default true. only: string // Comma seperated list of dot-notated elements to only include in output (like --> hide: string // Comma seperated list of dot-notated elements to explude from output (like --hide=data.b64). Overruled by "only" txo: object // The inside of a config object to initiate a TXO output. pool: object; // Config object to manage the pool size of rpc requests: See more about chiqq on npm. // Is merged with {concurrency:5,retryMax:3,retryCooling:1000,retryFactor:2} splitDelimiter: fn // function to indicate if elements is delimiter // defaults to: `(e) => atobPipe === e.b64 || OP.RETURN === e.op || OP.FALSE === e.op` Usage specific for the CLI:
only: string // Comma seperated list of dot-notated elements to only include in output (like `--> hide: string // Comma seperated list of dot-notated elements to explude from output (like `--hide=data.b64`). txo: object // The inside of a config object to initiate a TXO output. skip: number // For piped data only: how many lines to skip before starting to execute. cleanData: string // If you need to trim or pick the info out from a datastructure. For txid it will identify and use the first valid 64 char hex string from the input. // For rawtx it will use the longest hex string found in the input. pool: object; // The inside of a config object to manage the pool size of rpc requests: See more about chiqq on npm. // Is merged with default: --pool=concurrency:5,retryMax:3,retryCooling:1000,retryFactor:2Example
Here is an example for the CLI that makes it easy to skim what is going on in the OP_RETURN data
$ txho txid c27d17bc9f427e5b287bee09437ef6d2749c321650a9670eb185d21873a65169 --cellAuto --
returns
An example using node with default parameters
let result = txhofrom;console;The output will be: