Skip to content

Latest commit

 

History

History
333 lines (267 loc) · 9.58 KB

bitcoind.md

File metadata and controls

333 lines (267 loc) · 9.58 KB
Raw

Bitcoin Service

The Bitcoin Service is a Node.js interface to Bitcoin Core for querying information about the bitcoin block chain. It will manage starting and stopping bitcoind or connect to several running bitcoind processes. It uses a branch of a branch of Bitcoin Core with additional indexes for querying information about addresses and blocks. Results are cached for performance and there are several additional API methods added for common queries.

Configuration

The default configuration will include a "spawn" configuration in "bitcoind". This defines the location of the block chain database and the location of the bitcoind daemon executable. The below configuration points to a local clone of bitcoin, and will start bitcoind automatically with your Node.js application.

  "servicesConfig": {
    "bitcoind": {
      "spawn": {
        "datadir": "/home/bitcore/.bitcoin",
        "exec": "/home/bitcore/bitcoin/src/bitcoind"
      }
    }
  }

It's also possible to connect to separately managed bitcoind processes with round-robin quering, for example:

  "servicesConfig": {
    "bitcoind": {
      "connect": [
        {
          "rpchost": "127.0.0.1",
          "rpcport": 30521,
          "rpcuser": "bitcoin",
          "rpcpassword": "local321",
          "zmqpubrawtx": "tcp://127.0.0.1:30611"
        },
        {
          "rpchost": "127.0.0.1",
          "rpcport": 30522,
          "rpcuser": "bitcoin",
          "rpcpassword": "local321",
          "zmqpubrawtx": "tcp://127.0.0.1:30622"
        },
        {
          "rpchost": "127.0.0.1",
          "rpcport": 30523,
          "rpcuser": "bitcoin",
          "rpcpassword": "local321",
          "zmqpubrawtx": "tcp://127.0.0.1:30633"
        }
      ]
    }
  }

Note: For detailed example configuration see regtest/cluster.js

API Documentation

Methods are available by directly interfacing with the service:

node.services.bitcoind.<methodName>

Chain

Getting Latest Blocks

// gives the block hashes sorted from low to high within a range of timestamps
var high = 1460393372; // Mon Apr 11 2016 12:49:25 GMT-0400 (EDT)
var low = 1460306965; // Mon Apr 10 2016 12:49:25 GMT-0400 (EDT)
node.services.bitcoind.getBlockHashesByTimestamp(high, low, function(err, blockHashes) {
  //...
});

// get the current tip of the chain
node.services.bitcoind.getBestBlockHash(function(err, blockHash) {
  //...
})

Getting Synchronization and Node Status

// gives a boolean if the daemon is fully synced (not the initial block download)
node.services.bitcoind.isSynced(function(err, synced) {
  //...
})

// gives the current estimate of blockchain download as a percentage
node.services.bitcoind.syncPercentage(function(err, percent) {
  //...
});

// gives information about the chain including total number of blocks
node.services.bitcoind.getInfo(function(err, info) {
  //...
});

Generate Blocks

// will generate a block for the "regtest" network (development purposes)
var numberOfBlocks = 10;
node.services.bitcoind.generateBlock(numberOfBlocks, function(err, blockHashes) {
  //...
});

Blocks and Transactions

Getting Block Information

It's possible to query blocks by both block hash and by height. Blocks are given as Node.js Buffers and can be parsed via Bitcore:

