[taler-docs] branch master updated: DD 41, incorporate points from discussion with Sebastian

[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 dfb06a0  DD 41, incorporate points from discussion with Sebastian
dfb06a0 is described below

commit dfb06a0ff21368253d8ce50b8da48140b3d96375
Author: Florian Dold <florian@dold.me>
AuthorDate: Fri Mar 31 16:35:17 2023 +0200

    DD 41, incorporate points from discussion with Sebastian
---
 .../041-wallet-balance-amount-definitions.rst      | 46 ++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
index 8784888..3270bf3 100644
--- a/design-documents/041-wallet-balance-amount-definitions.rst
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -34,6 +34,11 @@ Amounts
   differs based on the "instructed amount mode" that is specified
   together with the amount.  By default, the instructed amount
   is assumed to translate to the raw amount of the corresponding transaction.
+* "counterparty effective amount": An amount that **estimates** the effect
+  of the transaction of the balance (either wallet or bank account) of the 
other
+  party. This is usually a conservative estimate, i.e. when sending money,
+  this is the lower bound for the funds that the other party will obtain
+  *after* fees.
 
 Instructed Amount Modes
 -----------------------
@@ -58,6 +63,7 @@ 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.
 
 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
 
@@ -66,6 +72,46 @@ 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
 
+Illustrative Example
+--------------------
+
+To explain the differences between raw, effective and instructed amounts, 
consider the following scenario: Alice wants to send money
+to Bob via a P2P push payment.
+
+Example 1:
+
+* Alice starts a withdrawal of ``KUDOS:10`` from her bank's web interface into 
her Taler
+  wallet. The instructed amount is ``KUDOS:10`` and (by default for 
bank-integrated withdrawals),
+  the mode is ``raw-mode``.  After fees, ``KUDOS:9.8`` arrive in her Taler 
wallet.
+
+Example 3:
+
+* Alice wants to pay for a ``KUDOS:10`` monthly magazine subscription. Her 
Taler wallet is empty though.
+* She starts withdrawal through her Android wallet app, where she selects 
``KUDOS:10`` as the instructed
+  amount with ``mode=effective-mode``. This translates to 
``amountEffective=KUDOS:10`` and ``amountRaw=KUDOS:10.10``.
+* Alice is redirected to her banking app where she transfers ``KUDOS:10.10`` 
to the exchange.
+* Her Taler wallet balance will be ``KUDOS:10.10`` after the withdrawal 
completes.
+
+FIXME(dold): That flow does not work if withdrawal starts in the bank. Maybe 
there needs to be a mechanism
+where the wallet tells the bank the adjusted amount that needs to be 
transferred? That would be a new
+feature in the bank integration API.
+
+Example 4:
+
+* Alice has ``KUDOS:10`` in her wallet.
+* Alice wants to initiate a peer-push payment with ``amountInstructed=KUDOS:8``
+  and ``mode=effective-mode``. That means that after the payment, she expects
+  exactly ``KUDOS:2`` to remain in her wallet.
+* Due to the fee configuration, her wallet computes ``amountRaw=KUDOS:7.5`` 
and ``amountEffective=KUDOS:7.8``.
+  The effective amount in this case does **not** equal the instructed amount, 
despite the ``mode=effective-mode``.
+  That's because there no amount that can be spend so that the spend amount 
with resulting refresh
+  fees equal ``KUDOS:8``.
+* Alice confirms the peer-push payment initiation, and exactly ``KUDOS:7.5`` 
are credited
+  to the purse that her wallet creates.
+* Bob merges the purse into his reserve. Bob's wallet automatically withdraws
+  from the reserve, and his wallet balance increases by ``KUDOS:7.1``, since
+  withdrawal fees are deducted.
+
 Balances
 --------
 

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