[taler-docs] branch master updated: description of how amounts are calculated

[gnunet]

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

sebasjm pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 3fce863  description of how amounts are calculated
3fce863 is described below

commit 3fce863ce0a65712cf4c91d7d4fc099f679eb6c0
Author: Sebastian <sebasjm@gmail.com>
AuthorDate: Sat Apr 8 12:52:21 2023 -0300

    description of how amounts are calculated
---
 .../041-wallet-balance-amount-definitions.rst      | 240 ++++++++++++++++++++-
 1 file changed, 237 insertions(+), 3 deletions(-)

diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
index 9a1eec7..48deeab 100644
--- a/design-documents/041-wallet-balance-amount-definitions.rst
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -30,16 +30,250 @@ Amounts
 * "instructed amount": An instructed amount always refers to the amount that
   a user has explicitly specified as an input.  It is not directly a property
   of transactions, but might be added as metadata to transactions for
-  informational purpuses.  How the instructed amount is interpreted
+  informational purposes.  How the instructed amount is interpreted
   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
+* "counter-party 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.
 
+
+Transaction types
+----------
+
+WITHDRAW
+  raw amount is the total to be wired in exchange bank account
+
+  ``coins`` = select-coin(withdraw, mode, instructed_amount)
+  
+  if instructed_amount mode = raw
+    ``raw_amount`` = instructed_amount
+    
+    ``effective_amount`` = instructed_amount - coins.withdrawal_fee
+
+  if instructed_amount mode = effective
+    ``raw_amount`` = instructed_amount + coins.withdrawal_fee
+    
+    ``effective_amount`` = instructed_amount
+
+DEPOSIT
+  raw amount is the total wire transfer in the bank account
+
+  ``coins`` = select-coin(deposit, mode, instructed_amount)
+
+  if instructed_amount mode = raw
+    ``raw_amount`` = instructed_amount
+
+    ``effective_amount`` = instructed_amount + coins.deposit_fee + 
coins.refresh_fee + wire.transfer_fee 
+
+  if instructed_amount mode = effective
+    ``raw_amount`` = instructed_amount - coins.deposit_fee - coins.refresh_fee 
- wire.transfer_fee
+
+    ``effective_amount`` = instructed_amount
+
+PULL CREDIT
+  raw amount is the purse_value in the exchange that counter-party need will 
pay
+
+  ``coins`` = select-coin(pull, mode, instructed_amount)
+
+  if instructed_amount mode = raw
+    ``raw_amount`` = instructed_amount
+
+    ``effective_amount`` = instructed_amount - coins.withdrawal_fee - purse_fee
+
+  if instructed_amount mode = effective
+    ``raw_amount`` = instructed_amount + coins.withdrawal_fee + purse_fee
+
+    ``effective_amount`` = instructed_amount
+  
+  if instructed_amount mode = counter-party
+    ``raw_amount`` = instructed_amount - coins.counter-party_deposit_fee  
+
+    ``effective_amount`` = instructed_amount - coins.counter-party_deposit_fee 
- coins.withdrawal_fee - purse_fee
+
+  ``counter-party_raw_amount`` = raw_amount 
+  
+  ``counter-party_effective_amount`` = raw_amount + 
coins.counter-party_deposit_fee 
+
+  .. note::
+
+    counter-party_effective_amount is an estimation since refresh fee is not 
included. 
+    Refresh fee can't be calculated because depends on the coins available in 
the wallet 
+    of the counter-party
+
+  .. note::
+    coins.counter-party_deposit_fee is the minimum deposit_fee that can be 
calculated for the
+    given exchange. Counter-party may pay more if it have different 
preferences doing the coin 
+    selection.
+
+
+PUSH DEBIT
+  raw amount is the purse_value in the exchange to be withdrawn that 
counter-party will withdraw
+
+  ``coins`` = select-coin(push, mode, instructed_amount)
+
+  if instructed_amount mode = raw
+    ``raw_amount`` = instructed_amount
+
+    ``effective_amount`` = instructed_amount + coins.deposit_fee + purse_fee
+
+  if instructed_amount mode = effective
+    ``raw_amount`` = instructed_amount - coins.deposit_fee - purse_fee
+
+    ``effective_amount`` = instructed_amount
+ 
+  if instructed_amount mode = counter-party
+    ``raw_amount`` = instructed_amount + coins.counter-party_withdraw_fee  
+
+    ``effective_amount`` = instructed_amount - 
coins.counter-party_withdraw_fee - coins.withdrawal_fee - purse_fee
+ 
+  ``counter-party_raw_amount`` = raw_amount 
+
+  ``counter-party_effective_amount`` = raw_amount - 
coins.counter-party_withdraw_fee
+
+  .. note::
+    coins.counter-party_withdraw_fee is the minimum withdraw_fee that can be 
calculated for the
+    given exchange. Counter-party may pay more if it have different 
preferences doing the coin 
+    selection.
+
+
+------------
+
+.. note::
+  Next transaction types are not initiated in the wallet so instructed amount 
is not defined by the wallet user.
+
+  It may be helpful to calculate effective_amount to check if the wallet is 
able to perform the operation 
+
+``contract_wire_fee`` = min(wire.transfer_fee / 
contractTerms.amortization_factor, contractTerms.max_wire_fee)
+
+``max_merchant_fee`` = min(contractTerms.max_fee, contract_wire_fee)
+
+PAYMENT
+  raw amount is the net value of the order without fees 
+
+  ``instructed_amount`` = contractTerms.amount
+
+  ``coins`` = select-coin(deposit, mode, raw_amount)
+
+  ``raw_amount`` = instructed_amount - max_merchant_fee
+
+  ``effective_amount`` = instructed_amount + coins.deposit_fee + 
coins.refresh_fee + wire.transfer_fee - max_merchant_fee
+
+  .. note::
+    The current coin-selection algorithm the order_price is neither raw_amount 
nor effective_amount.
+    We can calculate the raw_amount of the payment as (contractTerms.amount - 
max_merchant_fee) and then this
+    operation becomes equivalent than a deposit (in terms of fee calculation).
+
+PUSH CREDIT
+  raw amount is the purse_value in the exchange to be withdrawn
+
+  ``instructed_amount`` = p2pContract.amount
+
+  ``coins`` = select-coin(withdraw, mode, raw_amount)
+
+  ``raw_amount`` = instructed_amount
+
+  ``effective_amount`` = instructed_amount - coins.withdrawal_fee
+
+  .. note::
+    In the case that the withdrawal_fee of the coin selection for the 
push-credit amount
+    is higher than the wire_fee of the exchange, can the wallet ask the 
exchange to make
+    a wire transfer of the purse instead of proceeding? 
+
+PULL DEBIT
+  raw amount is the net value of the invoice without fees 
+
+  ``instructed_amount`` = p2pContract.amount
+
+  ``coins`` = select-coin(deposit, mode, raw_amount)
+
+  ``raw_amount`` = instructed_amount
+
+  ``effective_amount`` = instructed_amount + coins.deposit_fee + 
coins.refresh_fee + wire.transfer_fee
+
+REFUND
+  raw amount is the amount that the merchant refunded
+
+  ``instructed_amount`` = refund.amount
+
+  ``raw_amount`` = instructed_amount 
+
+  ``effective_amount`` = instructed_amount - refund_fee - refresh_fee
+
+  .. note::
+    There may be the case that the merchant should refund all the value of the 
purchase
+    and that may include paying for the refund_fee.
+
+    Is there a way that the merchant can initiate a refund of purchase + 
refund_fee so 
+    the wallet will get the same effective_amount?
+
+TIP
+  raw amount is the amount that the merchant send as tip
+
+  ``instructed_amount`` = tip.amount
+
+  ``raw_amount`` = instructed_amount + withdrawal_fee
+
+  ``effective_amount`` = instructed_amount 
+
+  .. note:: 
+    We should not show fee for tips in the wallet since the merchant is the 
one choosing
+    the exchange and we can assume that those tips are paid by the merchant. 
+    So the wallet only care about the effective.
+
+Coin selection algorithm
+----------
+
+Is an optimization algorithm that will choose coins given a denomination list 
until amount is reached
+and the coins selected minimize the fee spent.
+
+``select-coin`` will receive 3 parameters:
+  * operation type: tell for which fee is doing the optimization (can be 
withdraw, deposit, push, pull)
+  * amount: how much value value the coins need to sum up
+  * mode: the interpretation of the amount parameter and affect the denom 
selection
+
+    - effective: the amount is the expected balance change
+    - raw: the amount include fee of the operation paid by this wallet
+    - counter-party: only valid for push and pull, the amount include fee of 
the operation and fee of the counter-party operation
+
+Given the operation type, the fees taking into account when doing the 
calculation
+
+  withdraw: 
+    - withdrawal_fee of denominations until amount
+
+  deposit: 
+    - deposit_fee for every coin until total
+    - refresh_fee of (total-amount)
+    - wire_transfer for every exchange
+
+  pull:
+    - withdraw_fee of the amount
+    - purse_fee of the exchange
+    - if the mode is counter-party it should also take into account the 
deposit_fee of selected exchange 
+
+  push:
+    - deposit_fee for every coin until total
+    - refresh_fee of (total - amount)
+    - purse_fee of the exchange
+    - if the mode is counter-party it should also take into account the 
withdrawal_fee of selected exchange 
+
+.. note::
+
+  select-coin must be predictable (select the same coins for the same 
parameters) and if
+  the difference between two amounts are the fee for a given operation:
+
+    operation: withdrawal
+
+    withdrawal_fee = amount1 - amount2
+
+  then the wallet should select the same coins using the correct mode 
+  
+    select-coin(withdraw, raw, amount1) == select-coin(withdraw, effective, 
amount2)
+
+
 Instructed Amount Modes
 -----------------------
 
@@ -64,7 +298,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. Difficult to compute accurately because coin 
selection by receiver may not match our expectations.
+* ``counter-party-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(grothoff): isn't this the 
counterparty-effective-mode you described above, and that would seem to exactly 
have this issue?
 

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