NAME
Bitcoin::Crypto::Block - Bitcoin block implementation
SYNOPSIS
use Bitcoin::Crypto qw(btc_block);
use Bitcoin::Crypto::Util qw(to_format);
# Create a new block
my $block = btc_block->new(
version => 1,
prev_block_hash => $previous_hash,
timestamp => 1697298600,
bits => 0x1d00ffff,
nonce => 12345,
height => 812164,
);
# Add transactions
$block->add_transaction($coinbase_tx);
$block->add_transaction($tx1);
$block->add_transaction($tx2);
# Calculate merkle root
my $merkle_root = $block->merkle_root;
# Get block info
print "Block hash: " . to_format([hex => $block->get_hash]) . "\n";
print "Block size: " . $block->size . " bytes\n";
print "Block weight: " . $block->weight . " WU\n";
# Parse from serialized data
my $block = btc_block->from_serialized($block_hex);
# Serialize block
my $serialized = $block->to_serialized;
# For locktime and sequence checks
my $next_block = btc_block->new(
timestamp => 1697299200,
height => 812165,
previous => $block,
);
print $next_block->median_time_past;DESCRIPTION
This is a complete Bitcoin block implementation that can parse, construct, and serialize Bitcoin blocks. It supports all standard Bitcoin block operations including transaction management, merkle root calculation, and block validation.
The class also provides the functionality required for locktime and sequence checks in transactions, as used in "verify" in Bitcoin::Crypto::Transaction and "block" in Bitcoin::Crypto::Transaction::UTXO. For transaction verification purposes, only the "timestamp", "height", and optionally "previous" attributes are required - other block header fields can be omitted.
INTERFACE
Attributes
version
Block version number. Default: 1.
writer: set_version
Available in the constructor.
prev_block_hash
Optional previous block hash as binary string (32 bytes)
Available in the constructor.
writer: set_prev_block_hash
predicate: has_prev_block_hash
merkle_root
Merkle root hash as binary string (32 bytes). This field serves as a cache that be calculated automatically and cleared on change of transactions. Calling reader of this field repeatedly without adding new transactions via "add_transaction" will not cause the recalculation of the merkle_root.
timestamp
Block timestamp as Unix timestamp. Default: current time.
Available in the constructor.
writer: set_timestamp
bits
Block difficulty target in compact notation. Default: 0x207fffff.
Available in the constructor.
writer: set_bits
nonce
Block nonce used in proof-of-work. Default: 0.
Available in the constructor.
writer: set_nonce
height
Optional block height.
Available in the constructor.
writer: set_height
predicate: has_height
previous
An optional instance of the previous block. Note that setting a previous block instance will automatically set "prev_block_hash" if previous block has transactions. It may silently replace the existing prev_block_hash.
Available in the constructor.
writer: set_previous
predicate: has_previous
transactions
Array reference of Bitcoin::Crypto::Transaction objects contained in this block. Use "add_transaction" to add transactions.
Methods
new
$block = $class->new(%args)This is a standard Moo constructor, which can be used to create the object. It takes arguments specified in "Attributes".
Returns class instance.
has_transactions
$bool = $object->has_transactions()Returns a true value if the block object contains at least one transactions. Using some methods (like "merkle_root") on block with no transactions will raise an exception.
add_transaction
$block = $object->add_transaction($transaction)
$block = $object->add_transaction(@transaction_args)Adds a transaction to the block. Can accept either a Bitcoin::Crypto::Transaction object or arguments to construct one.
Returns the block object for method chaining.
to_serialized
$bytes = $object->to_serialized(%args)Serializes the block into Bitcoin's binary format.
Available arguments:
witness- boolean, whether to include witness data (default: true)
Returns the serialized block as a binary string.
from_serialized
$block = $class->from_serialized($bytes)Creates a block object from serialized Bitcoin block data.
Takes the serialized block data as binary string.
Returns a new block instance.
get_hash
$hash = $object->get_hash()Calculates and returns the block hash (double SHA-256 of the block header).
Returns the hash as a binary string in display format (big-endian).
get_header
$header = $object->get_header()Returns the 80-byte block header in Bitcoin's binary format.
size
$size = $object->size()Returns the size of the serialized block in bytes.
weight
$weight = $object->weight()Returns the block weight in weight units (WU). Formula: base_size * 3 + total_size.
dump
$string = $object->dump()Returns a human-readable string representation of the block, including all block header fields, metrics, and transaction summaries.
median_time_past
$mtp = $object->median_time_past()This method returns the median time past described in BIP113 (median timestamp of previous 11 blocks).
Since this block implementation is as basic as it gets, it will happily calculate median time past from less than 11 blocks, if there aren't enough blocks chained via "previous".