Home

Awesome

blockchain-download

npm version Build Status Dependency Status

Download blockchain data from peers

Usage

npm install blockchain-download

blockchain-download provides streams which simplify downloading blockchain data (headers, full blocks, filtered blocks, or transactions) from network peers. Peers are provided by the bitcoin-net module.

HeaderStream

HeaderStream is used for syncing blockchain state with a module like blockchain-spv. It will download existing blocks from peers when doing an initial sync, and also outputs newly mined blocks relayed by the network.

Example sync:

var PeerGroup = require('bitcoin-net').PeerGroup
var HeaderStream = require('blockchain-download').HeaderStream
var Blockchain = require('blockchain-spv')
var params = require('webcoin-bitcoin-testnet')

// connect to P2P network
var peers = new PeerGroup(params.net)
peers.connect()

// create/load Blockchain
var db = levelup('bitcoin.chain', { db: require('memdown') })
var chain = new Blockchain(params.blockchain, db)

chain.createLocatorStream() // locators tell us which headers to fetch
  .pipe(HeaderStream(peers)) // pipe locators into new HeaderStream
  .pipe(chain.createWriteStream()) // pipe headers into Blockchain

This example will download block headers and add them to our Blockchain, which will verify them and save them to its database.

new HeaderStream(peers, [opts])

HeaderStream is a Transform stream. Its input should be "locators", which are arrays of block hashes (as Buffers), descending in height, which specify which blocks to download. For more info about locators, see the bitcoin wiki. Its output will be Arrays of BitcoinJS Block objects.

peers should be a bitcoin-net PeerGroup or Peer instance that the headers will be downloaded from.

opts may contain:

BlockStream

BlockStream is used to download full blocks or Bloom-filtered blocks, including transaction data.

Example blockchain scan:

var PeerGroup = require('bitcoin-net').PeerGroup
var BlockStream = require('blockchain-download').BlockStream
var Blockchain = require('blockchain-spv')
var params = require('webcoin-bitcoin-testnet')

// connect to P2P network
var peers = new PeerGroup(params.net)
peers.connect()

// create/load Blockchain
var db = levelup('bitcoin.chain', { db: require('memdown') })
var chain = new Blockchain(params.blockchain, db)

var blocks = new BlockStream(peers)
blocks.on('data', function (block) {
  console.log('got block:', block.height)
  for (var i = 0; i < block.transactions.length; i++) {
    // do something with transaction
  }
})
chain.createReadStream().pipe(blocks)

In this example, we first call chain.createReadStream() which will output the headers already stored in our Blockchain. Then we pipe the output to a BlockStream, which will fetch the complete data for each block. We can then do something with this output, such as checking if transactions are relevant to us (e.g. it was sent to our address).

new BlockStream(peers, [opts])

BlockStream is a Transform stream.

The stream input should be block objects which have a header property, which is a BitcoinJS Block.

The output will be objects containing the following properties (in addition to the properties of the input objects):

Full blocks (opts.filtered = false):

{
  transactions: [
    ... // BitcoinJS transaction objects
  ]
}

Merkle blocks (opts.filtered = true):

{
  transactions: [
    {}, // BitcoinJS transaction objects
    ...
  ],
  numTransactions: Number,
  hashes: [
    Buffer, // 32 bytes
    ...
  ],
  flags: Buffer // varying length
}

peers should be a bitcoin-net PeerGroup or Peer instance that the blocks will be downloaded from.

opts may contain: