Block Number

Overview

Block numbers provide an ordered index into a chain. A child block normally has a number one greater than its parent, allowing clients and explorers to request ranges and estimate progress. The concept is often called block height, although some implementations distinguish the height of a chain from a number stored in a block header. Documentation should follow the target protocol’s terminology and genesis convention.

A number does not uniquely identify block contents. If two producers create blocks for the same parent, both candidates can have the same number. Fork choice later selects one branch, and a reorganization can replace the block previously reported at that position. The stable reference is the Block ID, while the number is a convenient location that must be resolved against the current canonical chain.

Block numbers also should not be treated as precise time. Block intervals vary, networks can pause, and some protocols use slots that may be empty. Estimating a calendar deadline by adding a fixed number of blocks can be inaccurate. Smart contracts sometimes use block number for relative conditions, but off-chain applications should understand the protocol’s timing guarantees and upgrade history before converting numbers to timestamps.

Payment systems should store both inclusion block number and block ID, then update confirmation depth as new canonical blocks arrive. Historical queries should specify whether they need the block that was canonical at the time or the block currently canonical at that number. During reconciliation, a changed ID at the same number is a reorganization signal. Final settlement should depend on confirmation or finality policy, not merely reaching a numerical threshold.