bitcoin-p2p

node-bitcoin-p2p

This is a client library for the Bitcoin P2P network, written for Node.js, using MongoDB as its back end.

Differences to official client

The official client contains the node, wallet, GUI and miner. This library only contains the node, i.e. the P2P part of Bitcoin. Its intended use is as a server component to give lighter clients access to the data in the block chain (in real-time.)

Prerequisites

Please install a development version of the libgmp library. On Debian-based systems:

sudo aptitude install libgmp3-dev

You also need to have MongoDB installed and running:

sudo aptitude install mongodb

Make sure you have the latest build of Node.js from github installed. This library uses functionality introduced in Node.js 0.5.0.

Finally, you need npm.

Installation

Installation via NPM:

npm install node-bitcoin-p2p

Installation from git:

git clone git://github.com/justmoon/node-bitcoin-p2p.git --recursive
cd node-bitcoin-p2p
npm link

Upgrading

When upgrading node-bitcoin-p2p it is a good idea to reset its database:

mongo bitcoin --eval "db.dropDatabase()"

This won't be necessary once node-bitcoin-p2p is more stable, but for now new versions often break database compatibility and since it only takes about ten minutes to regenerate it makes sense to just reset it.

Usage

Several examples on how to start up the library are provided in the examples/ folder. To run an example simply call it with node:

node examples/simple.js

The most basic way to start node-bitcoin-p2p in your own code goes like this:

var Bitcoin = require('bitcoin-p2p');

node = new Bitcoin.Node();
node.start();

All the other examples presuppose you've already started a node using this code.

Once the node is running it will automatically connect to the Bitcoin network and begin downloading blocks. There are two major ways to get information from the library: Events and Storage.

Events

Get a reference to the BlockChain object to start listening to block chain changes:

var chain = node.getBlockChain();
// Log each block as it's added to the block chain
chain.addListener('blockSave', function (e) {
    console.log(e.block);
});

BlockChain emits the following events:

blockAdd - Triggered right before a block is saved to storage

• block The Block object for the block in question
• txs The transactions attached to the block
• chain The BlockChain object

blockSave - Triggered right after a block is saved to storage

• block The Block object for the block in question
• txs The transactions attached to the block
• chain The BlockChain object

blockRevoke - Triggered as the main chain is rolled back due to a split (warning: block chain reorg is still buggy)

• block The Block object for the block in question
• txs The transactions attached to the block
• chain The BlockChain object

txAdd - Triggered right before a transaction is saved to storage

• block Containing Block object
• index The index of the transaction in question
• tx The Transaction object
• chain The BlockChain object

txSave - Triggered right after a transaction is saved to storage

• block Containing Block object
• index The index of the transaction in question
• tx The Transaction object
• chain The BlockChain object

txRevoke - Triggered when a confirmed transaction is reverted as the containing block is no longer in the main chain (warning: block chain reorg is still buggy)

• block Containing Block object
• index The index of the transaction in question
• tx The Transaction object
• chain The BlockChain object

TransactionStore emits the following events:

txNotify - A transaction was added to the memory pool

• tx The Transaction object
• store The TransactionStore object

txCancel - A transaction was removed from the memory pool (because it was confirmed or because a conflicting transaction was confirmed)

• tx The Transaction object
• txHash The transaction's hash in base64
• store The TransactionStore object

If the setting feature.liveAccounting is enabled, you can also listen to txNotify:[pubKeyHash as base64] and txCancel:[pubKeyHash as base64] to get events for a specific address only.

Storage

node-bitcoin-p2p uses the Mongoose ORM layer. You can find the schemas for the database objects in the source code under lib/schema/.

All the models are instantiated by the Storage class, so all you need to do is get a reference to that from the Bitcoin Node and you're good to go:

var storage = node.getStorage();
storage.Transaction.findOne({hash: hash}, function (err, tx) {
    // In real code, you'd handle the error of course
    if (err) return;

    storage.Block.findOne({_id: tx.block}, function (err, block) {
        if (err) return;

        // Do something fancy here...
    });
});

There are also some convenience functions you can use:

var chain = node.getBlockChain();
chain.getBlockByHash(hash, function (err, block) {
    if (err) return;

    // Do something with the Block
    console.log(block);
});

Logging

node-bitcoin-p2p logs using the winston library. Currently, it defaults to logging anything on the debug log level and higher. Here are the available log levels:

• netdbg - Networking events (sending/receiving messages)
• bchdbg - Block chain events (adding blocks)
• debug - Other verbose logging
• info - General information and status messages
• warn - Something rare happened (e.g. strange pubKeyScript)
• error - Something bad happened

If you run node-bitcoin-p2p from a compatible shell, you should get a fairly nice series of log messages as it is booting up.

Tests

To run the test, please install Vows and run the following command:

vows test/* --spec

Status

The library is currently alpha quality. Here are some things it currently lacks:

• Correct handling of block chain splits
• Verify difficulty transitions
• Accept incoming Bitcoin connections (optionally)
• Store hashes etc. as MongoDB BinData instead of base64

On top of that, it could use a lot more documentation, test cases and general bug fixing across the board.

You can find more information on the Issues tab on Github.

Credits

node-bitcoin-p2p - Node.js Bitcoin client
Copyright (c) 2011 Stefan Thomas [e-mail].

Native extensions are
Copyright (c) 2011 Andrew Schaaf [e-mail]

Parts of this software are based on BitcoinJ
Copyright (c) 2011 Google Inc.