048-wallet-exchange-lifecycle.rst (6486B)
1 DD 48: Wallet Exchange Lifecycle and Management 2 ############################################### 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Marc Stibane, Sebastian, Florian Dold, Christian Grothoff 8 :First published: 2023-08-22 9 :Last substantive change: 2025-07-03 10 :Implementation evidence: taler-typescript-core (2023-08-30), taler-android (2024-01-30) 11 :Normative references: ``wallet/wallet-core.md`` 12 :Upstream follow-up: Regenerate ``wallet/wallet-core.md`` from current taler-typescript-core; the checked-in output has a stale ``DeleteExchangeOp`` discriminator and comment. 13 14 Summary 15 ======= 16 17 This design document covers the lifecycle and management 18 of exchanges in the wallet. 19 20 Motivation 21 ========== 22 23 At the time this design was written, the wallet implementation lacked requests 24 to manage exchanges and always fetched the ``/keys`` information of all 25 exchanges because it did not distinguish between used and preset/added 26 exchanges. The current wallet API implements exchange-management requests. 27 28 Requirements 29 ============ 30 31 The following properties of exchanges managed by the wallet 32 are important: 33 34 * is the exchange used for something (coins, (account-)reserves, purses, ...) 35 * did the user (ever) accept the ToS? 36 * does the exchange have newer ToS available? 37 * is a current version of /keys (including former /wire) downloaded? 38 * were there errors downloading or checking the keys info? 39 * is the exchange permanently added or ephemeral? 40 41 * ephemeral exchange records are created when the user 42 checks fees of an exchange but doesn't use it, 43 they would typically be hidden in the UI 44 45 46 Proposed Solution 47 ================= 48 49 Exchange Entry Status 50 --------------------- 51 52 The wallet exposes three separate status fields for each exchange entry: 53 54 * the entry status 55 * the update status 56 * the ToS status 57 58 59 Entry Status 60 ~~~~~~~~~~~~ 61 62 * ``preset``: Exchange record has been added to the exchange (typically as 63 a hardcoded preset in wallet-core). While the exchange can be selected for operations, 64 the wallet doesn't update the status yet, i.e. no /keys queries are done. 65 * ``ephemeral``: Exchange has been updated (or update has been attempted) at 66 least once (for example as part of checking the fees for a transaction using 67 the exchange). However, the exchange is not yet used for any resource in the wallet. 68 In this state, the exchange record will be garbage-collected eventually. 69 * ``used``: The exchange is known and used, the wallet regularly queries /keys. 70 71 Transitions: 72 73 * A transition from ``used`` to ``ephemeral`` is not possible, 74 since this would eventually remove preset exchanges and likely confuse 75 the user. 76 77 Update Status 78 ~~~~~~~~~~~~~ 79 80 * ``initial``: Not updated, no need to update 81 * ``initial-update``: Update pending, possibly with error 82 * ``suspended``: Exchange was manually disabled, should not be contacted 83 anymore, but record is kept in the wallet. Mostly useful for testing. 84 * ``unavailable-update``: The exchange is currently unavailable to be used for withdrawals, 85 but it is possible that the exchange starts working again in the future. 86 The wallet will re-try contacting the exchange. The wallet will still try 87 operations that *spend* coins, but the user might be warned about the bad 88 exchange status. 89 90 Examples: 91 92 * The exchange updated to a new protocol version that is incompatible with the wallet 93 * The exchange advertises a new master public key. This might be a temporary 94 configuration issue or malicious attack. 95 * The exchange only advertises outdated denomination keys, making new withdrawals 96 impossible. 97 * ``ready``: Exchange is useable. 98 * ``ready-update``: Exchange is useable, but currently being updated. If it is discovered 99 that the information from the exchange is indeed too outdated (unknown signing key in response, 100 no denomination), the entry must transition to ``outdated-update``. 101 * ``outdated-update``: Information in the wallet's DB about the exchange is too old to be used, 102 it must be updated before proceeding. 103 104 ToS Status 105 ~~~~~~~~~~ 106 107 * ``pending``: The wallet is still trying to download the ToS. 108 Possibly the last download attempt failed, will be reflected in an 109 error details object. 110 * ``proposed``: The user needs to accept the current ToS. 111 * ``accepted``: The user has accepted the latest version of the ToS. 112 * ``missing-tos``: The terms of service are missing, the exchange did not configure any. 113 114 Management Requests 115 ------------------- 116 117 * ``listExchanges``: List exchanges with their status info. 118 * ``addExchange``: Adds an exchange, entry status will be ``ephemeral`` 119 until the user actually uses the exchange. 120 * ``getExchangeResources``: List resources (number of coins, reserves, ...) associated 121 with the exchange. 122 * ``deleteExchange({exchangeUrl: string, purge: boolean})``: Removes an exchange. 123 Unless ``purge: true`` is specified, only an exchange without any associated 124 resources can be deleted. 125 * ``getExchangeTos({exchangeUrl: string, acceptLanguage?: string[], acceptFormat?: string[]}) => { language: string, mime: string, content: string, altLanguages: string[] }`` 126 127 FIXME: Purging should probably delete *all* resources associated with the exchange. 128 But does it also remove the associated transactions? 129 130 ToS Management 131 -------------- 132 133 The wallet only stores the last accepted ToS ETag and the ETag last offered by 134 the exchange. The ToS contents are not stored by the wallet database (and thus 135 not included in backups). However, the wallet implementation may cache the 136 ``/terms`` response on the level of the HTTP client. 137 138 In future iterations, the UI might specify the prefered language and content type 139 for ``/terms``, so that the wallet can already download the full response (not just ``HEAD``). 140 141 142 Definition of Done 143 ================== 144 145 * [x] states implemented in wallet-core 146 * [x] exchange management specified on a UI level 147 * [ ] WebExtension implementation verified against the full DD 148 * [x] Android wallet exchange deletion implemented 149 * [ ] iOS wallet implementation verified against the full DD 150 151 Discussion / Q&A 152 ================ 153 154 * Should there be a "permanently failed" update state? 155 156 * dold => I don't think so, as it means that temporary configuration issues on the side of the 157 exchange might *permanently* brick users' wallets. 158 The wallet should always re-try contacting the exchange and of course possibly report 159 information to the auditor.