Polygon PoS Transaction Finality and App Crediting
How many confirmations to wait on Polygon PoS before crediting? Use Bor’s finalized block tag, verify the receipt and block hash, and separate deposits from exits.
Onchain Daily Newsroom5 min read

Credit a Polygon PoS transaction when its block is at or below Bor’s finalized block, after verifying a successful receipt and the canonical block hash. Polygon PoS milestones provide deterministic finality within seconds, so a fixed confirmation count adds delay without giving the app a stronger rule.
This rule applies to a transaction being credited on Polygon PoS, such as a deposit that increases a user’s app balance. A Polygon-side deposit made through the Polygon bridge is a useful case because the destination-side credit can be tied to Bor’s finalized block, while a later exit to Ethereum follows a separate checkpoint requirement.
Use the finalized block as the crediting threshold
For Polygon PoS crediting, compare the transaction’s block number with the block returned by eth_getBlockByNumber('finalized'). Bor supports the finalized block tag, and Heimdall milestones finalize Bor blocks. Once the transaction’s block is at or below that finalized height, its block has deterministic finality under the Polygon PoS consensus process.
The comparison is a threshold, not a request to wait a set number of blocks after inclusion. A transaction can be included in a Bor block before that block becomes finalized. The app should wait for the finalized height to reach that block, then perform its receipt and hash checks before crediting.
Use these inputs and outcomes in the crediting path:
- Transaction receipt: Fetch the receipt by transaction hash. A missing receipt means the transaction is still pending or the RPC cannot report it, so do not credit. Require status to equal 1; a failed transaction has no successful execution to credit.
- Receipt block number: Read the block number from the receipt. Query eth_getBlockByNumber('finalized'); crediting is eligible only when the finalized block number is greater than or equal to the receipt’s block number.
- Canonical block hash: Fetch the block at the receipt’s height using eth_getBlockByNumber with that block number, then compare its hash with the receipt’s block hash. If they differ, do not credit from that receipt; resolve the transaction against the current canonical chain.
- RPC response: Treat unavailable, malformed, or unsupported finalized-tag responses as a failure to establish finality. Retry or alert through the app’s normal RPC failure path, and make no credit until the required values are available and consistent.
A successful result is therefore specific: a receipt exists, its status is successful, its block is finalized, and the hash at that height matches. These checks make the app’s decision auditable and keep a transient RPC or reorganization issue from turning into an incorrect balance update.
A fixed confirmation count is simpler to describe, but it is a guess about how deep a reorganization might reach. Waiting for more confirmations delays users, and choosing a larger count does not establish the same deterministic finality condition as the finalized tag. The tag takes slightly more implementation care because the app must handle RPC failures and compare the receipt’s block data, but it gives the crediting rule a protocol-defined stopping point.
Keep Polygon finality separate from Ethereum checkpoints
Polygon PoS finality and checkpoint inclusion on Ethereum answer different questions. A milestone finalizes Bor blocks on Polygon PoS; a checkpoint records Polygon block information on Ethereum. A checkpoint is relevant when a bridge operation must release funds on Ethereum, not as an extra prerequisite for crediting a Polygon-side deposit.
Waiting for a checkpoint before increasing an app balance for a finalized Polygon deposit adds delay without improving the safety of that Polygon-side credit. For a Polygon bridge flow, identify which chain the app is crediting: a deposit credited on Polygon uses the finalized-tag rule, while an exit that releases funds on Ethereum must wait for the checkpoint. The destination chain determines the required signal.
Choose a fixed confirmation count only when a legacy integration cannot expose the finalized tag, and document that the count is a latency-versus-risk approximation rather than a finality guarantee. Choose the finalized block tag when crediting on Polygon PoS and the RPC endpoint supports it. Choose checkpoint inclusion when the app is releasing funds on Ethereum through the bridge. This keeps reorg safety, delay, and implementation effort tied to the operation that is actually being settled.
Related
How long does a Polygon transaction take to confirm?
A Polygon transaction is included when Bor produces a block containing it; finality follows when Heimdall milestones finalize that block. The time varies with when the transaction is included and when the next milestone finalizes its block, so an app should use the finalized response rather than hard-code a duration.
What is a reorg on Polygon PoS?
A reorg changes which blocks are on the canonical chain, which is why a receipt’s block hash should be checked against the block at the same height. Once the block is finalized by a milestone, Polygon PoS finality means a reorg cannot remove it; before then, the app should not treat inclusion alone as final.
Implement the finalized-height comparison and receipt checks in the crediting path, then test its retry behavior against unavailable RPC responses. That gives the app a clear, repeatable point to credit Polygon deposits while preserving checkpoint waiting for Ethereum releases.