23.38. DD 37: Wallet Transaction Lifecycle

Design status:

Accepted

Implementation status:

Implemented

DD shepherd:

TBD

Historical contributors:

Sebastian, Özgür Kesim, Christian Grothoff, Florian Dold

First published:

2023-02-13

Last substantive change:

2026-09-07

Normative references:

Wallet-Core API Documentation

23.38.1. Summary

This document describes the transaction lifecycle exposed by wallet-core: what a transaction is doing, what lets it progress, and which actions a frontend can request. It defines the common state model and the meaning of each transaction’s stages without prescribing screen layouts or translated strings.

Transactions in the same state can have different available actions, depending on their type and circumstances. Frontends must use the returned txActions rather than reconstruct permissions from the state name.

23.38.2. State notation and public data

States are written as major[:minor][/working]. For example, dialog:proposed, pending:withdraw/working, pending:kyc, and done. Diagram labels may wrap after a colon or before /working; the line break is not part of the state string. The colon and minor component are omitted when there is no minor state; /working is appended only when txState.working is true.

/working signals that the transaction is in an active processing phase. UIs typically show a loading indicator during this phase and keep it until the flag clears. Processing includes time spent awaiting HTTP responses or retry delays; the flag does not measure instantaneous CPU or network activity. When it clears, the UI renders the resulting state: often a pending wait for an external event, a dialog requiring a user decision, or a finalizing or terminal outcome. Clearing /working does not imply successful completion.

A pending transaction without /working generally waits for a condition to change. Wallet-core may still poll, send requests, and resume processing automatically once that condition changes. Finalizing work can likewise continue without an active loading indicator. The flag describes one transaction’s processing phase for presentation, not overall wallet activity.

For example:

• pending:withdraw/working: active withdrawal processing, typically shown with a loading indicator.

• pending:exchange-wait-reserve: waiting for funding while polling the exchange.

• dialog:proposed: waiting for a user decision.

• finalizing:track: background tracking of bank delivery.

• done: completion.

In a state expression, /idle matches working being false or absent. It can therefore match dialog and terminal states as well as pending waits; it is not a separate lifecycle stage. Omitting the qualifier from a state expression accepts either value of working. A displayed state simply omits the suffix when the flag is false or absent; it does not append /idle.

State expressions select states; they are distinct from the concrete state labels in the tables and diagrams. An expression with an omitted minor component matches any minor: pending is equivalent to pending:*. Use pending:- to match only a pending state with no minor component. Thus pending/idle selects pending states whose working flag is false or absent, regardless of their minor. pending:kyc/idle selects only the operation-KYC wait. * matches any major or minor component, and comma-separated expressions select any of their alternatives.

The working flag is primarily transitional. A future lifecycle model may express the distinction between active processing and waiting through separate major states instead of this flag and its /working and /idle qualifiers. This document describes the current representation; the future major-state names and migration are not specified here.

Use the major state to identify suspension and txActions to determine available actions. A suspended major state takes precedence over the processing hint: render the transaction as paused even if working is still true. The processing hint does not grant action permissions.

The tables below group states with shared behavior and list each family’s members in the left column. The same public state can appear in different contexts with different actions. Diagrams show selected paths; their conceptual groups are explicitly labeled. They omit repeated retry and suspension edges, and do not imply that every transaction visits every node.

23.38.3. Using lifecycle data in a UI

Read type, txState, txActions, and the transaction details together. The type and minor state explain the operation, the major state determines its lifecycle stage, and working guides the loading indicator. Translate these into user-facing descriptions rather than displaying state expressions as the ordinary status text. For an unfamiliar minor state, retain the major-state presentation and use the returned actions and details.

Field	Meaning
txState.major / minor	Lifecycle stage and optional operation-specific detail. Minor states also occur in dialog, finalizing, suspended, and terminal stages.
txState.working	An active-processing hint used for loading indicators, as described above. It does not measure progress or determine action permissions.
txActions	Currently advertised generic actions: retry, suspend, resume, abort, fail, and delete. The API checks availability again when an action is requested.
error	Details of an attempt that encountered an error. A recoverable network error does not itself make the transaction failed.
abortReason / failReason	Reasons for abandoning the original operation or for failure, where supplied. Consult these and the transaction-specific details to distinguish recovery outcomes.
amountRaw	Transaction amount before fees or extra costs.
amountEffective	Amount shown at confirmation, including estimated fees. It is preserved if the operation fails, expires, or is aborted.
amountEffectiveFinal	Settled wallet balance effect when known, including fees and recovery. It is nonnegative; the transaction type determines debit or credit. Absence means that the amount is not yet settled or cannot be established, not that its value is zero.

