What is Polygon finality and how does it affect your dApp?

Quick decision guide: how finality affects your app

Before diving into the mechanics, ask yourself: does your application need to wait for finality before acting? The answer determines your RPC strategy and user experience.

• Payments and settlement: If you're building a payment app, you need to wait for finality to avoid reversals. With Polygon's ~5 second finality, you can show a confirmed state quickly, but you should still check for finality before releasing funds.
• DeFi and trading: For swaps or liquidations, waiting for finality reduces the risk of reorgs, but adds latency. You might choose to accept probabilistic finality for speed, but be prepared to handle reorgs.
• Gaming and NFTs: These can often work with probabilistic finality, but if you're minting rare items, you might want to wait for finality to prevent duplicates.

Next step: If you need to monitor finality, use an RPC provider that offers reliable access to the latest finalized block. OnFinality provides dedicated nodes and RPC endpoints that can help you query finality status efficiently.

What is finality in blockchain?

Finality is the guarantee that a transaction or block cannot be reversed or altered. In blockchain, there are two main types:

• Probabilistic finality: The more blocks are built on top of a transaction, the less likely it is to be reorged. Bitcoin uses this model.
• Deterministic finality: Once a block is finalized, it is irreversible. Ethereum uses Casper FFG, and Polygon uses a milestone mechanism.

Polygon PoS uses deterministic finality, meaning that once a milestone is finalized, the included transactions are permanent.

How Polygon finality works

Polygon achieves finality through two mechanisms: milestones and checkpoints.

Milestones

Milestones provide fast deterministic finality on Polygon itself, without waiting for a checkpoint to be submitted to Ethereum. At every Heimdall height, validators propose the Bor block hashes they have seen since the last finalized milestone, using vote extensions in CometBFT consensus. When finalizing Heimdall height H+1, Heimdall looks for the longest common sequence of block hashes from all validators with 2/3 or more agreement. That sequence is finalized as the new milestone.

With the Heimdall v2 upgrade, block times in Heimdall are 1-2 seconds, so milestones are voted on and finalized much faster. This brings finality to about 5 seconds.

Checkpoints

Checkpoints are periodic snapshots of the Polygon chain state that are submitted to Ethereum. They provide additional security by anchoring Polygon's state to Ethereum, but they are slower (typically every 30 minutes to 1 hour). Checkpoints are not required for finality on Polygon itself, but they are important for cross-chain bridges and other applications that need Ethereum-level finality.

Why finality matters for developers

Understanding finality is critical for building reliable applications. Here are some reasons:

• User experience: If you wait for finality, users may see delays. With Polygon's fast finality, you can provide a better UX.
• Reorg handling: Even with deterministic finality, there can be temporary reorgs before a milestone is finalized. You need to handle these in your application.
• Cross-chain interactions: If you're bridging assets, you need to wait for finality on the source chain before minting on the destination chain.

Querying finality on Polygon

You can query finality status using RPC methods. Here are some examples:

Using curl

To get the latest finalized block, you can use the eth_getBlockByNumber method with the tag finalized:

curl -X POST https://polygon.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["finalized", false],"id":1}'

Using ethers.js

const { ethers } = require('ethers');

const provider = new ethers.JsonRpcProvider('https://polygon.api.onfinality.io/public');

async function getFinalizedBlock() {
  const block = await provider.getBlock('finalized');
  console.log('Finalized block:', block.number);
}

getFinalizedBlock();

Using viem

import { createPublicClient, http } from 'viem';
import { polygon } from 'viem/chains';

const client = createPublicClient({
  chain: polygon,
  transport: http('https://polygon.api.onfinality.io/public'),
});

const block = await client.getBlock({ blockTag: 'finalized' });
console.log('Finalized block:', block.number);

Monitoring finality and handling reorgs

Even with fast finality, you should monitor for reorgs, especially if you're building high-value applications. Here are some tips:

• Track the latest finalized block: Poll the finalized tag and compare it to the latest block. If the difference is large, there might be an issue.
• Use WebSocket subscriptions: Subscribe to newHeads and listen for reorgs by tracking block hashes.
• Set up alerts: Use monitoring tools to alert you if finality is delayed or if there are deep reorgs.

Example WebSocket subscription

const WebSocket = require('ws');
const ws = new WebSocket('wss://polygon.api.onfinality.io/public');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_subscribe',
    params: ['newHeads'],
    id: 1
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  if (message.method === 'eth_subscription') {
    const block = message.params.result;
    console.log('New block:', block.number, block.hash);
  }
});

Finality and RPC provider selection

When choosing an RPC provider for Polygon, consider how they handle finality-related queries and reorgs. Here's a comparison:

OnFinality offers both public and dedicated endpoints, allowing you to scale as needed. For production apps, consider a dedicated node for more consistent performance.

Common pitfalls and troubleshooting

• Not waiting for finality: If you don't wait for finality, you risk accepting transactions that might be reorged. Always check the finalized tag for critical operations.
• Using the wrong block tag: Some RPC providers may not support the finalized tag. Make sure your provider does.
• Ignoring reorgs: Even with deterministic finality, there can be temporary reorgs. Monitor for them.
• RPC rate limits: Public endpoints may have rate limits. For high-throughput applications, use a dedicated node.

Key Takeaways

• Polygon finality is now about 5 seconds thanks to the Heimdall v2 upgrade.
• Finality is deterministic via milestones, with checkpoints providing additional security on Ethereum.
• Developers should query the finalized tag to ensure transactions are irreversible.
• Choose an RPC provider that supports finality queries and WebSocket subscriptions, like OnFinality.
• Monitor for reorgs and set up alerts to maintain application reliability.

Frequently Asked Questions

What is the difference between probabilistic and deterministic finality?

Probabilistic finality means there is a chance of reorganization, while deterministic finality means once a block is finalized, it cannot be reverted. Polygon uses deterministic finality via milestones.

How long does Polygon finality take?

With Heimdall v2, finality is achieved in about 5 seconds, down from 1-2 minutes previously.

Do I need to wait for finality on Polygon?

It depends on your application. For payments and high-value transactions, yes. For casual interactions, you might accept probabilistic finality.

How can I check if a transaction is finalized?

You can use the eth_getTransactionReceipt method and check the block number against the latest finalized block. Alternatively, use the finalized tag in eth_getBlockByNumber.

What is a checkpoint?

A checkpoint is a snapshot of Polygon's state submitted to Ethereum. It provides additional security and is used for cross-chain bridges.

Does OnFinality support Polygon finality queries?

Yes, OnFinality's Polygon RPC endpoint supports the finalized tag and WebSocket subscriptions. For more details, see the Polygon network page.