Skip to content
Javascript library for converting txids to txrefs and back
Branch: master
Clone or download
Pull request Compare This branch is 2 commits ahead, 9 commits behind WebOfTrustInfo:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

TX Ref conversion javascript library


Javascript library for Bech32 Encoded TX References, ported from Jonas Schnelli's reference implementation for the Rebooting Web Of Trust's BTCR Hackathon. It uses Peter Wuille's Bech32 library for Bech32 encoding and decoding.

See the current draft of the Bech32 Encoded Transaction Position References BIP.

This implementation works as follows:

  • Encoding:

  • Decoding:

    • Decodes the bech32-encoded tx ref javascript Bech32 library
    • Extracts the block height and position as shown in btc_txref_decode
    • Find the txid corresponding to the blockheight and position from a blockchain explorer

This library is for prototype use only. Some future improvements would include:

  • Checking confirmation count from the API results; warn if less than 6 (or some other threshold).
  • Compare results from multiple blockchain explorer APIs
  • Flexible accessor if a local bitcoin node is available.
  • Robust error checking

You can use this as a node package or in a browser. The browserified script is available as btcr_converter.js.


You can experiment with this library in the BTCR TX Playground


In these examples, note the following:

  • Prefixes: mainnet tx refs start with the tx1 prefix, whereas testnet tx refs start with "txtest1"
  • Length: ignoring the prefixes, testnet refs are 2 characters longer than mainnet

Convert a TXID to a TX ref

let txrefConverter = require('./txrefConverter');

  .then(result => {
    console.log(result); // expect "tx1-rk63-uvxf-9pqc-sy"

Convert a TX ref to a TXID

let txrefConverter = require('./txrefConverter');

  .then(result => {
    console.log(result); // expect "f8cdaff3ebd9e862ed5885f8975489090595abe1470397f79780ead1c7528107"

Finer grained functions

Given the chain, block height and position, encode as a TX ref


let txrefConverter = require('./txrefConverter');

let result = txrefConverter.txrefDecode('tx1-rzqq-qqqq-uvlj-ez');
console.log(result.blockHeight); // expect 1
console.log(result.blockIndex);  // expect 0
console.log(result.chain);       // expect "mainnet"


let txrefConverter = require('./txrefConverter');

let result = txrefConverter.txrefEncode("testnet", 1152194, 1);
console.log(result); // expect "txtest1-xyv2-xzyq-qqm5-tyke"

Given a TX ref, extract the chain, block height and position

let txrefConverter = require('./txrefConverter');

let result = txrefConverter.txrefEncode("mainnet", 0, 0);
console.log(result); // expect "tx1-rqqq-qqqq-qmhu-qk"

Get transaction details

Given a txid and chain, lookup the transaction details:

let txrefConverter = require('./txrefConverter');

getTxDetails("f8cdaff3ebd9e862ed5885f8975489090595abe1470397f79780ead1c7528107", "testnet")
    .then(data => {
      console.log(data.numConfirmations); // and other transaction data obtained from the explorer
      var result = txrefEncode(chain, data.blockHeight, data.blockIndex);
      return result
    }, error => {


npm install

Using in a browser

npm run build generates the browserified script btcr_converter.js, which you can include in your web project.

The following shows how you can use it:

<script src="./btcr_converter-browserified.js"></script>

BtcrUtils.txidToTxref(txid, chain)
  .then(function (result, err) {
      // populate widget with result

See the BTCR playground code repository btcr-tx-playground for working code samples.

Running tests

npm run test
You can’t perform that action at this time.