Bitcoin Block

A Block instance represents the information of a block in the bitcoin network. Given a hexadecimal string representation of the serialization of a block with its transactions, you can instantiate a Block instance. Methods are provided to calculate and check the merkle root hash (if enough data is provided), but transactions won't necessarily be valid spends, and this class won't validate them. A binary representation as a Buffer instance is also valid input for a Block's constructor.

// instantiate a new block instance
var block = new Block(hexaEncodedBlock);

// will verify that the corresponding block transactions match the header
assert(block.validMerkleRoot());

// blocks have several properties
assert(block.header); // an instance of block header, more info below
assert(block.transactions); // an array of transactions, more info below

For detailed technical information about a block please visit Blocks on the Bitcoin Wiki.

Block Header

Each instance of Block has a BlockHeader (which can be instantiated separately). The header has validation methods, to verify that the block.

// will verify that the nonce demonstrates enough proof of work
assert(block.header.validProofOfWork());

// will verify that timestamp is not too far in the future
assert(block.header.validTimestamp());

// each header has the following properties
assert(block.header.version);
assert(block.header.prevHash);
assert(block.header.merkleRoot);
assert(block.header.time);
assert(block.header.bits);
assert(block.header.nonce);

For more information about the specific properties of a block header please visit the Block hashing algorithm page on the Bitcoin Wiki.

Transactions

The set of transactions in a block is an array of instances of Transaction and can be explored by iterating on the block's transactions member.

for (var i in block.transactions) {
  var transaction = block.transactions[i];
}

Block

Kind: global class

new Block(arg)

Instantiate a Block from a Buffer, JSON object, or Object with the properties of the Block

Param Type Description
arg * A Buffer, JSON string, or Object

block.toObject ⇒ Object

Kind: instance property of Block
Returns: Object - - A plain object with the block properties

block.toBuffer() ⇒ Buffer

Kind: instance method of Block
Returns: Buffer - - A buffer of the block

block.toString() ⇒ string

Kind: instance method of Block
Returns: string - - A hex encoded string of the block

block.toBufferWriter(bw) ⇒ BufferWriter

Kind: instance method of Block
Returns: BufferWriter - - An instance of BufferWriter representation of the Block

Param Type Description
bw BufferWriter An existing instance of BufferWriter

block.getTransactionHashes() ⇒ Array

Will iterate through each transaction and return an array of hashes

Kind: instance method of Block
Returns: Array - - An array with transaction hashes

block.getMerkleTree() ⇒ Array

Will build a merkle tree of all the transactions, ultimately arriving at a single point, the merkle root.

Kind: instance method of Block
Returns: Array - - An array with each level of the tree after the other.
Link: https://en.bitcoin.it/wiki/Protocol_specification#Merkle_Trees

block.getMerkleRoot() ⇒ Buffer

Calculates the merkleRoot from the transactions.

Kind: instance method of Block
Returns: Buffer - - A buffer of the merkle root hash

block.validMerkleRoot() ⇒ Boolean

Verifies that the transactions in the block match the header merkle root

Kind: instance method of Block
Returns: Boolean - - If the merkle roots match

block._getHash() ⇒ Buffer

Kind: instance method of Block
Returns: Buffer - - The little endian hash buffer of the header

block.inspect() ⇒ string

Kind: instance method of Block
Returns: string - - A string formatted for the console

Block.fromObject(obj) ⇒ Block

Kind: static method of Block
Returns: Block - - An instance of block

Param Type Description
obj Object A plain JavaScript object

Block.fromBufferReader(br) ⇒ Block

Kind: static method of Block
Returns: Block - - An instance of block

Param Type Description
br BufferReader A buffer reader of the block

Block.fromBuffer(buf) ⇒ Block

Kind: static method of Block
Returns: Block - - An instance of block

Param Type Description
buf Buffer A buffer of the block

Block.fromString(str) ⇒ Block

Kind: static method of Block
Returns: Block - - A hex encoded string of the block

Param Type Description
str string str - A hex encoded string of the block

Block.fromRawBlock(data) ⇒ Block

Kind: static method of Block
Returns: Block - - An instance of block

Param Type Description
data Binary Raw block binary data or buffer

BlockHeader

Kind: global class

new BlockHeader()

Instantiate a BlockHeader from a Buffer, JSON object, or Object with the properties of the BlockHeader

Returns: BlockHeader - - An instance of block header

Type Description
* A Buffer, JSON string, or Object

blockHeader.toObject ⇒ Object

Kind: instance property of BlockHeader
Returns: Object - - A plain object of the BlockHeader

