Block Confirmations

On Polygon PoS a transaction is included in a Bor block within about 2 seconds, but inclusion is not the same as finality — the tip of the chain can still be reorganized until a Heimdall checkpoint anchors it to Ethereum L1. Counting confirmations is how you bridge that gap: each additional block built on top of the one holding your transaction makes a reversal less likely, and a checkpoint makes it effectively impossible. This guide shows how to count confirmations against https://polygon.therpc.io/YOUR_API_KEY, choose thresholds that match the value at stake in MATIC, and wait for the right level of finality before you treat a transaction on chain 137 as done.

Understanding Confirmations

What a confirmation is: A confirmation is one block built on top of the block that contains your transaction. If your transaction landed in block N and the chain head is at block M, it has M − N confirmations — exactly what the getConfirmations example computes from eth_getTransaction and eth_getBlockNumber.
Why they matter: A transaction with zero or one confirmation sits at the reorgable tip and could be dropped if Bor reorganizes that height. Each added confirmation buries it deeper and raises the cost of reversal; enough confirmations — and ultimately a Heimdall checkpoint to Ethereum — turn "probably settled" into "settled".
Recommended counts on Polygon: Scale the threshold to value. A few confirmations suffice for low-value MATIC transfers or UI feedback; tens of blocks for medium-value flows; and for high-value settlement, wait until the block is included in a Heimdall checkpoint, after which it is effectively irreversible on L1. Higher value means a deeper, more expensive reorg is needed to undo it, so demand more confirmations.
Mainnet vs. testnet: Mainnet (chain ID 137) carries the full validator set and real checkpoint cadence, so its confirmation guarantees are the ones to plan around. The Amoy testnet behaves similarly in mechanics but offers no economic security — use it to exercise your confirmation logic, never to gauge real-world finality, and keep your production thresholds tuned to mainnet.

Implementation Examples

1// Check number of confirmations
2const getConfirmations = async (txHash) => {
3  const tx = await web3.eth.getTransaction(txHash);
4  const currentBlock = await web3.eth.getBlockNumber();
5  return tx.blockNumber ? currentBlock - tx.blockNumber : 0;
6};
7 
8// Wait for specific number of confirmations
9const waitForConfirmations = async (txHash, confirmations = 6) => {
10  while ((await getConfirmations(txHash)) < confirmations) {
11    await new Promise((resolve) => setTimeout(resolve, 1000));
12  }
13  return true;
14};

Security Considerations

Thresholds by value: Tie the confirmation count to the MATIC value at risk — a few blocks for small transfers, tens for medium amounts, and a Heimdall checkpoint for large settlement. The deeper a transaction is buried, the more economically infeasible a reversal becomes, so the threshold should rise with the cost of being wrong.
Handle invalidation: If a reorg drops a transaction you had already counted as confirmed, re-fetch its receipt; a null receipt or a changed blockNumber means it was orphaned. Roll back any state you derived from it, then either wait for it to be re-mined or resubmit it, deduping by transaction hash so you never apply the effect twice.
Network factors: Required counts on Polygon depend on the ~2s block time (confirmations accrue quickly, so waiting is cheap in wall-clock terms), the shallow-but-real Bor reorg depth, and the periodic Heimdall checkpoint interval that bounds true finality. Account for all three when picking a threshold for chain 137.
Monitor progress: In production, track confirmation depth per pending transaction by polling against https://polygon.therpc.io/YOUR_API_KEY or subscribing to new headers, surface the count to users, and alert if a transaction stops gaining confirmations — a sign it was dropped from the mempool or orphaned by a reorg.

What a confirmation is: A confirmation is one block built on top of the block that contains your transaction. If your transaction landed in block N and the chain head is at block M, it has M − N confirmations — exactly what the getConfirmations example computes from eth_getTransaction and eth_getBlockNumber.

Why they matter: A transaction with zero or one confirmation sits at the reorgable tip and could be dropped if Bor reorganizes that height. Each added confirmation buries it deeper and raises the cost of reversal; enough confirmations — and ultimately a Heimdall checkpoint to Ethereum — turn "probably settled" into "settled".

Recommended counts on Polygon: Scale the threshold to value. A few confirmations suffice for low-value MATIC transfers or UI feedback; tens of blocks for medium-value flows; and for high-value settlement, wait until the block is included in a Heimdall checkpoint, after which it is effectively irreversible on L1. Higher value means a deeper, more expensive reorg is needed to undo it, so demand more confirmations.

Mainnet vs. testnet: Mainnet (chain ID 137) carries the full validator set and real checkpoint cadence, so its confirmation guarantees are the ones to plan around. The Amoy testnet behaves similarly in mechanics but offers no economic security — use it to exercise your confirmation logic, never to gauge real-world finality, and keep your production thresholds tuned to mainnet.

Implementation Examples

1// Check number of confirmations
2const getConfirmations = async (txHash) => {
3  const tx = await web3.eth.getTransaction(txHash);
4  const currentBlock = await web3.eth.getBlockNumber();
5  return tx.blockNumber ? currentBlock - tx.blockNumber : 0;
6};
7 
8// Wait for specific number of confirmations
9const waitForConfirmations = async (txHash, confirmations = 6) => {
10  while ((await getConfirmations(txHash)) < confirmations) {
11    await new Promise((resolve) => setTimeout(resolve, 1000));
12  }
13  return true;
14};

Security Considerations

Thresholds by value: Tie the confirmation count to the MATIC value at risk — a few blocks for small transfers, tens for medium amounts, and a Heimdall checkpoint for large settlement. The deeper a transaction is buried, the more economically infeasible a reversal becomes, so the threshold should rise with the cost of being wrong.

Handle invalidation: If a reorg drops a transaction you had already counted as confirmed, re-fetch its receipt; a null receipt or a changed blockNumber means it was orphaned. Roll back any state you derived from it, then either wait for it to be re-mined or resubmit it, deduping by transaction hash so you never apply the effect twice.

Network factors: Required counts on Polygon depend on the ~2s block time (confirmations accrue quickly, so waiting is cheap in wall-clock terms), the shallow-but-real Bor reorg depth, and the periodic Heimdall checkpoint interval that bounds true finality. Account for all three when picking a threshold for chain 137.

Monitor progress: In production, track confirmation depth per pending transaction by polling against https://polygon.therpc.io/YOUR_API_KEY or subscribing to new headers, surface the count to users, and alert if a transaction stops gaining confirmations — a sign it was dropped from the mempool or orphaned by a reorg.

Block Confirmations

Understanding Confirmations

Implementation Examples

Security Considerations

See also

Pronto para usar isso em produção?

Block Confirmations

Understanding Confirmations

Implementation Examples

Security Considerations

See also