"Reorgs" and Associated Risks

In blockchain networks, transactions are grouped into blocks. Each blockchain has specific rules for determining which transactions are included in a block, along with criteria for invalidating recently created blocks if necessary.

This rewrite of history, known as a "reorganization" (or "reorg"), invalidates the transactions within the affected blocks, returning any transferred funds to their original owners. Such events pose a security risk, as an attacker could use a cryptocurrency transfer to pay for a good or service, then initiate a reorg to reverse the transfer, reclaiming their cryptocurrency while keeping the good or service. Cryptocurrency exchanges have lost hundreds of millions of dollars in these types of attacks, often called "51% attacks" after the method typically used.

Confirmations

To protect against reorg attacks, you can wait a specified number of blocks before acknowledging a transfer as final. Each additional block added after a transaction block increases the difficulty and as such reduces the likelihood that the original block will be invalidated. By selecting the number of blocks to wait before recognizing a transfer, receivers can balance speed (accepting a transfer quickly with minimal waiting of a few blocks, while increasing the risk of loss from a reorg) and security (waiting longer for more blocks to reduce reorg risk, but with slower transaction processing).

This waiting period, known as the "confirmation number," varies by blockchain. The Interlace APIs apply specific confirmation numbers for each supported chain.

Confirmations and Transfer Status

Once an incoming transfer is included in a block, the API will make it accessible to you, whether through polling the get transfers endpoint or by subscribing to notifications. However, the transfer will initially have a running status, and the associated hosted wallet balance will not be credited with the transfer amount until the required number of confirmations is achieved.

Once the necessary confirmations are reached, the transfer status will change to completed. If you have subscribed to notifications, you will receive an update indicating this status change.

While you may choose to consider an incoming transfer as completed before the status officially changes, allowing you to proceed with any dependent business processes, please be aware that this comes with risks. If a reorg occurs before the required confirmations are met, you might not receive the funds at all.