Use the settled amount to describe the actual wallet balance effect when it is available, and distinguish it from the original confirmation amount. State alone does not establish how much value was delivered, recovered, or lost. A wallet balance effect also does not establish receipt of a bank transfer by the counterparty. Ordinary merchant refunds remain separate credit records.

After a transaction-state-transition notification, refresh the affected transaction’s details and actions. The notification is a reason to refresh, not a replacement for the full transaction. A deleted transition removes the entry from the UI; a lookup may also find that it has already disappeared. Fetch current data when reopening a screen or reconnecting to wallet-core, since the UI may not have observed every transition. After requesting an action, display the resulting state rather than assuming the action completed the transaction.

Accepting a proposed transaction uses its transaction-specific confirmation action. These confirmations, following a bank confirmation URL, visiting a KYC URL, and making a bank transfer are separate from the generic transaction actions.

23.38.4. Common States

Major state	Meaning
dialog	A proposal or choice is waiting for the user, or an order is waiting for another wallet. It is not a terminal state.
pending	The requested operation has more work to do. It may be actively processing or waiting for the bank, exchange, another wallet, or KYC.
finalizing	Post-processing or recovery remains. Payment auto-refund monitoring and deposit tracking use this stage, but so does hard-limit recovery of an unsuccessful operation. It does not universally mean success.
aborting	The wallet is reconciling or recovering an operation that was aborted or expired. Cancellation can race with successful completion.
suspended	The pending operation is paused and may be resumed. This is not an aborted or failed outcome.
suspended-aborting / suspended-finalizing	Paused abort processing or finalizing work.
done	Successful completion of this transaction record. Subsequent explicit operations, such as requesting a refund or restoring a payment session, can make a payment active again.
aborted	The original operation was abandoned. Recovery and partial effects must be read from the transaction details.
failed	Processing ended unsuccessfully. This alone does not imply that all funds were lost.
expired	The operation ended because its validity period elapsed, after any required cleanup.
none / deleted	Notification-only endpoints: creation has no preceding state, and deletion has no remaining transaction history entry.

The final states are done, aborted, failed, expired, and deleted. Here, final means that ordinary processing of the transaction has ended; an explicit later operation may reactivate it. Suspended states, dialog, and finalizing are not final.

Common lifecycle: selected paths, with operation details omitted.

23.38.5. Common Transitions

Action	Effect when advertised
retry	Reset the associated task so another attempt can run without waiting for its existing retry delay. It does not approve a proposal, bypass KYC, or guarantee progress.
suspend	Pause processing while retaining the ability to resume. The usual major-state pairs are pending/suspended, aborting/suspended-aborting, and finalizing/suspended-finalizing.
resume	Restore the corresponding active operation. The minor state normally identifies the work to resume.
abort	Abandon the requested operation, possibly after reconciliation, purse deletion, refunds, or refreshes. It can finish successfully if the counterparty already completed the operation.
fail	Stop the operation in failure without completing further recovery. It is different from abort and can leave funds unrecovered.
delete	Remove the history record according to its transaction-specific cleanup rules. It does not reverse payments, erase already withdrawn coins, or substitute for refund or abort.

Actions are not universal even within one major state. For example, deposit KYC before submission does not advertise retry, while aggregate KYC does; refund records advertise only delete, even while pending. Some finalizing records allow deletion, but hard-limit recovery normally allows only retry. The operation tables below specify these differences. A state can change between reading it and requesting an action; refresh the transaction when wallet-core rejects a now-unavailable action.

23.38.6. KYC and balance limits

The exchange’s KYC/AML design is described in DD 23: Taler KYC; endpoint contracts are in Exchange RESTful API.

