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