txoh v1.3.0

TXOH - Transaction object hoisted

TXOH 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)

TXOH can be used 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 txoh -g

As module for node

yarn add txoh

Usage

There are two methods:

1. fromTx: Generates JSON from raw transaction data (Local operation and doesn't require a bitcoin node)
2. fromHash: Generates JSON from transaction hash. (requires a local bitcoin node for JSON-RPC)

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.

Any parameter after the two first parameters will be joined and treated like the content of a json5 object to configure the output. Example:

txid 0726963652a3...data...2274785e756d5f cellStr: 1 , outputSplit:0

see more in the section Configuration for details.

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):

txoh rawtx < input.txt > output.nldjson cat lostOfTxids.txt | txoh txid > output.nldjson

The sequence of the output is not guaranteed to be the same as the input. If this is needed xrags is suggested:

cat lostOfTxids.txt | xargt txoh txid >> output.nldjson

Node

fromTx

Generate JSON from raw transaction string.

Example

const txoh = require('txoh');
(async function () {
	let result = await txoh.fromTx(
		'0100000001d5001345e77e66fa74f0012a81017ea1223c7a8adbcc9e37f2860f95ba97966d000000006b483045022100c1a0c5ffc5b78e39acb5be1438e28a10e5aac8337f5da7e4c25ba4c5f3eb01b5022050e9997bae423585da52d7cdc8951379f5bff07adb6756ffe70e7c7181f8a5bd4121032b345f89620af75f59aa91d47cc359e4dd907816ce0652604922726025712f52ffffffff024a976200000000001976a914c6187747f80b85170eef7013218e7b0fa441479988ac44033f00000000001976a9147e4616b7453185a5f071417bb4ac08e226dbef9888ac00000000'
	);
	console.log(result);
})();

fromHash

The fromHash method needs to contact a bitcoin node to use JSON-RPC, therefore you need to have access to a 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:

const txoh = require('txoh');
(async function () {
	let result = await txoh.fromHash(
		'45c6113bb1ecddc976131022bc80f46684d8956ab1a7bb5fc5625b5f7a930438'
	);
	console.log(result);
})();

The output

TXOH 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 TXOH is similar but not equal to the output from TXO library or the related MOM notation. You can, however, get the original structure by providing the config variable txo with the configuration you normally provide TXO. The TXO functionality has been included to leverage the ability to pipe data.

High level format of the output:

{
  "tx": {
    "txid": [Transaction hash],
    "in": [    // an array with an object per input
      {
        "sender": {
          "txid": [Transaction h where this input originated]
          "iOut": [Index that this input had in the transactoin where it originated]
          "address": [base58 representation of the public key of the sender (the address)]
        },
        "payload": [ // an array with an object per output
          {
            "b64": [All data defaults to base64 (see more about configuration)]
          },
          {
            "op": [If data is an OP code the property is called "op"]
          },
          {        // if data is larger than includeDataMax (defaults to 512)
            "size": [number of bytes]
            "sha256": [hash of content],
            "ref": [a reference to identify data in the property ref]
            }
          }
        ]
      }
    ],
    "out": [
      {
        "receiver": {
          "value": [Amount of sathoshi in the output]
          "address": [receiver address]
        },
        "payload": [ // an array with an object per output (same as input)
          ...
        ],
        "split": [ // an array with arrays of sections split up by the delimiters like  OP_RETURN and the pipe |. Same idea as the MOM format.
          [  // First section - could forexample be a B:// format
            {
              ... objects like in paload
            }
          ],
          [  // second section- could forexample be a signing AIM protocol
            {
              ... object like in paload
            }
          ]
        ]
      }
    ]
  },
  "refs": [ // array of all refs hoisted from the structure (so you can loop over them)
      ...
  ]
  ref{    //object with refs as propertis of all refs hoisted from the structure (so you can access them directly)
      "<ref>":   {
      "size": [bytesize]
      "sha256": [hash],
      "b64": [data base 64 encoded],
      "ref": [The ref],
      "txid": [transaction hash of this transaction],
      "type": [input or output],
      "iTx": [index amongst input or output],
      "iPayload": [index in the input or output ]
    },
  }
}

Configuration of the output

The output can be adjusted with the following configuration.

{
    network: string,           // main or test
    outputPayload: boolean,    // Include "payload" in the output.
    outputSplit: boolean,      // Include "split" in the output.
    maxSizeData: number,       // What is the max size of data not hosted. Defaults to 512. If 0 no data is hoisted
    cellB64: boolean,          // Aways add a base64 representation of data to each cell. Default true
    cellStr: boolean,        // Aways add a string representation of data to each cell. Default false
    cellHex: boolean,        // Aways add a hex representation of data to each cell. Default false
    cellBuf: boolean,        // Aways add a buffer containing a data to each cell. Default false
    cellHash: boolean,       // Aways add a buffer containing a data to each cell. Default false
    skip: number             // How many lines to skip before starting to execute when piping data
    splitDelimiter: fn     // Function to determine if cell is a delimitor for split. Example: (c)=>{c.op===0}
}

