commit 95cceef3ee544bd4cb263ffc75360cf9eac0357a
parent c9ac9b5573e8bc4cfd4d55264888e787a1ed4c6a
Author: Florian Dold <florian@dold.me>
Date: Tue, 22 Aug 2023 10:41:17 +0200
DD48 first draft
Diffstat:
1 file changed, 107 insertions(+), 0 deletions(-)
diff --git a/design-documents/048-wallet-exchange-lifecycle.rst b/design-documents/048-wallet-exchange-lifecycle.rst
@@ -0,0 +1,107 @@
+DD 48: Wallet Exchange Lifecycle and Management
+###############################################
+
+Summary
+=======
+
+This design document covers the lifecycle and management
+of exchanges in the wallet.
+
+Motivation
+==========
+
+The current wallet implementation lacks requests to manage exchanges.
+It also always fetches the /keys info of all exchanges, because it doens't
+distinguish between used and preset/added exchanges.
+
+Requirements
+============
+
+The following properties of of exchanges managed by the wallet
+are important:
+
+* is the exchange used for something (coins, (account-)reserves, purses, ...)
+* did the user (ever) accept the ToS?
+* does the exchange have never ToS available?
+* is a current version of /keys (including former /wire) downloaded?
+* were there errors downloading or checking the keys info?
+* is the exchange permanently added or ephemeral?
+
+ * ephemeral exchange records are created when the user
+ checks fees of an exchange but doesn't use it,
+ they would typically be hidden in the UI
+
+
+Proposed Solution
+=================
+
+Exchange Entry Status
+---------------------
+
+The wallet exposes three separate status fields for each exchange entry:
+* the entry status
+* the update status
+* the ToS status
+
+
+entry status:
+
+* ``preset``: Exchange record has been added to the exchange (typically as
+ a hardcoded preset in wallet-core). While the exchange can be selected for operations,
+ the wallet doesn't update the status yet, i.e. no /keys queries are done.
+* ``ephemeral``: Exchange has been updated (or update has been attempted) at
+ least once (for example as part of checking the fees for a transaction using
+ the exchange). However, the exchange is not yet used for any resource in the wallet.
+* ``used``: The exchange known and used, the wallet regularly queries /keys.
+
+update status:
+
+* ``initial``: Not updated, no need to update
+* ``pending(update)``: Update pending, possibly with error
+* ``suspended(update)``: Exchange should not be contacted anymore, but record is kept
+ in the wallet. Mostly useful for testing.
+* ``failed``: Updating the exchange info failed permanently, the exchange is
+ not usable for any operations.
+* ``ready``
+
+FIXME: Do we distinguish between pending states where the exchange is still usable
+and pending states where we need to wait for the update step to finish?
+
+FIXME: Do we consider the exchange record "failed" when ToS download was impossible?
+Do we download (and store) plain-text ToS or just do a HEAD to get the etag?
+
+ToS status:
+
+* ``pending``: The wallet is still trying to download the ToS.
+ Possible the last download attempt failed.
+* ``accepted``: The user has accepted the latest version of the ToS.
+* ``proposed``: The user needs to accept the current ToS
+* ``outdated``: The user has previously accepted the ToS, but the exchange
+ has a newer version available now.
+
+FIXME: Do we really need to distinguish between ``proposed`` and ``outdated``?
+
+Management Requests
+-------------------
+
+* ``listExchanges``: List exchanges with their status info.
+* ``addExchange``: Adds an exchange, entry status will be ``used``.
+* ``getExchangeResources``: List resources (number of coins, reserves, ...) associated
+ with the exchange.
+* ``deleteExchange({purge: boolean})``: Removes an exchange.
+ Unless ``purge: true`` is specified, only an exchange without any associated
+ resources can be deleted.
+
+FIXME: Purging should probably delete *all* resources associated with the exchange.
+But does it also remove the associated transactions?
+
+Definition of Done
+==================
+
+* states implemented in wallet-core
+* exchange management specified on a UI level and implemented in UIs
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
