Block Management Best Practices

A script that reads Polygon blocks on your laptop can ignore failed requests, shallow Bor reorgs, and memory growth — a production service cannot. At ~2 seconds per block, chain 137 produces tens of thousands of blocks a day, and any gap, duplicate, or unhandled error compounds into state that no longer matches PolygonScan. Production-grade block handling demands explicit retry logic, reorg awareness, bounded memory, and observability that development code never needs. This guide delivers the concrete patterns and copy-ready checklists to run Polygon block processing reliably against https://polygon.therpc.io/YOUR_API_KEY, from robust fetching through reorg recovery to the monitoring you ship before going live.

Error Handling and Recovery

• Robust retries: Retry failed eth_getBlock calls 3–5 times with exponential backoff and jitter (1s, 2s, 4s). Keep the window short relative to Polygon's ~2s block time — if a recent height keeps failing, re-anchor to latest rather than hammering a stale block number.
• Timeouts without data loss: Set an explicit per-request timeout and, on a timeout, persist the last fully processed block before failing the attempt. On recovery, replay every Bor block from that checkpoint to the current head so no transaction on chain 137 is skipped.
• Reorg-safe processing: Check each new block's parentHash against the hash you last recorded. On a mismatch, walk back to the common ancestor, roll back any state derived from the orphaned blocks, and re-apply the canonical chain — never mutate irreversible state on a block that is still within reorg range.
• Fallback nodes: Configure a secondary Polygon endpoint and fail over automatically when the primary errors repeatedly or lags the chain head. A fallback keeps your processor live during a single-provider incident; route all reads through one client wrapper so confirmation and reorg logic stay identical across providers.

Performance Optimization

• Cache finalized blocks: Cache the bodies and receipts of blocks that are several confirmations deep — they are immutable on Polygon and never need re-fetching. Size the cache to your working set (an LRU holding a few thousand recent blocks is plenty for most apps) and keep only a short-lived cache for the reorgable tip.
• Batch to cut overhead: Group block and receipt reads into JSON-RPC batches of 10–20 instead of one request per block. Given Polygon's ~2s cadence and ~43k blocks/day, batching is what lets a backfill keep pace with the chain instead of falling permanently behind.
• Efficient polling: Poll on an interval tuned to the 2-second block time, add jitter to avoid synchronized bursts against https://polygon.therpc.io/YOUR_API_KEY, and skip work when latest has not advanced. A newBlockHeaders subscription is cheaper still and reacts within the block window.
• Bounded memory on ranges: When scanning large historical ranges, process in fixed-size windows and release each window before fetching the next, as the processBlockRange example does. Never load an unbounded number of Bor blocks into memory at once — stream the range so peak memory stays flat regardless of how many blocks you cover.

Security Considerations

• Confirmations by value: Scale your safety margin to the amount at risk. Low-value MATIC actions are usually safe after a handful of confirmations; medium-value flows warrant tens of blocks; and for high-value settlement wait until the block is covered by a Heimdall checkpoint to Ethereum L1, after which the transaction is effectively irreversible.
• Validate integrity: Before processing, confirm the block's number, hash, and parentHash form a continuous chain with the block you handled previously. Reject any block whose parent does not match your recorded head — that gap is the signature of a reorg or a node serving inconsistent data.
• Avoid double-processing: The real "replay" risk on Polygon is your own pipeline acting twice on one Bor block after a retry or reconnect, not a signature replay. Make every side effect idempotent by keying it on transaction hash and log index, and dedupe against work already committed.
• Spot anomalies: Treat block times far from ~2s, missing block numbers, a frozen chain head, or an abnormally deep reorg as red flags. Any of these can mean a malfunctioning node, a network problem on chain 137, or an endpoint following a minority fork — pause irreversible actions until the chain head behaves normally again.

Implementation Examples

