bitcoind: update jsdocs and cleanup
This commit is contained in:
parent
88872734de
commit
4662ca0850
|
@ -15,25 +15,41 @@ var _ = bitcore.deps._;
|
||||||
|
|
||||||
var index = require('../');
|
var index = require('../');
|
||||||
var log = index.log;
|
var log = index.log;
|
||||||
var errors = index.errors;
|
|
||||||
var Service = require('../service');
|
var Service = require('../service');
|
||||||
var Transaction = require('../transaction');
|
var Transaction = require('../transaction');
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Provides an interface to native bindings to [Bitcoin Core](https://github.com/bitcoin/bitcoin)
|
* Provides a friendly event driven API to bitcoind in Node.js. Manages starting and
|
||||||
* compiled as a static library. The C++ bindings can be found at `src/libbitcoind.cc`
|
* stopping bitcoind as a child process for application support, as well as connecting
|
||||||
|
* to multiple bitcoind processes for server infrastructure. Results are cached in an
|
||||||
|
* LRU cache for improved performance and methods added for common queries.
|
||||||
|
*
|
||||||
* @param {Object} options
|
* @param {Object} options
|
||||||
* @param {Node} options.node - A reference to the node
|
* @param {Node} options.node - A reference to the node
|
||||||
*/
|
*/
|
||||||
function Bitcoin(options) {
|
function Bitcoin(options) {
|
||||||
/* jshint maxstatements: 20 */
|
|
||||||
var self = this;
|
|
||||||
if (!(this instanceof Bitcoin)) {
|
if (!(this instanceof Bitcoin)) {
|
||||||
return new Bitcoin(options);
|
return new Bitcoin(options);
|
||||||
}
|
}
|
||||||
|
|
||||||
Service.call(this, options);
|
Service.call(this, options);
|
||||||
|
this.options = options;
|
||||||
|
|
||||||
|
this._initCaches();
|
||||||
|
|
||||||
|
// bitcoind child process
|
||||||
|
this.spawn = false;
|
||||||
|
|
||||||
|
// available bitcoind nodes
|
||||||
|
this._initClients();
|
||||||
|
}
|
||||||
|
util.inherits(Bitcoin, Service);
|
||||||
|
|
||||||
|
Bitcoin.dependencies = [];
|
||||||
|
|
||||||
|
Bitcoin.DEFAULT_CONFIG = 'whitelist=127.0.0.1\n' + 'txindex=1\n' + 'addressindex=1\n' + 'server=1\n';
|
||||||
|
|
||||||
|
Bitcoin.prototype._initCaches = function() {
|
||||||
// caches valid until there is a new block
|
// caches valid until there is a new block
|
||||||
this.utxosCache = LRU(50000);
|
this.utxosCache = LRU(50000);
|
||||||
this.txidsCache = LRU(50000);
|
this.txidsCache = LRU(50000);
|
||||||
|
@ -49,13 +65,10 @@ function Bitcoin(options) {
|
||||||
this.zmqKnownTransactions = LRU(50);
|
this.zmqKnownTransactions = LRU(50);
|
||||||
this.zmqLastBlock = 0;
|
this.zmqLastBlock = 0;
|
||||||
this.zmqUpdateTipTimeout = false;
|
this.zmqUpdateTipTimeout = false;
|
||||||
|
};
|
||||||
|
|
||||||
this.options = options;
|
Bitcoin.prototype._initClients = function() {
|
||||||
|
var self = this;
|
||||||
// bitcoind child process
|
|
||||||
this.spawn = false;
|
|
||||||
|
|
||||||
// available bitcoind nodes
|
|
||||||
this.nodes = [];
|
this.nodes = [];
|
||||||
this.nodesIndex = 0;
|
this.nodesIndex = 0;
|
||||||
Object.defineProperty(this, 'client', {
|
Object.defineProperty(this, 'client', {
|
||||||
|
@ -67,13 +80,7 @@ function Bitcoin(options) {
|
||||||
enumerable: true,
|
enumerable: true,
|
||||||
configurable: false
|
configurable: false
|
||||||
});
|
});
|
||||||
|
};
|
||||||
}
|
|
||||||
util.inherits(Bitcoin, Service);
|
|
||||||
|
|
||||||
Bitcoin.dependencies = [];
|
|
||||||
|
|
||||||
Bitcoin.DEFAULT_CONFIG = 'whitelist=127.0.0.1\n' + 'txindex=1\n' + 'addressindex=1\n' + 'server=1\n';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Called by Node to determine the available API methods.
|
* Called by Node to determine the available API methods.
|
||||||
|
@ -507,7 +514,6 @@ Bitcoin.prototype.start = function(callback) {
|
||||||
/**
|
/**
|
||||||
* Helper to determine the state of the database.
|
* Helper to determine the state of the database.
|
||||||
* @param {Function} callback
|
* @param {Function} callback
|
||||||
* @returns {Boolean} If the database is fully synced
|
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.isSynced = function(callback) {
|
Bitcoin.prototype.isSynced = function(callback) {
|
||||||
this.syncPercentage(function(err, percentage) {
|
this.syncPercentage(function(err, percentage) {
|
||||||
|
@ -525,7 +531,6 @@ Bitcoin.prototype.isSynced = function(callback) {
|
||||||
/**
|
/**
|
||||||
* Helper to determine the progress of the database.
|
* Helper to determine the progress of the database.
|
||||||
* @param {Function} callback
|
* @param {Function} callback
|
||||||
* @returns {Number} An estimated percentage of the syncronization status
|
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.syncPercentage = function(callback) {
|
Bitcoin.prototype.syncPercentage = function(callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
|
@ -538,6 +543,12 @@ Bitcoin.prototype.syncPercentage = function(callback) {
|
||||||
});
|
});
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Will get the balance for an address or multiple addresses
|
||||||
|
* @param {String|Address|Array} addressArg - An address string, bitcore address, or array of addresses
|
||||||
|
* @param {Object} options
|
||||||
|
* @param {Function} callback
|
||||||
|
*/
|
||||||
Bitcoin.prototype.getAddressBalance = function(addressArg, options, callback) {
|
Bitcoin.prototype.getAddressBalance = function(addressArg, options, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
var addresses = [addressArg];
|
var addresses = [addressArg];
|
||||||
|
@ -561,6 +572,12 @@ Bitcoin.prototype.getAddressBalance = function(addressArg, options, callback) {
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Will get the unspent outputs for an address or multiple addresses
|
||||||
|
* @param {String|Address|Array} addressArg - An address string, bitcore address, or array of addresses
|
||||||
|
* @param {Object} options
|
||||||
|
* @param {Function} callback
|
||||||
|
*/
|
||||||
Bitcoin.prototype.getAddressUnspentOutputs = function(addressArg, options, callback) {
|
Bitcoin.prototype.getAddressUnspentOutputs = function(addressArg, options, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
var addresses = [addressArg];
|
var addresses = [addressArg];
|
||||||
|
@ -605,6 +622,12 @@ Bitcoin.prototype._getTxidsFromMempool = function(deltas) {
|
||||||
return mempoolTxids;
|
return mempoolTxids;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Will get the txids for an address or multiple addresses
|
||||||
|
* @param {String|Address|Array} addressArg - An address string, bitcore address, or array of addresses
|
||||||
|
* @param {Object} options
|
||||||
|
* @param {Function} callback
|
||||||
|
*/
|
||||||
Bitcoin.prototype.getAddressTxids = function(addressArg, options, callback) {
|
Bitcoin.prototype.getAddressTxids = function(addressArg, options, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
var queryMempool = _.isUndefined(options.queryMempool) ? true : options.queryMempool;
|
var queryMempool = _.isUndefined(options.queryMempool) ? true : options.queryMempool;
|
||||||
|
@ -776,6 +799,12 @@ Bitcoin.prototype._paginateTxids = function(fullTxids, from, to) {
|
||||||
return txids;
|
return txids;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Will detailed transaction history for an address or multiple addresses
|
||||||
|
* @param {String|Address|Array} addressArg - An address string, bitcore address, or array of addresses
|
||||||
|
* @param {Object} options
|
||||||
|
* @param {Function} callback
|
||||||
|
*/
|
||||||
Bitcoin.prototype.getAddressHistory = function(addressArg, options, callback) {
|
Bitcoin.prototype.getAddressHistory = function(addressArg, options, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
var addresses = [addressArg];
|
var addresses = [addressArg];
|
||||||
|
@ -818,6 +847,12 @@ Bitcoin.prototype.getAddressHistory = function(addressArg, options, callback) {
|
||||||
});
|
});
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Will get the summary including txids and balance for an address or multiple addresses
|
||||||
|
* @param {String|Address|Array} addressArg - An address string, bitcore address, or array of addresses
|
||||||
|
* @param {Object} options
|
||||||
|
* @param {Function} callback
|
||||||
|
*/
|
||||||
Bitcoin.prototype.getAddressSummary = function(addressArg, options, callback) {
|
Bitcoin.prototype.getAddressSummary = function(addressArg, options, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
var summary = {};
|
var summary = {};
|
||||||
|
@ -896,8 +931,9 @@ Bitcoin.prototype.getAddressSummary = function(addressArg, options, callback) {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Will retrieve a block as a Node.js Buffer from disk.
|
* Will retrieve a block as a Bitcore object
|
||||||
* @param {String|Number} block - A block hash or block height number
|
* @param {String|Number} block - A block hash or block height number
|
||||||
|
* @param {Function} callback
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.getBlock = function(blockArg, callback) {
|
Bitcoin.prototype.getBlock = function(blockArg, callback) {
|
||||||
// TODO apply performance patch to the RPC method for raw data
|
// TODO apply performance patch to the RPC method for raw data
|
||||||
|
@ -935,6 +971,12 @@ Bitcoin.prototype.getBlock = function(blockArg, callback) {
|
||||||
|
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Will retrieve an array of block hashes within a range of timestamps
|
||||||
|
* @param {Number} high - The more recent timestamp in seconds
|
||||||
|
* @param {Number} low - The older timestamp in seconds
|
||||||
|
* @param {Function} callback
|
||||||
|
*/
|
||||||
Bitcoin.prototype.getBlockHashesByTimestamp = function(high, low, callback) {
|
Bitcoin.prototype.getBlockHashesByTimestamp = function(high, low, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
self.client.getBlockHashes(high, low, function(err, response) {
|
self.client.getBlockHashes(high, low, function(err, response) {
|
||||||
|
@ -955,7 +997,7 @@ Bitcoin.prototype.getBlockHashesByTimestamp = function(high, low, callback) {
|
||||||
* height: 10
|
* height: 10
|
||||||
* }
|
* }
|
||||||
* @param {String|Number} block - A block hash or block height
|
* @param {String|Number} block - A block hash or block height
|
||||||
* @returns {Object}
|
* @param {Function} callback
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.getBlockHeader = function(block, callback) {
|
Bitcoin.prototype.getBlockHeader = function(block, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
|
@ -990,7 +1032,7 @@ Bitcoin.prototype.getBlockHeader = function(block, callback) {
|
||||||
/**
|
/**
|
||||||
* Will estimate the fee per kilobyte.
|
* Will estimate the fee per kilobyte.
|
||||||
* @param {Number} blocks - The number of blocks for the transaction to be confirmed.
|
* @param {Number} blocks - The number of blocks for the transaction to be confirmed.
|
||||||
* @returns {Number}
|
* @param {Function} callback
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.estimateFee = function(blocks, callback) {
|
Bitcoin.prototype.estimateFee = function(blocks, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
|
@ -1003,10 +1045,10 @@ Bitcoin.prototype.estimateFee = function(blocks, callback) {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Will add a transaction to the mempool and relay to connected peers, the function
|
* Will add a transaction to the mempool and relay to connected peers
|
||||||
* will throw an error if there were validation problems.
|
* @param {String|Transaction} transaction - The hex string of the transaction
|
||||||
* @param {String} transaction - The hex string of the transaction
|
* @param {Boolean=} allowAbsurdFees - Enable large fees
|
||||||
* @param {Boolean} allowAbsurdFees - Enable large fees
|
* @param {Function} callback
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.sendTransaction = function(tx, allowAbsurdFees, callback) {
|
Bitcoin.prototype.sendTransaction = function(tx, allowAbsurdFees, callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
|
@ -1031,7 +1073,7 @@ Bitcoin.prototype.sendTransaction = function(tx, allowAbsurdFees, callback) {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Will get a transaction as a Node.js Buffer from disk and the mempool.
|
* Will get a transaction as a Bitcore Transaction. Results include the mempool.
|
||||||
* @param {String} txid - The transaction hash
|
* @param {String} txid - The transaction hash
|
||||||
* @param {Boolean} queryMempool - Include the mempool
|
* @param {Boolean} queryMempool - Include the mempool
|
||||||
* @param {Function} callback
|
* @param {Function} callback
|
||||||
|
@ -1059,12 +1101,11 @@ Bitcoin.prototype.getTransaction = function(txid, queryMempool, callback) {
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Will get a transaction with additional information about the block, in the format:
|
* Will get a transaction as Bitcore Transaction with additional fields:
|
||||||
* {
|
* {
|
||||||
* blockHash: '2725743288feae6bdaa976590af7cb12d7b535b5a242787de6d2789c73682ed1',
|
* __blockHash: '2725743288feae6bdaa976590af7cb12d7b535b5a242787de6d2789c73682ed1',
|
||||||
* height: 48,
|
* __height: 48,
|
||||||
* timestamp: 1442951110, // in seconds
|
* __timestamp: 1442951110, // in seconds
|
||||||
* buffer: <Buffer...> // transaction buffer
|
|
||||||
* }
|
* }
|
||||||
* @param {String} txid - The transaction hash
|
* @param {String} txid - The transaction hash
|
||||||
* @param {Boolean} queryMempool - Include the mempool
|
* @param {Boolean} queryMempool - Include the mempool
|
||||||
|
@ -1100,7 +1141,7 @@ Bitcoin.prototype.getTransactionWithBlockInfo = function(txid, queryMempool, cal
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Will get the best block hash for the chain.
|
* Will get the best block hash for the chain.
|
||||||
* @returns {String}
|
* @param {Function} callback
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.getBestBlockHash = function(callback) {
|
Bitcoin.prototype.getBestBlockHash = function(callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
|
@ -1127,9 +1168,11 @@ Bitcoin.prototype.getInputForOutput = function(txid, index, options, callback) {
|
||||||
* connections: 0,
|
* connections: 0,
|
||||||
* difficulty: 4.6565423739069247e-10,
|
* difficulty: 4.6565423739069247e-10,
|
||||||
* testnet: false,
|
* testnet: false,
|
||||||
|
* network: 'testnet'
|
||||||
* relayfee: 1000,
|
* relayfee: 1000,
|
||||||
* errors: ''
|
* errors: ''
|
||||||
* }
|
* }
|
||||||
|
* @param {Function} callback
|
||||||
*/
|
*/
|
||||||
Bitcoin.prototype.getInfo = function(callback) {
|
Bitcoin.prototype.getInfo = function(callback) {
|
||||||
var self = this;
|
var self = this;
|
||||||
|
|
Loading…
Reference in New Issue