Working with Blocks

Blocks are the unit in which Base records everything — every transfer, swap on Aerodrome or Uniswap, and contract call lands in a block, and the chain appends a new one roughly every 2 seconds through its sequencer. Almost anything you build on Base, from a wallet showing balances to an indexer feeding analytics, ultimately comes down to reading blocks correctly and reacting to new ones, which makes block handling a foundational skill rather than an advanced one. After this guide you will be able to retrieve a block by number or hash over JSON-RPC against https://base.therpc.io/YOUR_API_KEY, watch for new blocks as the sequencer produces them, count confirmations, and reason about when a block on this OP Stack L2 is safe to treat as final.

Core Concepts

Block structure: a Base block carries a number and hash, a parentHash linking it to the previous block, a timestamp (Unix seconds), a gasLimit and gasUsed, a baseFeePerGas (Base uses EIP-1559), and the list of transactions. The parentHash chain is what lets you verify continuity and detect reorgs. Its uncles array is always empty on Base, since the single-sequencer model produces no uncle blocks.
JSON-RPC retrieval: you fetch blocks by calling eth_getBlockByNumber (with a number, or the latest/pending/finalized/safe tags) or eth_getBlockByHash. Passing a true transaction flag returns full transaction objects instead of just hashes, as the getBlock(blockNumber, true) example shows. All of this runs over a single endpoint, https://base.therpc.io/YOUR_API_KEY.
Block monitoring: monitoring means reacting to new Base blocks as they arrive — needed by indexers, transaction trackers, and any app that must update when state changes. Subscribe to newHeads for push delivery at the ~2s cadence, and fall back to polling eth_blockNumber where a subscription is not available.
Confirmations and finality: a transaction's confirmation count is the current head number minus the block it landed in; each new ~2s block adds one. More confirmations make a reorg displacing the transaction exponentially less likely, which is how confirmation depth approximates finality.
Finality on Base: sequencer inclusion is fast but provisional. A Base block becomes truly final only once its batch is settled on Ethereum L1 — the OP Stack rollup inherits L1 security for finality. For high-value decisions, wait for that L1 settlement (or the finalized tag) rather than relying on confirmation depth alone.

Block Retrieval

1// Get latest block number
2const blockNumber = await web3.eth.getBlockNumber();
3 
4// Get block by number
5const block = await web3.eth.getBlock(blockNumber);
6 
7// Get block with full transaction details
8const blockWithTx = await web3.eth.getBlock(blockNumber, true);

Best Practices

Delays and timeouts: set a sensible request timeout and retry idempotent reads with bounded exponential backoff. Because Base produces a block every ~2s, a stale or slow read is often best resolved by moving to the next block rather than retrying the same height indefinitely.
Error handling: distinguish a transient failure (timeout, rate limit, 5xx) which should retry, from a null block result for a head the sequencer has not yet propagated, which should simply wait. Never assume a single call to base.therpc.io succeeds — wrap every block read in explicit error handling.
Reorg awareness: the recent head can be rewritten by a shallow reorg, so verify each new block's parentHash against the last block you saw and do not treat recent blocks as permanent. Account for reorgs whenever you persist state derived from the latest blocks.
Caching: cache finalized historical blocks by hash — they are immutable once settled on L1 — and avoid caching the reorg-prone head, or give it only a few seconds' TTL. Caching cuts repeated lookups and Compute Unit spend without serving stale data.
Gas and block space: watch baseFeePerGas, gasUsed, and gasLimit across recent blocks so you can price transactions sensibly and detect congestion. On Base these signal when the L2 is busy and fees are climbing, which directly affects whether your transactions land quickly.

Block structure: a Base block carries a number and hash, a parentHash linking it to the previous block, a timestamp (Unix seconds), a gasLimit and gasUsed, a baseFeePerGas (Base uses EIP-1559), and the list of transactions. The parentHash chain is what lets you verify continuity and detect reorgs. Its uncles array is always empty on Base, since the single-sequencer model produces no uncle blocks.

JSON-RPC retrieval: you fetch blocks by calling eth_getBlockByNumber (with a number, or the latest/pending/finalized/safe tags) or eth_getBlockByHash. Passing a true transaction flag returns full transaction objects instead of just hashes, as the getBlock(blockNumber, true) example shows. All of this runs over a single endpoint, https://base.therpc.io/YOUR_API_KEY.

Block monitoring: monitoring means reacting to new Base blocks as they arrive — needed by indexers, transaction trackers, and any app that must update when state changes. Subscribe to newHeads for push delivery at the ~2s cadence, and fall back to polling eth_blockNumber where a subscription is not available.

Confirmations and finality: a transaction's confirmation count is the current head number minus the block it landed in; each new ~2s block adds one. More confirmations make a reorg displacing the transaction exponentially less likely, which is how confirmation depth approximates finality.

Finality on Base: sequencer inclusion is fast but provisional. A Base block becomes truly final only once its batch is settled on Ethereum L1 — the OP Stack rollup inherits L1 security for finality. For high-value decisions, wait for that L1 settlement (or the finalized tag) rather than relying on confirmation depth alone.

Block Retrieval

1// Get latest block number
2const blockNumber = await web3.eth.getBlockNumber();
3 
4// Get block by number
5const block = await web3.eth.getBlock(blockNumber);
6 
7// Get block with full transaction details
8const blockWithTx = await web3.eth.getBlock(blockNumber, true);

Best Practices

Delays and timeouts: set a sensible request timeout and retry idempotent reads with bounded exponential backoff. Because Base produces a block every ~2s, a stale or slow read is often best resolved by moving to the next block rather than retrying the same height indefinitely.

Error handling: distinguish a transient failure (timeout, rate limit, 5xx) which should retry, from a null block result for a head the sequencer has not yet propagated, which should simply wait. Never assume a single call to base.therpc.io succeeds — wrap every block read in explicit error handling.

Reorg awareness: the recent head can be rewritten by a shallow reorg, so verify each new block's parentHash against the last block you saw and do not treat recent blocks as permanent. Account for reorgs whenever you persist state derived from the latest blocks.

Caching: cache finalized historical blocks by hash — they are immutable once settled on L1 — and avoid caching the reorg-prone head, or give it only a few seconds' TTL. Caching cuts repeated lookups and Compute Unit spend without serving stale data.

Gas and block space: watch baseFeePerGas, gasUsed, and gasLimit across recent blocks so you can price transactions sensibly and detect congestion. On Base these signal when the L2 is busy and fees are climbing, which directly affects whether your transactions land quickly.

Working with Blocks

Core Concepts

Block Retrieval

Best Practices

See also

Pronto para usar isso em produção?

Working with Blocks

Core Concepts

Block Retrieval

Best Practices

See also