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