Canonical Transaction

Overview

A canonical transaction appears in a block that the network currently recognizes as part of accepted history. A transaction seen in the mempool, a proposal, or a non-canonical block does not meet this condition even if its signature and execution were otherwise valid.

Canonical inclusion can remain reversible near the chain head. A reorganization may remove the containing block and return the transaction to the mempool, replace it with a conflicting transaction, or leave it absent from the new branch. Payment systems should store transaction hash, block hash, position, execution status, and confirmation or finality evidence. They must not equate canonical with successful because a reverted smart-contract call can be canonically included. Settlement policy should require both successful execution and sufficient permanence.

Repeated callbacks, node disagreements, reorganization, and delayed receipts must not create duplicate credits or irreversible state transitions before the required network evidence is available. Implementations need idempotent processing keyed to stable transaction and business identifiers. Operational records should retain the raw transaction, network identifier, sender and destination, asset and amount, block reference, execution status, and observed timestamps. These records allow a later rescan to reconstruct the result when an endpoint, webhook, or local index becomes unreliable.

Unknown, pending, included, failed, replaced, and finalized conditions need separate handling, together with a recovery procedure for transactions whose observed state conflicts across providers. Status labels should describe what is known without overstating settlement. Implementation note: Canonical transactions belong to accepted history, but payment settlement also requires successful execution and adequate finality.