abstract-common-blockchain

A test suite and interface you can use to implement standard Bitcoin blockchain API calls for various backends and platforms.

Combines the common-blockchain REST API with bitcoind JSON-RPC.

The goal of this module is to define a de-facto standard blockchain API. Inspired by the abstract-blob-store and abstract-leveldown modules, which have test suites that are usable as modules.

Publishing a test suite as a module lets multiple modules all ensure compatibility since they use the same test suite. For example, s3-blob-store uses abstract-blob-store, and so does torrent-blob-store, bitstore-blob-store and many others.

Using this module will help to create easy to consume APIs for building custom bitcoin transactions.

API Provider Coverage

We made a quick way for developers to gauge which providers support specific parts of abstract common blockchain so they can make the decision to download the correct npm package (or maybe a combination of a couple). The score in the table is a subjective measure of which endpoints we think are slightly more important to others. If you don't agree with some of the weightings or if you are a api provider who wants us to update our wrappers to support some new functionality, send us an email.

How to use

To use the test suite from this module you can require('abstract-common-blockchain/tests/testnet') or require('abstract-common-blockchain/tests/mainnet')

An example of this can be found in the chain-unofficial test suite. There is also an example in tests/run.js in this repo.

You have to implement a setup and teardown function:

var common = {
  setup: function(t, cb) {
    // setup takes a tap/tape compatible test instance in and a callback
    // this method should construct a new commonBlockchain instance and pass it to the callback:
    var commonBlockchain = biteasyAPI({ network: 'testnet' })
    cb(null, commonBlockchain)
  },
  teardown: function(t, commonBlockchain, cb) {
    // teardown takes in the test instance, as well as the commonBlockchain instance
    else cb()
    // be sure to call cb() when you are done with teardown
  }
}

To run the tests simply pass your test module (tap or tape or any other compatible modules are supported) and your common methods in:

var abstractCommonBlockchainTests = require('abstract-common-blockchain/tests/testnet')
abstractCommonBlockchainTests(test, common)

How to build blockchain software

Create an SPV wallet with BitcoinJS, CryptoCoinJS or Bitcore to sign transactions and messages.

var bitcoin = require("bitcoinjs-lib")

var address = "n3PDRtKoHXHNt8FU17Uu9Te81AnKLa7oyU"
var privateKeyWIF = "KyjhazeX7mXpHedQsKMuGh56o3rh8hm8FGhU3H6HPqfP9pA4YeoS"

var signFromPrivateKeyWIF = function(privateKeyWIF) {
  return function(txHex, callback) {
    var tx = bitcoin.Transaction.fromHex(txHex);
    var key = bitcoin.ECKey.fromWIF(privateKeyWIF)
    tx.sign(0, key)
    callback(false, tx)
  }
};

var signRawTransaction = signFromPrivateKeyWIF(privateKeyWIF)

var signMessage = function (message, callback) {
  var key = bitcoin.ECKey.fromWIF(privateKeyWIF)
  var network = bitcoin.networks.testnet
  callback(false, bitcoin.Message.sign(key, message, network).toString('base64'))
}

var commonWallet = {
  signRawTransaction: signRawTransaction,
  signMessage: signMessage
}

Read and write data from the blockchain with a provider like Blocktrail, Blockcypher, Biteasy or various others.

Example (Biteasy)

var biteasyAPI = require('biteasy-unofficial')

var commonBlockchain = biteasyAPI({ network: 'testnet' })

commonBlockchain.Addresses.Transactions([
  "n3PDRtKoHXHNt8FU17Uu9Te81AnKLa7oyU"
], function (err, resp) {
  console.log(resp)
});

Create custom bitcoin transactions and data formats to embed in the blockchain with Blocksign, Blockcast, and Open Publish.

var openpublish = require('openpublish')

var sha1 = "dc724af18fbdd4e59189f5fe768a5f8311527050"

openpublish.register({
  sha1: sha1,
  address: address,
  commonBlockchain: commonBlockchain,
  commonWallet: commonWallet
}, function(err, receipt) {

})

API

A valid common blockchain interface should implement the following APIs. There is a public-access CORS-enabled testnet implementation hosted by Blockai available at index.js in this repo.

Be sure to check out types.json in this repo for information about inputs and ouputs of common blockchain functions.

