Best Practices

Polygon PoS settles a new Bor block roughly every 2 seconds, so an application that reads blocks ad hoc quickly accumulates subtle bugs — missed events, stale balances, and state that disagrees with PolygonScan. A systematic approach to block management turns that fast, high-throughput stream into something predictable: every request has a retry path, every reorg has a recovery path, and every cached value has a known lifetime. This guide covers the four areas that matter most when you connect to https://polygon.therpc.io/YOUR_API_KEY at production scale — reliability of your RPC calls, performance under Polygon's ~2s cadence, security when acting on block data, and maintainability so the code stays correct as your integration grows.

Core Principles

• Reliability: Every interaction with the Polygon RPC must tolerate a slow or failed response without losing data. Treat each eth_getBlock or eth_getTransactionReceipt call as fallible, track the last block you fully processed, and make re-processing the same Bor block idempotent so a retry never double-counts.
• Performance: With a block arriving every ~2 seconds on chain 137, block-heavy workloads live or die on batching and subscriptions. Batch ranged reads, cache immutable block bodies, and subscribe to newBlockHeaders instead of polling so you stay ahead of the chain rather than chasing it.
• Security: Never act on block data until it is deep enough to be safe from a shallow Bor reorg, and validate that the block hash, parent hash, and number form a consistent chain before you mutate state. Cross-check high-value events against a second view of the chain.
• Maintainability: Isolate Polygon-specific logic — confirmation thresholds, MATIC fee handling, checkpoint awareness — behind a small, well-named module so the rest of your codebase is shielded from RPC shapes and a future client upgrade touches one file.
• Error handling: Adopt a fail-soft philosophy: classify errors (transient network vs. permanent RPC error vs. reorg), retry only the transient ones with bounded exponential backoff, and surface the rest loudly rather than swallowing them.

Implementation Guidelines

1// Reliable block fetching with retry mechanism
2const fetchBlockWithRetry = async (blockNumber, maxRetries = 3) => {
3  let retries = 0;
4  while (retries < maxRetries) {
5    try {
6      const block = await web3.eth.getBlock(blockNumber);
7      if (block) return block;
8      throw new Error('Block not found');
9    } catch (error) {
10      retries++;
11      if (retries === maxRetries) throw error;
12      await new Promise((resolve) => setTimeout(resolve, 1000 * retries));
13    }
14  }
15};
16 
17// Safe event handling with error boundaries
18const createBlockListener = (callback) => {
19  return web3.eth
20    .subscribe('newBlockHeaders')
21    .on('data', async (blockHeader) => {
22      try {
23        await callback(blockHeader);
24      } catch (error) {
25        console.error('Block processing error:', error);
26        // Implement your error handling strategy
27      }
28    })
29    .on('error', (error) => {
30      console.error('Subscription error:', error);
31      // Implement your reconnection strategy
32    });
33};

Error Handling

• Retry with bounded backoff: Wrap each Polygon RPC call in a retry loop of 3–5 attempts using exponential backoff (for example 1s, 2s, 4s) with a small random jitter. Because Bor blocks are only ~2s apart, keep the total retry window short — if a read for a recent block fails for more than a few seconds, the chain has likely moved on and you should re-anchor to latest rather than keep retrying a stale height.
• Graceful network interruptions: When the connection drops mid-processing, persist the last fully processed block number and resume from there on reconnect. Never assume the gap was empty — replay every Bor block between your checkpoint and the new latest so no events on chain 137 are skipped.
• Production logging: Log each failure with the method, block number, attempt count, and the error code so you can tell a transient timeout apart from a malformed-response or rate-limit error. Aggregate error rates per endpoint and alert when the failure ratio for https://polygon.therpc.io/YOUR_API_KEY crosses a threshold.
• Fallback providers: Configure at least one secondary Polygon endpoint and fail over when the primary returns repeated errors or stalls behind the chain head. Keep the providers behind a single client wrapper so reads, retries, and confirmation tracking behave identically regardless of which node answered.

Performance Optimization

• Cache immutable data: A finalized Bor block — its hash, timestamp, transactions, and receipts — never changes, so cache it indefinitely once it is several blocks deep. Cache only recent (still-reorgable) heads briefly, with a short TTL of a few seconds, since on Polygon the very tip can still be reorganized before a Heimdall checkpoint anchors it.
• Batch ranged reads: When backfilling or scanning a range, send block and receipt requests in JSON-RPC batches (10–20 per batch is a good starting point) instead of one round trip per block. At ~2s block time the chain produces roughly 43,000 blocks a day, so batching cuts round-trip overhead dramatically and lets you keep pace during catch-up.
• Efficient polling: If you must poll, align the interval with the ~2s Polygon block time, add jitter so many clients do not hit the endpoint on the same tick, and back off when no new block has appeared. Always poll by block number and skip work when latest has not advanced.
• Prefer WebSocket subscriptions: A newBlockHeaders subscription pushes each Bor header the moment it is produced, so you react within Polygon's 2-second window instead of discovering blocks one poll interval late. Subscriptions also cut request volume — one stream replaces continuous polling — which lowers cost and load on https://polygon.therpc.io/YOUR_API_KEY.

Security Considerations

• Validate integrity: Before acting on a Polygon block, confirm that its parentHash matches the hash of the block you previously processed and that block numbers increase by one. A broken parent link is your first signal that a Bor reorg occurred or that a node returned inconsistent data.
• Survive reorgs: Because Polygon reorgs are shallow but real, hold off on irreversible actions until a transaction is buried under enough confirmations, and design state updates so they can be rolled back to the common ancestor if a recently confirmed block disappears. Wait for a Heimdall checkpoint to L1 for anything truly high-value.
• Mitigate replay vectors: Re-processing the same Bor block after a retry or reconnect must not re-trigger side effects, so key every payout, mint, or notification by transaction hash and log index and dedupe against work already done. The risk on Polygon is not a cross-chain replay of signatures but your own pipeline acting twice on one event.
• Monitor anomalies: Watch for block times that drift far from ~2 seconds, sudden gaps in block numbers, a stalled chain head, or an unusually deep reorg — any of these can indicate a node malfunction, a network issue on chain 137, or an endpoint serving a minority fork, and should pause irreversible actions until resolved.

Maintenance

• Health checks: Run a periodic probe that fetches latest from https://polygon.therpc.io/YOUR_API_KEY, compares its number and timestamp against your own clock, and confirms your processor is no more than a few blocks behind the chain head. Flag the pipeline unhealthy if the head stops advancing for more than a handful of ~2s intervals.
• Actionable alerts: Alert on the signals that map to user-visible breakage — processing lag in blocks, RPC error rate, reorg depth, and confirmation latency — rather than raw request counts. A rising lag on chain 137 is the earliest sign your consumers are falling behind real-time.
• Structured reviews: When reviewing block-handling changes, check explicitly for the Polygon-specific traps: missing retry/backoff, no parentHash continuity check, hardcoded confirmation counts, and assumptions that the latest block is final. Require a test that exercises a simulated reorg before merging.

See also

• Syncing Strategies Guide - Optimal synchronization methods
• Chain Reorganization Guide - Handling chain restructuring