Block Events — Block Lifecycle

Subscribe

{"subscribe": ["BlockStart", "BlockEnd", "BlockFinalized"]}

Or any subset: BlockStart, BlockEnd, BlockQC, BlockFinalized, BlockVerified, BlockReject.

Message Format

All events are delivered inside an Events batch:

{
  "seq": 42,
  "Events": [
    {
      "event_name": "BlockStart",
      "block_number": 56147820,
      "txn_idx": null,
      "txn_hash": null,
      "commit_stage": "Proposed",
      "payload": {
        "type": "BlockStart",
        "block_number": 56147820,
        "block_id": "0x...",
        "round": 1,
        "epoch": 100,
        "parent_eth_hash": "0x...",
        "timestamp": 1708345678,
        "beneficiary": "0x...",
        "gas_limit": 30000000,
        "base_fee_per_gas": "0x3b9aca00"
      },
      "seqno": 9876543210,
      "timestamp_ns": 1708345678000000000
    }
  ]
}

Event Types

BlockStart

Block execution begins. Triggers Proposed lifecycle stage.

Payload Field	Type	Description
block_number	number	Block height
block_id	string	Consensus block ID
round	number	Consensus round
epoch	number	Epoch
parent_eth_hash	string	Parent block Ethereum hash
timestamp	number	Block unix timestamp
beneficiary	string	Block producer address
gas_limit	number	Gas limit
base_fee_per_gas	string	EIP-1559 base fee (hex U256)

BlockEnd

Execution complete. Does not change the public lifecycle stage.

Payload Field	Type	Description
eth_block_hash	string	Ethereum block hash
state_root	string	State root
receipts_root	string	Receipts trie root
logs_bloom	string	Bloom filter
gas_used	number	Gas consumed

BlockQC

Quorum Certificate: 2/3+ validators voted. Triggers Voted stage (~400 ms).

Payload Field	Type	Description
block_id	string	Block ID
block_number	number	Block height
round	number	Round

BlockFinalized

Block finalized, irreversible. Triggers Finalized stage (~800 ms).

Payload Field	Type	Description
block_id	string	Block ID
block_number	number	Block height

BlockVerified

State root verified. Verified stage (terminal).

Payload Field	Type	Description
block_number	number	Block height

BlockReject

Block dropped. Rejected stage (terminal).

Payload Field	Type	Description
reason	number	Rejection reason code

BlockPerfEvmEnter / BlockPerfEvmExit

EVM profiling markers. Blocked by default, available with --unrestricted.

Event Ordering Within a Block

BlockStart
  TxnHeaderStart(0) ... TxnEnd(0)
  TxnHeaderStart(1) ... TxnEnd(1)
  ...
  TxnHeaderStart(N) ... TxnEnd(N)
BlockEnd

Lifecycle events (BlockQC, BlockFinalized, BlockVerified) arrive separately, after the corresponding consensus event.

Usage Examples

Monitor New Blocks

{"subscribe": ["BlockStart"]}

Full Block Lifecycle

{"subscribe": ["BlockStart", "BlockEnd", "BlockFinalized"]}

Track Finalization

{"subscribe": ["BlockFinalized", "BlockVerified", "BlockReject"]}

The commit_stage Field

Every event carries commit_stage, the block's current stage at the time of sending. For live streams, BlockStart always arrives with commit_stage: "Proposed".

Frequency

~2-3 blocks per second (at 400 ms block time). Each block generates at minimum BlockStart + BlockEnd.