api-wallet-core.rst (23845B)
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/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 **10: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 68 69 .. _wallet-core-conventions: 70 71 --------------------- 72 Protocol conventions 73 --------------------- 74 75 Operations 76 ^^^^^^^^^^ 77 78 Every interaction with wallet-core starts with the client sending a 79 `CoreApiRequestEnvelope`. The ``operation`` field selects the operation, 80 ``id`` is a client-chosen request identifier that is echoed back in the 81 response (allowing multiple requests to be in flight), and ``args`` carries 82 the operation-specific request payload. Operations that take no arguments 83 use an empty object (`EmptyObject`). 84 85 .. ts:def:: CoreApiRequestEnvelope 86 87 interface CoreApiRequestEnvelope { 88 // Client-chosen request identifier, echoed in the response. 89 id: string; 90 91 // Name of the operation, e.g. "getBalances". 92 operation: string; 93 94 // Operation-specific request payload. 95 args: unknown; 96 } 97 98 .. ts:def:: EmptyObject 99 100 // Placeholder for operations without arguments or without a result. 101 type EmptyObject = Record<string, never>; 102 103 Responses and errors 104 ^^^^^^^^^^^^^^^^^^^^ 105 106 A request is always answered with exactly one of the following envelopes: 107 108 .. ts:def:: CoreApiResponseSuccess 109 110 interface CoreApiResponseSuccess { 111 // Distinguishes the message from errors and notifications. 112 type: "response"; 113 114 // Operation that was invoked. 115 operation: string; 116 117 // Request identifier from the corresponding request. 118 id: string; 119 120 // Operation-specific result payload. 121 result: unknown; 122 } 123 124 .. ts:def:: CoreApiResponseError 125 126 interface CoreApiResponseError { 127 // Distinguishes the message from responses and notifications. 128 type: "error"; 129 130 // Operation that was invoked. 131 operation: string; 132 133 // Request identifier from the corresponding request. 134 id: string; 135 136 // Details about the failure. 137 error: TalerErrorDetail; 138 } 139 140 The ``error`` object carries a numeric ``code`` from the 141 `error code registry <error-codes>`_ plus optional details. It has the 142 same structure as the `ErrorDetail` of the REST APIs (see 143 :ref:`http-common`), but allows arbitrary additional fields depending on 144 the error code: 145 146 .. ts:def:: TalerErrorDetail 147 148 interface TalerErrorDetail { 149 // Numeric error code unique to the condition. 150 code: TalerErrorCode; 151 152 // When did the error occur. 153 when?: AbsoluteTime; 154 155 // Human-readable description of the error. May change without notice! 156 hint?: string; 157 158 // Additional fields specific to the error code. 159 [x: string]: unknown; 160 } 161 162 For each operation, this specification lists the *expected* error codes: 163 conditions the caller can reasonably react to inline (for example 164 ``WALLET_TRANSACTION_NOT_FOUND`` or 165 ``WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE``). Any other failure 166 (network problems, protocol violations, internal errors) is also reported 167 via the error envelope, but is not listed per operation. 168 169 Initialization 170 ^^^^^^^^^^^^^^ 171 172 :ts:op:`initWallet` (or 173 :ts:op:`setWalletRunConfig`) must be the first 174 request made to wallet-core; every other operation fails until 175 initialization has completed. Once the wallet has been shut down via 176 :ts:op:`shutdown`, every operation other than 177 ``shutdown`` itself fails with ``WALLET_CORE_NOT_AVAILABLE`` until 178 wallet-core is restarted and initialized again. 179 180 Notifications 181 ^^^^^^^^^^^^^ 182 183 In addition to responses, wallet-core spontaneously sends *notifications* 184 to connected clients, for example when the balance or the state of a 185 transaction changes. Notifications are not correlated with a request 186 ``id``. Clients should use them as a trigger to re-query state, not as an 187 authoritative state transfer. See :ref:`wallet-core-notifications` for the 188 list of notification types. 189 190 .. ts:def:: CoreApiNotification 191 192 interface CoreApiNotification { 193 // Distinguishes the message from responses. 194 type: "notification"; 195 196 // A WalletNotification object. 197 payload: unknown; 198 } 199 200 201 .. _wallet-core-transports: 202 203 ---------- 204 Transports 205 ---------- 206 207 The request/response protocol above is transport-agnostic. The following 208 transports are in use: 209 210 **In-process.** Front-ends that link against wallet-core as a library 211 obtain a ``WalletCoreApiClient`` with two methods: ``call(operation, args)`` 212 returns the result or throws on error, and ``callForResult(operation, 213 args)`` returns expected errors (see above) as a ``Result`` value instead of 214 throwing. Notifications are delivered via a registered listener. 215 216 **Unix-domain socket.** ``taler-wallet-cli`` can serve the wallet-core API 217 over a Unix-domain socket (by default ``~/.wallet-core.sock``), allowing 218 separate processes — and thus other programming languages — to act as 219 wallet-core clients. The framing protocol is line-based; JSON messages may 220 span multiple lines and are wrapped in control lines that start with ``%``: 221 222 .. code:: none 223 224 # On connect, both sides greet each other: 225 server> %hello-from-server 226 client> %hello-from-client 227 228 # A request is sent as: 229 client> %request 230 client> {"operation":"getBalances","id":"req-1","args":{}} 231 client> %end 232 233 # Responses and notifications are both sent as messages: 234 server> %message 235 server> {"type":"response","operation":"getBalances","id":"req-1","result":{...}} 236 server> %end 237 238 # Protocol-level errors terminate the connection: 239 server> %error: invalid message 240 241 **Browser messaging.** The WebExtension front-end talks to wallet-core 242 across the extension's message channel. The same request, response and 243 notification envelopes are wrapped in a versioned browser RPC message; see 244 :doc:`/wallet/browser-integration` for details. 245 246 247 .. _wallet-core-operations: 248 249 ---------- 250 Operations 251 ---------- 252 253 The operations are grouped by topic. Each operation is introduced by a 254 signature line with the operation's name, as sent in the ``operation`` 255 field of the `CoreApiRequestEnvelope`. Unless noted otherwise, the 256 operation's ``args`` must be an object of the stated request type, and a 257 successful ``result`` is an object of the stated response type. 258 259 Operations annotated *read-only* are pure functions of the wallet's 260 stored state: they perform no database writes, do not create, cancel or 261 otherwise affect transactions or background tasks, emit no notifications 262 and perform no network requests. All other operations document their 263 side effects explicitly. Operations annotated *deprecated* are kept for 264 backwards compatibility and should not be used by new clients. 265 266 267 Initialization and lifecycle 268 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 269 270 .. include:: wallet-core/init/init-wallet.rst 271 272 .. include:: wallet-core/init/set-wallet-run-config.rst 273 274 .. include:: wallet-core/init/get-version.rst 275 276 .. include:: wallet-core/init/shutdown.rst 277 278 Generic request management 279 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 280 281 Long-running operations that expose a ``progressToken`` can be cancelled or 282 nudged with the following requests. 283 284 .. include:: wallet-core/requests/retry-progress-token-now.rst 285 286 .. include:: wallet-core/requests/cancel-progress-token.rst 287 288 Hints 289 ^^^^^ 290 291 Hints inform wallet-core about the state of the host application. They do 292 not query information and never return a meaningful result. 293 294 .. include:: wallet-core/hints/hint-network-availability.rst 295 296 .. include:: wallet-core/hints/hint-power-state.rst 297 298 .. include:: wallet-core/hints/dismiss-wallet-warning.rst 299 300 .. include:: wallet-core/hints/hint-application-resumed.rst 301 302 Balances 303 ^^^^^^^^ 304 305 .. include:: wallet-core/balances/get-balances.rst 306 307 .. include:: wallet-core/balances/get-balance-detail.rst 308 309 Transactions 310 ^^^^^^^^^^^^ 311 312 Every longer-running business process of the wallet (withdrawals, payments, 313 refreshes, peer-to-peer transfers, deposits, ...) is represented as a 314 *transaction* with a state machine. Transaction state changes are reported 315 via :ref:`transaction-state-transition 316 <wallet-notif-transaction-state-transition>` notifications. 317 318 .. include:: wallet-core/transactions/get-transactions.rst 319 320 .. include:: wallet-core/transactions/get-transactions-v2.rst 321 322 .. include:: wallet-core/transactions/get-transaction-by-id.rst 323 324 .. include:: wallet-core/transactions/resolve-transaction-reference.rst 325 326 .. include:: wallet-core/transactions/abort-transaction.rst 327 328 .. include:: wallet-core/transactions/fail-transaction.rst 329 330 .. include:: wallet-core/transactions/suspend-transaction.rst 331 332 .. include:: wallet-core/transactions/resume-transaction.rst 333 334 .. include:: wallet-core/transactions/delete-transaction.rst 335 336 .. include:: wallet-core/transactions/retry-transaction.rst 337 338 .. include:: wallet-core/transactions/list-associated-refreshes.rst 339 340 .. include:: wallet-core/transactions/wait-transaction-state.rst 341 342 Withdrawals 343 ^^^^^^^^^^^ 344 345 Withdrawal operations bring coins from an exchange into the wallet, either 346 via a bank-integrated flow (the user authorizes the transfer in their 347 banking application) or via a manual wire transfer to the exchange. 348 349 .. include:: wallet-core/withdrawals/prepare-withdraw-exchange.rst 350 351 .. include:: wallet-core/withdrawals/prepare-bank-integrated-withdrawal.rst 352 353 .. include:: wallet-core/withdrawals/confirm-withdrawal.rst 354 355 .. include:: wallet-core/withdrawals/accept-bank-integrated-withdrawal.rst 356 357 .. include:: wallet-core/withdrawals/get-withdrawal-details-for-amount.rst 358 359 .. include:: wallet-core/withdrawals/accept-manual-withdrawal.rst 360 361 .. include:: wallet-core/withdrawals/get-withdrawal-details-for-uri.rst 362 363 Merchant payments 364 ^^^^^^^^^^^^^^^^^ 365 366 Payment operations handle ``taler://pay/`` and ``taler://pay-template/`` 367 URIs as well as payments to Paivana-protected resources, and follow-up 368 actions such as refund queries and payment hand-off between wallets. 369 370 .. include:: wallet-core/payments/get-choices-for-payment.rst 371 372 .. include:: wallet-core/payments/prepare-pay-for-uri-v2.rst 373 374 .. include:: wallet-core/payments/prepare-pay-for-template-v2.rst 375 376 .. include:: wallet-core/payments/prepare-pay-for-paivana.rst 377 378 .. include:: wallet-core/payments/get-paivana-cookie.rst 379 380 .. include:: wallet-core/payments/unclaim-payment.rst 381 382 .. include:: wallet-core/payments/reclaim-payment.rst 383 384 .. include:: wallet-core/payments/check-pay-for-template.rst 385 386 .. include:: wallet-core/payments/start-refund-query-for-uri.rst 387 388 .. include:: wallet-core/payments/start-refund-query.rst 389 390 .. include:: wallet-core/payments/confirm-pay.rst 391 392 Deposits 393 ^^^^^^^^ 394 395 Deposit operations send coins from the wallet to a bank account, usually 396 the wallet user's own account. 397 398 .. include:: wallet-core/deposits/check-deposit.rst 399 400 .. include:: wallet-core/deposits/create-deposit-group.rst 401 402 .. include:: wallet-core/deposits/convert-deposit-amount.rst 403 404 .. include:: wallet-core/deposits/get-max-deposit-amount.rst 405 406 .. include:: wallet-core/deposits/get-deposit-wire-types.rst 407 408 .. include:: wallet-core/deposits/get-deposit-wire-types-for-currency.rst 409 410 Peer-to-peer payments 411 ^^^^^^^^^^^^^^^^^^^^^ 412 413 Peer-to-peer payments move funds directly between two wallets. In a *push* 414 payment, the sender initiates the transfer; in a *pull* payment, the 415 receiver requests to be paid by the sender. 416 417 .. include:: wallet-core/p2p/prepare-peer-push-credit.rst 418 419 .. include:: wallet-core/p2p/check-peer-push-debit.rst 420 421 .. include:: wallet-core/p2p/check-peer-push-debit-v2.rst 422 423 .. include:: wallet-core/p2p/initiate-peer-push-debit.rst 424 425 .. include:: wallet-core/p2p/confirm-peer-push-credit.rst 426 427 .. include:: wallet-core/p2p/check-peer-pull-credit.rst 428 429 .. include:: wallet-core/p2p/initiate-peer-pull-credit.rst 430 431 .. include:: wallet-core/p2p/prepare-peer-pull-debit.rst 432 433 .. include:: wallet-core/p2p/confirm-peer-pull-debit.rst 434 435 .. include:: wallet-core/p2p/get-max-peer-push-debit-amount.rst 436 437 Exchange management 438 ^^^^^^^^^^^^^^^^^^^ 439 440 These operations manage the set of exchanges known to the wallet, their 441 terms of service and their key material. 442 443 .. include:: wallet-core/exchanges/add-exchange.rst 444 445 .. include:: wallet-core/exchanges/list-exchanges.rst 446 447 .. include:: wallet-core/exchanges/list-withdrawal-exchange-candidates.rst 448 449 .. include:: wallet-core/exchanges/get-default-exchanges.rst 450 451 .. include:: wallet-core/exchanges/get-exchange-entry-by-url.rst 452 453 .. include:: wallet-core/exchanges/update-exchange-entry.rst 454 455 .. include:: wallet-core/exchanges/get-exchange-resources.rst 456 457 .. include:: wallet-core/exchanges/complete-exchange-base-url.rst 458 459 .. include:: wallet-core/exchanges/delete-exchange.rst 460 461 .. include:: wallet-core/exchanges/purge-exchange-legacy-keys.rst 462 463 .. include:: wallet-core/exchanges/confirm-exchange-key-change.rst 464 465 .. include:: wallet-core/exchanges/set-exchange-tos-accepted.rst 466 467 .. include:: wallet-core/exchanges/set-exchange-tos-forgotten.rst 468 469 .. include:: wallet-core/exchanges/get-exchange-tos.rst 470 471 .. include:: wallet-core/exchanges/get-exchange-detailed-info.rst 472 473 .. include:: wallet-core/exchanges/start-exchange-wallet-kyc.rst 474 475 Bank accounts 476 ^^^^^^^^^^^^^ 477 478 Bank accounts known to the wallet are used as targets for deposits and as 479 a fallback when entering peer-to-peer payment information manually. 480 481 .. include:: wallet-core/bank-accounts/list-bank-accounts.rst 482 483 .. include:: wallet-core/bank-accounts/get-bank-account-by-id.rst 484 485 .. include:: wallet-core/bank-accounts/add-bank-account.rst 486 487 .. include:: wallet-core/bank-accounts/forget-bank-account.rst 488 489 Global currency management 490 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 491 492 These operations manage the wallet's configuration for a global currency: 493 the auditors that the wallet trusts for a currency and the exchanges 494 offering it, as well as the currency specification itself. 495 496 .. include:: wallet-core/global-currency/list-global-currency-exchanges.rst 497 498 .. include:: wallet-core/global-currency/list-global-currency-auditors.rst 499 500 .. include:: wallet-core/global-currency/add-global-currency-exchange.rst 501 502 .. include:: wallet-core/global-currency/remove-global-currency-exchange.rst 503 504 .. include:: wallet-core/global-currency/add-global-currency-auditor.rst 505 506 .. include:: wallet-core/global-currency/remove-global-currency-auditor.rst 507 508 .. include:: wallet-core/global-currency/get-currency-specification.rst 509 510 Tokens 511 ^^^^^^ 512 513 Token families represent discount tokens and subscription tokens obtained 514 during merchant payments. 515 516 .. include:: wallet-core/tokens/list-discounts.rst 517 518 .. include:: wallet-core/tokens/delete-discount.rst 519 520 .. include:: wallet-core/tokens/list-subscriptions.rst 521 522 .. include:: wallet-core/tokens/delete-subscription.rst 523 524 Donau 525 ^^^^^ 526 527 The *donau* (donation authority) collects donation receipts for the wallet 528 user. These operations configure the donau and query donation statements. 529 530 .. include:: wallet-core/donau/set-donau.rst 531 532 .. include:: wallet-core/donau/get-donau.rst 533 534 .. include:: wallet-core/donau/get-donau-statements.rst 535 536 Contacts 537 ^^^^^^^^ 538 539 .. include:: wallet-core/contacts/add-contact.rst 540 541 .. include:: wallet-core/contacts/delete-contact.rst 542 543 .. include:: wallet-core/contacts/get-contacts.rst 544 545 Mailbox 546 ^^^^^^^ 547 548 The mailbox is used to receive ``taler://`` URIs (for example payment 549 requests) from other wallet users. 550 551 .. include:: wallet-core/mailbox/get-mailbox.rst 552 553 .. include:: wallet-core/mailbox/initialize-mailbox.rst 554 555 .. include:: wallet-core/mailbox/get-mailbox-message.rst 556 557 .. include:: wallet-core/mailbox/add-mailbox-message.rst 558 559 .. include:: wallet-core/mailbox/delete-mailbox-message.rst 560 561 .. include:: wallet-core/mailbox/send-taler-uri-mailbox-message.rst 562 563 .. include:: wallet-core/mailbox/refresh-mailbox.rst 564 565 Aliases (taldir) 566 ^^^^^^^^^^^^^^^^ 567 568 Aliases map human-readable identifiers to wallet addresses via a *taldir* 569 service, allowing senders to pay the wallet user without exchanging URIs 570 out of band. 571 572 .. include:: wallet-core/taldir/register-alias.rst 573 574 .. include:: wallet-core/taldir/complete-register-alias.rst 575 576 .. include:: wallet-core/taldir/lookup-alias.rst 577 578 Database management 579 ^^^^^^^^^^^^^^^^^^^ 580 581 These operations back up, restore, migrate and clear the wallet database. 582 583 .. include:: wallet-core/database/import-db.rst 584 585 .. include:: wallet-core/database/export-db.rst 586 587 .. include:: wallet-core/database/export-db-to-file.rst 588 589 .. include:: wallet-core/database/import-db-from-file.rst 590 591 .. include:: wallet-core/database/migrate-database.rst 592 593 .. include:: wallet-core/database/clear-db.rst 594 595 .. include:: wallet-core/database/recycle.rst 596 597 Data validation and conversion 598 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 599 600 Utility operations to validate and convert between data formats used by 601 the front-ends. 602 603 .. include:: wallet-core/validation/validate-iban.rst 604 605 .. include:: wallet-core/validation/canonicalize-base-url.rst 606 607 .. include:: wallet-core/validation/convert-iban-account-field-to-payto.rst 608 609 .. include:: wallet-core/validation/convert-iban-payto-to-account-field.rst 610 611 .. include:: wallet-core/validation/get-banking-choices-for-payto.rst 612 613 .. include:: wallet-core/validation/get-qr-codes-for-payto.rst 614 615 Diagnostics 616 ^^^^^^^^^^^ 617 618 .. include:: wallet-core/diagnostics/get-diagnostics.rst 619 620 .. include:: wallet-core/diagnostics/get-active-tasks.rst 621 622 Testing and debugging 623 ^^^^^^^^^^^^^^^^^^^^^ 624 625 These operations are only meant for integration tests and developer 626 experiments. They are not part of the API surface a production front-end 627 should rely on. 628 629 .. include:: wallet-core/testing/apply-dev-experiment.rst 630 631 .. include:: wallet-core/testing/testing-get-sample-transactions.rst 632 633 .. include:: wallet-core/testing/withdraw-testkudos.rst 634 635 .. include:: wallet-core/testing/withdraw-test-balance.rst 636 637 .. include:: wallet-core/testing/run-integration-test.rst 638 639 .. include:: wallet-core/testing/run-integration-test-v2.rst 640 641 .. include:: wallet-core/testing/dump-coins.rst 642 643 .. include:: wallet-core/testing/test-crypto.rst 644 645 .. include:: wallet-core/testing/test-pay.rst 646 647 .. include:: wallet-core/testing/set-coin-suspended.rst 648 649 .. include:: wallet-core/testing/force-refresh.rst 650 651 .. include:: wallet-core/testing/testing-wait-transactions-final.rst 652 653 .. include:: wallet-core/testing/testing-wait-refreshes-final.rst 654 655 .. include:: wallet-core/testing/testing-wait-transaction-state.rst 656 657 .. include:: wallet-core/testing/testing-wait-exchange-state.rst 658 659 .. include:: wallet-core/testing/testing-wait-exchange-ready.rst 660 661 .. include:: wallet-core/testing/testing-wait-tasks-done.rst 662 663 .. include:: wallet-core/testing/testing-wait-balance.rst 664 665 .. include:: wallet-core/testing/testing-get-db-stats.rst 666 667 .. include:: wallet-core/testing/testing-set-timetravel.rst 668 669 .. include:: wallet-core/testing/testing-get-denom-stats.rst 670 671 .. include:: wallet-core/testing/testing-recover-coins.rst 672 673 .. include:: wallet-core/testing/testing-check-coins.rst 674 675 .. include:: wallet-core/testing/testing-ping.rst 676 677 .. include:: wallet-core/testing/testing-get-reserve-history.rst 678 679 .. include:: wallet-core/testing/testing-reset-all-retries.rst 680 681 .. include:: wallet-core/testing/testing-wait-wallet-kyc.rst 682 683 .. include:: wallet-core/testing/testing-plan-migrate-exchange-base-url.rst 684 685 .. include:: wallet-core/testing/testing-run-fixup.rst 686 687 .. include:: wallet-core/testing/testing-get-flight-records.rst 688 689 .. include:: wallet-core/testing/testing-get-performance-stats.rst 690 691 .. include:: wallet-core/testing/testing-corrupt-withdrawal-coin-sel.rst 692 693 694 .. _wallet-core-notifications: 695 696 ------------- 697 Notifications 698 ------------- 699 700 Notifications are sent by wallet-core to all connected clients whenever 701 relevant state changes. The ``payload`` of a `CoreApiNotification` is a 702 `WalletNotification`, a discriminated union on the ``type`` field. Clients 703 should treat notifications as hints to re-query the affected state; the 704 notification contents are deliberately minimal and must not be relied upon 705 as an authoritative state transfer. 706 707 .. ts:def:: WalletNotification 708 709 type WalletNotification = 710 | CoinRecoveryProgressNotification 711 | BalanceChangeNotification 712 | BankAccountChangeNotification 713 | BackupOperationErrorNotification 714 | ContactAddedNotification 715 | ContactDeletedNotification 716 | MailboxMessageAddedNotification 717 | MailboxMessageDeletedNotification 718 | ExchangeStateTransitionNotification 719 | TransactionStateTransitionNotification 720 | TaskProgressNotification 721 | RequestObservabilityEventNotification 722 | IdleNotification 723 | RequestProgressNotification 724 | RequestProgressPhaseNotification 725 | DatabaseMaintenanceProgressNotification; 726 727 .. ts:def:: NotificationType 728 729 enum NotificationType { 730 CoinRecoveryProgress = "coin-recovery-progress", 731 BalanceChange = "balance-change", 732 BankAccountChange = "bank-account-change", 733 BackupOperationError = "backup-error", 734 ContactAdded = "contact-added", 735 ContactDeleted = "contact-deleted", 736 MailboxMessageAdded = "mailbox-message-added", 737 MailboxMessageDeleted = "mailbox-message-deleted", 738 TransactionStateTransition = "transaction-state-transition", 739 ExchangeStateTransition = "exchange-state-transition", 740 Idle = "idle", 741 TaskObservabilityEvent = "task-observability-event", 742 RequestObservabilityEvent = "request-observability-event", 743 RequestProgressError = "request-progress-error", 744 RequestProgressPhase = "request-progress-phase", 745 DatabaseMaintenanceProgress = "database-maintenance-progress", 746 } 747 748 .. include:: wallet-core/notifications.rst