Transaction states, hashes and safe recovery
Keep success states distinct
| Stage | Valid display | Invalid conclusion |
|---|---|---|
| User confirmation | Authorized; preparing construction or signature | Paid |
| Transaction hash obtained | Broadcast / awaiting confirmation | Recipient credited |
| Successful included receipt | Execution succeeded on-chain | Every business confirmation condition is met |
| Required native confirmation reached | The actual included / safe / finalized fact | Confirmation inferred solely from elapsed time |
| Wallet reconciled | Inputs, outputs and reservations checked | Merchant fulfillment is complete |
| Merchant Checkout succeeded | The session met its required conditions | Refunds and additional receipts have been handled |
Keep the hash when a receipt explicitly reports rollback. A network timeout is an unknown result, not proof of financial failure. See state terminology and merchant payment lifecycle.
Persist recovery information
Before submission, save a stable operation ID, account, network, asset and intent. Associate the hash immediately after submission, not after confirmation. Encrypt private inventory, complete Notes and recovery material; exclude them from public analytics logs.
If a hash is available before indexing catches up, display a local pending record with an explorer link. Not indexed does not mean nonexistent. Merge server records by stable operation/output identities when they arrive rather than showing a duplicate payment.
One hash can contain several outputs
A private transaction may include both a recipient output and a payer remainder. A list can show a business summary, but details must distinguish asset, ownership and available actions. Access to the payer's own remainder does not grant access to the recipient's funds.
Do not match ordinary transfers and private outputs merely by amount or time. Display initiation and arrival/confirmation times, network, actual network fee and public hash where available. Show private fields only with the required account capability.
Recovery decisions
| Situation | Action |
|---|---|
| Signature rejected before submission | Return to editing; do not create on-chain success |
| Allowance succeeded but payment did not | Check existing allowance and the original operation before requesting another approval |
| Hash exists but waiting timed out | Query that hash and account state; resume the original operation, not a second payment |
| One RPC reports no transaction | Check another trusted node; do not immediately release inputs |
| Receipt succeeded but inventory is stale | Resume syncing and reconciliation instead of paying again |
| Confirmation or block identity changed | Revalidate against the canonical chain rather than retaining a stale terminal conclusion |
See WalletSession for recovery. HTTP idempotency rules do not replace on-chain nonce management, input reservations or order-level fulfillment deduplication.