npm package: @summa-tx/bitcoin-verifier-ses
Description: Secure Ecmascript Bitcoin SPV Proofs
Author: Summa
Latest version: 0.3.0

# 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`:
```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

```js
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

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

### Tooling
Bitcoin SPV
* [GitHub](https://github.com/summa-tx/bitcoin-spv)
* [NPM](https://www.npmjs.com/package/@summa-tx/bitcoin-spv-js-clients)

Bcoin
* [Docs](https://bcoin.io/api-docs/index.html)
* [GitHub](https://github.com/bcoin-org/bcoin)

### 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)
```