README

bitcoin verifier ses

Verify Bitcoin SPV Proofs in SES

Getting Started

Node.js version 10 or greater is required.

git clone https://github.com/summa-tx/bitcoin-verifier-ses.git
cd bitcoin-verifier-ses
npm install

Library Interface

The SPVProof object follows the format found in @summa-tx/bitcoin-spv-js:

/**
 * @typedef {Object} Header
 * @property {Uint8Array}    raw The bitcoin header
 * @property {Uint8Array}    hash The hash of the header
 * @property {Number}        height The height
 * @property {Uint8Array}    merkle_root The merkle root of the header
 * @property {Uint8Array}    prevhash The hash of the previous header
 */

/**
 * @typedef {Object} Proof
 * @property {Uint8Array}    version The version
 * @property {Uint8Array}    vin The vin
 * @property {Uint8Array}    vout The vout
 * @property {Uint8Array}    locktime The locktime
 * @property {Uint8Array}    tx_id The tx ID
 * @property {Number}        index The index
 * @property {Uint8Array}    intermediate_nodes The intermediate nodes
 * @property {Header}        confirming_header The bitcoin header
 */

The Verifier object is defined in lib/primitives.

The Verifier composes predicate functions. These functions can be found in the lib/predicates directory. Each predicate function accepts two arguments, an untrusted proof object and an endowments object, which is set when constructing the Verifier.

When a Verifier object is constructed, it accepts an object with a list of predicates and an endowments object. The predicates are applied in the order in which they appear in the list. Each predicate is passed data from the endowments object if the function name matches the key in the endowments object. If the value in the endowments object is an array, then the predicate will be applied with each object in that array, otherwise it will be applied with the value.

Note: You must pass through an endowments object, even if the predicate(s) does not require it.

Usage

const { Verifier } = require('@summa-tx/bitcoin-verifier-ses');
const { BcoinClient } = require('@summa-tx/bitcoin-spv-js-clients');
const {
  isValidHeaderChain,
  isEnoughWork,
  isCorrectRecipient,
  isValidHeaderChain,
  consumesUTXO
} = require('@summa-tx/bitcoin-verifier-ses/predicates');

// set up a verifier object
// each predicate is a function that must evaluate
// to true for the proof to evaluate to true
// each predicate is passed an untrusted proof object
// and the endowments object
const verifier = new Verifier({
  predicates: [
    isValidHeaderChain,
    isEnoughWork,
    isCorrectRecipient,
    isValidHeaderChain,
    consumesUTXO
  ],
  endowments: {
    isEnoughWork: {
      nwork: /* <big endian hex string or BigInt> */
    },
    isCorrectRecipient: {
      outputScript: /* <Uint8Array> */,
      outputIndex: /* <Number> */
    },
    consumesUTXO: {
      inputIndex: /* <Number> */,
      prevout: {
        hash: /* <Uint8Array> */,
        index: /* <Number> */
      }
    }
  }
});

// the Verifier is an EventEmitter
verifier.on('valid', async (proof) => {
  // react to valid proof here
});

verifier.on('invalid', async (proof) => {
  // react to invalid proof here
});

// see bcoin docs for config options
const client = new BcoinClient({});
const txid = '2f8a31d9b288cc27bcffb44d6de3dc3a8b77a45cbf481c129c86f4d4c';

// fetch proof
const proof = await client.getProof(txid);

// verify the proof
const [valid, reason] = verifier.verify(proof);

if (!valid) {
  throw new Error(reason);
}

CLI Tools

./bin/proof --http-host <http-host> --api-key <apikey> --txid <txid>

Tooling

Bitcoin SPV

GitHub
NPM

Bcoin

Docs
GitHub

Dependencies

This software is based on bcoin.

This software is licensed under the MIT License.

Copyright (c) 2014-2015, Fedor Indutny (https://github.com/indutny)
Copyright (c) 2014-2019, Christopher Jeffrey (https://github.com/chjj)
Copyright (c) 2014-2020, Bcoin Contributors (https://github.com/bcoin-org)

Usage no npm install needed!