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.