RanchiMall/flocore-p2p
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #5 from eordano/docs/improve

Browse Source 
Improved jsdocs and documentation
This commit is contained in:
Yemel Jardi 2015-01-20 11:35:51 -03:00
commit 7416ea6d97
8 changed files with 178 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -2,12 +2,8 @@
coverage
node_modules
lib/errors/index.js
npm-debug.log
bitcore-p2p.js
bitcore-p2p.min.js
tests.js
bower_components
report
.DS_Store

50
docs/messages.md Normal file
View File

@ -0,0 +1,50 @@
title: Messages
description: A superclass for the messages of the bitcoin network
---
# Messages
The bitcoin protocol specifies a set of [messages](https://en.bitcoin.it/wiki/Protocol_specification) that can be sent from peer to peer. `bitcore-p2p` provides support for some of these messages.
## List of Messages
### Version
The version message (`ver`) is used on connection creation, to advertise the type of node. The remote node will respond with its version, and no communication is possible until both peers have exchanged their versions. By default, bitcore advertises itself as named `bitcore` with the current version of the `bitcore-p2p` package.
### VerAck
Finishes the connection handshake started by the `ver` message.
### Inventory
From the bitcoin protocol spec: "Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to getblocks.".
### GetData
From the bitcoin protocol spec: `getdata` is used in response to `inv`, to retrieve the content of a specific object, and is usually sent after receiving an `inv` packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).
GetData inherits from Inventory, as they both have the same structure.
### Ping
Sent to another peer mainly to check the connection is still alive.
### Pong
Sent in response to a `ping` message.
### Address and GetAddresses
Provides information on known nodes of the network. `GetAddresses` is used to query another peer for known addresses.
### GetHeaders and Headers
`getheaders` allows a peer to query another about blockheaders. `headers` is sent in response to a `getheaders` message, containing information about block headers.
### GetBlocks and Block
Same as `getheaders` and `headers`, but the response comes one block at the time.
### Transaction
Message that contains a transaction.

8
lib/errors.js Normal file
View File

@ -0,0 +1,8 @@
'use strict';
var spec = {
name: 'P2P',
message: 'Internal Error on bitcore-p2p Module {0}'
};
module.exports = require('bitcore').errors.extend(spec);

47
lib/errors/build.js
View File

@ -1,47 +0,0 @@
'use strict';
var _ = require('lodash');
var fs = require('fs');
var defineElement = function(fullName, baseClass, message) {
return fullName + ' = function() {\n' +
' this.message = ' + message + ';\n' +
' this.stack = this.message + \'\\n\' + (new Error()).stack;\n' +
'};\n' +
fullName + '.prototype = Object.create(' + baseClass + '.prototype);\n' +
fullName + '.prototype.name = "' + fullName + '";\n\n';
};
var traverseNode = function(baseClass, errorDefinition) {
var className = baseClass + '.' + errorDefinition.name;
var generated = defineElement(className, baseClass, errorDefinition.message);
if (errorDefinition.errors) {
generated += childDefinitions(className, errorDefinition.errors);
}
return generated;
};
/* jshint latedef: false */
var childDefinitions = function(parent, childDefinitions) {
var generated = '';
_.each(childDefinitions, function(childDefinition) {
generated += traverseNode(parent, childDefinition);
});
return generated;
};
/* jshint latedef: true */
var traverseRoot = function(errorsDefinition) {
var fullName = 'bitcore.errors';
var generated = '\'use strict\';\n\n';
generated += '/* jshint maxlen: 300 */\n';
generated += '/* jshint quotmark: false */\n';
generated += '/* AUTOGENERATED FILE. DON\'T EDIT, MODIFY "lib/errors/spec.js" INSTEAD */\n\n';
generated += 'var bitcore = require(\'bitcore\');\n\n';
generated += childDefinitions(fullName, errorsDefinition);
generated += 'module.exports = bitcore.errors;\n';
return generated;
};
var data = require('./spec');
fs.writeFileSync(__dirname + '/index.js', traverseRoot(data));

13
lib/errors/spec.js
View File

@ -1,13 +0,0 @@
'use strict';
function format(arg) {
return '\'' + arg
.replace('{0}', '\' + arguments[0] + \'')
.replace('{1}', '\' + arguments[1] + \'')
.replace('{2}', '\' + arguments[2] + \'') + '\'';
}
module.exports = [{
name: 'P2P',
message: format('Internal Error on bitcore-p2p Module {0}')
}];

136
lib/messages.js
View File

