Skip to main content

Transaction states, hashes and safe recovery

Keep success states distinct​

StageValid displayInvalid conclusion
User confirmationAuthorized; preparing construction or signaturePaid
Transaction hash obtainedBroadcast / awaiting confirmationRecipient credited
Successful included receiptExecution succeeded on-chainEvery business confirmation condition is met
Required native confirmation reachedThe actual included / safe / finalized factConfirmation inferred solely from elapsed time
Wallet reconciledInputs, outputs and reservations checkedMerchant fulfillment is complete
Merchant Checkout succeededThe session met its required conditionsRefunds 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​

SituationAction
Signature rejected before submissionReturn to editing; do not create on-chain success
Allowance succeeded but payment did notCheck existing allowance and the original operation before requesting another approval
Hash exists but waiting timed outQuery that hash and account state; resume the original operation, not a second payment
One RPC reports no transactionCheck another trusted node; do not immediately release inputs
Receipt succeeded but inventory is staleResume syncing and reconciliation instead of paying again
Confirmation or block identity changedRevalidate 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.