taler-docs

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

commit 9581208ee1bcf0e88e369057865a4cf38a8eb9b1
parent dea90d901d712807e4739c1a27933a38f3c2bd32
Author: Florian Dold <dold@taler.net>
Date:   Tue, 10 Nov 2026 17:57:59 +0100

wallet-core docs: document peer-credit observations

Diffstat:
Mcore/api-wallet-core.rst | 309+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 302 insertions(+), 7 deletions(-)

diff --git a/core/api-wallet-core.rst b/core/api-wallet-core.rst @@ -183,9 +183,10 @@ Notifications In addition to responses, wallet-core spontaneously sends *notifications* to connected clients, for example when the balance or the state of a transaction changes. Notifications are not correlated with a request -``id``. Clients should use them as a trigger to re-query state, not as an -authoritative state transfer. See :ref:`wallet-core-notifications` for the -list of notification types. +``id``. Most are hints to re-query state; snapshot notifications instead +carry complete state for a registered observation, correlated by its +``observationId``. See :ref:`wallet-core-observations` and +:ref:`wallet-core-notifications` for the observation lifecycle and payloads. .. ts:def:: CoreApiNotification @@ -339,6 +340,227 @@ via :ref:`transaction-state-transition .. include:: wallet-core/transactions/wait-transaction-state.rst +.. _wallet-core-observations: + +Transaction observations +^^^^^^^^^^^^^^^^^^^^^^^^ + +Observations deliver complete snapshots for a UI view, including the +transaction and the prerequisites needed to present its next action. +Install the notification listener before registering: the initial snapshot +can arrive before the registration response. Preparation and confirmation +remain separate operations. + +.. ts:op:: observePeerPushCredit + + 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. + + **Request:** + + The request ``args`` must be an `ObservePeerPushCreditRequest` 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 + retrying an observation. Multiple observations of the same transaction + are independent. + + **Response:** + + On success, the result is an `EmptyObject`. The initial snapshot and + subsequent updates arrive as `PeerPushCreditSnapshotNotification` + objects, correlated by ``observationId`` rather than the request ``id``. + Registration validates the transaction's type and existence; a failed + registration leaves no observation behind. + + **Side effects:** + + Creates an in-memory subscription and emits notifications. Each snapshot + reads the transaction, exchange 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. + + **Expected errors:** + + ``WALLET_CORE_API_BAD_REQUEST`` for a malformed or wrong-type transaction + ID, an invalid observation ID, or an observation ID already in use; + ``WALLET_TRANSACTION_NOT_FOUND`` if the transaction does not exist. + + **Details:** + + Completed, failed and aborted transactions remain observable. Database + import or clearing refreshes observations against the replacement data. + Deletion produces a final ``snapshot: null`` notification. Shutdown + discards observations; reconnecting clients must register again. See + :ref:`observation-snapshot <wallet-notif-observation-snapshot>` for + replacement and revision rules, and + :ref:`observation-error <wallet-notif-observation-error>` for later read + failures. + +.. ts:def:: ObservePeerPushCreditRequest + + interface ObservePeerPushCreditRequest { + transactionId: TransactionIdStr; + observationId: string; + } + +.. ts:op:: stopObservation + + End an observation without stopping transaction processing. + + **Request:** + + The request ``args`` must be a `StopObservationRequest` object. + ``observationId`` has the same format as when registering. + + **Response:** + + On success, the result is an `EmptyObject`. Stopping an unknown or + already stopped observation is successful and has no effect. + + **Side effects:** + + Removes the subscription and its timer. In-flight reads cannot publish + new snapshots after it is stopped. Notifications already queued on the + transport can still arrive: remove the observation from the client's + notification routing before sending this request. + + **Expected errors:** + + ``WALLET_CORE_API_BAD_REQUEST`` for an invalid observation ID. + +.. ts:def:: StopObservationRequest + + interface StopObservationRequest { + observationId: string; + } + +**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 +``hint`` and ``message`` limited to 1024 characters each. Use +:ts:op:`getTransactionById` for full diagnostic details. + +.. ts:def:: PeerPushCreditSnapshot + + interface PeerPushCreditSnapshot { + transaction: ObservedPeerPushCreditTransaction; + + // Null when the exchange entry is absent. + exchange: PeerPushCreditExchangeSnapshot | null; + + confirmation: { + // Empty when confirmation is available based on local knowledge. + unavailableReasons: PeerPushCreditConfirmationUnavailableReason[]; + }; + } + +.. ts:def:: ObservedPeerPushCreditTransaction + + interface ObservedPeerPushCreditTransaction { + type: "peer-push-credit"; + transactionId: TransactionIdStr; + localTransactionId?: string; + legacy?: boolean; + timestamp: TalerPreciseTimestamp; + scopes: ScopeInfo[]; + txState: TransactionState; + txActions: TransactionAction[]; + amountRaw: AmountString; + + // Initial estimate, including fees; preserved after failure. + amountEffective: AmountString; + + // Settled balance effect, when it can be established. + amountEffectiveFinal?: AmountString; + + info: PeerInfoShort; + exchangeBaseUrl: string; + kycUrl?: string; + kycAmlReview?: boolean; + retryInfo?: TransactionRetryInfo; + error?: ErrorInfoSummary; + abortReason?: ErrorInfoSummary; + failReason?: ErrorInfoSummary; + } + +.. ts:def:: TransactionRetryInfo + + interface TransactionRetryInfo { + retryCounter: number; + nextRetry: TalerPreciseTimestamp; + } + +.. ts:def:: PeerPushCreditExchangeSnapshot + + interface PeerPushCreditExchangeSnapshot { + exchangeBaseUrl: string; + tosStatus: ExchangeTosStatus; + unconfirmedKeyChange?: ExchangeKeyChangeInfo; + exchangeUpdateStatus: ExchangeUpdateStatus; + currencySpec: CurrencySpecification; + walletKycRequestedThreshold?: string; + tosCurrentEtag?: string; + kycHardLimit?: AmountString; + kycSoftLimit?: AmountString; + lastUpdateError?: ErrorInfoSummary; + } + +.. ts:def:: PeerPushCreditConfirmationUnavailableReason + + type PeerPushCreditConfirmationUnavailableReason = + | "not-proposed" + | "expired" + | "exchange-not-ready" + | "exchange-keys-not-accepted" + | "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``. +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. + +**KYC and retry information** + +``transaction.txState`` is the authoritative transaction status, including +KYC in an associated withdrawal. There is no separate KYC phase in the +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 +``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``. + +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. + + Withdrawals ^^^^^^^^^^^ @@ -699,14 +921,18 @@ Notifications Notifications are sent by wallet-core to all connected clients whenever relevant state changes. The ``payload`` of a `CoreApiNotification` is a -`WalletNotification`, a discriminated union on the ``type`` field. Clients -should treat notifications as hints to re-query the affected state; the -notification contents are deliberately minimal and must not be relied upon -as an authoritative state transfer. +`WalletNotification`, a discriminated union on the ``type`` field. Most +notifications are hints to re-query the affected state. The +``observation-snapshot`` variant instead carries a complete replacement +snapshot for a registered observation. Route observation notifications by +``observationId``; clients may receive notifications for observations they +did not register and should ignore those IDs. .. ts:def:: WalletNotification type WalletNotification = + | ObservationSnapshotNotification + | ObservationErrorNotification | CoinRecoveryProgressNotification | BalanceChangeNotification | BankAccountChangeNotification @@ -727,6 +953,8 @@ as an authoritative state transfer. .. ts:def:: NotificationType enum NotificationType { + ObservationSnapshot = "observation-snapshot", + ObservationError = "observation-error", CoinRecoveryProgress = "coin-recovery-progress", BalanceChange = "balance-change", BankAccountChange = "bank-account-change", @@ -746,3 +974,70 @@ as an authoritative state transfer. } .. include:: wallet-core/notifications.rst + + +Observation notifications +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _wallet-notif-observation-snapshot: + +**observation-snapshot** + +All snapshot observations use this notification type. ``observationType`` +discriminates the payload; the first supported variant is +``peer-push-credit``. + +.. ts:def:: ObservationType + + enum ObservationType { + PeerPushCredit = "peer-push-credit", + } + +.. ts:def:: ObservationSnapshotNotification + + type ObservationSnapshotNotification = PeerPushCreditSnapshotNotification; + +.. ts:def:: PeerPushCreditSnapshotNotification + + interface PeerPushCreditSnapshotNotification { + type: "observation-snapshot"; + observationType: "peer-push-credit"; + observationId: string; + revision: number; + transactionId: TransactionIdStr; + snapshot: PeerPushCreditSnapshot | null; + } + +Revision 1 carries the initial snapshot. Revisions increase within one +observation only when its snapshot changes; they are not database or +transaction versions. Replace the previous snapshot in full, including +clearing optional fields that disappeared. Clients can ignore revisions +no newer than the last one applied for that observation ID. + +Updates can be coalesced: snapshots describe current state and do not +promise to report every intermediate transition. A final ``snapshot: null`` +means the transaction was deleted and the observation has ended. Stop +routing updates for that ID and discard its previous snapshot. + +.. _wallet-notif-observation-error: + +**observation-error** + +If a snapshot cannot be built after successful registration, wallet-core +emits an `ObservationErrorNotification` and ends the observation. Its error +summary has the same size limits as errors in snapshots. Initial read +failures instead fail the registration request. + +.. ts:def:: ObservationErrorNotification + + interface ObservationErrorNotification { + type: "observation-error"; + observationType: ObservationType; + observationId: string; + error: ErrorInfoSummary; + } + +This is an observation failure, not a failed payment. A UI may retain the +last snapshot as stale, disable confirmation, and offer to register again +with a fresh observation ID. Disconnection also requires a new registration; +wait for its first snapshot before enabling actions based on current state.