Public state	Meaning and continuation
pending:kyc-init/working	Wallet-core is obtaining KYC details or initializing wallet balance authorization. This is used by withdrawals, deposits, and P2P credits. There is not yet a usable KYC continuation just because a transaction has entered this state.
pending:kyc	Operation-specific KYC has an access token. Wallet-core supplies a KYC URL and polls the exchange. Used for withdrawal, deposit/aggregation, and P2P merge requirements.
pending:balance-kyc	A withdrawal or P2P credit would exceed the authorized wallet balance at the exchange. Wait for authorization or for a balance change that makes the incoming amount permissible.
pending:kyc-auth	A direct deposit requires proof of control of its target bank account. Follow kycAuthTransferInfo to make a transfer from that account to the exchange. Token access can then become available for ordinary KYC.
finalizing:kyc-hard-limit/working	An operation exceeded a hard limit. Wallet-core performs operation-specific cleanup; passing ordinary KYC cannot raise that hard limit.
failed:kyc-hard-limit	The original operation failed after hard-limit handling. Inspect failReason and recovery details; this state does not by itself establish successful return of funds.

Ordinary KYC waiting has suspended counterparts with the same minor component. Paused deposit recovery can expose suspended-finalizing:kyc-hard-limit. There is no public merge-kyc, withdraw-kyc, or aml minor state. Merge KYC is exposed as kyc-init or kyc. Exchange aml_review influences polling; wallet-core does not expose a separate transaction state distinguishing staff review from a user-interactive check. Consequently, pending:kyc does not prove that further user input is needed.

Shared KYC flow: selected waiting paths; return to the interrupted operation.

The KYC diagram shows common paths, not a compulsory sequence. An operation can start with known authorization, retry directly, or move back through initialization. A bank-account authentication request can also arise after ordinary deposit KYC has already started.

23.38.6.1. KYC data and polling

kycUrl identifies the exchange’s KYC web interface. Treat it as a continuation for a transaction whose KYC details are available, not as proof that KYC succeeded. Offer the supplied URL when the transaction is waiting in kyc or balance-kyc and the URL is available. During kyc-init, show that KYC details are being obtained; the presence of a URL alone does not establish that initialization is complete. Do not construct a continuation URL from state names. The KYC access token grants access to the account’s KYC process and is not a user-facing identifier.

kycAuthTransferInfo.debitPaytoUri specifies the account that must send the authentication transfer; a transfer from another account will not authenticate it. accountPub identifies the account key. Prefer transferOptionsExt: it groups transfer instructions, amounts, and expiry by exchange credit account. Use the supplied account-specific instructions and amounts for the authentication transfer.

Wallet-core monitors the exchange’s authorization status and rechecks whether the operation can proceed as authorization, limits, or the balance change. The UI does not need to poll the exchange itself. When the user returns from the KYC page, refresh the transaction and show its current state. Merely closing that page does not complete a transaction, and continued KYC waiting does not necessarily mean that the user must submit information again.

An account’s KYC status can include limits that still restrict the particular operation. Wallet-core evaluates the operation, projected balance, and relevant transaction volume against these limits. A hard limit may also reject an operation during preparation, before a transaction is created.

Balance authorization is shared by transactions at the same exchange. It covers the projected wallet balance after the incoming operation, including value awaiting refresh. Fees do not increase that coin balance. Use the balance and limit information supplied by wallet-core for explanations; reconstructing it from the visible transaction list can miss relevant value or account-specific limits.

23.38.6.2. Hard-limit recovery

When an in-progress operation encounters a hard limit, it reports WALLET_KYC_LIMIT_EXCEEDED and starts recovery rather than remaining indefinitely in ordinary operation-KYC waiting:

• Withdrawals request reserve closure back to the originating account. A successful close and a permanently failed close both end in failed:kyc-hard-limit; the failure reason distinguishes them. Temporary failures keep recovery active. Acceptance of reserve closure is not proof that the bank has already credited the return transfer.

• Deposits use refund and refresh recovery. Fully recovered hard-limit deposits end in failed:kyc-hard-limit; partial recovery, refund failure, or an already completed wire transfer use the deposit outcomes below.

• P2P push credits reconcile whether a merge committed. P2P pull credits delete/reconcile the purse. If funds were already merged, recovery can continue through withdrawal instead of immediately ending in failure.

Balance authorization has its own exchange-level lifecycle. A balance-KYC wait does not necessarily enter the transaction hard-limit recovery path described here.

23.38.7. Transaction Type: Withdrawal

