Package Exports

bitcoin-protocol

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (bitcoin-protocol) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

bitcoin-protocol

Bitcoin network protocol streams

This module encodes and decodes low-level network protocol data using streams.

You may want a higher-level module like bitcoin-net, which some things for you such as connection handshakes, sending keepalive pings, etc.

Usage

npm install bitcoin-protocol

var net = require('net')
var bp = require('bitcoin-protocol')

var decoder = bp.createDecodeStream()
decoder.on('data', function (message) { console.log(message) })

var encoder = bp.createEncodeStream()

var socket = net.connect(8333, '127.0.0.1', function () {
  socket.pipe(decoder)
  encoder.pipe(socket)

  encoder.write({
    magic: 0xd9b4bef9,
    command: 'version',
    payload: {
      version: 70012,
      services: Buffer(8).fill(0),
      timestamp: Math.round(Date.now() / 1000),
      receiverAddress: {
        services: Buffer('0100000000000000', 'hex'),
        address: '0.0.0.0',
        port: 8333
      },
      senderAddress: {
        services: Buffer(8).fill(0),
        address: '0.0.0.0',
        port: 8333
      },
      nonce: Buffer(8).fill(123),
      userAgent: 'foobar',
      startHeight: 0,
      relay: true
    }
  })
})

Methods

`createDecodeStream([opts])`

Creates a stream which parses raw network bytes written to it and outputs message objects.

Opts may contain:

{
  magic: Number
  // If provided, the decoder will check if messages' "magic" field matches
  // this value. If it does not match, the stream will emit an error.
}

`createEncodeStream([opts])`

Creates a stream which encodes message objects to raw network bytes.

Opts may contain:

{
  magic: Number
  // If provided, the encoder will automatically add the "magic" field to each
  // message written to it.
}

Format

Decoder

Emitted by the decoder:

{
  magic: Number,
  command: String,
  length: Number,
  checksum: Buffer, // 8 bytes,
  payload: Object // see below for detailed payload formats
}

Encoder

Written to the encoder:

{
  magic: Number, // optional if you set this in the options
  command: String,
  payload: Object // see below for detailed payload formats
}

Payload Reference

The formats for the objects used as message payloads for the various commands are as follows. See the wiki for more information about these messages.

`version`

{
  version: Number,
  services: Buffer, // 8 bytes
  timestamp: Number,
  receiverAddress: {
    services: Buffer, // 8 bytes
    address: String, // ipv4 or ipv6
    port: Number
  },
  senderAddress: {
    services: Buffer, // 8 bytes
    address: String, // ipv4 or ipv6
    port: Number
  },
  nonce: Buffer, // 8 bytes
  userAgent: String,
  startHeight: Number,
  relay: Boolean
}

`verack`, `getaddr`, `mempool`, `filterclear`, `sendheaders`

// no payload needed

`addr`

[
  {
    time: Number,
    services: Buffer, // 8 bytes
    address: String, // ipv4 or ipv6
    port: Number
  },
  ...
]

`inv`, `getdata`, `notfound`

[
  {
    type: Number,
    hash: Buffer // 32 bytes
  },
  ...
]

`getblocks`, `getheaders`

{
  version: Number,
  locator: [
    Buffer // 32 bytes
  ],
  hashStop: Buffer // 32 bytes
}

`tx`

{
  version: Number,
  ins: [
    {
      hash: Buffer, // 32 bytes
      index: Number,
      script: Buffer, // varying length
      sequence: Number
    },
    ...
  ],
  outs: [
    {
      value: BN, // from 'bn.js' package
      script: Buffer // varying length
    },
    ...
  ],
  locktime: Number
}

`block`

{
  header: {
    version: Number,
    prevHash: Buffer, // 32 bytes
    merkleRoot: Buffer, // 32 bytes
    timestamp: Number,
    bits: Number,
    nonce: Number,
  },
  transactions: [
    {}, // same format as 'tx' message
    ...
  ]
}

`headers`

[
  {
    header: {
      version: Number,
      prevHash: Buffer, // 32 bytes
      merkleRoot: Buffer, // 32 bytes
      timestamp: Number,
      bits: Number,
      nonce: Number,
    },
    nTransactions: Number
  },
  ...
]

`ping`, `pong`

{
  nonce: Buffer // 8 bytes
}

`reject`

{
  message: String,
  ccode: Number,
  reason: String,
  data: Buffer // varying length
}

`filterload`

{
  data: Buffer, // varying length
  nHashFuncs: Number,
  nTweak: Number,
  nFlags: Number
}

`filteradd`

{
  data: Buffer // varying length
}

`merkleblock`

{
  header: {
    version: Number,
    prevHash: Buffer, // 32 bytes
    merkleRoot: Buffer, // 32 bytes
    timestamp: Number,
    bits: Number,
    nonce: Number
  },
  numTransactions: Number,
  hashes: [
    Buffer // 32 bytes
  ],
  flags: Buffer // varying length
}

`alert`

{
  payload: Buffer, // varying length
  signature: Buffer // varying length
}