blockHeader.toBuffer() ⇒ Buffer

Kind: instance method of BlockHeader
Returns: Buffer - - A Buffer of the BlockHeader

blockHeader.toString() ⇒ string

Kind: instance method of BlockHeader
Returns: string - - A hex encoded string of the BlockHeader

blockHeader.toBufferWriter(bw) ⇒ BufferWriter

Kind: instance method of BlockHeader
Returns: BufferWriter - - An instance of BufferWriter representation of the BlockHeader

Param Type Description
bw BufferWriter An existing instance BufferWriter

blockHeader.getTargetDifficulty(bits) ⇒ BN

Returns the target difficulty for this block

Kind: instance method of BlockHeader
Returns: BN - An instance of BN with the decoded difficulty bits

Param Type
bits Number

blockHeader.getDifficulty() ⇒ Number

Kind: instance method of BlockHeader
Link: https://en.bitcoin.it/wiki/Difficulty

blockHeader._getHash() ⇒ Buffer

Kind: instance method of BlockHeader
Returns: Buffer - - The little endian hash buffer of the header

blockHeader.validTimestamp() ⇒ Boolean

Kind: instance method of BlockHeader
Returns: Boolean - - If timestamp is not too far in the future

blockHeader.validProofOfWork() ⇒ Boolean

Kind: instance method of BlockHeader
Returns: Boolean - - If the proof-of-work hash satisfies the target difficulty

blockHeader.inspect() ⇒ string

Kind: instance method of BlockHeader
Returns: string - - A string formatted for the console

BlockHeader.fromObject(obj) ⇒ BlockHeader

Kind: static method of BlockHeader
Returns: BlockHeader - - An instance of block header

Param Type Description
obj Object A plain JavaScript object

BlockHeader.fromRawBlock(data) ⇒ BlockHeader

Kind: static method of BlockHeader
Returns: BlockHeader - - An instance of block header

Param Type Description
data Binary Raw block binary data or buffer

BlockHeader.fromBuffer(buf) ⇒ BlockHeader

Kind: static method of BlockHeader
Returns: BlockHeader - - An instance of block header

Param Type Description
buf Buffer A buffer of the block header

BlockHeader.fromString(str) ⇒ BlockHeader

Kind: static method of BlockHeader
Returns: BlockHeader - - An instance of block header

Param Type Description
str string A hex encoded buffer of the block header

BlockHeader.fromBufferReader(br) ⇒ BlockHeader

Kind: static method of BlockHeader
Returns: BlockHeader - - An instance of block header

Param Type Description
br BufferReader A BufferReader of the block header

MerkleBlock

Kind: global class

new MerkleBlock(arg)

Instantiate a MerkleBlock from a Buffer, JSON object, or Object with the properties of the Block

Param Type Description
arg * A Buffer, JSON string, or Object representing a MerkleBlock

merkleBlock.header : BlockHeader

Kind: instance property of MerkleBlock

merkleBlock.numTransactions : Number

Kind: instance property of MerkleBlock

merkleBlock.hashes : Array.<String>

Kind: instance property of MerkleBlock

merkleBlock.flags : Array.<Number>

Kind: instance property of MerkleBlock

merkleBlock.toObject ⇒ Object

Kind: instance property of MerkleBlock
Returns: Object - - A plain object with the MerkleBlock properties

merkleBlock.toBuffer() ⇒ Buffer

Kind: instance method of MerkleBlock
Returns: Buffer - - A buffer of the block

merkleBlock.toBufferWriter(bw) ⇒ BufferWriter

Kind: instance method of MerkleBlock
Returns: BufferWriter - - An instance of BufferWriter representation of the MerkleBlock

Param Type Description
bw BufferWriter An existing instance of BufferWriter

merkleBlock.validMerkleTree() ⇒ Boolean

Verify that the MerkleBlock is valid

Kind: instance method of MerkleBlock
Returns: Boolean - - True/False whether this MerkleBlock is Valid

MerkleBlock.fromBuffer(buf) ⇒ MerkleBlock

Kind: static method of MerkleBlock
Returns: MerkleBlock - - A MerkleBlock object

Param Type Description
buf Buffer MerkleBlock data in a Buffer object

MerkleBlock.fromBufferReader(br) ⇒ MerkleBlock

Kind: static method of MerkleBlock
Returns: MerkleBlock - - A MerkleBlock object

Param Type Description
br BufferReader MerkleBlock data in a BufferReader object

MerkleBlock.fromObject(obj) ⇒ Block

Kind: static method of MerkleBlock
Returns: Block - - An instance of block

Param Type Description
obj Object A plain JavaScript object