Manual and bank-integrated withdrawals eventually wait for reserve funding and withdraw coins. Bank-integrated withdrawals additionally register the reserve and wait for confirmation at the bank. Depending on how the operation was prepared, approval in the wallet can precede transaction creation or appear as dialog:proposed. This wallet approval is separate from confirmation of the transfer at the bank.

Withdrawal progress, with bank-only steps on the right.

State or family	Progress and available actions
dialog:proposed	Confirm the withdrawal through its dedicated API, or abort to refuse it.
pending:bank-register-reserve/working; pending:bank-confirm-transfer	Register the reserve, then wait for bank confirmation. Actions: retry, suspend, abort. Suspended counterparts: resume, abort.
pending:exchange-wait-reserve	Wait for reserve funding, then withdraw. Actions: retry, suspend; also abort until funding has been observed. Suspended counterpart: resume and the same conditional abort.
pending:withdraw/working	Withdraw selected coins; reselect denominations when necessary, with no additional public state for that step. Actions: retry, suspend. suspended:withdraw: resume.
KYC initialization and waiting pending:kyc-init/working pending:kyc pending:balance-kyc	Actions: retry, suspend; also abort until funding has been observed. Suspended counterparts: resume and the same conditional abort.
aborting:bank/working	Ask the bank to abort. Actions: retry, suspend, fail. suspended-aborting:bank: resume, fail.
finalizing:kyc-hard-limit/working	Return-to-origin recovery. Only retry is advertised.
Terminal outcomes done failed failed:aborting-bank failed:kyc-hard-limit aborted:bank aborted:exchange aborted:refused aborted:completed-by-other-wallet	Only delete.

When the bank rejects an abort because it already confirmed the transfer (HTTP 409), wallet-core retains suspended:exchange-wait-reserve so the withdrawal can be resumed. A successful bank abort becomes aborted:bank; an unknown bank operation becomes failed. Aborting a manual withdrawal before observed funding produces aborted:exchange; it does not undo a bank transfer. Do not promise a returned amount or arrival time from that state alone.

Withdrawals performed as part of P2P receipts or other operations are tracked through the containing transaction. A P2P credit can remain pending:withdraw/working while its underlying withdrawal is in KYC or recovery; the containing transaction need not expose every sub-step.

23.38.8. Transaction Type: Payment

A merchant payment claims an order, obtains user approval, and submits the payment. A shared/unclaimed order may instead wait for another wallet. After payment, monitoring auto-refunds is finalizing work. Explicit refund checks and session restoration can reactivate a completed payment.

rebind-session restores access to an already paid order in another merchant session; it does not request another purchase. auto-refund checks for merchant-offered refunds, check-refund performs an explicit refund check, and accept-refund processes the offered refund. These stages can therefore occur after the original payment succeeded.

Main payment path and automatic refund monitoring.

After processing a refund, wallet-core returns to finalizing:auto-refund if the auto-refund deadline is still in the future. That repeated monitoring path is omitted from the diagram; its final done node applies when no more monitoring remains. done appears at both exits to keep the flow readable.

State or family	Progress and available actions
dialog:proposed	An ordinary or shared proposal. Confirm through the payment API; generic actions are retry, delete. Refusal uses the proposal API and can produce aborted:refused.
dialog:waiting-for-other-wallet	An unclaimed/shared order is waiting on another wallet. Generic action: delete.
Pending processing pending:claim-proposal/working pending:submit-payment/working pending:rebind-session/working pending:auto-refund/working pending:check-refund/working pending:accept-refund/working	Each advertises retry, suspend, abort. Suspended counterparts advertise resume, abort.
finalizing:auto-refund	Wait for automatic refunds after successful payment. A refund moves to pending:accept-refund/working; monitoring completion returns to done. Actions: retry, suspend, delete.
suspended-finalizing:auto-refund	Paused automatic refund monitoring. Actions: resume, delete.
aborting/working	Abort payment using refund/recovery processing. Actions: retry, suspend, fail. suspended-aborting: resume, fail.
Terminal outcomes done aborted aborted:refused aborted:continued-with-other-wallet expired failed failed:claim-proposal failed:abort failed:paid-by-other failed:repurchase	Each advertises delete.