Addresses

commonBlockchain.Addresses.Summary

Summary returns a JSON of information regarding provided Bitcoin addresses.

commonBlockchain.Addresses.Summary([
  "1HUTmSsFp9Rg4FYRftp85GGyZFEndZSoeq",
  "1DmUeGjuQWLHxq5jhyn3uPCD9N16Ar9xGw"
], function (err, resp) {
  console.log(resp);
});

commonBlockchain.Addresses.Transactions

Transactions returns a JSON with a list of transactions associated with the provided Bitcoin addresses.

commonBlockchain.Addresses.Transactions([
  "1HUTmSsFp9Rg4FYRftp85GGyZFEndZSoeq",
  "1DmUeGjuQWLHxq5jhyn3uPCD9N16Ar9xGw"
], function (err, resp) {
  console.log(resp);
});

commonBlockchain.Addresses.Unspents

Unspents returns a JSON with a list of unspent outputs for the provided Bitcoin addresses.

commonBlockchain.Addresses.Unspents([
  "1HUTmSsFp9Rg4FYRftp85GGyZFEndZSoeq",
  "1DmUeGjuQWLHxq5jhyn3uPCD9N16Ar9xGw"
], function (err, resp) {
  console.log(resp);
});

Blocks

commonBlockchain.Blocks.Get

Get returns a JSON of information for the provided block IDs.

commonBlockchain.Blocks.Get([
  "00000000000000000216a936ebc1962e319a51bab8d3eae69335ac940284491d",
  "00000000000000001034f207d3ce18f03054ddfb0e4dba712f5b76cb1cda9499"
], function (err, resp) {
  console.log(resp);
});

commonBlockchain.Blocks.Latest

Latest returns a JSON of the latest blocks to hit a commonBlockChainAPI's endpoint.

commonBlockchain.Blocks.Latest(function (err, resp) {
  console.log(resp);
});

commonBlockchain.Blocks.Propagate

Propagate takes in raw block hex and will propagate it to the common blockchain API's network (NOTE: not supported by most providers)

commonBlockchain.Blocks.Propagate(blockHex, function (err, resp) {
  console.log(resp);
});

commonBlockchain.Blocks.Transactions

Transactions returns a JSON of transactions for the provided block IDs.

commonBlockchain.Blocks.Transactions([
  "00000000000000000216a936ebc1962e319a51bab8d3eae69335ac940284491d",
  "00000000000000001034f207d3ce18f03054ddfb0e4dba712f5b76cb1cda9499"
], function (err, resp) {
  console.log(resp);
});

Transactions

commonBlockchain.Transactions.Get

Get returns a JSON with transaction data for provided transaction IDs.

commonBlockchain.Transactions.Get([
  "186efd8689fc403e5cc6faeef9497fcf177750b52afe55f407244d0c95625836",
  "9375818c85a6712416dac6edd403498180ee9ee0e604bd11ec35beaea384da51"
], function (err, resp) {
  console.log(resp);
});

commonBlockchain.Transactions.Latest

Latest returns a JSON of the latest transactions to hit a common blockchain API's endpoint.

commonBlockchain.Transactions.Latest(function (err, resp) {
  console.log(resp);
});

commonBlockchain.Transactions.Outputs

Outputs returns a JSON of output information for provided transaction IDs. NOTE: "txid" and "txId" can be used interchangebly in this context to support the union of both bitcoind and common blockchain's standards.

commonBlockchain.Transactions.Outputs([
  {
    vout: 0,
    txId: "186efd8689fc403e5cc6faeef9497fcf177750b52afe55f407244d0c95625836"
  }
], function (err, resp) {
  console.log(resp);
});

commonBlockchain.Transactions.Propagate

Propagates the transaction supplied via raw hex.

commonBlockchain.Transactions.Propagate(hex, function (err, resp) {
  console.log(resp);
});

commonBlockchain.Transactions.Status

Transactions returns a JSON of transactions for the provided transaction IDs.

commonBlockchain.Transactions.Status([
  "186efd8689fc403e5cc6faeef9497fcf177750b52afe55f407244d0c95625836",
  "9375818c85a6712416dac6edd403498180ee9ee0e604bd11ec35beaea384da51"
], function (err, resp) {
  console.log(resp);
});