[taler-docs] branch master updated: DD48 first draft

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 95cceef3 DD48 first draft
95cceef3 is described below

commit 95cceef3ee544bd4cb263ffc75360cf9eac0357a
Author: Florian Dold <florian@dold.me>
AuthorDate: Tue Aug 22 10:41:17 2023 +0200

    DD48 first draft
---
 design-documents/048-wallet-exchange-lifecycle.rst | 107 +++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/design-documents/048-wallet-exchange-lifecycle.rst 
b/design-documents/048-wallet-exchange-lifecycle.rst
new file mode 100644
index 00000000..4449f054
--- /dev/null
+++ 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.)

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.