Messages

The bitcoin protocol specifies a set of messages that can be sent from peer to peer. bitcore-p2p provides support for some of these messages.

To create a message, you can use any of the message constructors, here is a simple example:

var messages = new Messages();
var message = messages.Ping();

There are also several convenient helpers for inventory based messages:

message = messages.GetData.forTransaction(txHash);
message = messages.GetData.forBlock(blockHash);
message = messages.Inventory.forTransaction(txHash);

As well as sending "tx" and "block" messages with Bitcore instances:

message = messages.Block(block);
message = messages.Transaction(transaction);

Note: A list of further messages is available below.

For advanced usage, you can also customize which constructor is used for Block and Transaction messages by passing it as an argument to Messages, for example:

var messages = new Messages({Block: MyBlock, Transaction: MyTransaction});

And additionally a custom network:

var messages = new Messages({network: Networks.testnet});

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.

NotFound

notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set. Contains inventory information specifying which items were not found.

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.

Custom Messages

It is possible to extend the default peer to peer messages and add custom ones. First you will need to create a message which resembles the default messages in lib/messages/commands.

Then to add the custom message:

messages.add('custom', 'Custom', CustomMessage);

var customMessage = messages.Custom('argument');

Messages

Kind: global class

new Messages([options])

A factory to build Bitcoin protocol messages.

Param Type Description
[options] Object
[options.network] Network
[options.Block] function A block constructor
[options.BlockHeader] function A block header constructor
[options.MerkleBlock] function A merkle block constructor
[options.Transaction] function A transaction constructor

messages.parseBuffer(dataBuffer)

Kind: instance method of Messages

Param Type
dataBuffer Buffers

Message

Kind: global class

new Message([options])

Base message that can be inherited to add an additional getPayload method to modify the message payload.

Param Type
[options] Object
[options.command] String
[options.network] Network

message.toBuffer

Kind: instance class of Message

AddrMessage ⇐ Message

Kind: global class
Extends: Message

new AddrMessage([arg], [options])

Param Type Description
[arg] Array An array of addrs
[options] Object

AlertMessage ⇐ Message

Kind: global class
Extends: Message

new AlertMessage([arg], options)

Param Type
[arg] Object
[arg.payload] Buffer
[arg.signature] Buffer
options Object

BlockMessage ⇐ Message

Kind: global class
Extends: Message

new BlockMessage([arg], options)

Param Type Description
[arg] Block An instance of a Block
options Object
options.Block function A block constructor

FilteraddMessage ⇐ Message

Kind: global class
Extends: Message

new FilteraddMessage([data], [options])

Request peer to add data to a bloom filter already set by 'filterload'

Param Type Description
[data] Buffer Array of bytes representing bloom filter data
[options] Object

FilterclearMessage ⇐ Message

Kind: global class
Extends: Message

new FilterclearMessage()

Request peer to clear data for a bloom filter

FilterloadMessage ⇐ Message

Kind: global class
Extends: Message

new FilterloadMessage([arg], options)

Request peer to send inv messages based on a bloom filter

Param Type Description
[arg] BloomFilter An instance of BloomFilter
options Object

GetaddrMessage ⇐ Message

Kind: global class
Extends: Message

new GetaddrMessage(options)

Request information about active peers

Param Type
options Object

GetblocksMessage ⇐ Message

Kind: global class
Extends: Message

new GetblocksMessage([arg], options)

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.

Param Type Description
[arg] Object
[arg.starts] Array Array of buffers or strings with the starting block hashes
[arg.stop] Buffer Hash of the last block
options Object

GetdataMessage ⇐ Message

Kind: global class
Extends: Message

new GetdataMessage(arg)

Param Type Description
arg Object | Array options - If options is an array will use as "inventory"
[options.inventory] Array An array of inventory items

GetheadersMessage ⇐ Message

Kind: global class
Extends: Message

new GetheadersMessage([options])

Query another peer about block headers. It can query for multiple block hashes, and the response will contain all the chains of blocks starting from those hashes.

Param Type Description
[options] Object
[options.starts] Array Array of buffers or strings with the starting block hashes
[options.stop] Buffer Hash of the last block

HeadersMessage ⇐ Message

Kind: global class
Extends: Message

new HeadersMessage(arg, [options])

Sent in response to a getheaders message. It contains information about block headers.

Param Type Description
arg Array An array of BlockHeader instances
[options] Object
[options.headers] Array array of block headers
options.BlockHeader function a BlockHeader constructor

