commit dfb06a0ff21368253d8ce50b8da48140b3d96375
parent 84746f12bb7cebcff39d903b03e76a0fe51df9b5
Author: Florian Dold <florian@dold.me>
Date: Fri, 31 Mar 2023 16:35:17 +0200
DD 41, incorporate points from discussion with Sebastian
Diffstat:
1 file changed, 46 insertions(+), 0 deletions(-)
diff --git 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
--------
