Working with Blocks

Almost everything you read from Ethereum is, at bottom, a block. Transactions, receipts, logs, balances, gas prices — they all live inside the chain of blocks that a new validator extends every 12 seconds. Learn to fetch, read, and follow blocks and you've learned the substrate the rest of the JSON-RPC API sits on top of. It's the first thing worth getting comfortable with on chain 1.

This is the foundational guide. After it you'll know what a block actually contains, how to pull one by number or hash, how to follow the head live with a newHeads subscription, and what Ethereum's block tags (latest, safe, finalized) mean for trusting the data. The deeper, scenario-specific guides on reorgs, confirmations, gas, and production hardening build on the vocabulary established here. You can follow along against https://ethereum.therpc.io/YOUR_API_KEY.

Core Concepts

What's inside a block. An Ethereum block has a header and a body. The header carries number, hash, parentHash (the link to the previous block), timestamp, gasLimit and gasUsed, the EIP-1559 baseFeePerGas, the stateRoot, and post-Dencun blobGasUsed/excessBlobGas. The body holds the ordered list of transactions. Post-Merge, sha3Uncles is the empty-list hash and the uncles array is empty.
How retrieval works over JSON-RPC. You ask for a block by number with eth_getBlockByNumber or by hash with eth_getBlockByHash. A boolean flag controls whether you get full transaction objects or just their hashes. The block parameter also accepts the tags latest, safe, finalized, pending, and earliest in place of a number.
What monitoring means. Monitoring is following new blocks as they arrive rather than fetching one and stopping. You need it for indexers, watchers, and any UI that reacts to on-chain activity. The clean way is an eth_subscribe('newHeads') subscription over the WebSocket endpoint, which pushes each new block within its 12-second slot.
Confirmations and finality. A confirmation is a block built on top of the one holding your transaction — but on post-Merge Ethereum, the meaningful question isn't how many, it's whether the block has finalized. Read the gap to the finalized tag rather than tallying a fixed count.
What finality means here. Casper FFG finalizes checkpoints after about two epochs (~12.8 minutes). A finalized block is irreversible unless a third of all staked ETH is slashed; safe is a softer justified guarantee; latest can still reorg out. That tag, not a confirmation number, is what tells you a block is settled on chain 1.

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

Expect delays, set timeouts. A block request can hang on a slow node or a network blip. Give each call a sensible timeout and a short retry, but don't retry forever for a block that may simply not exist yet — at the head, a number can be one slot ahead of what's been produced.
Handle the null and the error distinctly. A request for a not-yet-mined block returns null, not an error; an actual failure throws. Code both paths separately so you don't mistake "not produced yet" for "node is broken." Also treat block fields as hex strings and parse them before comparing.
Account for reorgs whenever you read latest. Any data pulled at latest can be reorged away before it finalizes. If you're acting on it, check that each new block's parentHash matches what you last stored, and prefer finalized for anything you can't undo. (The reorg guide goes deeper.)
Cache by finality. Blocks at or below finalized never change — cache them indefinitely keyed by hash. Don't cache latest or pending for long, since both move; a TTL of a slot or two is plenty.
Watch gas and block space. Each block exposes gasUsed against gasLimit and the current baseFeePerGas. Tracking how full blocks are running tells you whether the base fee is about to climb, which is what you need to set fees that get your transactions included without overpaying.

What's inside a block. An Ethereum block has a header and a body. The header carries number, hash, parentHash (the link to the previous block), timestamp, gasLimit and gasUsed, the EIP-1559 baseFeePerGas, the stateRoot, and post-Dencun blobGasUsed/excessBlobGas. The body holds the ordered list of transactions. Post-Merge, sha3Uncles is the empty-list hash and the uncles array is empty.

How retrieval works over JSON-RPC. You ask for a block by number with eth_getBlockByNumber or by hash with eth_getBlockByHash. A boolean flag controls whether you get full transaction objects or just their hashes. The block parameter also accepts the tags latest, safe, finalized, pending, and earliest in place of a number.

What monitoring means. Monitoring is following new blocks as they arrive rather than fetching one and stopping. You need it for indexers, watchers, and any UI that reacts to on-chain activity. The clean way is an eth_subscribe('newHeads') subscription over the WebSocket endpoint, which pushes each new block within its 12-second slot.

Confirmations and finality. A confirmation is a block built on top of the one holding your transaction — but on post-Merge Ethereum, the meaningful question isn't how many, it's whether the block has finalized. Read the gap to the finalized tag rather than tallying a fixed count.

What finality means here. Casper FFG finalizes checkpoints after about two epochs (~12.8 minutes). A finalized block is irreversible unless a third of all staked ETH is slashed; safe is a softer justified guarantee; latest can still reorg out. That tag, not a confirmation number, is what tells you a block is settled on chain 1.

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

Expect delays, set timeouts. A block request can hang on a slow node or a network blip. Give each call a sensible timeout and a short retry, but don't retry forever for a block that may simply not exist yet — at the head, a number can be one slot ahead of what's been produced.

Handle the null and the error distinctly. A request for a not-yet-mined block returns null, not an error; an actual failure throws. Code both paths separately so you don't mistake "not produced yet" for "node is broken." Also treat block fields as hex strings and parse them before comparing.

Account for reorgs whenever you read latest. Any data pulled at latest can be reorged away before it finalizes. If you're acting on it, check that each new block's parentHash matches what you last stored, and prefer finalized for anything you can't undo. (The reorg guide goes deeper.)

Cache by finality. Blocks at or below finalized never change — cache them indefinitely keyed by hash. Don't cache latest or pending for long, since both move; a TTL of a slot or two is plenty.

Watch gas and block space. Each block exposes gasUsed against gasLimit and the current baseFeePerGas. Tracking how full blocks are running tells you whether the base fee is about to climb, which is what you need to set fees that get your transactions included without overpaying.

Working with Blocks

Core Concepts

Block Retrieval

Best Practices

See also

Bereit, das in der Produktion aufzurufen?

Working with Blocks

Core Concepts

Block Retrieval

Best Practices

See also