commit 3177f1141de276c3d498be1bddb4aec2aeb87ba1
parent e63b013bb8b0c4d4d7d0306258b09124f00f8bb8
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Thu, 23 Oct 2025 17:53:02 +0200
add auto-refresh spec (#6563)
Diffstat:
2 files changed, 139 insertions(+), 0 deletions(-)
diff --git a/design-documents/071-auto-refresh.rst b/design-documents/071-auto-refresh.rst
@@ -0,0 +1,138 @@
+DD 71: Auto-refresh
+###################
+
+Summary
+=======
+
+This document describes when the wallet should automatically refresh
+non-dirty coins.
+
+
+Motivation
+==========
+
+The wallet must refresh non-dirty coins before they expire, least the
+user looses the money. However, this should not be done too early to
+avoid refresh fees and/or excessive load on the exchange. On the other
+hand, we need to be careful to not hold off for too long and risk
+the wallet not going online before the expiration time.
+
+We note that there obviously is no perfect solution, as at least in
+principle the user could always not restart the wallet until the
+expiration time.
+
+
+Requirements
+============
+
+* Do not loose funds under most conditions
+* Do not cause clearly avoidable refresh operations
+* Try to educate the user if they are about to get into trouble
+* Independently of any specific approach, the wallet
+ MUST spend those coins first that are earliest to
+ their expiration time within their equivalence class
+ as that is always the best way to avoid expiration.
+* While lifetimes of denominations are often identical,
+ that may not always be the case. Theoretically, an
+ exchange could significantly increase or decrease the
+ deposit period at any time. The solution should
+ take this into consideration.
+
+
+Proposed Solution
+=================
+
+1. For each denomination, consider if a refresh would
+ lengthen the expiration date by more than a factor
+ of four (4x), that is if the deposit expiration time
+ of the denomination(s) we could currently withdraw
+ is more than 4x as long as what remains for the
+ denomination. If so, refresh
+ all coins of that denomination.
+
+
+ ..note::
+
+ This basically suggests that a refresh
+ would have a significant positive **impact**.
+
+2. For each denomination, consider if the remaining
+ deposit period is less than **6** months, if the
+ refresh fee would be zero, and if after refreshing
+ the deposit expiration time would exceed **12** months,
+ and if we are not on battery power. If so, refresh
+ all coins of that denomination.
+
+ ..note::
+
+ This is again a significant impact, and it is basically
+ gratis for the user.
+
+3. For each denomination, consider if the remaining
+ deposit period is less than **3** months, and if
+ after refreshing the deposit expiration time would
+ be larger. If so, refresh all coins of that denomination.
+ If afterwards the expiration time exceeds **12** months,
+ show the user a warning:
+
+ "This wallet was offline for too long. Make sure to
+ start it at least every **3 months** to avoid the
+ risk of loosing funds to expiration."
+
+ ..note::
+
+ This is basically a last-minute effort (unless we have
+ an exchange with extremely short expiration periods).
+ We do not like getting into this situation, so it is
+ time to educate the user.
+
+4. Explicitly show a warning in the balances list of
+ the respective currency if the remaining deposit
+ period for any coin drops below 90 days.
+ Distinguish in the warning key causes:
+ 1) "We are offline and cannot expand the validity period."
+ 2) "The payment service provider does not offer longer
+ validity periods."
+
+ ..note::
+
+ This should prevent us from getting into trouble if
+ e-cash is lost anyway.
+
+
+Definition of Done
+==================
+
+* Implemented in wallet-core
+* Changes to interactions for signalling warnings to GUIs
+* dev-experiments exist to trigger special alerts to users
+* GUIs have been designed and tested
+
+
+Alternatives
+============
+
+The wallet currently implements simple rules for auto-refresh:
+
+1. After 75% of a denomination's "deposit lifespan" has passed,
+ we do "auto-refresh check" for all coins of the exchange
+
+2. During this auto-refresh check, all coins that are >50% into
+ their deposit lifespan are auto-refreshed.
+
+This is risky as it does not consider absolute lifespans or user
+behavior.
+
+
+Drawbacks
+=========
+
+* This approach does not (yet) consider user behavior. We could
+ theoretically learn from that.
+
+
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -82,4 +82,5 @@ Design documents that start with "XX" are considered deprecated.
068-tokens-roadmap
069-exchange-base-url-completion
070-alias-directory-mailbox
+ 070-auto-refresh
999-template