Aborting a session replay or an explicit refund check returns the payment to done; it does not undo the original payment. Payment abort can also race with payment completion. Repurchase detection creates a failed:repurchase record, normally filtered from history, while restoring access through the original payment. Refund credits are separate records; a payment returning to done after accepting a refund does not mean that no refund occurred.

23.38.9. Transaction Type: Deposit

A direct deposit sends coins to an exchange for delivery to a bank account. After submission, finalizing:track waits for the exchange’s wire-transfer status, taking the wire deadline into account. Tracking can discover a new KYC requirement and make the transaction pending again.

Deposit submission, delivery tracking, and abort recovery.

State or family	Progress and available actions
pending:deposit/working	Submit deposits. Actions: retry, suspend, abort. suspended (without a minor): only resume.
Submission KYC pending:kyc-init/working pending:kyc pending:kyc-auth	Actions: suspend, abort. Suspended counterparts: resume, abort.
Aggregation KYC pending:kyc-init/working pending:kyc	KYC after deposits were submitted. Actions: retry, suspend, fail. Suspended counterparts: resume, fail.
finalizing:track	Track delivery. Actions: suspend, delete. suspended-finalizing:track: resume, delete. KYC can interrupt tracking.
pending:track / suspended:track	Delivery tracking on older transactions. Active actions: retry, suspend, fail; suspended actions: resume, fail.
aborting	Refund deposited contributions and refresh recoverable coins. Actions: retry, suspend, fail. suspended-aborting: resume, fail.
finalizing:kyc-hard-limit/working	Recovery after a hard-limit rejection. Only retry.
suspended-finalizing:kyc-hard-limit	Paused hard-limit recovery. Actions: resume, fail.

All terminal outcomes below advertise delete. Their states distinguish delivery, recovered value, and unsuccessful recovery.

Outcome	Interpretation
done	Ordinary deposit completed.
done:deposit-abort-too-late	The exchange already wired the deposit; abort could not recover it.
aborted:deposit-abort-recovered	Abort recovery completed, including required refreshes.
failed:deposit-abort-partial	The abort had a mixed or partial outcome across contributions.
failed:deposit-abort-refund-failed	A permanent refund failure prevented establishing complete recovery.
failed:deposit-abort-recovery-failed	Refresh recovery failed after refund/reconciliation.
failed:kyc-hard-limit	Hard-limit rejection with completed recovery.
failed:deposit / failed:track	Deposit or tracking processing failed.

An exchange refund acknowledgment is not yet recovered spendable value: wallet-core waits for the associated refresh. A refund lookup returning 404 also requires reconciliation and refresh; it does not prove successful bank delivery. The deposit’s amounts and recovery details distinguish the settled financial effect.

23.38.10. P2P transactions

Push and pull each have a debit (payer) and a credit (receiver) record. Their public states describe each wallet’s local progress, not one shared state machine. Preparing or downloading a proposal can precede creation of the transaction and are not separate transaction states.

A purse holds funds at the exchange for a P2P payment. Merging it assigns the funds to the receiver’s reserve, from which the receiver withdraws coins. The sender’s payment can therefore be complete before the receiver has obtained spendable coins.

Credit-side KYC is shared with the section above. Public kyc covers merge authorization; balance-kyc gates the wallet’s resulting balance. An already committed merge must be reconciled even if the user has aborted.

23.38.10.1. Transaction Type: Peer Push Debit

The sender creates and funds a purse, then shares its payment URI while waiting for the receiver to merge it. Abort or expiry deletes the purse and recovers value before reaching the appropriate terminal state.

P2P push: selected sender and receiver paths.

State or family	Progress and available actions
pending:create-purse/working; pending:ready	Create/fund the purse, then wait for its merge. Actions: retry, suspend, abort. Suspended counterparts: resume, abort.
aborting:delete-purse/working	Deletion/recovery after abort or expiry. Actions: retry, suspend, fail. suspended-aborting:delete-purse: resume, fail.
done, aborted, expired, failed	Final outcomes. Each advertises delete. Reconciliation can discover successful delivery despite an abort request.

23.38.10.2. Transaction Type: Peer Push Credit

