071-auto-refresh.rst (4589B)
1 DD 71: Auto-refresh 2 ################### 3 4 :Design status: Accepted 5 :Implementation status: Prototype 6 :DD shepherd: TBD 7 :Historical contributors: Christian Grothoff 8 :First published: 2025-10-23 9 :Last substantive change: 2025-10-23 10 :Implementation evidence: ``taler-typescript-core`` (2026-08-19, not merged into the reviewed HEAD) 11 12 Summary 13 ======= 14 15 This document describes when the wallet should automatically refresh 16 non-dirty coins. 17 18 19 Motivation 20 ========== 21 22 The wallet must refresh non-dirty coins before they expire, least the 23 user looses the money. However, this should not be done too early to 24 avoid refresh fees and/or excessive load on the exchange. On the other 25 hand, we need to be careful to not hold off for too long and risk 26 the wallet not going online before the expiration time. 27 28 We note that there obviously is no perfect solution, as at least in 29 principle the user could always not restart the wallet until the 30 expiration time. 31 32 33 Requirements 34 ============ 35 36 * Do not loose funds under most conditions 37 * Do not cause clearly avoidable refresh operations 38 * Try to educate the user if they are about to get into trouble 39 * Independently of any specific approach, the wallet 40 MUST spend those coins first that are earliest to 41 their expiration time within their equivalence class 42 as that is always the best way to avoid expiration. 43 * While lifetimes of denominations are often identical, 44 that may not always be the case. Theoretically, an 45 exchange could significantly increase or decrease the 46 deposit period at any time. The solution should 47 take this into consideration. 48 49 50 Proposed Solution 51 ================= 52 53 1. For each denomination, consider if a refresh would 54 lengthen the expiration date by more than a factor 55 of four (4x), that is if the deposit expiration time 56 of the denomination(s) we could currently withdraw 57 is more than 4x as long as what remains for the 58 denomination. If so, refresh 59 all coins of that denomination. 60 61 62 .. note:: 63 64 This basically suggests that a refresh 65 would have a significant positive **impact**. 66 67 2. For each denomination, consider if the remaining 68 deposit period is less than **6** months, if the 69 refresh fee would be zero, and if after refreshing 70 the deposit expiration time would exceed **12** months, 71 and if we are not on battery power. If so, refresh 72 all coins of that denomination. 73 74 .. note:: 75 76 This is again a significant impact, and it is basically 77 gratis for the user. 78 79 3. For each denomination, consider if the remaining 80 deposit period is less than **3** months, and if 81 after refreshing the deposit expiration time would 82 be larger. If so, refresh all coins of that denomination. 83 If afterwards the expiration time exceeds **12** months, 84 show the user a warning: 85 86 "This wallet was offline for too long. Make sure to 87 start it at least every **3 months** to avoid the 88 risk of loosing funds to expiration." 89 90 .. note:: 91 92 This is basically a last-minute effort (unless we have 93 an exchange with extremely short expiration periods). 94 We do not like getting into this situation, so it is 95 time to educate the user. 96 97 4. Explicitly show a warning in the balances list of 98 the respective currency if the remaining deposit 99 period for any coin drops below 90 days. 100 Distinguish in the warning key causes: 101 102 1. "We are offline and cannot expand the validity period." 103 2. "The payment service provider does not offer longer 104 validity periods." 105 106 .. note:: 107 108 This should prevent us from getting into trouble if 109 e-cash is lost anyway. 110 111 112 Definition of Done 113 ================== 114 115 * [x] Prototype implemented in a wallet-core feature branch 116 * [ ] Prototype merged into the main branch 117 * [ ] Changes to interactions for signalling warnings to GUIs 118 * [ ] Dev experiments exist to trigger special alerts to users 119 * [ ] GUIs have been designed and tested 120 121 122 Alternatives 123 ============ 124 125 The wallet currently implements simple rules for auto-refresh: 126 127 1. After 75% of a denomination's "deposit lifespan" has passed, 128 we do "auto-refresh check" for all coins of the exchange 129 130 2. During this auto-refresh check, all coins that are >50% into 131 their deposit lifespan are auto-refreshed. 132 133 This is risky as it does not consider absolute lifespans or user 134 behavior. 135 136 137 Drawbacks 138 ========= 139 140 * This approach does not (yet) consider user behavior. We could 141 theoretically learn from that. 142 143 144 145 Discussion / Q&A 146 ================ 147 148 (This should be filled in with results from discussions on mailing lists / personal communication.)