commit 792f2001051ef66384d7ffd14ddb9c77bfeabcd5
parent f191768a1821475eae90db78a4efe03f87ec06b5
Author: Florian Dold <dold@taler.net>
Date: Sat, 5 Sep 2026 18:47:50 +0200
wallet: describe persisted background renewal reports
Explain report invalidation, snapshot calculation, publication, and the
cached information returned while background maintenance is pending.
Diffstat:
1 file changed, 22 insertions(+), 0 deletions(-)
diff --git a/wallet/auto-refresh.rst b/wallet/auto-refresh.rst
@@ -48,6 +48,28 @@ redraw or postpone a deadline. Temporarily ineligible inputs retain their deadli
while the wallet waits for a valid plan. Retry backoff is randomized and capped
by the time to urgency, or remaining lifetime once urgent.
+Background balance reporting
+============================
+
+Renewal information is computed by the ``refresh-balance`` maintenance task and
+persisted by balance scope. A balance request only reads the saved report and its
+input generation; it does not load denominations, scan refresh history, or run
+output selection. The report survives closing and reopening the wallet.
+
+Changes to holdings, exchange keys and trust, refresh progress, and relevant
+retry errors invalidate the report in the same transaction as their inputs.
+The task reads a consistent snapshot, releases the database transaction, and
+computes the report while periodically yielding to other wallet work. It publishes
+only if the input generation is still current, then notifies balance clients.
+A changed generation causes another calculation instead of publishing stale data.
+
+Known warnings and recovery notices remain visible while a report is being
+updated. A cost bound is withheld when its generation, balance amount, or time
+validity no longer matches; clients see a checking indication until the new report
+is ready. An empty cache also returns a checking indication without blocking the
+balance request. The task schedules itself for the next relevant validity or key
+freshness boundary, with a daily upper limit between checks.
+
Power observations
==================
