[taler-docs] branch master updated: some comments on DDs

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 56e7647  some comments on DDs
56e7647 is described below

commit 56e7647fa8ac9e6d3891ad5c386e91dae5853daa
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Thu Apr 6 17:00:23 2023 +0200

    some comments on DDs
---
 core/tos.rst                                           |  7 ++++---
 design-documents/003-tos-rendering.rst                 | 18 ++++++++++++++++++
 design-documents/038-demobanks-protocol-suppliers.rst  |  6 ++++++
 .../041-wallet-balance-amount-definitions.rst          | 17 ++++++++++-------
 4 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/core/tos.rst b/core/tos.rst
index 0cdb898..6c36be4 100644
--- a/core/tos.rst
+++ b/core/tos.rst
@@ -29,9 +29,10 @@ and the privacy policy of a service.
   the case if the terms of service were not configured correctly.
 
   When returning a full response (not a "304 Not Modified"), the server
-  should also include a "Acceptable-Languages" header which includes
-  a space-separated list of the languages in which the terms of service
-  are available in. Clients can use this to generate a language switcher
+  should also include a "Avail-Languages" header which includes
+  a comma-separated list of the languages in which the terms of service
+  are available in (see `availability hints specification
+  
<https://datatracker.ietf.org/doc/draft-nottingham-http-availability-hints/>`_).
 Clients can use this to generate a language switcher
   for users that may not have expressed a proper language preference.
 
 
diff --git a/design-documents/003-tos-rendering.rst 
b/design-documents/003-tos-rendering.rst
index 9b19ee0..d84a495 100644
--- a/design-documents/003-tos-rendering.rst
+++ b/design-documents/003-tos-rendering.rst
@@ -22,6 +22,24 @@ way.
 Proposed Solution
 =================
 
+Internationalization
+--------------------
+
+The server will parse the ``Accept-Languages`` request header to determine
+which language the user will most likely want to read the terms of service
+in. If multiple languages are given, the server will check against the
+available languages and return the one with the highest preference.
+
+Additionally, the server will return an ``Avail-Languages`` header which
+details what other langauges the terms of service are available in. The
+user interface in the wallet should then allow the user to switch to one
+of these alternatives using some language switcher.
+
+
+Encoding
+--------
+
+
 The service providers can output legal agreements in various formats,
 determined via the ``"Accept: "`` request header.  The format provider **must**
 support the ``text/plain`` mime type.  The format provider **must** support
diff --git a/design-documents/038-demobanks-protocol-suppliers.rst 
b/design-documents/038-demobanks-protocol-suppliers.rst
index f4523d2..dcfd557 100644
--- a/design-documents/038-demobanks-protocol-suppliers.rst
+++ b/design-documents/038-demobanks-protocol-suppliers.rst
@@ -150,3 +150,9 @@ subscriber that made the request.
    lead to **ambiguity**, in case two different demobanks host respectively
    one bank account under the same label.  This is not possible however
    in the current version, as Sandbox only admits one ``default`` demobank.
+
+
+Alternatives
+============
+
+Drop support for multitenancy banking. What is the benefit of this anyway?
diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
index a7c1202..9a1eec7 100644
--- a/design-documents/041-wallet-balance-amount-definitions.rst
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -53,24 +53,27 @@ For withdrawal:
 
 FIXME(dold): However, that does not really cover the user case where the 
merchant charges fees and the user has to pay for that. So in theory we could 
have a mode that withdraws enough to pay for some particular claimed order, but 
IMHO that's overkill.
 
-For deposits:
+For deposits (where there is no contract that already specifies an amount):
 
-* ``max-mode``: The instructed amount is ignored (can be zero in the request), 
and all coins are spent
+* ``max-mode``: The instructed amount is ignored (can be zero in the request), 
and all coins are spent (note that the calculation should be made available 
when the user is asked to specify an amount when using a template)
 * ``raw-mode`` (default): The instructed amount is what will be paid to the 
"merchant" (or the customer's bank account), ignoring wire fees
-* ``effective-mode``: The instructed amount is how the wallet's balance will 
be affected. Difficult to compute accurately because refresh is involved.
+* ``effective-mode``: The instructed amount is how the wallet's balance will 
be affected. Difficult to compute accurately because refresh is involved. Note 
that the calculation should ideally again be made available when the user is 
asked to specify an amount when using a template.
 
+  
 For peer-push-debit:
 
 * ``raw-mode`` (default): The instructed amount is what will be paid, deposit 
fees are covered by the sender, withdrawal fees from the reserve by the receiver
 * ``effective-mode``: Instructed amount is the effect on the material balance. 
Difficult to compute accurately because refresh is involved.
-* ``counterparty-effective-mode``: Instructed amount is the effect on the 
counterparty's wallet balance.
+* ``counterparty-effective-mode``: Instructed amount is the effect on the 
counterparty's wallet balance. Difficult to compute accurately because coin 
selection by receiver may not match our expectations.
 
-FIXME(dold): Should we also have a mode where withdrawal fees are covered by 
the side that does peer-push-debit? However, that assumes the other party has 
the same withdrawal coin selection algorithm
+FIXME(dold): Should we also have a mode where withdrawal fees are covered by 
the side that does peer-push-debit? However, that assumes the other party has 
the same withdrawal coin selection algorithm. FIXME(grothoff): isn't this the 
counterparty-effective-mode you described above, and that would seem to exactly 
have this issue?
 
 For peer-pull-credit:
 
-* ``raw-mode`` (default): Amount that the other party has to put in the 
reserve, where the other party has to pay deposit fees
-* ``effective-mode``: Amount that be added to on the initiator's balance
+* ``raw-mode`` (default): Amount that the other party has to put in the 
reserve. The payer has to pay any deposit fees on top. The receiver balance is 
increased by the specified amount minus any withdraw fees.
+* ``effective-mode``: Amount by which the initiator's balance is increased. 
Difficult to compute as the receiver has to simulate different coin selections 
and their effect on withdraw fees to arrive at the minimum total amount that 
must be deposited into the reserve.
+
+
 
 Illustrative Example
 --------------------

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