summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTorsten Grote <t@grobox.de>2020-04-23 16:08:41 -0300
committerTorsten Grote <t@grobox.de>2020-04-23 16:08:41 -0300
commitd2a49c7f9998249cf4ed23c631bdbc976b9ba8cf (patch)
tree3d18c0e32206c0d5a8d21c7d308e25f2a167c6c2
parent3c1500b932e81453d5acbb0b83422953dd56a0ec (diff)
downloaddocs-d2a49c7f9998249cf4ed23c631bdbc976b9ba8cf.tar.gz
docs-d2a49c7f9998249cf4ed23c631bdbc976b9ba8cf.tar.bz2
docs-d2a49c7f9998249cf4ed23c631bdbc976b9ba8cf.zip
Add Design Doc 004: Wallet Withdrawal Flow
-rw-r--r--conf.py5
-rw-r--r--design-documents/004-wallet-withdrawal-flow.rst129
-rw-r--r--design-documents/index.rst1
3 files changed, 135 insertions, 0 deletions
diff --git a/conf.py b/conf.py
index 4010d57b..a1a653af 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 00000000..e448a773
--- /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 4f3732ab..aa0ca65a 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