Working with Blocks

Blocks are the unit of truth on Polygon: every balance, event, and transaction receipt is recorded in a Bor block, and a new one arrives on chain 137 roughly every 2 seconds. Whether you are tracking deposits, indexing events, or confirming a MATIC transfer, reading and reasoning about blocks correctly is the foundation everything else stands on. After this guide you will be able to retrieve blocks by number or hash from https://polygon.therpc.io/YOUR_API_KEY, monitor the chain head in real time, count confirmations, and understand what finality actually means on Polygon — the groundwork for the more advanced reorg, gas, and best-practice guides that follow.

Core Concepts

Block structure: A Polygon (Bor) block carries a header and a body. The header holds the block number, hash, parentHash linking it to the previous block, the validator-set timestamp (~2s apart), gasLimit and gasUsed, and baseFeePerGas from the EIP-1559 fee market. The body holds the list of transactions. The parentHash chain is what lets you verify continuity and detect reorgs.
JSON-RPC retrieval: You fetch blocks by calling methods like eth_getBlockByNumber and eth_getBlockByHash (wrapped here as web3.eth.getBlock). Pass a number, a hash, or a tag such as latest; pass true as the second argument to expand full transaction objects instead of just hashes, as the blockWithTx example shows.
Block monitoring: Monitoring means reacting to each new block as it is produced — needed whenever you track deposits, index events, or update UI in real time. On Polygon's ~2s cadence, subscribe to newBlockHeaders for low latency rather than polling, and always process by block number so you neither skip nor double-handle a Bor block.
Confirmations and finality: A confirmation is each block built on top of the one holding your transaction; the more there are, the deeper it is buried and the harder to reverse. Counting confirmations is how you approach finality progressively before treating a transaction as settled.
Finality on Polygon: A fresh block at the tip of chain 137 is not final — it can still be replaced by a shallow Bor reorg. True finality comes when the block is included in a periodic Heimdall checkpoint anchored to Ethereum L1, after which it is effectively irreversible. Wait for enough confirmations for routine MATIC actions and for a checkpoint for high-value settlement.

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 an explicit timeout on every block request and retry transient failures with bounded exponential backoff. Keep the retry window short relative to Polygon's ~2s block time — if a recent height keeps failing, re-anchor to latest rather than chasing a stale block number.
Error handling: Handle the case where getBlock returns null (the block is not yet available or you queried beyond the head), distinguish a network timeout from a malformed response, and never let an unhandled error silently drop a Bor block from your processing — that gap is how state drifts from PolygonScan.
Account for reorgs: Whenever you act on the latest few blocks, assume the tip can still be reorganized on Polygon. Track each block's parentHash against the one you recorded, and wait past the shallow-reorg window — or for a Heimdall checkpoint — before treating a block as final.
Cache the right data: Cache finalized blocks freely — a block several confirmations deep is immutable on chain 137, so its hash, timestamp, transactions, and receipts never change. Cache the reorgable tip only briefly with a short TTL, since it can still be replaced.
Watch gas and block space: Track baseFeePerGas and how full recent blocks are (gasUsed versus gasLimit) so you price transactions to confirm promptly without overpaying in MATIC. A run of near-full blocks signals congestion on chain 137 and a rising base fee.

Block structure: A Polygon (Bor) block carries a header and a body. The header holds the block number, hash, parentHash linking it to the previous block, the validator-set timestamp (~2s apart), gasLimit and gasUsed, and baseFeePerGas from the EIP-1559 fee market. The body holds the list of transactions. The parentHash chain is what lets you verify continuity and detect reorgs.

JSON-RPC retrieval: You fetch blocks by calling methods like eth_getBlockByNumber and eth_getBlockByHash (wrapped here as web3.eth.getBlock). Pass a number, a hash, or a tag such as latest; pass true as the second argument to expand full transaction objects instead of just hashes, as the blockWithTx example shows.

Block monitoring: Monitoring means reacting to each new block as it is produced — needed whenever you track deposits, index events, or update UI in real time. On Polygon's ~2s cadence, subscribe to newBlockHeaders for low latency rather than polling, and always process by block number so you neither skip nor double-handle a Bor block.

Confirmations and finality: A confirmation is each block built on top of the one holding your transaction; the more there are, the deeper it is buried and the harder to reverse. Counting confirmations is how you approach finality progressively before treating a transaction as settled.

Finality on Polygon: A fresh block at the tip of chain 137 is not final — it can still be replaced by a shallow Bor reorg. True finality comes when the block is included in a periodic Heimdall checkpoint anchored to Ethereum L1, after which it is effectively irreversible. Wait for enough confirmations for routine MATIC actions and for a checkpoint for high-value settlement.

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 an explicit timeout on every block request and retry transient failures with bounded exponential backoff. Keep the retry window short relative to Polygon's ~2s block time — if a recent height keeps failing, re-anchor to latest rather than chasing a stale block number.

Error handling: Handle the case where getBlock returns null (the block is not yet available or you queried beyond the head), distinguish a network timeout from a malformed response, and never let an unhandled error silently drop a Bor block from your processing — that gap is how state drifts from PolygonScan.

Account for reorgs: Whenever you act on the latest few blocks, assume the tip can still be reorganized on Polygon. Track each block's parentHash against the one you recorded, and wait past the shallow-reorg window — or for a Heimdall checkpoint — before treating a block as final.

Cache the right data: Cache finalized blocks freely — a block several confirmations deep is immutable on chain 137, so its hash, timestamp, transactions, and receipts never change. Cache the reorgable tip only briefly with a short TTL, since it can still be replaced.

Watch gas and block space: Track baseFeePerGas and how full recent blocks are (gasUsed versus gasLimit) so you price transactions to confirm promptly without overpaying in MATIC. A run of near-full blocks signals congestion on chain 137 and a rising base fee.

Working with Blocks

Core Concepts

Block Retrieval

Best Practices

See also

هل أنت مستعد لاستدعاء هذا في الإنتاج؟

Working with Blocks

Core Concepts

Block Retrieval

Best Practices

See also