taler-docs

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

api-wallet-core.rst (45260B)


      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2021-2026 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero General Public License as published by the Free Software
      7   Foundation; either version 3.0, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 
     16   @author Florian Dold
     17 
     18 ================
     19 Wallet-Core API
     20 ================
     21 
     22 This chapter specifies the API that *wallet-core*, the reference GNU Taler
     23 wallet implementation, exposes to its clients.  Clients of this API are the
     24 various wallet front-ends (the command-line interface, the WebExtension, the
     25 mobile applications and other user interfaces embedding wallet-core), as well
     26 as test harnesses.
     27 
     28 Unlike most other APIs in GNU Taler, this is **not** an HTTP REST API:
     29 wallet-core runs inside (or alongside) the client application and is driven
     30 via an operation-based request/response message protocol.  Each request
     31 names an *operation* and carries operation-specific JSON arguments; the
     32 response either carries the operation-specific result or a structured error.
     33 In the documentation, we use TypeScript syntax to describe the JSON objects,
     34 as with the REST APIs.
     35 
     36 The reference for all operations and their payloads is the TypeScript source
     37 of wallet-core (``packages/taler-wallet-core/src/wallet-api-types.ts`` and
     38 ``packages/taler-util/src/types-taler-wallet.ts``); a per-operation reference
     39 generated from these sources is also available in the
     40 :doc:`wallet-core reference </wallet/wallet-core>`.
     41 
     42 The `glossary <https://docs.taler.net/developer/taler-developer-manual.html#developer-glossary>`_
     43 defines all specific terms used in this section.
     44 
     45 
     46 ---------------
     47 Version History
     48 ---------------
     49 
     50 The wallet-core API is versioned using the :ref:`libtool version range
     51 format <http-common>` (``current[:revision[:age]]``).  The currently
     52 implemented protocol version is **11:0:0**, reported via the
     53 :ts:op:`getVersion` operation.
     54 
     55 **Version history:**
     56 
     57 * ``v4``: first tracked version; adds denomination-loss transactions
     58 * ``v5``: requests must use canonicalized base URLs
     59 * ``v6``: bank-integrated withdrawal via prepare/confirm steps
     60 * ``v7``: introduces the transaction finalizing state
     61 * ``v8``: removes the v1 ``preparePay`` operations
     62 * ``v9``: payments can be handed off to another wallet
     63   (:ts:op:`unclaimPayment` and
     64   :ts:op:`reclaimPayment`)
     65 * ``v10``: privacy-scrubbed diagnostics reports
     66   (:ts:op:`getDiagnostics`)
     67 * ``v11`` moves renewal details from :ts:op:`getBalances` to
     68   :ts:op:`getBalanceRefreshInfo` and :ts:op:`observeBalanceRefreshInfo`.
     69   Balance-change notifications can omit the transaction hint.
     70 
     71 
     72 .. _wallet-core-conventions:
     73 
     74 ---------------------
     75 Protocol conventions
     76 ---------------------
     77 
     78 Operations
     79 ^^^^^^^^^^
     80 
     81 Every interaction with wallet-core starts with the client sending a
     82 `CoreApiRequestEnvelope`.  The ``operation`` field selects the operation,
     83 ``id`` is a client-chosen request identifier that is echoed back in the
     84 response (allowing multiple requests to be in flight), and ``args`` carries
     85 the operation-specific request payload.  Operations that take no arguments
     86 use an empty object (`EmptyObject`).
     87 
     88 .. ts:def:: CoreApiRequestEnvelope
     89 
     90   interface CoreApiRequestEnvelope {
     91     // Client-chosen request identifier, echoed in the response.
     92     id: string;
     93 
     94     // Name of the operation, e.g. "getBalances".
     95     operation: string;
     96 
     97     // Operation-specific request payload.
     98     args: unknown;
     99   }
    100 
    101 .. ts:def:: EmptyObject
    102 
    103   // Placeholder for operations without arguments or without a result.
    104   type EmptyObject = Record<string, never>;
    105 
    106 Responses and errors
    107 ^^^^^^^^^^^^^^^^^^^^
    108 
    109 A request is always answered with exactly one of the following envelopes:
    110 
    111 .. ts:def:: CoreApiResponseSuccess
    112 
    113   interface CoreApiResponseSuccess {
    114     // Distinguishes the message from errors and notifications.
    115     type: "response";
    116 
    117     // Operation that was invoked.
    118     operation: string;
    119 
    120     // Request identifier from the corresponding request.
    121     id: string;
    122 
    123     // Operation-specific result payload.
    124     result: unknown;
    125   }
    126 
    127 .. ts:def:: CoreApiResponseError
    128 
    129   interface CoreApiResponseError {
    130     // Distinguishes the message from responses and notifications.
    131     type: "error";
    132 
    133     // Operation that was invoked.
    134     operation: string;
    135 
    136     // Request identifier from the corresponding request.
    137     id: string;
    138 
    139     // Details about the failure.
    140     error: TalerErrorDetail;
    141   }
    142 
    143 The ``error`` object carries a numeric ``code`` from the
    144 :ref:`error code registry <error-codes>` plus optional details.  It has the
    145 same structure as the `ErrorDetail` of the REST APIs (see
    146 :ref:`http-common`), but allows arbitrary additional fields depending on
    147 the error code:
    148 
    149 .. ts:def:: TalerErrorDetail
    150 
    151   interface TalerErrorDetail {
    152     // Numeric error code unique to the condition.
    153     code: TalerErrorCode;
    154 
    155     // When did the error occur.
    156     when?: AbsoluteTime;
    157 
    158     // Human-readable description of the error.  May change without notice!
    159     hint?: string;
    160 
    161     // Additional fields specific to the error code.
    162     [x: string]: unknown;
    163   }
    164 
    165 For each operation, this specification lists the *expected* error codes:
    166 conditions the caller can reasonably react to inline (for example
    167 ``WALLET_TRANSACTION_NOT_FOUND`` or
    168 ``WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE``).  Any other failure
    169 (network problems, protocol violations, internal errors) is also reported
    170 via the error envelope, but is not listed per operation.
    171 
    172 Initialization
    173 ^^^^^^^^^^^^^^
    174 
    175 :ts:op:`initWallet` (or
    176 :ts:op:`setWalletRunConfig`) must be the first
    177 request made to wallet-core; every other operation fails until
    178 initialization has completed.  Once the wallet has been shut down via
    179 :ts:op:`shutdown`, every operation other than
    180 ``shutdown`` itself fails with ``WALLET_CORE_NOT_AVAILABLE`` until
    181 wallet-core is restarted and initialized again.
    182 
    183 Notifications
    184 ^^^^^^^^^^^^^
    185 
    186 In addition to responses, wallet-core spontaneously sends *notifications*
    187 to connected clients, for example when the balance or the state of a
    188 transaction changes.  Notifications are not correlated with a request
    189 ``id``.  Most are hints to re-query state; snapshot notifications instead
    190 carry complete state for a registered observation, correlated by its
    191 ``observationId``.  See :ref:`wallet-core-observations` and
    192 :ref:`wallet-core-notifications` for the observation lifecycle and payloads.
    193 
    194 .. ts:def:: CoreApiNotification
    195 
    196   interface CoreApiNotification {
    197     // Distinguishes the message from responses.
    198     type: "notification";
    199 
    200     // A WalletNotification object.
    201     payload: unknown;
    202   }
    203 
    204 
    205 .. _wallet-core-transports:
    206 
    207 ----------
    208 Transports
    209 ----------
    210 
    211 The request/response protocol above is transport-agnostic.  The following
    212 transports are in use:
    213 
    214 **In-process.**  Front-ends that link against wallet-core as a library
    215 obtain a ``WalletCoreApiClient`` with two methods: ``call(operation, args)``
    216 returns the result or throws on error, and ``callForResult(operation,
    217 args)`` returns expected errors (see above) as a ``Result`` value instead of
    218 throwing.  Notifications are delivered via a registered listener.
    219 
    220 **Unix-domain socket.**  ``taler-wallet-cli`` can serve the wallet-core API
    221 over a Unix-domain socket (by default ``~/.wallet-core.sock``), allowing
    222 separate processes — and thus other programming languages — to act as
    223 wallet-core clients.  The framing protocol is line-based; JSON messages may
    224 span multiple lines and are wrapped in control lines that start with ``%``:
    225 
    226 .. code:: none
    227 
    228   # On connect, both sides greet each other:
    229   server> %hello-from-server
    230   client> %hello-from-client
    231 
    232   # A request is sent as:
    233   client> %request
    234   client> {"operation":"getBalances","id":"req-1","args":{}}
    235   client> %end
    236 
    237   # Responses and notifications are both sent as messages:
    238   server> %message
    239   server> {"type":"response","operation":"getBalances","id":"req-1","result":{...}}
    240   server> %end
    241 
    242   # Protocol-level errors terminate the connection:
    243   server> %error: invalid message
    244 
    245 **Browser messaging.**  The WebExtension front-end talks to wallet-core
    246 across the extension's message channel.  The same request, response and
    247 notification envelopes are wrapped in a versioned browser RPC message; see
    248 :doc:`/wallet/browser-integration` for details.
    249 
    250 
    251 .. _wallet-core-operations:
    252 
    253 ----------
    254 Operations
    255 ----------
    256 
    257 The operations are grouped by topic.  Each operation is introduced by a
    258 signature line with the operation's name, as sent in the ``operation``
    259 field of the `CoreApiRequestEnvelope`.  Unless noted otherwise, the
    260 operation's ``args`` must be an object of the stated request type, and a
    261 successful ``result`` is an object of the stated response type.
    262 
    263 Operations annotated *read-only* are pure functions of the wallet's
    264 stored state: they perform no database writes, do not create, cancel or
    265 otherwise affect transactions or background tasks, emit no notifications
    266 and perform no network requests.  All other operations document their
    267 side effects explicitly.  Operations annotated *deprecated* are kept for
    268 backwards compatibility and should not be used by new clients.
    269 
    270 
    271 Initialization and lifecycle
    272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    273 
    274 .. include:: wallet-core/init/init-wallet.rst
    275 
    276 .. include:: wallet-core/init/set-wallet-run-config.rst
    277 
    278 .. include:: wallet-core/init/get-version.rst
    279 
    280 .. include:: wallet-core/init/shutdown.rst
    281 
    282 Generic request management
    283 ^^^^^^^^^^^^^^^^^^^^^^^^^^
    284 
    285 Long-running operations that expose a ``progressToken`` can be cancelled or
    286 nudged with the following requests.
    287 
    288 .. include:: wallet-core/requests/retry-progress-token-now.rst
    289 
    290 .. include:: wallet-core/requests/cancel-progress-token.rst
    291 
    292 Hints
    293 ^^^^^
    294 
    295 Hints inform wallet-core about the state of the host application.  They do
    296 not query information and never return a meaningful result.
    297 
    298 .. include:: wallet-core/hints/hint-network-availability.rst
    299 
    300 .. include:: wallet-core/hints/hint-power-state.rst
    301 
    302 .. include:: wallet-core/hints/dismiss-wallet-warning.rst
    303 
    304 .. include:: wallet-core/hints/hint-application-resumed.rst
    305 
    306 Balances
    307 ^^^^^^^^
    308 
    309 .. include:: wallet-core/balances/get-balances.rst
    310 
    311 .. include:: wallet-core/balances/get-balance-detail.rst
    312 
    313 Transactions
    314 ^^^^^^^^^^^^
    315 
    316 Every longer-running business process of the wallet (withdrawals, payments,
    317 refreshes, peer-to-peer transfers, deposits, ...) is represented as a
    318 *transaction* with a state machine.  Transaction state changes are reported
    319 via :ref:`transaction-state-transition
    320 <wallet-notif-transaction-state-transition>` notifications.
    321 
    322 .. include:: wallet-core/transactions/get-transactions.rst
    323 
    324 .. include:: wallet-core/transactions/get-transactions-v2.rst
    325 
    326 .. include:: wallet-core/transactions/get-transaction-by-id.rst
    327 
    328 .. include:: wallet-core/transactions/resolve-transaction-reference.rst
    329 
    330 .. include:: wallet-core/transactions/abort-transaction.rst
    331 
    332 .. include:: wallet-core/transactions/fail-transaction.rst
    333 
    334 .. include:: wallet-core/transactions/suspend-transaction.rst
    335 
    336 .. include:: wallet-core/transactions/resume-transaction.rst
    337 
    338 .. include:: wallet-core/transactions/delete-transaction.rst
    339 
    340 .. include:: wallet-core/transactions/retry-transaction.rst
    341 
    342 .. include:: wallet-core/transactions/list-associated-refreshes.rst
    343 
    344 .. include:: wallet-core/transactions/wait-transaction-state.rst
    345 
    346 .. _wallet-core-observations:
    347 
    348 Transaction observations
    349 ^^^^^^^^^^^^^^^^^^^^^^^^
    350 
    351 Observations deliver complete snapshots for a UI view, including the
    352 transaction and the prerequisites needed to present its next action.
    353 Install the notification listener before registering: the initial snapshot
    354 can arrive before the registration response.  Preparation and confirmation
    355 remain separate operations.
    356 
    357 .. ts:op:: observeTransaction
    358 
    359   Observe an existing transaction of any `TransactionType`.  Obtain its
    360   ``transactionId`` from the relevant preparation operation or transaction
    361   history; this operation does not accept a payment or withdrawal URI.
    362 
    363   **Request:**
    364 
    365   The request ``args`` must be an `ObserveTransactionRequest` object.
    366   ``observationId`` is a caller-generated, nonempty string of at most 256
    367   characters, unique among active observations in this wallet instance.
    368   Use a fresh ID for each registration, including after reconnecting or
    369   retrying an observation.  Multiple observations of the same transaction
    370   are independent.
    371 
    372   **Response:**
    373 
    374   On success, the result is an `EmptyObject`.  The initial snapshot and
    375   subsequent updates arrive as `TransactionSnapshotNotification`
    376   objects, correlated by ``observationId`` rather than the request ``id``.
    377   Registration validates the transaction's type and existence; a failed
    378   registration leaves no observation behind.
    379 
    380   **Side effects:**
    381 
    382   Creates an in-memory subscription and emits notifications.  Each snapshot
    383   reads the transaction, exchanges and confirmation prerequisites from one
    384   consistent database view.  Observing makes no network requests, writes
    385   no persistent data and does not advance the transaction.  Changes to
    386   snapshot inputs, including balances, exchange data and payment choices,
    387   can produce updates without a transaction state transition.  Expiration
    388   and fee-validity deadlines can also change the snapshot.
    389 
    390   **Expected errors:**
    391 
    392   ``WALLET_CORE_API_BAD_REQUEST`` for a malformed or unsupported transaction
    393   ID, an invalid observation ID, or an observation ID already in use;
    394   ``WALLET_TRANSACTION_NOT_FOUND`` if the transaction does not exist.
    395 
    396   **Details:**
    397 
    398   Completed, failed and aborted transactions remain observable.  Database
    399   import or clearing refreshes observations against the replacement data.
    400   Deletion produces a final ``snapshot: null`` notification.  Shutdown
    401   discards observations; reconnecting clients must register again.  See
    402   :ref:`observation-snapshot <wallet-notif-observation-snapshot>` for
    403   replacement and revision rules, and
    404   :ref:`observation-error <wallet-notif-observation-error>` for later read
    405   failures.
    406 
    407   This request replaces ``observePeerPushCredit``.  Clients must use
    408   ``observationType: "transaction"`` and inspect ``snapshot.type`` for the
    409   transaction-specific payload.  Call :ts:op:`stopObservation` when the
    410   view closes.
    411 
    412 .. ts:def:: ObserveTransactionRequest
    413 
    414   interface ObserveTransactionRequest {
    415     transactionId: TransactionIdStr;
    416     observationId: string;
    417   }
    418 
    419 .. ts:op:: stopObservation
    420 
    421   End an observation without stopping transaction processing.
    422 
    423   **Request:**
    424 
    425   The request ``args`` must be a `StopObservationRequest` object.
    426   ``observationId`` has the same format as when registering.
    427 
    428   **Response:**
    429 
    430   On success, the result is an `EmptyObject`.  Stopping an unknown or
    431   already stopped observation is successful and has no effect.
    432 
    433   **Side effects:**
    434 
    435   Removes the subscription and its timer.  In-flight reads cannot publish
    436   new snapshots after it is stopped.  Notifications already queued on the
    437   transport can still arrive: remove the observation from the client's
    438   notification routing before sending this request.
    439 
    440   **Expected errors:**
    441 
    442   ``WALLET_CORE_API_BAD_REQUEST`` for an invalid observation ID.
    443 
    444 .. ts:def:: StopObservationRequest
    445 
    446   interface StopObservationRequest {
    447     observationId: string;
    448   }
    449 
    450 **Snapshot contents**
    451 
    452 A `TransactionSnapshot` contains the transaction's display fields and an
    453 ``exchanges`` array of relevant cached exchange summaries.  Missing exchange
    454 records are omitted from this array; they do not prevent observing the
    455 transaction.  The outer ``type`` matches ``transaction.type`` and determines
    456 which additional fields are present.
    457 
    458 Full contract terms, terms-of-service documents, internal state IDs and
    459 standalone KYC access tokens/payto hashes are excluded.  Actionable KYC
    460 links and transfer instructions remain available.  Preparation supplies peer
    461 contract terms; use :ts:op:`getTransactionById` with ``includeContractTerms``
    462 for merchant contract documents and :ts:op:`getExchangeTos` for terms of
    463 service.  Errors and failure/abort reasons have compact summaries, with
    464 ``hint`` and ``message`` limited to 1024 characters each.  Use
    465 :ts:op:`getTransactionById` for full diagnostic details.
    466 
    467 .. ts:def:: TransactionSnapshot
    468 
    469   type TransactionSnapshot =
    470     | PaymentSnapshot
    471     | WithdrawalSnapshot
    472     | InternalWithdrawalSnapshot
    473     | PeerPushCreditSnapshot
    474     | PeerPullCreditSnapshot
    475     | PeerPushDebitSnapshot
    476     | PeerPullDebitSnapshot
    477     | RefundSnapshot
    478     | RefreshSnapshot
    479     | DepositSnapshot
    480     | RecoupSnapshot
    481     | DenomLossSnapshot;
    482 
    483 
    484 .. ts:def:: TransactionSnapshotCommon
    485 
    486   interface TransactionSnapshotCommon {
    487     exchanges: ObservedExchange[];
    488   }
    489 
    490 
    491 .. ts:def:: PaymentSnapshot
    492 
    493   interface PaymentSnapshot extends TransactionSnapshotCommon {
    494     type: "payment";
    495     transaction: ObservedPaymentTransaction;
    496     payment: ObservedPaymentChoices | null;
    497     confirmation: {
    498       unavailableReasons: TransactionConfirmationUnavailableReason[];
    499     };
    500     currentDonauInfo?: { donauBaseUrl: string };
    501   }
    502 
    503 
    504 .. ts:def:: WithdrawalSnapshot
    505 
    506   interface WithdrawalSnapshot extends TransactionSnapshotCommon {
    507     type: "withdrawal";
    508     transaction: ObservedWithdrawalTransaction;
    509     bank?: ObservedBankWithdrawal;
    510   }
    511 
    512 
    513 .. ts:def:: InternalWithdrawalSnapshot
    514 
    515   interface InternalWithdrawalSnapshot extends TransactionSnapshotCommon {
    516     type: "internal-withdrawal";
    517     transaction: ObservedInternalWithdrawalTransaction;
    518   }
    519 
    520 
    521 .. ts:def:: PeerPushCreditSnapshot
    522 
    523   interface PeerPushCreditSnapshot extends TransactionSnapshotCommon {
    524     type: "peer-push-credit";
    525     transaction: ObservedPeerPushCreditTransaction;
    526     confirmation: {
    527       unavailableReasons: PeerPushCreditConfirmationUnavailableReason[];
    528     };
    529   }
    530 
    531 
    532 .. ts:def:: PeerPullCreditSnapshot
    533 
    534   interface PeerPullCreditSnapshot extends TransactionSnapshotCommon {
    535     type: "peer-pull-credit";
    536     transaction: ObservedPeerPullCreditTransaction;
    537   }
    538 
    539 
    540 .. ts:def:: PeerPushDebitSnapshot
    541 
    542   interface PeerPushDebitSnapshot extends TransactionSnapshotCommon {
    543     type: "peer-push-debit";
    544     transaction: ObservedPeerPushDebitTransaction;
    545   }
    546 
    547 
    548 .. ts:def:: PeerPullDebitSnapshot
    549 
    550   interface PeerPullDebitSnapshot extends TransactionSnapshotCommon {
    551     type: "peer-pull-debit";
    552     transaction: ObservedPeerPullDebitTransaction;
    553     confirmation: {
    554       unavailableReasons: TransactionConfirmationUnavailableReason[];
    555     };
    556   }
    557 
    558 
    559 .. ts:def:: RefundSnapshot
    560 
    561   interface RefundSnapshot extends TransactionSnapshotCommon {
    562     type: "refund";
    563     transaction: ObservedRefundTransaction;
    564   }
    565 
    566 
    567 .. ts:def:: RefreshSnapshot
    568 
    569   interface RefreshSnapshot extends TransactionSnapshotCommon {
    570     type: "refresh";
    571     transaction: ObservedRefreshTransaction;
    572   }
    573 
    574 
    575 .. ts:def:: DepositSnapshot
    576 
    577   interface DepositSnapshot extends TransactionSnapshotCommon {
    578     type: "deposit";
    579     transaction: ObservedDepositTransaction;
    580   }
    581 
    582 
    583 .. ts:def:: RecoupSnapshot
    584 
    585   interface RecoupSnapshot extends TransactionSnapshotCommon {
    586     type: "recoup";
    587     transaction: ObservedRecoupTransaction;
    588   }
    589 
    590 
    591 .. ts:def:: DenomLossSnapshot
    592 
    593   interface DenomLossSnapshot extends TransactionSnapshotCommon {
    594     type: "denom-loss";
    595     transaction: ObservedDenomLossTransaction;
    596   }
    597 
    598 For merchant payments, ``payment`` contains choices, affordability, costs,
    599 token availability and default/automatic selection.  It is null before
    600 contract download and outside payment review.  ``currentDonauInfo``, when
    601 present, identifies the configured donation service without exposing the
    602 taxpayer identifier.
    603 
    604 For bank-integrated withdrawals, ``bank`` contains the latest cached bank
    605 presentation when available.  ``transaction.txState`` takes precedence over
    606 the cached bank status.  Exchange candidates for an editable setup form
    607 remain a separate setup query.  Internal withdrawals can be observed by ID,
    608 but remain hidden from ordinary history and must not be counted again as
    609 an additional balance effect alongside their parent transaction.
    610 
    611 .. ts:def:: ObservedPaymentChoices
    612 
    613   interface ObservedPaymentChoices {
    614     choices: ChoiceSelectionDetail[];
    615     defaultChoiceIndex?: number;
    616     automaticExecution?: boolean;
    617     automaticExecutableIndex?: number;
    618   }
    619 
    620 .. ts:def:: ObservedBankWithdrawal
    621 
    622   interface ObservedBankWithdrawal {
    623     operationId: string;
    624     status: WithdrawalOperationStatusFlag;
    625     confirmTransferUrl?: string;
    626     currency: string;
    627     amount: AmountString | undefined;
    628     editableAmount: boolean;
    629     maxAmount: AmountString | undefined;
    630     wireFee: AmountString | undefined;
    631     defaultExchangeBaseUrl?: string;
    632     editableExchange: boolean;
    633   }
    634 
    635 `ObservedTransaction` includes only the following common and type-specific
    636 fields of `Transaction`, with their existing meanings and optionality.
    637 Each variant below extends `ObservedTransactionCommon`.  Fields added to
    638 `Transaction` are not automatically included in snapshots.
    639 
    640 .. ts:def:: ObservedTransaction
    641 
    642   type ObservedTransaction =
    643     | ObservedPaymentTransaction
    644     | ObservedWithdrawalTransaction
    645     | ObservedInternalWithdrawalTransaction
    646     | ObservedPeerPushCreditTransaction
    647     | ObservedPeerPullCreditTransaction
    648     | ObservedPeerPushDebitTransaction
    649     | ObservedPeerPullDebitTransaction
    650     | ObservedRefundTransaction
    651     | ObservedRefreshTransaction
    652     | ObservedDepositTransaction
    653     | ObservedRecoupTransaction
    654     | ObservedDenomLossTransaction;
    655 
    656 
    657 .. ts:def:: ObservedPaymentTransaction
    658 
    659   interface ObservedPaymentTransaction extends ObservedTransactionCommon {
    660     type: "payment";
    661     merchantBaseUrl: string;
    662     unclaimedPayUri?: TalerUriString;
    663     info: OrderShortInfo | undefined;
    664     totalRefundRaw: AmountString;
    665     totalRefundEffective: AmountString;
    666     refundPending: AmountString | undefined;
    667     refunds: RefundInfoShort[];
    668     refundQueryActive: boolean;
    669     posConfirmation: string | undefined;
    670     posConfirmationDeadline?: TalerProtocolTimestamp;
    671     posConfirmationViaNfc?: boolean;
    672     repurchaseTransactionId?: TransactionIdStr;
    673     choiceIndex?: number;
    674   }
    675 
    676 
    677 .. ts:def:: ObservedWithdrawalTransaction
    678 
    679   interface ObservedWithdrawalTransaction extends ObservedTransactionCommon {
    680     type: "withdrawal";
    681     exchangeBaseUrl: string | undefined;
    682     withdrawalDetails: WithdrawalDetails;
    683   }
    684 
    685 
    686 .. ts:def:: ObservedInternalWithdrawalTransaction
    687 
    688   interface ObservedInternalWithdrawalTransaction extends ObservedTransactionCommon {
    689     type: "internal-withdrawal";
    690     exchangeBaseUrl: string;
    691     withdrawalDetails: WithdrawalDetails;
    692   }
    693 
    694 
    695 .. ts:def:: ObservedPeerPushCreditTransaction
    696 
    697   interface ObservedPeerPushCreditTransaction extends ObservedTransactionCommon {
    698     type: "peer-push-credit";
    699     exchangeBaseUrl: string;
    700     info: PeerInfoShort;
    701   }
    702 
    703 
    704 .. ts:def:: ObservedPeerPullCreditTransaction
    705 
    706   interface ObservedPeerPullCreditTransaction extends ObservedTransactionCommon {
    707     type: "peer-pull-credit";
    708     exchangeBaseUrl: string;
    709     info: PeerInfoShort;
    710     talerUri: string | undefined;
    711   }
    712 
    713 
    714 .. ts:def:: ObservedPeerPushDebitTransaction
    715 
    716   interface ObservedPeerPushDebitTransaction extends ObservedTransactionCommon {
    717     type: "peer-push-debit";
    718     exchangeBaseUrl: string;
    719     info: PeerInfoShort;
    720     talerUri?: string;
    721   }
    722 
    723 
    724 .. ts:def:: ObservedPeerPullDebitTransaction
    725 
    726   interface ObservedPeerPullDebitTransaction extends ObservedTransactionCommon {
    727     type: "peer-pull-debit";
    728     exchangeBaseUrl: string;
    729     info: PeerInfoShort;
    730   }
    731 
    732 
    733 .. ts:def:: ObservedRefundTransaction
    734 
    735   interface ObservedRefundTransaction extends ObservedTransactionCommon {
    736     type: "refund";
    737     refundedTransactionId: string;
    738     paymentInfo: RefundPaymentInfo | undefined;
    739     isAbortRecovery?: boolean;
    740   }
    741 
    742 
    743 .. ts:def:: ObservedRefreshTransaction
    744 
    745   interface ObservedRefreshTransaction extends ObservedTransactionCommon {
    746     type: "refresh";
    747     refreshReason: RefreshReason;
    748     originatingTransactionId?: string;
    749     refreshInputAmount: AmountString;
    750     refreshOutputAmount: AmountString;
    751   }
    752 
    753 
    754 .. ts:def:: ObservedDepositTransaction
    755 
    756   interface ObservedDepositTransaction extends ObservedTransactionCommon {
    757     type: "deposit";
    758     depositGroupId: string;
    759     targetPaytoUri: string;
    760     accountPub: string;
    761     wireTransferDeadline: TalerProtocolTimestamp;
    762     wireTransferProgress: number;
    763     deposited: boolean;
    764     trackingState: DepositTransactionTrackingState[];
    765   }
    766 
    767 
    768 .. ts:def:: ObservedRecoupTransaction
    769 
    770   interface ObservedRecoupTransaction extends ObservedTransactionCommon {
    771     type: "recoup";
    772   }
    773 
    774 
    775 .. ts:def:: ObservedDenomLossTransaction
    776 
    777   interface ObservedDenomLossTransaction extends ObservedTransactionCommon {
    778     type: "denom-loss";
    779     lossEventType: DenomLossEventType;
    780     exchangeBaseUrl: string;
    781   }
    782 
    783 .. ts:def:: ObservedTransactionCommon
    784 
    785   interface ObservedTransactionCommon {
    786     transactionId: TransactionIdStr;
    787     localTransactionId?: string;
    788     legacy?: boolean;
    789     timestamp: TalerPreciseTimestamp;
    790     scopes: ScopeInfo[];
    791     txState: TransactionState;
    792     txActions: TransactionAction[];
    793     amountRaw: AmountString;
    794 
    795     // Initial estimate, including fees; preserved after failure.
    796     amountEffective: AmountString;
    797 
    798     // Settled balance effect, when it can be established.
    799     amountEffectiveFinal?: AmountString;
    800 
    801     kycUrl?: string;
    802     kycAmlReview?: boolean;
    803     kycAuthTransferInfo?: KycAuthTransferInfo;
    804     retryInfo?: TransactionRetryInfo;
    805     error?: ObservedTransactionError;
    806     abortReason?: ObservedTransactionError;
    807     failReason?: ObservedTransactionError;
    808   }
    809 
    810 .. ts:def:: ObservedTransactionError
    811 
    812   interface ObservedTransactionError extends ErrorInfoSummary {
    813     // Recovery target for exchange terms/key acceptance errors only.
    814     exchangeBaseUrl?: string;
    815   }
    816 
    817 .. ts:def:: TransactionRetryInfo
    818 
    819   interface TransactionRetryInfo {
    820     retryCounter: number;
    821     nextRetry: TalerPreciseTimestamp;
    822   }
    823 
    824 .. ts:def:: ObservedExchange
    825 
    826   interface ObservedExchange {
    827     exchangeBaseUrl: string;
    828     tosStatus: ExchangeTosStatus;
    829     unconfirmedKeyChange?: ExchangeKeyChangeInfo;
    830     exchangeUpdateStatus: ExchangeUpdateStatus;
    831     currencySpec: CurrencySpecification;
    832     walletKycRequestedThreshold?: string;
    833     tosCurrentEtag?: string;
    834     kycHardLimit?: AmountString;
    835     kycSoftLimit?: AmountString;
    836     lastUpdateError?: ErrorInfoSummary;
    837   }
    838 
    839 .. ts:def:: PeerPushCreditConfirmationUnavailableReason
    840 
    841   type PeerPushCreditConfirmationUnavailableReason =
    842     | "not-proposed"
    843     | "expired"
    844     | "exchange-not-ready"
    845     | "exchange-keys-not-accepted"
    846     | "exchange-tos-not-accepted"
    847     | "kyc-hard-limit";
    848 
    849 .. ts:def:: TransactionConfirmationUnavailableReason
    850 
    851   type TransactionConfirmationUnavailableReason =
    852     | PeerPushCreditConfirmationUnavailableReason
    853     | "contract-unavailable";
    854 
    855 ``confirmation.unavailableReasons`` reports locally known confirmation
    856 blockers for merchant payments, incoming peer push payments and outgoing
    857 peer pull payments.  An empty array means no such blocker is known; merchant
    858 payment choices still carry their individual affordability results.
    859 :ts:op:`confirmPay`, :ts:op:`confirmPeerPushCredit` and
    860 :ts:op:`confirmPeerPullDebit` remain authoritative and recheck prerequisites
    861 and remote state.  Other actions come from ``transaction.txActions``.
    862 Observation does not reserve coins.  Peer invoice amounts preserve the
    863 preparation estimate; confirmation checks the current purse balance and
    864 selects available coins.  An expired peer share link is omitted even before
    865 the persisted transaction state catches up.  A missing ``talerUri`` alone
    866 does not indicate loading: use the transaction state and actions.
    867 
    868 The amounts have the same meaning as in :ts:op:`getTransactionById`:
    869 ``amountEffective`` preserves the initial estimate, while
    870 ``amountEffectiveFinal`` describes the settled balance effect when known.
    871 
    872 **KYC and retry information**
    873 
    874 ``transaction.txState`` is the authoritative transaction status, including
    875 KYC in an associated withdrawal.  There is no separate KYC phase in the
    876 snapshot.  The minor states ``kyc-init``, ``kyc`` and ``balance-kyc`` retain
    877 their existing meanings; the major state distinguishes pending from
    878 suspended processing.
    879 
    880 ``transaction.kycUrl`` belongs to the active KYC requirement.  For peer
    881 credits, a link left from merge KYC is not exposed during ordinary withdrawal
    882 or after completion.  ``transaction.kycAmlReview`` carries the exchange's
    883 ``aml_review`` hint for that requirement.  When true, present waiting for
    884 review; a portal link can offer details without telling the user to submit
    885 information.  False means the exchange is not reporting this condition;
    886 it does not rule out an undisclosed review.  An absent field means no
    887 applicable value was reported.
    888 
    889 ``transaction.error`` describes the active operation, including an associated
    890 withdrawal or wallet-balance KYC task.  ``retryInfo``, when present, contains
    891 that same task's stored retry counter and next automatic retry time.  Both
    892 fields disappear when the task recovers.  User-initiated retry availability
    893 still comes from ``txActions``.
    894 
    895 The exchange's ``walletKycRequestedThreshold`` is account-level metadata,
    896 not an independent reason to prompt for transaction KYC.  Soft/hard limits,
    897 included for peer credits, reflect cached knowledge.  Neither those limits
    898 nor the transaction KYC fields predict clearance for a future exchange
    899 request; the observation adds no balance preview or KYC prediction.
    900 
    901 
    902 Withdrawals
    903 ^^^^^^^^^^^
    904 
    905 Withdrawal operations bring coins from an exchange into the wallet, either
    906 via a bank-integrated flow (the user authorizes the transfer in their
    907 banking application) or via a manual wire transfer to the exchange.
    908 
    909 .. include:: wallet-core/withdrawals/prepare-withdraw-exchange.rst
    910 
    911 .. include:: wallet-core/withdrawals/prepare-bank-integrated-withdrawal.rst
    912 
    913 .. include:: wallet-core/withdrawals/confirm-withdrawal.rst
    914 
    915 .. include:: wallet-core/withdrawals/accept-bank-integrated-withdrawal.rst
    916 
    917 .. include:: wallet-core/withdrawals/get-withdrawal-details-for-amount.rst
    918 
    919 .. include:: wallet-core/withdrawals/accept-manual-withdrawal.rst
    920 
    921 .. include:: wallet-core/withdrawals/get-withdrawal-details-for-uri.rst
    922 
    923 Merchant payments
    924 ^^^^^^^^^^^^^^^^^
    925 
    926 Payment operations handle ``taler://pay/`` and ``taler://pay-template/``
    927 URIs as well as payments to Paivana-protected resources, and follow-up
    928 actions such as refund queries and payment hand-off between wallets.
    929 
    930 .. include:: wallet-core/payments/get-choices-for-payment.rst
    931 
    932 .. include:: wallet-core/payments/prepare-pay-for-uri-v2.rst
    933 
    934 .. include:: wallet-core/payments/prepare-pay-for-template-v2.rst
    935 
    936 .. include:: wallet-core/payments/prepare-pay-for-paivana.rst
    937 
    938 .. include:: wallet-core/payments/get-paivana-cookie.rst
    939 
    940 .. include:: wallet-core/payments/unclaim-payment.rst
    941 
    942 .. include:: wallet-core/payments/reclaim-payment.rst
    943 
    944 .. include:: wallet-core/payments/check-pay-for-template.rst
    945 
    946 .. include:: wallet-core/payments/start-refund-query-for-uri.rst
    947 
    948 .. include:: wallet-core/payments/start-refund-query.rst
    949 
    950 .. include:: wallet-core/payments/confirm-pay.rst
    951 
    952 Deposits
    953 ^^^^^^^^
    954 
    955 Deposit operations send coins from the wallet to a bank account, usually
    956 the wallet user's own account.
    957 
    958 .. include:: wallet-core/deposits/check-deposit.rst
    959 
    960 .. include:: wallet-core/deposits/create-deposit-group.rst
    961 
    962 .. include:: wallet-core/deposits/convert-deposit-amount.rst
    963 
    964 .. include:: wallet-core/deposits/get-max-deposit-amount.rst
    965 
    966 .. include:: wallet-core/deposits/get-deposit-wire-types.rst
    967 
    968 .. include:: wallet-core/deposits/get-deposit-wire-types-for-currency.rst
    969 
    970 Peer-to-peer payments
    971 ^^^^^^^^^^^^^^^^^^^^^
    972 
    973 Peer-to-peer payments move funds directly between two wallets.  In a *push*
    974 payment, the sender initiates the transfer; in a *pull* payment, the
    975 receiver requests to be paid by the sender.
    976 
    977 .. include:: wallet-core/p2p/prepare-peer-push-credit.rst
    978 
    979 .. include:: wallet-core/p2p/check-peer-push-debit.rst
    980 
    981 .. include:: wallet-core/p2p/check-peer-push-debit-v2.rst
    982 
    983 .. include:: wallet-core/p2p/initiate-peer-push-debit.rst
    984 
    985 .. include:: wallet-core/p2p/confirm-peer-push-credit.rst
    986 
    987 .. include:: wallet-core/p2p/check-peer-pull-credit.rst
    988 
    989 .. include:: wallet-core/p2p/initiate-peer-pull-credit.rst
    990 
    991 .. include:: wallet-core/p2p/prepare-peer-pull-debit.rst
    992 
    993 .. include:: wallet-core/p2p/confirm-peer-pull-debit.rst
    994 
    995 .. include:: wallet-core/p2p/get-max-peer-push-debit-amount.rst
    996 
    997 Exchange management
    998 ^^^^^^^^^^^^^^^^^^^
    999 
   1000 These operations manage the set of exchanges known to the wallet, their
   1001 terms of service and their key material.
   1002 
   1003 .. include:: wallet-core/exchanges/add-exchange.rst
   1004 
   1005 .. include:: wallet-core/exchanges/list-exchanges.rst
   1006 
   1007 .. include:: wallet-core/exchanges/list-withdrawal-exchange-candidates.rst
   1008 
   1009 .. include:: wallet-core/exchanges/get-default-exchanges.rst
   1010 
   1011 .. include:: wallet-core/exchanges/get-exchange-entry-by-url.rst
   1012 
   1013 .. include:: wallet-core/exchanges/update-exchange-entry.rst
   1014 
   1015 .. include:: wallet-core/exchanges/get-exchange-resources.rst
   1016 
   1017 .. include:: wallet-core/exchanges/complete-exchange-base-url.rst
   1018 
   1019 .. include:: wallet-core/exchanges/delete-exchange.rst
   1020 
   1021 .. include:: wallet-core/exchanges/purge-exchange-legacy-keys.rst
   1022 
   1023 .. include:: wallet-core/exchanges/confirm-exchange-key-change.rst
   1024 
   1025 .. include:: wallet-core/exchanges/set-exchange-tos-accepted.rst
   1026 
   1027 .. include:: wallet-core/exchanges/set-exchange-tos-forgotten.rst
   1028 
   1029 .. include:: wallet-core/exchanges/get-exchange-tos.rst
   1030 
   1031 .. include:: wallet-core/exchanges/get-exchange-detailed-info.rst
   1032 
   1033 .. include:: wallet-core/exchanges/start-exchange-wallet-kyc.rst
   1034 
   1035 Bank accounts
   1036 ^^^^^^^^^^^^^
   1037 
   1038 Bank accounts known to the wallet are used as targets for deposits and as
   1039 a fallback when entering peer-to-peer payment information manually.
   1040 
   1041 .. include:: wallet-core/bank-accounts/list-bank-accounts.rst
   1042 
   1043 .. include:: wallet-core/bank-accounts/get-bank-account-by-id.rst
   1044 
   1045 .. include:: wallet-core/bank-accounts/add-bank-account.rst
   1046 
   1047 .. include:: wallet-core/bank-accounts/forget-bank-account.rst
   1048 
   1049 Global currency management
   1050 ^^^^^^^^^^^^^^^^^^^^^^^^^^
   1051 
   1052 These operations manage the wallet's configuration for a global currency:
   1053 the auditors that the wallet trusts for a currency and the exchanges
   1054 offering it, as well as the currency specification itself.
   1055 
   1056 .. include:: wallet-core/global-currency/list-global-currency-exchanges.rst
   1057 
   1058 .. include:: wallet-core/global-currency/list-global-currency-auditors.rst
   1059 
   1060 .. include:: wallet-core/global-currency/add-global-currency-exchange.rst
   1061 
   1062 .. include:: wallet-core/global-currency/remove-global-currency-exchange.rst
   1063 
   1064 .. include:: wallet-core/global-currency/add-global-currency-auditor.rst
   1065 
   1066 .. include:: wallet-core/global-currency/remove-global-currency-auditor.rst
   1067 
   1068 .. include:: wallet-core/global-currency/get-currency-specification.rst
   1069 
   1070 Tokens
   1071 ^^^^^^
   1072 
   1073 Token families represent discount tokens and subscription tokens obtained
   1074 during merchant payments.
   1075 
   1076 .. include:: wallet-core/tokens/list-discounts.rst
   1077 
   1078 .. include:: wallet-core/tokens/delete-discount.rst
   1079 
   1080 .. include:: wallet-core/tokens/list-subscriptions.rst
   1081 
   1082 .. include:: wallet-core/tokens/delete-subscription.rst
   1083 
   1084 Donau
   1085 ^^^^^
   1086 
   1087 The *donau* (donation authority) collects donation receipts for the wallet
   1088 user.  These operations configure the donau and query donation statements.
   1089 
   1090 .. include:: wallet-core/donau/set-donau.rst
   1091 
   1092 .. include:: wallet-core/donau/get-donau.rst
   1093 
   1094 .. include:: wallet-core/donau/get-donau-statements.rst
   1095 
   1096 Contacts
   1097 ^^^^^^^^
   1098 
   1099 .. include:: wallet-core/contacts/add-contact.rst
   1100 
   1101 .. include:: wallet-core/contacts/delete-contact.rst
   1102 
   1103 .. include:: wallet-core/contacts/get-contacts.rst
   1104 
   1105 Mailbox
   1106 ^^^^^^^
   1107 
   1108 The mailbox is used to receive ``taler://`` URIs (for example payment
   1109 requests) from other wallet users.
   1110 
   1111 .. include:: wallet-core/mailbox/get-mailbox.rst
   1112 
   1113 .. include:: wallet-core/mailbox/initialize-mailbox.rst
   1114 
   1115 .. include:: wallet-core/mailbox/get-mailbox-message.rst
   1116 
   1117 .. include:: wallet-core/mailbox/add-mailbox-message.rst
   1118 
   1119 .. include:: wallet-core/mailbox/delete-mailbox-message.rst
   1120 
   1121 .. include:: wallet-core/mailbox/send-taler-uri-mailbox-message.rst
   1122 
   1123 .. include:: wallet-core/mailbox/refresh-mailbox.rst
   1124 
   1125 Aliases (taldir)
   1126 ^^^^^^^^^^^^^^^^
   1127 
   1128 Aliases map human-readable identifiers to wallet addresses via a *taldir*
   1129 service, allowing senders to pay the wallet user without exchanging URIs
   1130 out of band.
   1131 
   1132 .. include:: wallet-core/taldir/register-alias.rst
   1133 
   1134 .. include:: wallet-core/taldir/complete-register-alias.rst
   1135 
   1136 .. include:: wallet-core/taldir/lookup-alias.rst
   1137 
   1138 Database management
   1139 ^^^^^^^^^^^^^^^^^^^
   1140 
   1141 These operations back up, restore, migrate and clear the wallet database.
   1142 
   1143 .. include:: wallet-core/database/import-db.rst
   1144 
   1145 .. include:: wallet-core/database/export-db.rst
   1146 
   1147 .. include:: wallet-core/database/export-db-to-file.rst
   1148 
   1149 .. include:: wallet-core/database/import-db-from-file.rst
   1150 
   1151 .. include:: wallet-core/database/migrate-database.rst
   1152 
   1153 .. include:: wallet-core/database/clear-db.rst
   1154 
   1155 .. include:: wallet-core/database/recycle.rst
   1156 
   1157 Data validation and conversion
   1158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1159 
   1160 Utility operations to validate and convert between data formats used by
   1161 the front-ends.
   1162 
   1163 .. include:: wallet-core/validation/validate-iban.rst
   1164 
   1165 .. include:: wallet-core/validation/canonicalize-base-url.rst
   1166 
   1167 .. include:: wallet-core/validation/convert-iban-account-field-to-payto.rst
   1168 
   1169 .. include:: wallet-core/validation/convert-iban-payto-to-account-field.rst
   1170 
   1171 .. include:: wallet-core/validation/get-banking-choices-for-payto.rst
   1172 
   1173 .. include:: wallet-core/validation/get-qr-codes-for-payto.rst
   1174 
   1175 Diagnostics
   1176 ^^^^^^^^^^^
   1177 
   1178 .. include:: wallet-core/diagnostics/get-diagnostics.rst
   1179 
   1180 .. include:: wallet-core/diagnostics/get-active-tasks.rst
   1181 
   1182 Testing and debugging
   1183 ^^^^^^^^^^^^^^^^^^^^^
   1184 
   1185 These operations are only meant for integration tests and developer
   1186 experiments.  They are not part of the API surface a production front-end
   1187 should rely on.
   1188 
   1189 .. include:: wallet-core/testing/apply-dev-experiment.rst
   1190 
   1191 .. include:: wallet-core/testing/testing-get-sample-transactions.rst
   1192 
   1193 .. include:: wallet-core/testing/withdraw-testkudos.rst
   1194 
   1195 .. include:: wallet-core/testing/withdraw-test-balance.rst
   1196 
   1197 .. include:: wallet-core/testing/run-integration-test.rst
   1198 
   1199 .. include:: wallet-core/testing/run-integration-test-v2.rst
   1200 
   1201 .. include:: wallet-core/testing/dump-coins.rst
   1202 
   1203 .. include:: wallet-core/testing/test-crypto.rst
   1204 
   1205 .. include:: wallet-core/testing/test-pay.rst
   1206 
   1207 .. include:: wallet-core/testing/set-coin-suspended.rst
   1208 
   1209 .. include:: wallet-core/testing/force-refresh.rst
   1210 
   1211 .. include:: wallet-core/testing/testing-wait-transactions-final.rst
   1212 
   1213 .. include:: wallet-core/testing/testing-wait-refreshes-final.rst
   1214 
   1215 .. include:: wallet-core/testing/testing-wait-transaction-state.rst
   1216 
   1217 .. include:: wallet-core/testing/testing-wait-exchange-state.rst
   1218 
   1219 .. include:: wallet-core/testing/testing-wait-exchange-ready.rst
   1220 
   1221 .. include:: wallet-core/testing/testing-wait-tasks-done.rst
   1222 
   1223 .. include:: wallet-core/testing/testing-wait-balance.rst
   1224 
   1225 .. include:: wallet-core/testing/testing-get-db-stats.rst
   1226 
   1227 .. include:: wallet-core/testing/testing-set-timetravel.rst
   1228 
   1229 .. include:: wallet-core/testing/testing-get-denom-stats.rst
   1230 
   1231 .. include:: wallet-core/testing/testing-recover-coins.rst
   1232 
   1233 .. include:: wallet-core/testing/testing-check-coins.rst
   1234 
   1235 .. include:: wallet-core/testing/testing-ping.rst
   1236 
   1237 .. include:: wallet-core/testing/testing-get-reserve-history.rst
   1238 
   1239 .. include:: wallet-core/testing/testing-reset-all-retries.rst
   1240 
   1241 .. include:: wallet-core/testing/testing-wait-wallet-kyc.rst
   1242 
   1243 .. include:: wallet-core/testing/testing-plan-migrate-exchange-base-url.rst
   1244 
   1245 .. include:: wallet-core/testing/testing-run-fixup.rst
   1246 
   1247 .. include:: wallet-core/testing/testing-get-flight-records.rst
   1248 
   1249 .. include:: wallet-core/testing/testing-get-performance-stats.rst
   1250 
   1251 .. include:: wallet-core/testing/testing-corrupt-withdrawal-coin-sel.rst
   1252 
   1253 
   1254 .. _wallet-core-notifications:
   1255 
   1256 -------------
   1257 Notifications
   1258 -------------
   1259 
   1260 Notifications are sent by wallet-core to all connected clients whenever
   1261 relevant state changes.  The ``payload`` of a `CoreApiNotification` is a
   1262 `WalletNotification`, a discriminated union on the ``type`` field.  Most
   1263 notifications are hints to re-query the affected state.  The
   1264 ``observation-snapshot`` variant instead carries a complete replacement
   1265 snapshot for a registered observation.  Route observation notifications by
   1266 ``observationId``; clients may receive notifications for observations they
   1267 did not register and should ignore those IDs.
   1268 
   1269 .. ts:def:: WalletNotification
   1270 
   1271   type WalletNotification =
   1272     | ObservationSnapshotNotification
   1273     | ObservationErrorNotification
   1274     | CoinRecoveryProgressNotification
   1275     | BalanceChangeNotification
   1276     | BankAccountChangeNotification
   1277     | BackupOperationErrorNotification
   1278     | ContactAddedNotification
   1279     | ContactDeletedNotification
   1280     | MailboxMessageAddedNotification
   1281     | MailboxMessageDeletedNotification
   1282     | ExchangeStateTransitionNotification
   1283     | TransactionStateTransitionNotification
   1284     | TaskProgressNotification
   1285     | RequestObservabilityEventNotification
   1286     | IdleNotification
   1287     | RequestProgressNotification
   1288     | RequestProgressPhaseNotification
   1289     | DatabaseMaintenanceProgressNotification;
   1290 
   1291 .. ts:def:: NotificationType
   1292 
   1293   enum NotificationType {
   1294     ObservationSnapshot = "observation-snapshot",
   1295     ObservationError = "observation-error",
   1296     CoinRecoveryProgress = "coin-recovery-progress",
   1297     BalanceChange = "balance-change",
   1298     BankAccountChange = "bank-account-change",
   1299     BackupOperationError = "backup-error",
   1300     ContactAdded = "contact-added",
   1301     ContactDeleted = "contact-deleted",
   1302     MailboxMessageAdded = "mailbox-message-added",
   1303     MailboxMessageDeleted = "mailbox-message-deleted",
   1304     TransactionStateTransition = "transaction-state-transition",
   1305     ExchangeStateTransition = "exchange-state-transition",
   1306     Idle = "idle",
   1307     TaskObservabilityEvent = "task-observability-event",
   1308     RequestObservabilityEvent = "request-observability-event",
   1309     RequestProgressError = "request-progress-error",
   1310     RequestProgressPhase = "request-progress-phase",
   1311     DatabaseMaintenanceProgress = "database-maintenance-progress",
   1312   }
   1313 
   1314 .. include:: wallet-core/notifications.rst
   1315 
   1316 
   1317 Observation notifications
   1318 ^^^^^^^^^^^^^^^^^^^^^^^^^
   1319 
   1320 .. _wallet-notif-observation-snapshot:
   1321 
   1322 **observation-snapshot**
   1323 
   1324 All snapshot observations use this notification type.  ``observationType``
   1325 discriminates the observed domain; transaction observations use
   1326 ``"transaction"``.  ``snapshot.type`` identifies the transaction type.
   1327 
   1328 .. ts:def:: ObservationType
   1329 
   1330   enum ObservationType {
   1331     Transaction = "transaction",
   1332     BalanceRefreshInfo = "balance-refresh-info",
   1333   }
   1334 
   1335 .. ts:def:: ObservationSnapshotNotification
   1336 
   1337   type ObservationSnapshotNotification =
   1338     | TransactionSnapshotNotification
   1339     | BalanceRefreshSnapshotNotification;
   1340 
   1341 .. ts:def:: BalanceRefreshSnapshotNotification
   1342 
   1343   interface BalanceRefreshSnapshotNotification {
   1344     type: "observation-snapshot";
   1345     observationType: "balance-refresh-info";
   1346     observationId: string;
   1347     revision: number;
   1348     scopeInfo: ScopeInfo;
   1349     snapshot: WalletRefreshInfo | null;
   1350   }
   1351 
   1352 .. ts:def:: TransactionSnapshotNotification
   1353 
   1354   interface TransactionSnapshotNotification {
   1355     type: "observation-snapshot";
   1356     observationType: "transaction";
   1357     observationId: string;
   1358     revision: number;
   1359     transactionId: TransactionIdStr;
   1360     snapshot: TransactionSnapshot | null;
   1361   }
   1362 
   1363 Revision 1 carries the initial snapshot.  Revisions increase within one
   1364 observation only when its snapshot changes; they are not database or
   1365 transaction versions.  Replace the previous snapshot in full, including
   1366 clearing optional fields that disappeared.  Clients can ignore revisions
   1367 no newer than the last one applied for that observation ID.
   1368 
   1369 Updates can be coalesced: snapshots describe current state and do not
   1370 promise to report every intermediate transition.  A final ``snapshot: null``
   1371 means the subject is absent and the observation has ended.  Stop
   1372 routing updates for that ID and discard its previous snapshot.
   1373 
   1374 .. _wallet-notif-observation-error:
   1375 
   1376 **observation-error**
   1377 
   1378 If a snapshot cannot be built after successful registration, wallet-core
   1379 emits an `ObservationErrorNotification` and ends the observation.  Its error
   1380 summary has the same size limits as errors in snapshots.  Initial read
   1381 failures instead fail the registration request.
   1382 
   1383 .. ts:def:: ObservationErrorNotification
   1384 
   1385   interface ObservationErrorNotification {
   1386     type: "observation-error";
   1387     observationType: ObservationType;
   1388     observationId: string;
   1389     error: ErrorInfoSummary;
   1390   }
   1391 
   1392 This is an observation failure, not a failed payment.  A UI may retain the
   1393 last snapshot as stale, disable confirmation, and offer to register again
   1394 with a fresh observation ID.  Disconnection also requires a new registration;
   1395 wait for its first snapshot before enabling actions based on current state.