Block Structure and Encoding

Purpose and Scope

This document describes the block and header structure, encoding formats, hash calculation, Merkle root construction, and WBFT-specific Extra data structures used in the StableNet blockchain.
It focuses on how blocks are composed and validated, and what data is included in the header during the consensus process.

Related documents:

• Transaction data structures: Transaction Types and Encoding
• Block validation and chain insertion: Blockchain Management
• Block production process: Block Production

Block Structure Overview

A block consists of a header containing metadata, a body containing transactions, and optional withdrawals and uncles lists.
In StableNet (WBFT-based), uncles are not used and are always empty.

Block Type

Key fields of the Block structure (core/types/block.go):

Field	Type	Description
header	*Header	Block header containing metadata and Merkle roots
transactions	Transactions	List of transactions included in the block
uncles	[]*Header	Uncle block headers (not used)
withdrawals	Withdrawals	Withdrawals list (optional after Shanghai)
hash	atomic.Value	Cached block hash
size	atomic.Value	Cached RLP-encoded size

Blocks are treated as immutable objects after creation.
Internal data is copied during construction, and cached hash and size values never change afterward.

Header Structure

The Header is the core metadata of a block and contains cryptographic commitments to the block contents and execution results.

Core Header Fields

Field	Type	Description
ParentHash	common.Hash	Parent block header hash
UncleHash	common.Hash	Uncle list hash (EmptyUncleHash in StableNet)
Coinbase	common.Address	Block fee recipient address (validator address)
Root	common.Hash	State trie root after block execution
TxHash	common.Hash	Transaction Merkle root
ReceiptHash	common.Hash	Receipt Merkle root
Bloom	Bloom	Log bloom filter
Difficulty	*big.Int	Block difficulty (WBFT: always 1)
Number	*big.Int	Block number
GasLimit	uint64	Block gas limit
GasUsed	uint64	Total gas used
Time	uint64	Block timestamp
Extra	[]byte	WBFT consensus data (RLP-encoded)
MixDigest	common.Hash	PoW field (unused in WBFT)
Nonce	BlockNonce	PoW field (unused in WBFT)

StableNet specifics:

• Difficulty is set to 1 to identify WBFT blocks
• Coinbase is the validator’s consensus signing address and may differ from the operator address
• Extra contains WBFT round data, aggregated signatures, gas tip, and epoch information
• GasLimit is operated as a fixed value defined by chain parameters

Fork-Specific Optional Fields

The following fields exist only after specific forks and are included in RLP encoding only when non-nil.

Field	EIP	Fork	Description
BaseFee	EIP-1559	London	Block base fee
WithdrawalsHash	EIP-4895	Shanghai	Withdrawals Merkle root
BlobGasUsed	EIP-4844	Cancun	Blob gas usage
ExcessBlobGas	EIP-4844	Cancun	Excess blob gas
ParentBeaconRoot	EIP-4788	Cancun	Beacon chain parent root

Body Structure

The block body contains executable data:

• Transactions: Transaction list
• Uncles: Uncle headers (not used)
• Withdrawals: Withdrawals list (after the relevant fork)

RLP Encoding

Both blocks and headers use Recursive Length Prefix (RLP) encoding.

Block Encoding

A block is encoded as the following RLP list:

[header, transactions, uncles, withdrawals]

For pre-Shanghai blocks, the withdrawals element is omitted.

Header Encoding

Headers are RLP-encoded in the defined field order.
Optional fields are included only when present.

Block and Header Hashing

Standard Hashing

The block hash is calculated only from the header.

block_hash = keccak256(rlp(header))

The computed hash is cached to avoid repeated calculation.

WBFT-Specific Header Hashing

In WBFT, consensus signatures are included in the Extra field.
Therefore, signatures must be excluded from the hash used for signing.

This is handled by WBFTFilteredHeader():

• Removes PreparedSeal and CommittedSeal
• Preserves round number, epoch info, and gas tip
• Applied only when Difficulty == 1

This prevents circular dependencies between signatures and hashes.

Round-Dependent Hashes

During WBFT consensus rounds, a round-specific hash is used.
Even for the same block proposal, different rounds result in different signing hashes.

WBFT Extra Data Structure

WBFT consensus data is stored in the header’s Extra field as RLP-encoded data.

WBFTExtra Structure

Field	Type	Description
VanityData	[]byte	Vanity data
RandaoReveal	[]byte	BLS signature for randomness
PrevRound	uint32	Previous consensus round
PrevPreparedSeal	*WBFTAggregatedSeal	Previous prepare aggregated seal
PrevCommittedSeal	*WBFTAggregatedSeal	Previous commit aggregated seal
Round	uint32	Current consensus round
PreparedSeal	*WBFTAggregatedSeal	Current prepare aggregated seal
CommittedSeal	*WBFTAggregatedSeal	Current commit aggregated seal
GasTip	*big.Int	Governance-defined gas tip
EpochInfo	*EpochInfo	Next epoch info (epoch blocks only)

Fields with nil values are excluded from RLP encoding.

WBFTAggregatedSeal

Represents a BLS-aggregated signature from multiple validators.

Field	Type	Description
Sealers	SealerSet	Bitmap of signing validators
Signature	[]byte	Aggregated BLS signature

EpochInfo

Included only in epoch blocks and defines the validator set for the next epoch.

Field	Type	Description
Candidates	[]*Candidate	All validator candidates
Validators	[]uint32	Active validator indices
BLSPublicKeys	[][]byte	Validator BLS public keys

Merkle Root Calculation

TxHash

Calculated by building a Merkle Patricia Trie from the transaction list.
An empty list uses EmptyTxsHash.

ReceiptHash

Calculated in the same way from the receipt list.
The bloom filter is derived from receipts.

UncleHash

The hash of the uncle header list.
In StableNet, this is always EmptyUncleHash.

WithdrawalsHash

Calculated from the withdrawals list in post-Shanghai blocks.

Block Construction

NewBlock Function

NewBlock() constructs a block using the following steps:

1. Copy the header
2. Compute the transaction Merkle root
3. Compute the receipt root and bloom
4. Compute the uncle hash
5. Assemble the body data

For WBFT blocks:

• Difficulty = 1
• Extra contains the encoded WBFTExtra
• EpochInfo is included only in epoch blocks

After Shanghai, NewBlockWithWithdrawals() is used.

Header Sanity Checks

Header.SanityCheck() prevents DoS attacks caused by malformed inputs.

Field	Constraint
Number	64-bit range
Difficulty	Reasonable bit length
Extra	Maximum size limit
BaseFee	uint256 range

Block Size Calculation

The block size is the total RLP-encoded size and can be queried via Block.Size().
If blob transactions are included, sidecar data is also counted toward the size.