State or family	Progress and available actions
dialog:proposed	An incoming offer can be accepted through the P2P API. Generic actions: retry, delete.
Merge and merge KYC pending:merge/working pending:kyc-init/working pending:kyc	Merge into the bound reserve, satisfying KYC when needed. Actions: retry, suspend, abort. Suspended counterparts: resume, abort.
Balance KYC pending:kyc-init/working pending:balance-kyc	Actions: suspend, abort. Suspended counterparts: resume, abort.
pending:withdraw/working	Obtain the received coins via the child withdrawal. Actions: retry, suspend, fail. suspended:withdraw: resume, fail.
finalizing:merge/working	An abort is reconciling whether the merge committed. Only retry. If it committed, continue withdrawing; otherwise the receiver can finish aborted.
finalizing:kyc-hard-limit/working	Reconcile a hard-limit failure. Only retry; a committed merge can still require withdrawal.
done, aborted, expired, failed, failed:kyc-hard-limit	Final outcomes. Each advertises delete.

23.38.10.3. Transaction Type: Peer Pull Credit

The receiver creates an invoice purse and shares its URI. The payer deposits into that purse; once it is merged, the receiver withdraws the resulting funds. Creating the invoice can itself require merge or balance KYC.

P2P pull: selected invoice creator and payer paths.

State or family	Progress and available actions
Invoice creation, payment waiting, and merge KYC pending:create-purse/working pending:ready pending:kyc-init/working pending:kyc	Create the invoice, wait for payment, or satisfy merge KYC. Actions: retry, suspend, abort. Suspended counterparts: resume, abort.
Balance KYC pending:kyc-init/working pending:balance-kyc	Actions: suspend, abort. Suspended counterparts: resume, abort.
pending:withdraw/working	Withdraw the credit. Actions: retry, suspend. suspended:withdraw: only resume.
aborting:delete-purse	Delete/reconcile after user abort. Actions: retry, suspend, fail. suspended-aborting:delete-purse: resume, fail.
finalizing:delete-purse/working	Delete/reconcile after expiration. Actions: retry, suspend. The paused state is suspended:delete-purse, with only resume.
finalizing:kyc-hard-limit/working	Hard-limit cleanup. Only retry. If a payment already merged the purse, reconcile and withdraw rather than discarding the credit.
done, aborted, expired, failed, failed:kyc-hard-limit	Final outcomes. Each advertises delete.

23.38.10.4. Transaction Type: Peer Pull Debit

State or family	Progress and available actions
dialog:proposed	Accept the invoice through the P2P API. Generic actions: retry, delete.
pending:deposit/working	Deposit the payment into the invoice purse. Actions: suspend, abort. suspended:deposit: resume, abort.
aborting:deposit/working	Reconcile a possibly accepted deposit before deciding what can be recovered. Only suspend. suspended-aborting:deposit: only resume.
aborting:refresh/working	Refresh coins that can be recovered. Actions: suspend, fail. suspended-aborting:refresh: resume, fail.
done, aborted, expired, failed	Final outcomes. Each advertises delete. Reconciliation can discover that the payment succeeded rather than recovering the coins.

23.38.11. Other transaction families

23.38.11.1. Transaction Type: Refund

Refund records represent credits associated with a merchant payment, separate from that payment’s refund-processing states. The refund states are pending, done, aborted, failed, or expired, with no minor component or /working suffix. Every refund record advertises only delete. A failed refund group can still contain successful refund items; inspect its amounts rather than treating failure as a zero credit.

If isAbortRecovery is true, the recovered value is already included in the unsuccessful payment’s settled cost. Do not count that refund again when presenting the net balance effect of the payment and its refunds.

23.38.11.2. Transaction Type: Refresh

Refresh obtains fresh coins from existing value. Denomination reselection is part of the same processing phase. Refreshes are normally excluded from the transaction list unless includeRefreshes or includeAll is requested.

State	Progress and available actions
pending/working	Perform refresh or denomination reselection. Actions: retry, suspend.
suspended	Paused refresh. Only resume.
done / failed	Processing finished. Only delete.

23.38.11.3. Transaction Type: Recoup

Recoup recovers value affected by denomination revocation. Its public state and action table is the same as refresh: pending/working offers retry and suspend; suspended offers resume; done and failed offer delete. It is not modeled as user-abortable work.

23.38.11.4. Transaction Type: Denomination Loss

A denom-loss record accounts for value lost through denomination events. Its states are done and aborted, both with only delete. Here done means that recording the loss is complete, not that money was received or recovered.