[taler-docs] 01/02: better description of fees

[gnunet]

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

sebasjm pushed a commit to branch master
in repository docs.

commit d50b749673f5e60e8373f8ee1aae1d086be59817
Author: Sebastian <sebasjm@gmail.com>
AuthorDate: Mon Jun 12 22:50:27 2023 -0300

    better description of fees
---
 .../041-wallet-balance-amount-definitions.rst      | 80 ++++++++++++++++------
 1 file changed, 59 insertions(+), 21 deletions(-)

diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
index 56aaf401..e2da9865 100644
--- a/design-documents/041-wallet-balance-amount-definitions.rst
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -41,11 +41,13 @@ Amounts
   *after* fees.
 
 
-Transaction types
------------------
+Transaction types initialized by the wallet
+-------------------------------------------
 
-WITHDRAW
-  raw amount is the total to be wired in exchange bank account
+MANUAL_WITHDRAW
+  raw amount is the amount that need to be added into the exchange account,
+  this is not the same as the amount leaving the user account since their own
+  account may charge some fee that can be taken into account
 
   ``coins`` = select-coin(withdraw, mode, instructed_amount)
   
@@ -60,7 +62,9 @@ WITHDRAW
     ``effective_amount`` = instructed_amount
 
 DEPOSIT
-  raw amount is the total wire transfer in the bank account
+  raw amount is the amount leaving the exchange account without the wire fee,
+  this should be what the user see as an increase in the user bank account 
unless
+  there are some extra fee not seen from the exchange
 
   ``coins`` = select-coin(deposit, mode, instructed_amount)
 
@@ -74,8 +78,11 @@ DEPOSIT
 
     ``effective_amount`` = instructed_amount
 
-PULL CREDIT
-  raw amount is the purse_value in the exchange that counter-party need will 
pay
+PULL CREDIT (creating an invoice)
+  raw amount is the amount in the exchange that counter-party need will pay 
(purse_value),
+  this is exactly the same raw amount of the PULL DEBIT operation (paying the 
invoice)
+  counter-party amount is an aprox amount of the other wallet assuming the 
same coin selection
+  algorithm
 
   ``coins`` = select-coin(pull, mode, instructed_amount)
 
@@ -110,8 +117,11 @@ PULL CREDIT
     selection.
 
 
-PUSH DEBIT
-  raw amount is the purse_value in the exchange to be withdrawn that 
counter-party will withdraw
+PUSH DEBIT (creating a transfer)
+  raw amount is the amount in the exchange that counter-party need be able to 
withdraw (purse_value),
+  this is exactly the same raw amount of the PUSH CREDIT operation (getting 
the transfer)
+  counter-party amount is an aprox amount of the other wallet assuming the 
same coin selection
+  algorithm
 
   ``coins`` = select-coin(push, mode, instructed_amount)
 
@@ -139,32 +149,60 @@ PUSH DEBIT
     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 
+Transaction types completed by the wallet
+-------------------------------------------
+
+Next transaction types are not initiated in the wallet so instructed amount is 
not defined by the wallet user.
 
-``contract_wire_fee`` = min(wire.transfer_fee / 
contractTerms.amortization_factor, contractTerms.max_wire_fee)
+We need to calculate effective_amount to check if the wallet is able to 
perform the operation or the user accept 
+the fees.
+
+BANK_WITHDRAW
+  raw amount is that reached the bank account of the exchange,
+  this is not the same as the amount leaving the user account since their own
+  account may charge some fee that can be taken into 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
+
+
+.. note ::
+  how much wire_fee the merchant is willing to pay
+
+  ``merchant_wire_fee`` = min(wire.transfer_fee / 
contractTerms.amortization_factor, contractTerms.max_wire_fee)
+  
+  ``merchant_deposit_fee`` = min(contractTerms.max_fee, contract_wire_fee)
 
-``max_merchant_fee`` = min(contractTerms.max_fee, contract_wire_fee)
 
 PAYMENT
-  raw amount is the net value of the order without fees 
+  raw amount is the amount the merchant should get if is not doing aggregated 
transaction.
+
 
   ``instructed_amount`` = contractTerms.amount
 
   ``coins`` = select-coin(deposit, mode, raw_amount)
 
-  ``raw_amount`` = instructed_amount - max_merchant_fee
+  ``raw_amount`` = instructed_amount - merchant_deposit_fee
 
-  ``effective_amount`` = instructed_amount + coins.deposit_fee + 
coins.refresh_fee + wire.transfer_fee - max_merchant_fee
+  ``effective_amount`` = instructed_amount + coins.deposit_fee + 
coins.refresh_fee + (wire.transfer_fee - merchant_wire_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
+
+PUSH CREDIT (getting the transfer)
   raw amount is the purse_value in the exchange to be withdrawn
 
   ``instructed_amount`` = p2pContract.amount
@@ -180,7 +218,7 @@ PUSH CREDIT
     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
+PULL DEBIT (paying an invoice)
   raw amount is the net value of the invoice without fees 
 
   ``instructed_amount`` = p2pContract.amount
@@ -228,8 +266,8 @@ Is an optimization algorithm that will choose coins given a 
denomination list un
 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
+  * fee set: tell for which fee is doing the optimization (can be withdraw, 
deposit, push, pull)
+  * amount: how much 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

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