InvMessage ⇐ Message

Kind: global class
Extends: Message

new InvMessage([arg], options)

Param Type Description
[arg] Array An array of inventory
options Object
[options.inventory] Array An array of inventory items

MempoolMessage ⇐ Message

Kind: global class
Extends: Message
See: https://en.bitcoin.it/wiki/Protocol_documentation#mempool

new MempoolMessage(options)

The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed.

Param Type
options Object

MerkleblockMessage ⇐ Message

Kind: global class
Extends: Message
See: https://en.bitcoin.it/wiki/Protocol_documentation

new MerkleblockMessage(arg, [options])

Contains information about a MerkleBlock

Param Type Description
arg MerkleBlock An instance of MerkleBlock
[options] Object
options.MerkleBlock function a MerkleBlock constructor

NotfoundMessage ⇐ Message

Kind: global class
Extends: Message

new NotfoundMessage(arg, options)

Param Type Description
arg Array An array of inventory
options Object
[options.inventory] Array An array of inventory items

PingMessage ⇐ Message

Kind: global class
Extends: Message

new PingMessage(arg, [options])

A message to confirm that a connection is still valid.

Param Type Description
arg Number A nonce for the Ping message
[options] Object

PongMessage ⇐ Message

Kind: global class
Extends: Message

new PongMessage(arg, [options])

A message in response to a ping message.

Param Type Description
arg Number A nonce for the Pong message
[options] Object

RejectMessage ⇐ Message

Kind: global class
Extends: Message
See: https://en.bitcoin.it/wiki/Protocol_documentation#reject

new RejectMessage([arg], options)

The reject message is sent when messages are rejected.

Param Type Description
[arg] Object properties for the reject message
[arg.message] String type of message rejected
[arg.ccode] Number code relating to rejected message
[arg.reason] String text version of reason for rejection
[arg.data] Buffer Optional extra data provided by some errors.
options Object

TransactionMessage ⇐ Message

Kind: global class
Extends: Message

new TransactionMessage([arg], options)

Param Type Description
[arg] Transaction An instance of Transaction
options Object

VerackMessage ⇐ Message

Kind: global class
Extends: Message

new VerackMessage()

A message in response to a version message.

VersionMessage ⇐ Message

Kind: global class
Extends: Message
See: https://en.bitcoin.it/wiki/Protocol_documentation#version

new VersionMessage([arg], options)

The version message 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.

Param Type Description
[arg] Object properties for the version message
[arg.nonce] Buffer a random 8 byte buffer
[arg.subversion] String version of the client
[arg.services] BN
[arg.timestamp] Date
[arg.startHeight] Number
options Object

Inventory

Kind: global class

new Inventory(obj)

A constructor for inventory related Bitcoin messages such as "getdata", "inv" and "notfound".

Param Type Description
obj Object
obj.type Number Inventory.TYPE
obj.hash Buffer The hash for the inventory

inventory.toBuffer() ⇒ Buffer

Kind: instance method of Inventory
Returns: Buffer - - Serialized inventory

inventory.toBufferWriter(bw)

Kind: instance method of Inventory

Param Type Description
bw BufferWriter An instance of BufferWriter

Inventory.forItem(type, hash) ⇒ Inventory

A convenience constructor for Inventory.

Kind: static method of Inventory
Returns: Inventory - - A new instance of Inventory

Param Type Description
type Number Inventory.TYPE
hash Buffer | String The hash for the inventory

Inventory.forBlock(hash) ⇒ Inventory

A convenience constructor for Inventory for block inventory types.

Kind: static method of Inventory
Returns: Inventory - - A new instance of Inventory

Param Type Description
hash Buffer | String The hash for the block inventory

Inventory.forFilteredBlock(hash) ⇒ Inventory

A convenience constructor for Inventory for filtered/merkle block inventory types.

Kind: static method of Inventory
Returns: Inventory - - A new instance of Inventory

Param Type Description
hash Buffer | String The hash for the filtered block inventory

Inventory.forTransaction(hash) ⇒ Inventory

A convenience constructor for Inventory for transaction inventory types.

Kind: static method of Inventory
Returns: Inventory - - A new instance of Inventory

Param Type Description
hash Buffer | String The hash for the transaction inventory

Inventory.fromBuffer(payload)

Kind: static method of Inventory

Param Type Description
payload Buffer Serialized buffer of the inventory

Inventory.fromBufferReader(br)

Kind: static method of Inventory

Param Type Description
br BufferWriter An instance of BufferWriter