taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit 4ff818c30cb225be4153dd1527b5d494361d016d
parent f060f500b5453502fcf42eafc199a39ce7220a4b
Author: Florian Dold <dold@taler.net>
Date:   Wed, 11 Nov 2026 00:05:55 +0100

wallet-core API: document observeTransaction

Diffstat:
Mcore/api-wallet-core.rst | 445+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 390 insertions(+), 55 deletions(-)

diff --git a/core/api-wallet-core.rst b/core/api-wallet-core.rst @@ -351,15 +351,15 @@ Install the notification listener before registering: the initial snapshot can arrive before the registration response. Preparation and confirmation remain separate operations. -.. ts:op:: observePeerPushCredit +.. ts:op:: observeTransaction - Observe an existing incoming peer push payment. Obtain its - ``transactionId`` from :ts:op:`preparePeerPushCredit` or the transaction - history; this operation does not accept a payment URI. + Observe an existing transaction of any `TransactionType`. Obtain its + ``transactionId`` from the relevant preparation operation or transaction + history; this operation does not accept a payment or withdrawal URI. **Request:** - The request ``args`` must be an `ObservePeerPushCreditRequest` object. + The request ``args`` must be an `ObserveTransactionRequest` object. ``observationId`` is a caller-generated, nonempty string of at most 256 characters, unique among active observations in this wallet instance. Use a fresh ID for each registration, including after reconnecting or @@ -369,7 +369,7 @@ remain separate operations. **Response:** On success, the result is an `EmptyObject`. The initial snapshot and - subsequent updates arrive as `PeerPushCreditSnapshotNotification` + subsequent updates arrive as `TransactionSnapshotNotification` objects, correlated by ``observationId`` rather than the request ``id``. Registration validates the transaction's type and existence; a failed registration leaves no observation behind. @@ -377,14 +377,16 @@ remain separate operations. **Side effects:** Creates an in-memory subscription and emits notifications. Each snapshot - reads the transaction, exchange and confirmation prerequisites from one + reads the transaction, exchanges and confirmation prerequisites from one consistent database view. Observing makes no network requests, writes - no persistent data and does not advance the transaction. Expiration - can update confirmation availability without changing transaction state. + no persistent data and does not advance the transaction. Changes to + snapshot inputs, including balances, exchange data and payment choices, + can produce updates without a transaction state transition. Expiration + and fee-validity deadlines can also change the snapshot. **Expected errors:** - ``WALLET_CORE_API_BAD_REQUEST`` for a malformed or wrong-type transaction + ``WALLET_CORE_API_BAD_REQUEST`` for a malformed or unsupported transaction ID, an invalid observation ID, or an observation ID already in use; ``WALLET_TRANSACTION_NOT_FOUND`` if the transaction does not exist. @@ -399,9 +401,14 @@ remain separate operations. :ref:`observation-error <wallet-notif-observation-error>` for later read failures. -.. ts:def:: ObservePeerPushCreditRequest + This request replaces ``observePeerPushCredit``. Clients must use + ``observationType: "transaction"`` and inspect ``snapshot.type`` for the + transaction-specific payload. Call :ts:op:`stopObservation` when the + view closes. - interface ObservePeerPushCreditRequest { +.. ts:def:: ObserveTransactionRequest + + interface ObserveTransactionRequest { transactionId: TransactionIdStr; observationId: string; } @@ -439,33 +446,340 @@ remain separate operations. **Snapshot contents** -A `PeerPushCreditSnapshot` contains the transaction's display fields, -exchange prerequisites and locally known confirmation blockers. Full -contract terms, images, terms-of-service documents, internal state IDs and -KYC access tokens/payto hashes are excluded. Preparation supplies the peer -contract terms; :ts:op:`getExchangeTos` supplies the terms document on demand. -Errors and failure/abort reasons contain only an `ErrorInfoSummary`, with +A `TransactionSnapshot` contains the transaction's display fields and an +``exchanges`` array of relevant cached exchange summaries. Missing exchange +records are omitted from this array; they do not prevent observing the +transaction. The outer ``type`` matches ``transaction.type`` and determines +which additional fields are present. + +Full contract terms, terms-of-service documents, internal state IDs and +standalone KYC access tokens/payto hashes are excluded. Actionable KYC +links and transfer instructions remain available. Preparation supplies peer +contract terms; use :ts:op:`getTransactionById` with ``includeContractTerms`` +for merchant contract documents and :ts:op:`getExchangeTos` for terms of +service. Errors and failure/abort reasons have compact summaries, with ``hint`` and ``message`` limited to 1024 characters each. Use :ts:op:`getTransactionById` for full diagnostic details. +.. ts:def:: TransactionSnapshot + + type TransactionSnapshot = + | PaymentSnapshot + | WithdrawalSnapshot + | InternalWithdrawalSnapshot + | PeerPushCreditSnapshot + | PeerPullCreditSnapshot + | PeerPushDebitSnapshot + | PeerPullDebitSnapshot + | RefundSnapshot + | RefreshSnapshot + | DepositSnapshot + | RecoupSnapshot + | DenomLossSnapshot; + + +.. ts:def:: TransactionSnapshotCommon + + interface TransactionSnapshotCommon { + exchanges: ObservedExchange[]; + } + + +.. ts:def:: PaymentSnapshot + + interface PaymentSnapshot extends TransactionSnapshotCommon { + type: "payment"; + transaction: ObservedPaymentTransaction; + payment: ObservedPaymentChoices | null; + confirmation: { + unavailableReasons: TransactionConfirmationUnavailableReason[]; + }; + currentDonauInfo?: { donauBaseUrl: string }; + } + + +.. ts:def:: WithdrawalSnapshot + + interface WithdrawalSnapshot extends TransactionSnapshotCommon { + type: "withdrawal"; + transaction: ObservedWithdrawalTransaction; + bank?: ObservedBankWithdrawal; + } + + +.. ts:def:: InternalWithdrawalSnapshot + + interface InternalWithdrawalSnapshot extends TransactionSnapshotCommon { + type: "internal-withdrawal"; + transaction: ObservedInternalWithdrawalTransaction; + } + + .. ts:def:: PeerPushCreditSnapshot - interface PeerPushCreditSnapshot { + interface PeerPushCreditSnapshot extends TransactionSnapshotCommon { + type: "peer-push-credit"; transaction: ObservedPeerPushCreditTransaction; + confirmation: { + unavailableReasons: PeerPushCreditConfirmationUnavailableReason[]; + }; + } + + +.. ts:def:: PeerPullCreditSnapshot + + interface PeerPullCreditSnapshot extends TransactionSnapshotCommon { + type: "peer-pull-credit"; + transaction: ObservedPeerPullCreditTransaction; + } - // Null when the exchange entry is absent. - exchange: PeerPushCreditExchangeSnapshot | null; +.. ts:def:: PeerPushDebitSnapshot + + interface PeerPushDebitSnapshot extends TransactionSnapshotCommon { + type: "peer-push-debit"; + transaction: ObservedPeerPushDebitTransaction; + } + + +.. ts:def:: PeerPullDebitSnapshot + + interface PeerPullDebitSnapshot extends TransactionSnapshotCommon { + type: "peer-pull-debit"; + transaction: ObservedPeerPullDebitTransaction; confirmation: { - // Empty when confirmation is available based on local knowledge. - unavailableReasons: PeerPushCreditConfirmationUnavailableReason[]; + unavailableReasons: TransactionConfirmationUnavailableReason[]; }; } + +.. ts:def:: RefundSnapshot + + interface RefundSnapshot extends TransactionSnapshotCommon { + type: "refund"; + transaction: ObservedRefundTransaction; + } + + +.. ts:def:: RefreshSnapshot + + interface RefreshSnapshot extends TransactionSnapshotCommon { + type: "refresh"; + transaction: ObservedRefreshTransaction; + } + + +.. ts:def:: DepositSnapshot + + interface DepositSnapshot extends TransactionSnapshotCommon { + type: "deposit"; + transaction: ObservedDepositTransaction; + } + + +.. ts:def:: RecoupSnapshot + + interface RecoupSnapshot extends TransactionSnapshotCommon { + type: "recoup"; + transaction: ObservedRecoupTransaction; + } + + +.. ts:def:: DenomLossSnapshot + + interface DenomLossSnapshot extends TransactionSnapshotCommon { + type: "denom-loss"; + transaction: ObservedDenomLossTransaction; + } + +For merchant payments, ``payment`` contains choices, affordability, costs, +token availability and default/automatic selection. It is null before +contract download and outside payment review. ``currentDonauInfo``, when +present, identifies the configured donation service without exposing the +taxpayer identifier. + +For bank-integrated withdrawals, ``bank`` contains the latest cached bank +presentation when available. ``transaction.txState`` takes precedence over +the cached bank status. Exchange candidates for an editable setup form +remain a separate setup query. Internal withdrawals can be observed by ID, +but remain hidden from ordinary history and must not be counted again as +an additional balance effect alongside their parent transaction. + +.. ts:def:: ObservedPaymentChoices + + interface ObservedPaymentChoices { + choices: ChoiceSelectionDetail[]; + defaultChoiceIndex?: number; + automaticExecution?: boolean; + automaticExecutableIndex?: number; + } + +.. ts:def:: ObservedBankWithdrawal + + interface ObservedBankWithdrawal { + operationId: string; + status: WithdrawalOperationStatusFlag; + confirmTransferUrl?: string; + currency: string; + amount: AmountString | undefined; + editableAmount: boolean; + maxAmount: AmountString | undefined; + wireFee: AmountString | undefined; + defaultExchangeBaseUrl?: string; + editableExchange: boolean; + } + +`ObservedTransaction` includes only the following common and type-specific +fields of `Transaction`, with their existing meanings and optionality. +Each variant below extends `ObservedTransactionCommon`. Fields added to +`Transaction` are not automatically included in snapshots. + +.. ts:def:: ObservedTransaction + + type ObservedTransaction = + | ObservedPaymentTransaction + | ObservedWithdrawalTransaction + | ObservedInternalWithdrawalTransaction + | ObservedPeerPushCreditTransaction + | ObservedPeerPullCreditTransaction + | ObservedPeerPushDebitTransaction + | ObservedPeerPullDebitTransaction + | ObservedRefundTransaction + | ObservedRefreshTransaction + | ObservedDepositTransaction + | ObservedRecoupTransaction + | ObservedDenomLossTransaction; + + +.. ts:def:: ObservedPaymentTransaction + + interface ObservedPaymentTransaction extends ObservedTransactionCommon { + type: "payment"; + merchantBaseUrl: string; + unclaimedPayUri?: TalerUriString; + info: OrderShortInfo | undefined; + totalRefundRaw: AmountString; + totalRefundEffective: AmountString; + refundPending: AmountString | undefined; + refunds: RefundInfoShort[]; + refundQueryActive: boolean; + posConfirmation: string | undefined; + posConfirmationDeadline?: TalerProtocolTimestamp; + posConfirmationViaNfc?: boolean; + repurchaseTransactionId?: TransactionIdStr; + choiceIndex?: number; + } + + +.. ts:def:: ObservedWithdrawalTransaction + + interface ObservedWithdrawalTransaction extends ObservedTransactionCommon { + type: "withdrawal"; + exchangeBaseUrl: string | undefined; + withdrawalDetails: WithdrawalDetails; + } + + +.. ts:def:: ObservedInternalWithdrawalTransaction + + interface ObservedInternalWithdrawalTransaction extends ObservedTransactionCommon { + type: "internal-withdrawal"; + exchangeBaseUrl: string; + withdrawalDetails: WithdrawalDetails; + } + + .. ts:def:: ObservedPeerPushCreditTransaction - interface ObservedPeerPushCreditTransaction { + interface ObservedPeerPushCreditTransaction extends ObservedTransactionCommon { type: "peer-push-credit"; + exchangeBaseUrl: string; + info: PeerInfoShort; + } + + +.. ts:def:: ObservedPeerPullCreditTransaction + + interface ObservedPeerPullCreditTransaction extends ObservedTransactionCommon { + type: "peer-pull-credit"; + exchangeBaseUrl: string; + info: PeerInfoShort; + talerUri: string | undefined; + } + + +.. ts:def:: ObservedPeerPushDebitTransaction + + interface ObservedPeerPushDebitTransaction extends ObservedTransactionCommon { + type: "peer-push-debit"; + exchangeBaseUrl: string; + info: PeerInfoShort; + talerUri?: string; + } + + +.. ts:def:: ObservedPeerPullDebitTransaction + + interface ObservedPeerPullDebitTransaction extends ObservedTransactionCommon { + type: "peer-pull-debit"; + exchangeBaseUrl: string; + info: PeerInfoShort; + } + + +.. ts:def:: ObservedRefundTransaction + + interface ObservedRefundTransaction extends ObservedTransactionCommon { + type: "refund"; + refundedTransactionId: string; + paymentInfo: RefundPaymentInfo | undefined; + isAbortRecovery?: boolean; + } + + +.. ts:def:: ObservedRefreshTransaction + + interface ObservedRefreshTransaction extends ObservedTransactionCommon { + type: "refresh"; + refreshReason: RefreshReason; + originatingTransactionId?: string; + refreshInputAmount: AmountString; + refreshOutputAmount: AmountString; + } + + +.. ts:def:: ObservedDepositTransaction + + interface ObservedDepositTransaction extends ObservedTransactionCommon { + type: "deposit"; + depositGroupId: string; + targetPaytoUri: string; + accountPub: string; + wireTransferDeadline: TalerProtocolTimestamp; + wireTransferProgress: number; + deposited: boolean; + trackingState: DepositTransactionTrackingState[]; + } + + +.. ts:def:: ObservedRecoupTransaction + + interface ObservedRecoupTransaction extends ObservedTransactionCommon { + type: "recoup"; + } + + +.. ts:def:: ObservedDenomLossTransaction + + interface ObservedDenomLossTransaction extends ObservedTransactionCommon { + type: "denom-loss"; + lossEventType: DenomLossEventType; + exchangeBaseUrl: string; + } + +.. ts:def:: ObservedTransactionCommon + + interface ObservedTransactionCommon { transactionId: TransactionIdStr; localTransactionId?: string; legacy?: boolean; @@ -481,14 +795,20 @@ Errors and failure/abort reasons contain only an `ErrorInfoSummary`, with // Settled balance effect, when it can be established. amountEffectiveFinal?: AmountString; - info: PeerInfoShort; - exchangeBaseUrl: string; kycUrl?: string; kycAmlReview?: boolean; + kycAuthTransferInfo?: KycAuthTransferInfo; retryInfo?: TransactionRetryInfo; - error?: ErrorInfoSummary; - abortReason?: ErrorInfoSummary; - failReason?: ErrorInfoSummary; + error?: ObservedTransactionError; + abortReason?: ObservedTransactionError; + failReason?: ObservedTransactionError; + } + +.. ts:def:: ObservedTransactionError + + interface ObservedTransactionError extends ErrorInfoSummary { + // Recovery target for exchange terms/key acceptance errors only. + exchangeBaseUrl?: string; } .. ts:def:: TransactionRetryInfo @@ -498,9 +818,9 @@ Errors and failure/abort reasons contain only an `ErrorInfoSummary`, with nextRetry: TalerPreciseTimestamp; } -.. ts:def:: PeerPushCreditExchangeSnapshot +.. ts:def:: ObservedExchange - interface PeerPushCreditExchangeSnapshot { + interface ObservedExchange { exchangeBaseUrl: string; tosStatus: ExchangeTosStatus; unconfirmedKeyChange?: ExchangeKeyChangeInfo; @@ -523,10 +843,25 @@ Errors and failure/abort reasons contain only an `ErrorInfoSummary`, with | "exchange-tos-not-accepted" | "kyc-hard-limit"; -An empty ``confirmation.unavailableReasons`` lets the UI offer confirmation -without querying the exchange or repeating prerequisite checks. -:ts:op:`confirmPeerPushCredit` remains authoritative and rechecks those -prerequisites. Other transaction actions come from ``transaction.txActions``. +.. ts:def:: TransactionConfirmationUnavailableReason + + type TransactionConfirmationUnavailableReason = + | PeerPushCreditConfirmationUnavailableReason + | "contract-unavailable"; + +``confirmation.unavailableReasons`` reports locally known confirmation +blockers for merchant payments, incoming peer push payments and outgoing +peer pull payments. An empty array means no such blocker is known; merchant +payment choices still carry their individual affordability results. +:ts:op:`confirmPay`, :ts:op:`confirmPeerPushCredit` and +:ts:op:`confirmPeerPullDebit` remain authoritative and recheck prerequisites +and remote state. Other actions come from ``transaction.txActions``. +Observation does not reserve coins. Peer invoice amounts preserve the +preparation estimate; confirmation checks the current purse balance and +selects available coins. An expired peer share link is omitted even before +the persisted transaction state catches up. A missing ``talerUri`` alone +does not indicate loading: use the transaction state and actions. + The amounts have the same meaning as in :ts:op:`getTransactionById`: ``amountEffective`` preserves the initial estimate, while ``amountEffectiveFinal`` describes the settled balance effect when known. @@ -539,26 +874,26 @@ snapshot. The minor states ``kyc-init``, ``kyc`` and ``balance-kyc`` retain their existing meanings; the major state distinguishes pending from suspended processing. -``transaction.kycUrl`` belongs to the active KYC requirement. A link left -from merge KYC is not exposed during ordinary withdrawal or after -completion. ``transaction.kycAmlReview`` carries the exchange's +``transaction.kycUrl`` belongs to the active KYC requirement. For peer +credits, a link left from merge KYC is not exposed during ordinary withdrawal +or after completion. ``transaction.kycAmlReview`` carries the exchange's ``aml_review`` hint for that requirement. When true, present waiting for review; a portal link can offer details without telling the user to submit information. False means the exchange is not reporting this condition; it does not rule out an undisclosed review. An absent field means no applicable value was reported. -``transaction.error`` describes the active operation: peer merge, -wallet-balance KYC, or withdrawal. When an error is present, ``retryInfo`` -contains that same task's stored retry counter and next automatic retry -time. Both fields disappear when the task recovers. User-initiated retry -availability still comes from ``txActions``. +``transaction.error`` describes the active operation, including an associated +withdrawal or wallet-balance KYC task. ``retryInfo``, when present, contains +that same task's stored retry counter and next automatic retry time. Both +fields disappear when the task recovers. User-initiated retry availability +still comes from ``txActions``. The exchange's ``walletKycRequestedThreshold`` is account-level metadata, -not an independent reason to prompt for transaction KYC. Its soft/hard -limits reflect cached knowledge. Neither those limits nor the transaction -KYC fields predict clearance for a future exchange request; the observation -adds no balance preview or KYC prediction. +not an independent reason to prompt for transaction KYC. Soft/hard limits, +included for peer credits, reflect cached knowledge. Neither those limits +nor the transaction KYC fields predict clearance for a future exchange +request; the observation adds no balance preview or KYC prediction. Withdrawals @@ -984,28 +1319,28 @@ Observation notifications **observation-snapshot** All snapshot observations use this notification type. ``observationType`` -discriminates the payload; the first supported variant is -``peer-push-credit``. +discriminates the observed domain; transaction observations use +``"transaction"``. ``snapshot.type`` identifies the transaction type. .. ts:def:: ObservationType enum ObservationType { - PeerPushCredit = "peer-push-credit", + Transaction = "transaction", } .. ts:def:: ObservationSnapshotNotification - type ObservationSnapshotNotification = PeerPushCreditSnapshotNotification; + type ObservationSnapshotNotification = TransactionSnapshotNotification; -.. ts:def:: PeerPushCreditSnapshotNotification +.. ts:def:: TransactionSnapshotNotification - interface PeerPushCreditSnapshotNotification { + interface TransactionSnapshotNotification { type: "observation-snapshot"; - observationType: "peer-push-credit"; + observationType: "transaction"; observationId: string; revision: number; transactionId: TransactionIdStr; - snapshot: PeerPushCreditSnapshot | null; + snapshot: TransactionSnapshot | null; } Revision 1 carries the initial snapshot. Revisions increase within one