Blockchain Confirmations

This guide provides an overview of blockchain confirmations and their significance in ensuring the security of transactions. It discusses the concept of blockchain reorganizations and their potential associated risks. By waiting for confirmations, developers can protect against reorg attacks and ensure the validity of on-chain transactions.

Blockchain Transactions and Reorganizations

Transactions in a blockchain are grouped into blocks, each containing a set of transactions. Different blockchains have distinct rules for selecting which transactions are included in a block. Occasionally, recently generated blocks may be invalidated, resulting in a rewrite of the transaction history known as a "reorganization" or "reorg" for short. Such reorganizations invalidate any transactions in the invalidated blocks, essentially treating them as if they "never happened".

Reorganizations pose a security risk as attackers could exploit them by initiating a cryptocurrency transaction as payment for a good or service and triggering a reorg. This action would invalidate the transaction while allowing the attacker to retain the goods or services received.

The Importance of Confirmations

To mitigate the risk of reorg attacks, it is recommended to wait for several confirmed blocks before considering a transaction as valid. With each additional block added to the blockchain, the difficulty of invalidating previous blocks increases. By choosing the number of blocks to wait for, developers can balance transaction processing speed with the security of avoiding reorg-related losses.

The number of blocks to wait before deeming a transaction valid is called the "confirmation number". It is important to note that confirmation numbers may differ across different blockchain networks. Web3 Services and its APIs utilize specific confirmation numbers for each supported chain, considering factors such as historical performance, potential reorganizations, and overall network architecture.

Confirmation Numbers for Supported Chains

The following table showcases the confirmation numbers used by Web3 Services and its APIs for each supported chain. Please note that these numbers are based on Circle's considerations and may not reflect the inherent requirements or limits of the blockchain networks themselves.

Polygon PoS Confirmation Number

For transactions on Polygon PoS, Circle's platform requires 50 confirmations before considering them as complete. This process generally takes around 2 minutes. The chosen confirmation number represents three times the number of confirmations needed for sufficient transaction finality, based on the largest reorg observed thus far.

Confirmations and Transaction Status

As soon as an incoming transaction is included in a block, Web3 Services API enables access to the transaction details by polling the "get transaction endpoint" or subscribing to notifications. The transaction will start with a confirmed status and update the wallet's balance. If the confirmed balance is utilized for a transaction, be aware that there is a possibility that the transaction might be reversed as a result of blockchain reorganization.

Once the required confirmations have been obtained, the transaction status will change to completed. Developers who have subscribed to notifications will receive a message indicating this status change.

It is essential to note that considering an incoming transaction as completed before the status change can be risky, as the funds may not be received if a reorg occurs before the required number of confirmations is reached.

By following these guidelines and understanding the importance of blockchain confirmations, you can enhance the security and reliability of your applications when dealing with blockchain transactions.