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:
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