taler-docs

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

commit 80b90be258c618f99c21bb32694f9bf41ff3dda9
parent e8d46578aa13ef4aab7269052aeee542c2fa830e
Author: Florian Dold <dold@taler.net>
Date:   Tue, 17 Nov 2026 23:20:42 +0100

wallet API: document refresh info and balance changes

Diffstat:
Mcore/api-wallet-core.rst | 23++++++++++++++++++++---
Mcore/wallet-core/balances/get-balances.rst | 23++++++++++++++++++++---
Mcore/wallet-core/global-currency/add-global-currency-auditor.rst | 2+-
Mcore/wallet-core/global-currency/add-global-currency-exchange.rst | 2+-
Mcore/wallet-core/global-currency/remove-global-currency-auditor.rst | 2+-
Mcore/wallet-core/global-currency/remove-global-currency-exchange.rst | 2+-
Mcore/wallet-core/hints/dismiss-wallet-warning.rst | 7+++----
Mcore/wallet-core/notifications.rst | 12+++++++-----
Mwallet/auto-refresh.rst | 7++++---
Mwallet/wallet-core.md | 99+++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------
10 files changed, 125 insertions(+), 54 deletions(-)

diff --git a/core/api-wallet-core.rst b/core/api-wallet-core.rst @@ -49,7 +49,7 @@ Version History The wallet-core API is versioned using the :ref:`libtool version range format <http-common>` (``current[:revision[:age]]``). The currently -implemented protocol version is **10:0:0**, reported via the +implemented protocol version is **11:0:0**, reported via the :ts:op:`getVersion` operation. **Version history:** @@ -64,6 +64,9 @@ implemented protocol version is **10:0:0**, reported via the :ts:op:`reclaimPayment`) * ``v10``: privacy-scrubbed diagnostics reports (:ts:op:`getDiagnostics`) +* ``v11`` moves renewal details from :ts:op:`getBalances` to + :ts:op:`getBalanceRefreshInfo` and :ts:op:`observeBalanceRefreshInfo`. + Balance-change notifications can omit the transaction hint. .. _wallet-core-conventions: @@ -1326,11 +1329,25 @@ discriminates the observed domain; transaction observations use enum ObservationType { Transaction = "transaction", + BalanceRefreshInfo = "balance-refresh-info", } .. ts:def:: ObservationSnapshotNotification - type ObservationSnapshotNotification = TransactionSnapshotNotification; + type ObservationSnapshotNotification = + | TransactionSnapshotNotification + | BalanceRefreshSnapshotNotification; + +.. ts:def:: BalanceRefreshSnapshotNotification + + interface BalanceRefreshSnapshotNotification { + type: "observation-snapshot"; + observationType: "balance-refresh-info"; + observationId: string; + revision: number; + scopeInfo: ScopeInfo; + snapshot: WalletRefreshInfo | null; + } .. ts:def:: TransactionSnapshotNotification @@ -1351,7 +1368,7 @@ no newer than the last one applied for that observation ID. Updates can be coalesced: snapshots describe current state and do not promise to report every intermediate transition. A final ``snapshot: null`` -means the transaction was deleted and the observation has ended. Stop +means the subject is absent and the observation has ended. Stop routing updates for that ID and discard its previous snapshot. .. _wallet-notif-observation-error: diff --git a/core/wallet-core/balances/get-balances.rst b/core/wallet-core/balances/get-balances.rst @@ -43,9 +43,8 @@ .. ts:def:: WalletBalance interface WalletBalance { - // DD71 expiry information and conditional - // cost of keeping this balance. - refreshInfo?: WalletRefreshInfo; + // True when funds in this scope are at risk of expiring. + hasExpirationRisk?: boolean; // Scope of the funds covered by this balance. scopeInfo: ScopeInfo; @@ -75,6 +74,24 @@ disableDirectDeposits?: boolean; } +.. ts:op:: getBalanceRefreshInfo + :read-only: + + Takes ``{ scopeInfo: ScopeInfo }`` and returns the current + `WalletRefreshInfo` for the requested balance, or ``null`` if that balance + no longer exists. The request waits for a fresh calculation. The annual + cost bound can be unavailable when the wallet lacks sufficient information. + +.. ts:op:: observeBalanceRefreshInfo + + Takes ``{ scopeInfo: ScopeInfo, observationId: string }`` and returns + an empty object. Install the notification listener before registering. + The ID follows the same uniqueness and lifetime rules as + :ts:op:`observeTransaction`. The initial report and subsequent distinct + reports arrive as `BalanceRefreshSnapshotNotification` snapshots. A null + report ends the observation when the scope is absent. Use + :ts:op:`stopObservation` when the view closes. + .. ts:def:: WalletRefreshInfo interface WalletRefreshInfo { diff --git a/core/wallet-core/global-currency/add-global-currency-auditor.rst b/core/wallet-core/global-currency/add-global-currency-auditor.rst @@ -13,7 +13,7 @@ **Side effects:** Registers the auditor for the global currency in the wallet's - database. When the configuration changed, a ``balance-change`` + database. When the balance overview changed, a ``balance-change`` notification is emitted. **Details:** diff --git a/core/wallet-core/global-currency/add-global-currency-exchange.rst b/core/wallet-core/global-currency/add-global-currency-exchange.rst @@ -14,7 +14,7 @@ **Side effects:** Registers the exchange for the global currency in the wallet's - database. When the configuration changed, a ``balance-change`` + database. When the balance overview changed, a ``balance-change`` notification is emitted. **Details:** diff --git a/core/wallet-core/global-currency/remove-global-currency-auditor.rst b/core/wallet-core/global-currency/remove-global-currency-auditor.rst @@ -14,7 +14,7 @@ **Side effects:** Removes the registration from the wallet's database. When the - configuration changed, a ``balance-change`` notification is + balance overview changed, a ``balance-change`` notification is emitted. **Details:** diff --git a/core/wallet-core/global-currency/remove-global-currency-exchange.rst b/core/wallet-core/global-currency/remove-global-currency-exchange.rst @@ -15,7 +15,7 @@ Removes the registration from the wallet's database; removing the last exchange of a currency also removes the global - currency information. When the configuration changed, a + currency information. When the balance overview changed, a ``balance-change`` notification is emitted. **Details:** diff --git a/core/wallet-core/hints/dismiss-wallet-warning.rst b/core/wallet-core/hints/dismiss-wallet-warning.rst @@ -13,15 +13,14 @@ **Side effects:** - Persistently marks a completed renewal notice as dismissed; when a - notice was actually dismissed, a ``balance-change`` notification is - emitted. + Persistently marks a completed renewal notice as dismissed. Observers + of the affected scope receive the updated report. **Details:** When wallet-core automatically refreshed coins that were close to expiration, the renewal is reported as a `CashRenewalNotice` in the - ``refreshInfo.recoveries`` of the affected `WalletBalance`. Passing + ``recoveries`` of the scoped `WalletRefreshInfo` report. Passing the notice's ``warningId`` to this operation dismisses the notice, so that it is no longer reported. Renewal notices of refresh operations that are still active, as well as unknown warning identifiers, are diff --git a/core/wallet-core/notifications.rst b/core/wallet-core/notifications.rst @@ -43,9 +43,9 @@ The payload is a `CoinRecoveryProgressNotification` object. **balance-change** -Invalidates balance data, including flags and refresh information. The -monetary amounts need not have changed, for example when a refresh cost -becomes ready. Clients should re-query +Indicates a change to the balance overview, including amounts, scope +membership, capabilities, donation summaries or expiration-risk flags. +A new scope can have a zero available balance. Clients should re-query :ts:op:`getBalances` in response. The payload is a `BalanceChangeNotification` object. @@ -64,7 +64,7 @@ The payload is a `BalanceChangeNotification` object. // Transaction ID of the transaction that caused the balance // update. Only used as a hint for debugging, should not be // relied upon by clients. - hintTransactionId: string; + hintTransactionId?: string; } @@ -229,7 +229,9 @@ The payload is a `TransactionStateTransitionNotification` object. **exchange-state-transition** -Emitted when the state of an exchange entry changes. If +Emitted when the public state or substantive details of an exchange change. +Equal states may accompany changed fees, keys, terms or KYC information. +Updating the last-check timestamp alone does not emit this event. If ``oldExchangeState`` is missing, the entry was newly created; if ``newExchangeState`` is missing, the entry was deleted. diff --git a/wallet/auto-refresh.rst b/wallet/auto-refresh.rst @@ -83,8 +83,9 @@ opportunistic rule; necessary refreshes do not require external power. Balance warnings and recovery notices ==================================== -Each balance may contain ``refreshInfo`` with ``risks``, ``recoveries``, and -``annualCostBound``. Risks identify the exchange, amount and earliest expiration. +The balance overview includes ``hasExpirationRisk`` for each scope. +``getBalanceRefreshInfo`` and ``observeBalanceRefreshInfo`` supply the +scoped ``risks``, ``recoveries`` and ``annualCostBound``. Risks identify the exchange, amount and earliest expiration. They distinguish a pending renewal, a connection failure, an exchange error, unavailable suitable replacements established from fresh keys, a check in progress, and invalid validity dates. They do not assert device-wide offline @@ -99,7 +100,7 @@ wallet was previously offline. Conditional cost bound ====================== -The balance screen's expandable cost summary covers keeping the current balance +The scoped refresh report includes a bound for keeping the current balance for 365 days without payments or additional withdrawals. It is a conditional upper bound, not a predicted debit. It assumes continuously available compatible families with stable values, fees and lifetime bounds, and reveal completing diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md @@ -35,6 +35,8 @@ This file is auto-generated from the [taler-typescript-core](https://git.taler.n * [SendTalerUriMailboxMessageOp](#sendtalerurimailboxmessageop) ### Basic Wallet Information * [GetBalancesOp](#getbalancesop) +* [GetBalanceRefreshInfoOp](#getbalancerefreshinfoop) +* [ObserveBalanceRefreshInfoOp](#observebalancerefreshinfoop) * [GetBalancesDetailOp](#getbalancesdetailop) * [ConvertDepositAmountOp](#convertdepositamountop) * [GetMaxDepositAmountOp](#getmaxdepositamountop) @@ -689,8 +691,8 @@ export interface BalancesResponse { ``` ```{ts:def} WalletBalance export interface WalletBalance { - /** DD71 expiry information and conditional cost of keeping this balance. */ - refreshInfo?: WalletRefreshInfo; + /** True when this scope contains funds at risk of expiration. */ + hasExpirationRisk?: boolean; scopeInfo: ScopeInfo; available: AmountString; pendingIncoming: AmountString; @@ -711,6 +713,54 @@ export interface WalletBalance { disableDirectDeposits?: boolean; } ``` +```{ts:def} BalanceFlag +export declare enum BalanceFlag { + IncomingKyc = "incoming-kyc", + IncomingAml = "incoming-aml", + IncomingConfirmation = "incoming-confirmation", + OutgoingKyc = "outgoing-kyc", +} +``` +```{ts:def} DonauSummaryItem +export interface DonauSummaryItem { + /** Base URL of the donau service. */ + donauBaseUrl: string; + /** Legal domain of the donau service (if available). */ + legalDomain?: string; + /** Year of the donation(s). */ + year: number; + /** + * Sum of donation receipts we received from merchants in the + * applicable year. + */ + amountReceiptsAvailable: AmountString; + /** + * Sum of donation receipts that were already submitted + * to the donau in the applicable year. + */ + amountReceiptsSubmitted: AmountString; + /** + * Amount of the latest available statement. Missing if no statement + * was requested yet. + */ + amountStatement?: AmountString; +} +``` + +### GetBalanceRefreshInfoOp +```{ts:def} BalanceRefreshInfoRequest +export interface BalanceRefreshInfoRequest { + scopeInfo: ScopeInfo; +} +``` +```{ts:def} GetBalanceRefreshInfoOp +export type GetBalanceRefreshInfoOp = { + op: WalletApiOperation.GetBalanceRefreshInfo; + request: BalanceRefreshInfoRequest; + response: WalletRefreshInfo | null; +}; +// GetBalanceRefreshInfo = "getBalanceRefreshInfo" +``` ```{ts:def} WalletRefreshInfo export interface WalletRefreshInfo { risks: CashExpirationRisk[]; @@ -761,37 +811,20 @@ export type AnnualRefreshCostBound = { } ); ``` -```{ts:def} BalanceFlag -export declare enum BalanceFlag { - IncomingKyc = "incoming-kyc", - IncomingAml = "incoming-aml", - IncomingConfirmation = "incoming-confirmation", - OutgoingKyc = "outgoing-kyc", -} + +### ObserveBalanceRefreshInfoOp +```{ts:def} ObserveBalanceRefreshInfoOp +export type ObserveBalanceRefreshInfoOp = { + op: WalletApiOperation.ObserveBalanceRefreshInfo; + request: ObserveBalanceRefreshInfoRequest; + response: EmptyObject; +}; +// ObserveBalanceRefreshInfo = "observeBalanceRefreshInfo" ``` -```{ts:def} DonauSummaryItem -export interface DonauSummaryItem { - /** Base URL of the donau service. */ - donauBaseUrl: string; - /** Legal domain of the donau service (if available). */ - legalDomain?: string; - /** Year of the donation(s). */ - year: number; - /** - * Sum of donation receipts we received from merchants in the - * applicable year. - */ - amountReceiptsAvailable: AmountString; - /** - * Sum of donation receipts that were already submitted - * to the donau in the applicable year. - */ - amountReceiptsSubmitted: AmountString; - /** - * Amount of the latest available statement. Missing if no statement - * was requested yet. - */ - amountStatement?: AmountString; +```{ts:def} ObserveBalanceRefreshInfoRequest +export interface ObserveBalanceRefreshInfoRequest + extends BalanceRefreshInfoRequest { + observationId: string; } ``` @@ -4825,6 +4858,8 @@ export enum WalletApiOperation { CancelProgressToken = "cancelProgressToken", // Balances GetBalances = "getBalances", + GetBalanceRefreshInfo = "getBalanceRefreshInfo", + ObserveBalanceRefreshInfo = "observeBalanceRefreshInfo", GetBalanceDetail = "getBalanceDetail", // Misc. GetActiveTasks = "getActiveTasks",