[taler-docs] branch master updated: Add Design Doc 004: Wallet Withdrawal Flow

[gnunet]

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

torsten-grote pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new d2a49c7  Add Design Doc 004: Wallet Withdrawal Flow
d2a49c7 is described below

commit d2a49c7f9998249cf4ed23c631bdbc976b9ba8cf
Author: Torsten Grote <address@hidden>
AuthorDate: Thu Apr 23 16:08:41 2020 -0300

    Add Design Doc 004: Wallet Withdrawal Flow
---
 conf.py                                         |   5 +
 design-documents/004-wallet-withdrawal-flow.rst | 129 ++++++++++++++++++++++++
 design-documents/index.rst                      |   1 +
 3 files changed, 135 insertions(+)

diff --git a/conf.py b/conf.py
index 4010d57..a1a653a 100644
--- a/conf.py
+++ b/conf.py
@@ -57,6 +57,7 @@ extensions = [
     'sphinx.ext.imgmath',
     'httpdomain.httpdomain',
     'recommonmark',
+    'sphinx.ext.graphviz',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -350,3 +351,7 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# The output format for Graphviz when building HTML files.
+# This must be either 'png' or 'svg'; the default is 'png'.
+graphviz_output_format = 'svg'
diff --git a/design-documents/004-wallet-withdrawal-flow.rst 
b/design-documents/004-wallet-withdrawal-flow.rst
new file mode 100644
index 0000000..e448a77
--- /dev/null
+++ b/design-documents/004-wallet-withdrawal-flow.rst
@@ -0,0 +1,129 @@
+Design Doc 004: Wallet Withdrawal Flow
+######################################
+
+Summary
+=======
+
+This document describes the recommended way of implementing the user experience
+of withdrawing digital cash in GNU Taler wallets.
+
+Motivation
+==========
+
+When digital cash is withdrawn, it is tied to and in custody of an exchange.
+There can be many exchanges offered by different entities,
+each having their custom legal agreement documents and fee structures.
+The user is free to choose an exchange.
+Therefore, the process of withdrawing needs to account for this choice.
+
+Proposed Solution
+=================
+
+There are three screens involved in the process:
+
+1. **Select exchange**:
+   Here the user can pick an exchange from a list of known exchanges
+   or add a new one for immediate use.
+   For details see :doc:`002-wallet-exchange-management`.
+2. **Display an exchange's Terms of Service**:
+   Shows the terms and gives an option to accept them.
+   For details see :doc:`003-tos-rendering`.
+3. **Withdrawal details and confirmation**:
+   This should show the amount to be withdrawn along with its currency,
+   the currently selected exchange and the fee charged by it for the 
withdrawal.
+
+The user flow between these screens is described in the following graph:
+
+.. graphviz::
+
+   digraph G {
+       rankdir=LR;
+       nodesep=0.5;
+       default_exchange [
+           label = "Has default\nexchange?";
+           shape = diamond;
+       ];
+       tos_changed [
+           label = "ToS\nchanged?";
+           shape = diamond;
+       ];
+       tos_accepted [
+           label = "ToS\naccepted?";
+           shape = diamond;
+       ];
+       accept_tos [
+           label = "Accept\nToS?";
+           shape = diamond;
+       ];
+       withdrawal_action [
+           label = "Withdrawal\nAction";
+           shape = diamond;
+       ];
+       select_exchange [
+           label = "Select\nexchange";
+           shape = rect;
+       ];
+       tos [
+           label = "ToS";
+           shape = rect;
+       ];
+       withdraw [
+           label = "Confirm\nwithdrawal";
+           shape = rect;
+       ];
+       transactions [
+           label = "Transactions";
+           shape = circle;
+       ];
+
+       default_exchange -> tos_changed [label="Yes"];
+       default_exchange -> select_exchange [label="No"];
+       tos_changed -> tos [label="Yes"];
+       tos_changed -> withdraw [label="No"];
+       select_exchange -> tos_accepted;
+       tos_accepted -> tos_changed [label="Yes"];
+       tos_accepted -> tos [label="No"];
+       tos -> accept_tos;
+       accept_tos -> withdraw [label="Yes"];
+       accept_tos -> select_exchange [label="No"];
+       withdraw -> withdrawal_action;
+       withdrawal_action -> transactions [label="Confirm"];
+       withdrawal_action -> select_exchange [label="Change Exchange"];
+
+       { rank=same; tos_accepted; tos_changed; }
+       { rank=same; select_exchange; tos; }
+       { rank=same; withdrawal_action; withdraw; }
+   }
+
+This enables the user to change the current exchange at any time in the 
process.
+It ensures that the latest version of the exchange's terms of service have 
been accepted by the user
+before allowing them to confirm the withdrawal.
+
+Some special regional or test currencies might have only a single known 
exchange.
+For those, the wallet should not offer the option to change an exchange.
+
+Alternatives
+============
+
+We considered and rejected the following alternatives:
+
+* Do not allow more than one exchange to make Taler simpler to use and 
understand:
+  Taler wants to allow custom exchanges for custom currencies
+  and foster competition between exchanges for the same currency
+  to provide the best possible service to users at the lowest fee.
+* Do not require acceptance to terms of service:
+  Having these terms and prompting the user to accept them
+  is a legal and business requirement in many jurisdictions,
+  so Taler needs to support them.
+  However, Taler encourages exchanges to keep their terms as short and simple 
as possible.
+
+Discussion / Q&A
+================
+
+* Should wallets pre-set a default exchange for the most common currencies,
+  so that users will not be burdened to understand exchanges and their fee 
structures
+  when making their first withdrawal?
+  This could increase user retention, but discourage
+* What should happen when an exchange changes its terms of service
+  and the user wants to use the funds stored there,
+  but does not initiate a new withdrawal with that exchange?
diff --git a/design-documents/index.rst b/design-documents/index.rst
index 4f3732a..aa0ca65 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -13,3 +13,4 @@ and protocol.
   001-new-browser-integration  
   002-wallet-exchange-management
   003-tos-rendering
+  004-wallet-withdrawal-flow

-- 
To stop receiving notification emails like this one, please contact
address@hidden.