1import Web3 from 'web3';
2const web3 = new Web3('https://polygon.therpc.io/YOUR_API_KEY');
3 
4// Robust block fetching with retries
5const fetchBlockWithRetry = async (blockNumber, maxRetries = 3) => {
6  for (let i = 0; i < maxRetries; i++) {
7    try {
8      const block = await web3.eth.getBlock(blockNumber);
9      if (block) return block;
10      throw new Error('Block not found');
11    } catch (error) {
12      if (i === maxRetries - 1) throw error;
13      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)));
14    }
15  }
16};
17 
18// Efficient block monitoring
19const createBlockMonitor = (callback, errorHandler) => {
20  let lastProcessedBlock = 0;
21 
22  return web3.eth
23    .subscribe('newBlockHeaders')
24    .on('data', async (blockHeader) => {
25      try {
26        if (blockHeader.number <= lastProcessedBlock) return;
27        await callback(blockHeader);
28        lastProcessedBlock = blockHeader.number;
29      } catch (error) {
30        errorHandler(error);
31      }
32    })
33    .on('error', errorHandler);
34};
35 
36// Memory-efficient block processing
37const processBlockRange = async (startBlock, endBlock, processor) => {
38  const batchSize = 10;
39  for (let i = startBlock; i <= endBlock; i += batchSize) {
40    const batch = await Promise.all(
41      Array.from(
42        { length: Math.min(batchSize, endBlock - i + 1) },
43        (_, index) => fetchBlockWithRetry(i + index)
44      )
45    );
46    await processor(batch);
47  }
48};
49 
50// Handle block reorgs
51const monitorReorgs = async (callback) => {
52  let lastBlock = await web3.eth.getBlock('latest');
53 
54  return web3.eth.subscribe('newBlockHeaders').on('data', async (block) => {
55    if (block.parentHash !== lastBlock.hash) {
56      await callback({
57        oldBlock: lastBlock,
58        newBlock: block,
59      });
60    }
61    lastBlock = block;
62  });
63};

Development Checklist

• Type your block data: Define explicit TypeScript types for Polygon blocks, headers, and receipts so the compiler catches a missing baseFeePerGas, a misread parentHash, or a number/BigInt mix-up before it ships. Typed shapes are the cheapest defense against silently mishandling chain 137 data.
• Cover every error path: Ensure each RPC call has a retry, a timeout, and a terminal handler; that null or missing blocks are handled; and that a parentHash mismatch routes into reorg recovery rather than throwing into the void.
• Instrument early: Add structured logging (method, block number, attempt, error code) and metrics (processing lag, error rate, reorg depth) from the first commit so you are not blind when the integration first meets real Polygon traffic.
• Test the hard cases: Unit-test retry/backoff, null-block handling, reorg detection and rollback, and batch-range processing. Use mocked RPC responses to simulate a Bor reorg and a flapping endpoint so these paths are exercised before production, not discovered there.

Production Checklist

• Essential alerts: Page on processing lag (blocks behind the chain head), RPC error rate, reorg depth, and a stalled head. On Polygon these map directly to user impact — a head that stops advancing past a few ~2s intervals means your consumers are already seeing stale data.
• Circuit breakers: Wrap the Polygon endpoint in a circuit breaker that trips after sustained failures, so a struggling node stops receiving traffic and your downstream systems shed load instead of queuing doomed requests. Half-open the breaker periodically to test recovery.
• Multiple providers: Run with at least two Polygon RPC providers so a single-provider outage or a node stuck on a minority fork does not halt processing. Diversity of endpoints is the simplest insurance for chain 137 production traffic.
• Health checks: Have a watchdog confirm the pipeline is within a few blocks of latest, that block timestamps advance roughly every 2 seconds, and that the breaker and fallback are armed. Surface the result on a status dashboard.
• Fallback strategy: When the primary https://polygon.therpc.io/YOUR_API_KEY degrades, fail over to the secondary automatically and keep tracking the last processed block so the failover node resumes exactly where the primary left off, with no skipped or duplicated Bor blocks.

Common Pitfalls to Avoid

• Thin error handling: Without retries and timeouts, a single transient RPC hiccup drops a Bor block, and at ~2s cadence the gap is easy to miss — your processed state silently diverges from the real chain 137 and disagrees with PolygonScan.
• No reorg handling: Treating the latest block as final means a shallow Bor reorg leaves you with state derived from orphaned blocks — a credited payout that never happened, an event that got rolled back — and nothing to detect or undo it. Always check parentHash continuity.
• Poor monitoring: Without lag, error-rate, and reorg metrics you learn about a stalled or behind processor from users, not dashboards. On a fast chain like Polygon, minutes of blind lag is thousands of unprocessed blocks.
• Inadequate testing: Reorg recovery, retry/backoff, and null-block paths rarely fire in development, so untested pipelines look healthy until the first real reorg or endpoint flap on chain 137 corrupts state in production. Simulate these cases before you ship.

See also

• Working with Blocks - Fundamental concepts of block handling
• Chain Reorganization Guide - Handling chain reorgs
• Block Confirmations Guide - Understanding transaction finality