Transaction State

Overview

How it works

The lifecycle starts before broadcast. An application can create an unsigned transaction, collect approvals, sign it, and submit it. The receiving provider may return a hash even though the transaction has not propagated widely.

Pending state can include mempool acceptance, sequencer receipt, or a local queue. Account nonce gaps, low fees, invalid state, or provider outages can delay progress. A replacement can supersede the original while preserving the same nonce or business intent.

Inclusion means a block contains the transaction. Execution status determines whether it succeeded. Confirmations or protocol checkpoints advance it toward finality. Reorganizations can remove the block and return the transaction to pending or dropped state.

Applications should store state transitions with timestamps, block hashes, provider observations, and reason codes. A single mutable label loses important history. Conflicting provider states should produce review or uncertainty rather than an unsupported definitive result.

Transaction state is technical. Payment state adds asset matching, amount, invoice expiration, and merchant policy. Order state includes fulfillment and customer service. Keeping these models linked but separate prevents a successful blockchain transaction from completing the wrong business workflow.

State names should be normalized across providers but not oversimplified. One network’s `processed` status may be weaker than another’s `confirmed`, and a sequencer acknowledgment differs from base-layer settlement. Internal records should retain raw provider and protocol values alongside the normalized state. This allows policies to change without losing technical evidence and prevents a future integration from treating incompatible states as equivalent. Unknown or conflicting states should be represented explicitly rather than forced into a misleading success or failure label.

What matters in practice

A transaction may move from constructed to signed, submitted, pending, included, confirmed, replaced, reverted or rejected, depending on chain and wallet implementation. These are observations over time, not a single permanent database field. A wallet that says 'pending' may mean not broadcast, seen in a mempool, or included but below its safety threshold. Store timestamps, transaction identifiers, block references and evidence for each transition; allow re-evaluation when a chain reorganizes. If a user sees a timeout while submitting, first query the network before trying another payment.

Related glossary concepts

Transaction; Account Nonce; Invoice Expiration