@ -61,7 +61,7 @@ var parseMessage = function(network, dataBuffer) {
module.exports.parseMessage = parseMessage;
/**
* @desc Internal function that discards data until founds the next message.
* @desc Internal function that discards data until another message is found.
* @name P2P.Message#discardUntilNextMessage
*/
function discardUntilNextMessage(network, dataBuffer) {
@ -162,29 +162,66 @@ Message.prototype.serialize = function(network) {
module.exports.Message = Message;
/**
* Version Message
* The version message(`ver`) is used on connection creation, to advertise
* the type of node.The remote node will respond with its version, and no
* communication is possible until both peers have exchanged their versions.
* By default, bitcore advertises itself as named `bitcore:0.8`.
*
* @name P2P.Message.Version
* @param{string} subversion - version of the client
* @param{Buffer} nonce - a random 8 bytes buffer
*/
function Version(subversion, nonce) {
var packageInfo = require('../package.json');
this.command = 'version';
this.version = PROTOCOL_VERSION;
this.subversion = subversion || '/BitcoinX:0.1/';
this.subversion = subversion || '/bitcore:' + packageInfo.version + '/';
this.nonce = nonce || CONNECTION_NONCE;
}
util.inherits(Version, Message);
Version.prototype.fromBuffer = function(payload) {
var parser = new BufferReader(payload);
/**
* @type {number}
* @desc The version of the bitcoin protocol
*/
this.version = parser.readUInt32LE();
/**
* @type {BN}
* @desc A mapbit with service bits: what features are supported by the peer
*/
this.services = parser.readUInt64LEBN();
/**
* @type {BN}
* @desc The time this message was sent
*/
this.timestamp = parser.readUInt64LEBN();
/**
* @type {Buffer}
* @desc IPv4/6 address of the interface used to connect to this peer
*/
this.addr_me = parser.read(26);
/**
* @type {Buffer}
* @desc IPv4/6 address of the peer
*/
this.addr_you = parser.read(26);
/**
* @type {Buffer}
* @desc A random number
*/
this.nonce = parser.read(8);
/**
* @desc A random number
* @type {string}
*/
this.subversion = parser.readVarintBuf().toString();
/**
* @desc The height of the last block accepted in the blockchain by this peer
* @type {number}
*/
this.start_height = parser.readUInt32LE();
return this;
@ -208,13 +245,20 @@ Version.prototype.getPayload = function() {
module.exports.Version = Message.COMMANDS.version = Version;
/**
* Inv Message
* From the bitcoin protocol spec: "Allows a node to advertise its knowledge of
* one or more objects. It can be received unsolicited, or in reply to
* getblocks.".
*
* @name P2P.Message.Inventory
* @param{Array} inventory - reported elements
*/
function Inventory(inventory) {
this.command = 'inv';
/**
* @name P2P.Message.Inventory.inventory
* @desc An array of objects with `{type: int, hash: buffer}` signature
* @type {Array.Buffer}
*/
this.inventory = inventory || [];
}
util.inherits(Inventory, Message);
@ -247,7 +291,14 @@ Inventory.prototype.getPayload = function() {
module.exports.Inventory = Message.COMMANDS.inv = Inventory;
/**
* Getdata Message
* getdata is used in response to inv, to retrieve the content of a specific
* object, and is usually sent after receiving an inv packet, after filtering
* known elements. It can be used to retrieve transactions, but only if they
* are in the memory pool or relay set - arbitrary access to transactions in the
* chain is not allowed to avoid having clients start to depend on nodes having
* full transaction indexes (which modern nodes do not).
*
* (taken from bitcoin's protocol spec)
*
* @name P2P.Message.GetData
* @param{Array} inventory - requested elements
@ -261,13 +312,17 @@ util.inherits(GetData, Inventory);
module.exports.GetData = GetData;
/**
* Ping Message
* Sent to another peer mainly to check the connection is still alive.
*
* @name P2P.Message.Ping
* @param{Buffer} nonce - a random 8 bytes buffer
*/
function Ping(nonce) {
this.command = 'ping';
/**
* @desc A random number that should be returned by the peer in a pong message
* @type {number}
*/
this.nonce = nonce || CONNECTION_NONCE;
}
util.inherits(Ping, Message);
@ -284,13 +339,17 @@ Ping.prototype.getPayload = function() {
module.exports.Ping = Message.COMMANDS.ping = Ping;
/**
* Pong Message
* Sent in response to a Ping message
*
* @name P2P.Message.Pong
* @param{Buffer} nonce - a random 8 bytes buffer
*/
function Pong(nonce) {
this.command = 'pong';
/**
* @desc A random number that must match the one sent in the corresponding `ping` message
* @type {number}
*/
this.nonce = nonce || CONNECTION_NONCE;
}
@ -298,13 +357,17 @@ util.inherits(Pong, Ping);
module.exports.Pong = Message.COMMANDS.pong = Pong;
/**
* Addr Message
* Message used to notify about known addresses.
*
* @name P2P.Message.Addressess
* @param{Array} addresses - array of know addresses
*/
function Addresses(addresses) {
this.command = 'addr';
/**
* @type {Array.Buffer}
* @desc An array of ipv4/6 addresses
*/
this.addresses = addresses || [];
}
util.inherits(Addresses, Message);
@ -364,7 +427,7 @@ Addresses.prototype.getPayload = function() {
module.exports.Addresses = Message.COMMANDS.addr = Addresses;
/**
* GetAddr Message
* Query another node for known IPV4/6 addresses.
*
* @name P2P.Message.GetAddresses
*/
@ -376,7 +439,7 @@ util.inherits(GetAddresses, Message);
module.exports.GetAddresses = Message.COMMANDS.getaddr = GetAddresses;
/**
* Verack Message
* Finishes the connection handshake started by the `ver` message.
*
* @name P2P.Message.VerAck
*/
@ -388,7 +451,8 @@ util.inherits(VerAck, Message);
module.exports.VerAck = Message.COMMANDS.verack = VerAck;
/**
* Reject Message
* A reject message should be sent when a message is not supported or
* interpreted as invalid.
*
* @name P2P.Message.Reject
*/
@ -402,7 +466,7 @@ util.inherits(Reject, Message);
module.exports.Reject = Message.COMMANDS.reject = Reject;
/**
* Alert Message
* Used to send a message signed by a developer of the bitcoin project.
*
* @name P2P.Message.Alert
*/
@ -434,13 +498,18 @@ Alert.prototype.getPayload = function() {
module.exports.Alert = Message.COMMANDS.alert = Alert;
/**
* Headers Message
* Sent in response to a `getheaders` message. It contains information about
* block headers.
*
* @name P2P.Message.Headers
* @param{Array} blockheaders - array of block headers
*/
function Headers(blockheaders) {
this.command = 'headers';
/**
* @type {Array.BlockHeader}
* @desc An array of `BlockHeader`
*/
this.headers = blockheaders || [];
}
util.inherits(Headers, Message);
@ -473,13 +542,18 @@ Headers.prototype.getPayload = function() {
module.exports.Headers = Message.COMMANDS.headers = Headers;
/**
* Block Message
* Contains information about a Block
*
* @name P2P.Message.Block
* @param{Block} block
* @param {Block} block
*/
function Block(block) {
this.command = 'block';
/**
* @type {Block}
* The
*/
this.block = block;
}
util.inherits(Block, Message);
@ -496,13 +570,16 @@ Block.prototype.getPayload = function() {
module.exports.Block = Message.COMMANDS.block = Block;
/**
* Tx Message
* Contains information about a transaction
*
* @name P2P.Message.Transaction
* @param{Transaction} transaction
*/
function Transaction(transaction) {
this.command = 'tx';
/**
* @type {Transaction}
*/
this.transaction = transaction;
}
util.inherits(Transaction, Message);
@ -519,7 +596,9 @@ Transaction.prototype.getPayload = function() {
module.exports.Transaction = Message.COMMANDS.tx = Transaction;
/**
* Getblocks Message
* Query another peer about blocks. It can query for multiple block hashes,
* and the response will contain all the chains of blocks starting from those
* hashes.
*
* @name P2P.Message.GetBlocks
* @param{Array} starts - array of buffers with the starting block hashes
@ -527,8 +606,18 @@ module.exports.Transaction = Message.COMMANDS.tx = Transaction;
*/
function GetBlocks(starts, stop) {
this.command = 'getblocks';
/**
* @type {number}
*/
this.version = PROTOCOL_VERSION;
/**
* @type {Array.Buffer}
*/
this.starts = starts || [];
/**
* @type {Array.Buffer}
* @desc Hashes to limit the amount of blocks to be sent
*/
this.stop = stop || BufferUtil.NULL_HASH;
}
util.inherits(GetBlocks, Message);
@ -570,7 +659,7 @@ GetBlocks.prototype.getPayload = function() {
module.exports.GetBlocks = Message.COMMANDS.getblocks = GetBlocks;
/**
* Getheaders Message
* Request block headers starting from a hash
*
* @name P2P.Message.GetHeaders
* @param{Array} starts - array of buffers with the starting block hashes
@ -578,8 +667,17 @@ module.exports.GetBlocks = Message.COMMANDS.getblocks = GetBlocks;
*/
function GetHeaders(starts, stop) {
this.command = 'getheaders';
/**
* @type {number}
*/
this.version = PROTOCOL_VERSION;
/**
* @type {Array.Buffer}
*/
this.starts = starts || [];
/**
* @type {Array.Buffer}
*/
this.stop = stop || BufferUtil.NULL_HASH;
}
@ -587,7 +685,7 @@ util.inherits(GetHeaders, GetBlocks);
module.exports.GetHeaders = Message.COMMANDS.getheaders = GetHeaders;
/**
* GetMempool Message
* Request for transactions on the mempool
*
* @name P2P.Message.GetMempool
*/

2
package.json
View File

@ -59,7 +59,7 @@
"socks5-client": "^0.3.6"
},
"devDependencies": {
"bitcore-build": "=0.4.2",
"bitcore-build": "^0.4.2",
"brfs": "^1.2.0",
"chai": "~1.10.0",
"gulp": "^3.8.10",

3
test/messages.js
View File

@ -17,7 +17,8 @@ describe('Messages', function() {
var message = new Messages.Version();
message.command.should.equal('version');
message.version.should.equal(70000);
message.subversion.should.equal('/BitcoinX:0.1/');
var version = require('../package.json').version;
message.subversion.should.equal('/bitcore:' + version + '/');
should.exist(message.nonce);
});