Confirmation Tracking

Overview

Understand the idea

A tracker begins by locating the transaction through a node, indexer, or provider. Before inclusion, it may inspect mempool status, fee competitiveness, nonce dependencies, or replacement activity. After inclusion, it records the block hash and calculates confirmations against the current canonical tip.

Each new block can increase confidence, but the tracker must detect when the original block is no longer canonical. It may then reduce confirmations, locate the transaction in a replacement block, or return it to pending status. For smart-contract transactions, it should also verify execution success and relevant event logs.

What actually happens

A payment can be visible to nodes long before it is included in a block. Confirmation tracking records when a transaction becomes included and how its assurance changes afterward. On a Bitcoin-style chain, the block containing a transaction counts as the first confirmation; new blocks on the accepted history increase its depth. On other systems, the relevant measure may be protocol finality checkpoints rather than a simple block count. The tracking system must therefore know the precise network and its consensus rules.

The monitor begins with a transaction identifier and expected recipient or contract event. It checks the transaction's current inclusion, its block identifier and the current chain head. A chain reorganization can remove an inclusion, so the monitor must allow the tracked count to fall or become pending again. A good implementation stores observations with timestamps and evidence, rechecks independently and uses a defined threshold before marking an order eligible for fulfillment. If confirmations stall, it should report pending—not invent a failure.

Decisions and failure cases

A confirmation count is not a universal guarantee. Finality and the cost of reversing a transaction differ across chains and can depend on attack models, validators, checkpoints and bridge rules. Tracking only the count without verifying destination, asset and amount allows confidently confirmed wrong payments. Repeated polling should also tolerate node failures, indexer lag and duplicate notifications.

Related concepts

Confirmation, Payment State Tracking, Confirmation Latency.

Further reading

Bitcoin Developer Guide.