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:
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",