diff --git a/docs/build.md b/docs/build.md index 604d11de..5de2dc79 100644 --- a/docs/build.md +++ b/docs/build.md @@ -1,4 +1,8 @@ -## Build & Install +--- +title: Build & Install +description: Build & installation instructions for Bitcore Node +--- +# Build & Install This includes a detailed instructions for compiling. There are two main parts of the build, compiling Bitcoin Core as a static library and the Node.js bindings. @@ -89,4 +93,4 @@ Once everything is built, you can run bitcore-node via: npm start ``` -This will then start the syncing process for Bitcoin Core and the extended capabilities as provided by the built-in Address Module (details below). \ No newline at end of file +This will then start the syncing process for Bitcoin Core and the extended capabilities as provided by the built-in Address Module (details below). diff --git a/docs/bus.md b/docs/bus.md index 38e3a108..c0f20d0f 100644 --- a/docs/bus.md +++ b/docs/bus.md @@ -1,3 +1,7 @@ +--- +title: Bus +description: An event emitter for node events +--- # Bus The bus provides a way to subscribe to events from any of the services running. It's implemented abstract from transport specific implementation. The primary use of the bus in Bitcore Node is for subscribing to events via a web socket. @@ -29,4 +33,3 @@ bus.subscribe('address/transaction', ['13FMwCYz3hUhwPcaWuD2M1U2KzfTtvLM89']); // unsubscribe bus.unsubscribe('transaction'); ``` - diff --git a/docs/errors.md b/docs/errors.md index eeb9b487..1f074603 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -1,3 +1,7 @@ +--- +title: Errors +description: Errors for Bitcore Node +--- # Errors Many times there are cases where an error condition can be gracefully handled depending on a particular use. To assist in better error handling, errors will have different types so that it's possible to determine the type of error and handle appropriatly. @@ -14,4 +18,4 @@ node.services.address.getUnspentOutputs('00000000839a8...', function(err, output }); ``` -For more information about different types of errors, please see `lib/errors.js`. \ No newline at end of file +For more information about different types of errors, please see `lib/errors.js`. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..65869f3f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,61 @@ +Bitcore Node +============ + +A Bitcoin full node for building applications and services with Node.js. A node is extensible and can be configured to run additional services. At the minimum a node has native bindings to Bitcoin Core with the [Bitcoin Service](services/bitcoind.md). Additional services can be enabled to make a node more useful such as exposing new APIs, adding new indexes for addresses with the [Address Service](services/address.md), running a block explorer, wallet service, and other customizations. + +## Install + +```bash +npm install -g bitcore-node@latest +bitcore-node start +``` + +Note: For your convenience, we distribute binaries for x86_64 Linux and x86_64 Mac OS X. Upon npm install, the binaries for your platform will be downloaded. For more detailed installation instructions, or if you want to compile the project yourself, then please see the [Build & Install](build.md) documentation to build the project from source. + +## Prerequisites + +- Node.js v0.12 +- ~100GB of disk storage +- ~1GB of RAM +- Mac OS X >= 10.9, Ubuntu >= 12.04 (libc >= 2.15 and libstdc++ >= 6.0.16) + +## Configuration + +Bitcore Node includes a Command Line Interface (CLI) for managing, configuring and interfacing with your Bitcore Node. + +```bash +bitcore-node create -d mynode "My Node" +cd mynode +bitcore-node add +bitcore-node add https://github.com/yourname/helloworld +``` + +This will create a directory with configuration files for your node and install the necessary dependencies. For more information about (and developing) services, please see the [Service Documentation](services.md). + +To start bitcore-node as a daemon: + +```bash +bitcore-node start --daemon +``` + +## Add-on Services + +There are several add-on services available to extend the functionality of Bitcore Node: + +- [Insight API](https://github.com/bitpay/insight-api/tree/v0.3.0) +- [Insight UI](https://github.com/bitpay/insight/tree/v0.3.0) + +## Documentation + +- [Services](services.md) + - [Bitcoind](services/bitcoind.md) - Native bindings to Bitcoin Core + - [Database](services/db.md) - The foundation API methods for getting information about blocks and transactions. + - [Address](services/address.md) - Adds additional API methods for querying and subscribing to events with bitcoin addresses. + - [Web](services/web.md) - Creates an express application over which services can expose their web/API content +- [Build & Install](build.md) - How to build and install from source +- [Testing & Development](testing.md) - Developer guide for testing +- [Node](node.md) - Details on the node constructor +- [Bus](bus.md) - Overview of the event bus constructor +- [Errors](errors.md) - Reference for error handling and types +- [Patch](patch.md) - Information about the patch applied to Bitcoin Core +- [Release Process](release.md) - Information about verifying a release and the release process. diff --git a/docs/node.md b/docs/node.md index aa7cdbd2..8c9bb583 100644 --- a/docs/node.md +++ b/docs/node.md @@ -1,3 +1,7 @@ +--- +title: Node +description: A collection of services run as node. +--- # Node A node represents a collection of services that are loaded together. For more information about services, please see the [Services Documentation](services.md). diff --git a/docs/patch.md b/docs/patch.md index ef954572..42c55151 100644 --- a/docs/patch.md +++ b/docs/patch.md @@ -1,7 +1,11 @@ +--- +title: Bitcoin Core Patch +description: Description of the patch applied to Bitcoin Core to compile as a static library +--- # Static Library Patch To provide native bindings to JavaScript *(or any other language for that matter)*, Bitcoin code, itself, must be linkable. Currently, Bitcoin Core provides a JSON RPC interface to bitcoind as well as a shared library for script validation *(and hopefully more)* called libbitcoinconsensus. There is a node module, [node-libbitcoinconsensus](https://github.com/bitpay/node-libbitcoinconsensus), that exposes these methods. While these interfaces are useful for several use cases, there are additional use cases that are not fulfilled, and being able to implement customized interfaces is necessary. To be able to do this a few simple changes need to be made to Bitcoin Core to compile as a static library. The patch is located at `etc/bitcoin.patch` and adds a configure option `--enable-daemonlib` to compile all object files with `-fPIC` (Position Independent Code - needed to create a shared object), exposes leveldb variables and objects, exposes the threadpool to the bindings, and conditionally includes the main function. -Every effort will be made to ensure that this patch stays up-to-date with the latest release of Bitcoin. At the very least, this project began supporting Bitcoin Core v0.11. \ No newline at end of file +Every effort will be made to ensure that this patch stays up-to-date with the latest release of Bitcoin. At the very least, this project began supporting Bitcoin Core v0.11. diff --git a/docs/release.md b/docs/release.md index 46a56a80..71a76986 100644 --- a/docs/release.md +++ b/docs/release.md @@ -1,3 +1,7 @@ +--- +title: Release Process +description: Description to verify releases +--- # Release Process Binaries for the C++ binding file (which includes libbitcoind statically linked in) are distributed for convenience. The binary binding file `bitcoind.node` is signed and published to S3 for later download and installation. Source files can also be built if binaries are not desired. diff --git a/docs/scaffold.md b/docs/scaffold.md index f3eccf2d..e38c0b3a 100644 --- a/docs/scaffold.md +++ b/docs/scaffold.md @@ -1,3 +1,7 @@ +--- +title: Scaffolding +description: Description of functions for Bitcore Node configuration +--- # Scaffold A collection of functions for creating, managing, starting, stopping and interacting with a Bitcore Node. @@ -29,4 +33,3 @@ This function will remove a service from a node by uninstalling the necessary de ## Call Method This function will call an API method on a node via the JSON-RPC interface. - diff --git a/docs/services.md b/docs/services.md index a4c04bb9..69dbcf19 100644 --- a/docs/services.md +++ b/docs/services.md @@ -1,11 +1,9 @@ +--- +title: Services +description: Overview of Bitcore Node services architecture. +--- # Services -## Available Services - -- [Bitcoin Daemon](services/bitcoind.md) -- [DB](services/db.md) -- [Address](services/address.md) - ## Overview Bitcore Node has a service module system that can start up additional services that can include additional: diff --git a/docs/services/address.md b/docs/services/address.md index 8e5ee824..f304dae0 100644 --- a/docs/services/address.md +++ b/docs/services/address.md @@ -1,3 +1,7 @@ +--- +title: Address Service +description: Overview of the Address Service for Bitcore Node +--- # Address Service The address service builds on the [Bitcoin Service](bitcoind.md) and the [Database Service](db.md) to add additional functionality for querying and subscribing to information based on bitcoin addresses. This will typically represent the core functionality for wallet applications. diff --git a/docs/services/bitcoind.md b/docs/services/bitcoind.md index 5ad14bff..3d1548e7 100644 --- a/docs/services/bitcoind.md +++ b/docs/services/bitcoind.md @@ -1,6 +1,10 @@ +--- +title: Bitcoin Service +description: Overview of the Bitcoin Service for Bitcore Node +--- # Bitcoin Service -The Bitcoin Service adds a native Node.js interface to Bitcoin Core for querying information about the Bitcoin blockchain. Bindings are linked to Bitcoin Core compiled as a static library. +The Bitcoin Service adds a native [Node.js](https://nodejs.org) interface to [Bitcoin Core](https://github.com/bitcoin/bitcoin) for querying information about the Bitcoin blockchain. Bindings are linked to Bitcoin Core compiled as a static library. ## API Documentation diff --git a/docs/services/db.md b/docs/services/db.md index 1d7a6201..6b36f766 100644 --- a/docs/services/db.md +++ b/docs/services/db.md @@ -1,3 +1,7 @@ +--- +title: Database Service +description: Overview of the Database Service for Bitcore Node +--- # Database Service This service synchronizes a leveldb database with the [Bitcoin Service](bitcoind.md) block chain by connecting and disconnecting blocks to build new indexes that can be queried. Other services can extend the data that is indexed by implementing a `blockHandler` method, similar to the built-in [Address Service](address.md). diff --git a/docs/services/web.md b/docs/services/web.md index 8f9bea8a..a3e3dd68 100644 --- a/docs/services/web.md +++ b/docs/services/web.md @@ -1,3 +1,7 @@ +--- +title: Web Service +description: Overview of the Web Service for Bitcore Node +--- # Web Service The web service creates an express app which can be used by services for setting up web routes for API's, static content, web applications, etc. This allows users to interact with various bitcore node services over one http or https port. diff --git a/docs/testing.md b/docs/testing.md index aba45658..e5fe36ed 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,4 +1,8 @@ -## Development & Testing +--- +title: Development & Testing +description: Notes for development and debugging Bitcore Node +--- +# Development & Testing To run all of the JavaScript tests: @@ -49,4 +53,4 @@ To run the benchmarks: ```bash $ cd benchmarks $ node index.js -``` \ No newline at end of file +``` diff --git a/lib/node.js b/lib/node.js index 37eb5751..6d3aaa83 100644 --- a/lib/node.js +++ b/lib/node.js @@ -18,11 +18,13 @@ var errors = require('./errors'); * properties that can be shared across services, such as network settings. * * The array of services should have the format: + * ```js * { * name: 'bitcoind', * config: {}, // options to pass into constructor - * module: + * module: ServiceConstructor * } + * ``` * * @param {Object} config - The configuration of the node * @param {Array} config.services - The array of services diff --git a/lib/services/address/index.js b/lib/services/address/index.js index 3ecceb2c..94851a08 100644 --- a/lib/services/address/index.js +++ b/lib/services/address/index.js @@ -22,8 +22,9 @@ var AddressHistory = require('./history'); * functionality for getting information by base58check encoded addresses. This includes getting the * balance for an address, the history for a collection of addresses, and unspent outputs for * contstructing transactions. This is typically the core functionality for building a wallet. - * @param {Node} node - An instance of the node - * @param {String} [name] - An optional name of the service + * @param {Object} options + * @param {Node} options.node - An instance of the node + * @param {String} options.name - An optional name of the service */ var AddressService = function(options) { BaseService.call(this, options); diff --git a/lib/services/bitcoind.js b/lib/services/bitcoind.js index 80920c67..51edd638 100644 --- a/lib/services/bitcoind.js +++ b/lib/services/bitcoind.js @@ -11,8 +11,8 @@ var log = index.log; var Service = require('../service'); /** - * Provides an interface to native bindings to Bitcoin Core compiled as a static library. - * The C++ bindings can be found at src/libbitcoind.cc + * Provides an interface to native bindings to [Bitcoin Core](https://github.com/bitcoin/bitcoin) + * compiled as a static library. The C++ bindings can be found at `src/libbitcoind.cc` * @param {Object} options * @param {Node} options.node - A reference to the node */