Example

With the following input

const txoh = require('txoh');
(async function () {
	let result = await txoh.fromHash(
		'c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033.hex'
	);
	console.log(result);
})();

The output will be:

{
	"tx": {
		"txid": "c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033",
		"in": [
			{
				"seq": 4294967295,
				"sender": {
					"txid": "74f2d6e54bec9f89f92ce076d0a00b434509ae3733bb894e701a0c45cb33f40e",
					"iOut": 2,
					"address": "1KaDHtjkYE1BYhHyDe2UPYwfviEqtK3B9u"
				},
				"payload": [
					{
						"b64": "MEQCICwaHCvbsVKRYeei14Hbem9ygkY0tmOxQd7NzjxdhaLSAiAyJTp6ueSGSiLd/2pXyGjzlq994x4i71Z5fCWpXnY3BEE="
					},
					{
						"b64": "Ao+eiEtV+WVoSIeTZb1KqLuz3ru2+kHvnFSlISVTxrel"
					}
				]
			}
		],
		"out": [
			{
				"receiver": {
					"value": 0,
					"address": "false"
				},
				"payload": [
					{
						"op": 0
					},
					{
						"op": 106
					},
					{
						"b64": "MTlIeGlnVjRReUJ2M3RIcFFWY1VFUXlxMXB6WlZkb0F1dA=="
					},
					{
						"size": 86234,
						"sha256": "137dfc5d14a7019a76dec0dd580731383ab22b94546f626a208be346d28c4f65",
						"ref": "c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033.out.0.3"
					},
					{
						"b64": "aW1hZ2UvanBlZw=="
					},
					{
						"b64": "YmluYXJ5"
					},
					{
						"b64": "d2VpYmxvY2tfMTA3NDZfcG9zdF9pbWFnZS4xNTg5ODU3OTExMzUzMDE4LmpwZWc="
					}
				],
				"split": [
					[
						{
							"b64": "MTlIeGlnVjRReUJ2M3RIcFFWY1VFUXlxMXB6WlZkb0F1dA=="
						},
						{
							"size": 86234,
							"sha256": "137dfc5d14a7019a76dec0dd580731383ab22b94546f626a208be346d28c4f65",
							"ref": "c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033.out.0.3"
						},
						{
							"b64": "aW1hZ2UvanBlZw=="
						},
						{
							"b64": "YmluYXJ5"
						},
						{
							"b64": "d2VpYmxvY2tfMTA3NDZfcG9zdF9pbWFnZS4xNTg5ODU3OTExMzUzMDE4LmpwZWc="
						}
					]
				]
			},
			{
				"receiver": {
					"value": 5044,
					"address": "17iUBMxZ7zjWt6BHu4V5x6GmHy2bFy8RrZ"
				},
				"payload": [
					{
						"op": 118
					},
					{
						"op": 169
					},
					{
						"b64": "Sah/KWSCHydbR8ojw1Wb54qWcS8="
					},
					{
						"op": 136
					},
					{
						"op": 172
					}
				],
				"split": [
					[
						{
							"op": 118
						},
						{
							"op": 169
						},
						{
							"b64": "Sah/KWSCHydbR8ojw1Wb54qWcS8="
						},
						{
							"op": 136
						},
						{
							"op": 172
						}
					]
				]
			},
			{
				"receiver": {
					"value": 37481907,
					"address": "19BaCAxsYvJtq2k5cGLN3kQoPgQn9FU2VR"
				},
				"payload": [
					{
						"op": 118
					},
					{
						"op": 169
					},
					{
						"b64": "WcDfqhsZWBdi5HO/Lm27bbxgB3g="
					},
					{
						"op": 136
					},
					{
						"op": 172
					}
				],
				"split": [
					[
						{
							"op": 118
						},
						{
							"op": 169
						},
						{
							"b64": "WcDfqhsZWBdi5HO/Lm27bbxgB3g="
						},
						{
							"op": 136
						},
						{
							"op": 172
						}
					]
				]
			}
		]
	},
	"refs": ["c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033.out.0.3"],
	"ref": {
		"c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033.out.0.3": {
			"size": 86234,
			"sha256": "137dfc5d14a7019a76dec0dd580731383ab22b94546f626a208be346d28c4f65",
			"b64": "/9j/4AAQSkZJRgABAQAAAQABAAD... Lots of data ...2wBCIiAiIgIiICIiAiIgIiICIiB/9k=",
			"ref": "c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033.out.0.3",
			"txid": "c6a8c80aa75761afdd2bd9fdb0236e12f71cfa0769c51158d505a5ba23e38033",
			"type": "out",
			"iTx": 0,
			"iData": 3
		}
	}
}