var blockHeight = 0;
node.services.bitcoind.getRawBlock(blockHeight, function(err, blockBuffer) {
  if (err) {
    throw err;
  }
  var block = bitcore.Block.fromBuffer(blockBuffer);
  console.log(block);
};

// get a bitcore object of the block (as above)
node.services.bitcoind.getBlock(blockHash, function(err, block) {
  //...
};

// get only the block header and index (including chain work, height, and previous hash)
node.services.bitcoind.getBlockHeader(blockHeight, function(err, blockHeader) {
  //...
});

// get the block with a list of txids
node.services.bitcoind.getBlockOverview(blockHash, function(err, blockOverview) {
  //...
};

Retrieving and Sending Transactions

Get a transaction asynchronously by reading it from disk:

var txid = '7426c707d0e9705bdd8158e60983e37d0f5d63529086d6672b07d9238d5aa623';
node.services.bitcoind.getRawTransaction(txid, function(err, transactionBuffer) {
  if (err) {
    throw err;
  }
  var transaction = bitcore.Transaction().fromBuffer(transactionBuffer);
});

// get a bitcore object of the transaction (as above)
node.services.bitcoind.getTransaction(txid, function(err, transaction) {
  //...
});

// retrieve the transaction with input values, fees, spent and block info
node.services.bitcoind.getDetailedTransaction(txid, function(err, transaction) {
  //...
});

Send a transaction to the network:

var numberOfBlocks = 3;
node.services.bitcoind.estimateFee(numberOfBlocks, function(err, feesPerKilobyte) {
  //...
});

node.services.bitcoind.sendTransaction(transaction.serialize(), function(err, hash) {
  //...
});

Addresses

Get Unspent Outputs

One of the most common uses will be to retrieve unspent outputs necessary to create a transaction, here is how to get the unspent outputs for an address:

var address = 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW';
node.services.bitcoind.getAddressUnspentOutputs(address, options, function(err, unspentOutputs) {
  // see below
});

The unspentOutputs will have the format:

[
  {
    address: 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW',
    txid: '9d956c5d324a1c2b12133f3242deff264a9b9f61be701311373998681b8c1769',
    outputIndex: 1,
    height: 150,
    satoshis: 1000000000,
    script: '76a9140b2f0a0c31bfe0406b0ccc1381fdbe311946dadc88ac',
    confirmations: 3
  }
]

View Balances

var address = 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW';
node.services.bitcoind.getAddressBalance(address, options, function(err, balance) {
  // balance will be in satoshis with "received" and "balance"
});

View Address History

This method will give history of an address limited by a range of block heights by using the "start" and "end" arguments. The "start" value is the more recent, and greater, block height. The "end" value is the older, and lesser, block height. This feature is most useful for synchronization as previous history can be omitted. Furthermore for large ranges of block heights, results can be paginated by using the "from" and "to" arguments.

If "queryMempool" is set as true (it is true by default), it will show unconfirmed transactions from the bitcoin mempool. However, if you specify "start" and "end", "queryMempool" is ignored and is always false.

If "queryMempoolOnly" is set as true (it is false by default), it will show only unconfirmed transactions from mempool.

var addresses = ['mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW'];
var options = {
  start: 345000,
  end: 344000,
  queryMempool: true // since we presented range, queryMempool will be ignored
};
node.services.bitcoind.getAddressHistory(addresses, options, function(err, history) {
  // see below
});

The history format will be:

{
  totalCount: 1, // The total number of items within "start" and "end"
  items: [
    {
      addresses: {
        'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW': {
          inputIndexes: [],
          outputIndexes: [0]
        }
      },
      satoshis: 1000000000,
      tx: <detailed_transaction> // the same format as getDetailedTransaction
    }
  ]
}

View Address Summary

var address = 'mgY65WSfEmsyYaYPQaXhmXMeBhwp4EcsQW';
var options = {
  noTxList: false
};

node.services.bitcoind.getAddressSummary(address, options, function(err, summary) {
  // see below
});

The summary will have the format (values are in satoshis):

{
  totalReceived: 1000000000,
  totalSpent: 0,
  balance: 1000000000,
  unconfirmedBalance: 1000000000,
  appearances: 1,
  unconfirmedAppearances: 0,
  txids: [
    '3f7d13efe12e82f873f4d41f7e63bb64708fc4c942eb8c6822fa5bd7606adb00'
  ]
}

Notes:

  • totalReceived does not exclude change (the amount of satoshis originating from the same address)
  • unconfirmedBalance is the delta that the unconfirmed transactions have on the total balance (can be both positive and negative)
  • unconfirmedAppearances is the total number of unconfirmed transactions
  • appearances is the total confirmed transactions
  • txids Are sorted in block order with the most recent at the beginning. A maximum of 1000 (default) will be returned, the from and to options can be used to get further values.

Events

The Bitcoin Service exposes two events via the Bus, and there are a few events that can be directly registered:

node.services.bitcoind.on('tip', function(blockHash) {
  // a new block tip has been added, if there is a rapid update (with a second) this will not emit every tip update
});

node.services.bitcoind.on('tx', function(transactionBuffer) {
  // a new transaction has entered the mempool
});

node.services.bitcoind.on('block', function(blockHash) {
  // a new block has been added
});

For details on instantiating a bus for a node, see the Bus Documentation.

  • Name: bitcoind/rawtransaction
  • Name: bitcoind/hashblock
  • Name: bitcoind/addresstxid, Arguments: [address, address...]

Examples:

bus.subscribe('bitcoind/rawtransaction');
bus.subscribe('bitcoind/hashblock');
bus.subscribe('bitcoind/addresstxid', ['13FMwCYz3hUhwPcaWuD2M1U2KzfTtvLM89']);

bus.on('bitcoind/rawtransaction', function(transactionHex) {
  //...
});

bus.on('bitcoind/hashblock', function(blockhashHex) {
  //...
});

bus.on('bitcoind/addresstxid', function(data) {
  // data.address;
  // data.txid;
});