[taler-docs] branch master updated (3fe9d2eb -> 0ea38708)

[gnunet]

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

sebasjm pushed a change to branch master
in repository docs.

    from 3fe9d2eb simplify schema of age-withdraw
     new d50b7496 better description of fees
     new 0ea38708 more info

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 .../041-wallet-balance-amount-definitions.rst      | 140 ++++++++++++---------
 1 file changed, 81 insertions(+), 59 deletions(-)

diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
index 56aaf401..eb6c3d90 100644
--- a/design-documents/041-wallet-balance-amount-definitions.rst
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -41,13 +41,15 @@ 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)
+  ``coins`` = select-coin-for-operation(credit, mode, instructed_amount)
   
   if instructed_amount mode = raw
     ``raw_amount`` = instructed_amount
@@ -60,9 +62,11 @@ 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)
+  ``coins`` = select-coin-for-operation(debit, mode, instructed_amount)
 
   if instructed_amount mode = raw
     ``raw_amount`` = instructed_amount
@@ -74,10 +78,13 @@ 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)
+  ``coins`` = select-coin-for-operation(credit, mode, instructed_amount)
 
   if instructed_amount mode = raw
     ``raw_amount`` = instructed_amount
@@ -110,10 +117,13 @@ 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)
+  ``coins`` = select-coin-for-operation(debit, mode, instructed_amount)
 
   if instructed_amount mode = raw
     ``raw_amount`` = instructed_amount
@@ -139,37 +149,65 @@ 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-for-operation(credit, 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)
+  ``coins`` = select-coin-for-operation(debit, 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
 
-  ``coins`` = select-coin(withdraw, mode, raw_amount)
+  ``coins`` = select-coin-for-operation(credit, mode, raw_amount)
 
   ``raw_amount`` = instructed_amount
 
@@ -180,12 +218,12 @@ 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
 
-  ``coins`` = select-coin(deposit, mode, raw_amount)
+  ``coins`` = select-coin-for-operation(debit, mode, raw_amount)
 
   ``raw_amount`` = instructed_amount
 
@@ -224,45 +262,28 @@ TIP
 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
+Is an internal optimization algorithm that will choose coins given a 
denomination list or current coin list
+until amount is reached. The coins selected to minimize the fee spent.
 
-  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 
+``select-coin-for-operation`` will receive 3 parameters:
+  * operation: define if the coins are selected from wallet database or from 
denomination list. Possible values are:
+   - credit: reduce withdrawal fee, use exchange denomination list
+   - debit: reduce deposit fee, use database denomination and current coin 
count
+  * amount: how much value the coins need to sum up
+  * mode: the interpretation of the amount parameter
+    - net: the amount does not include the operation fee
+    - gross: the amount include the operation fee
 
-  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 
+If the operation is debit and with the current coins there is no way to reach 
the amount then
+ 1. an optimized withdrawal operation can be suggested (list of denominations)
+ 2. an optimized refresh operation can be suggested (amount gap, coin to be 
refreshed and list of denominations to withdraw)
 
 .. note::
 
-  select-coin must be predictable (select the same coins for the same 
parameters) and if
+  ``select-coin-for-operation`` 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
+    operation: credit
 
     withdrawal_fee = amount1 - amount2
 
@@ -282,7 +303,8 @@ For withdrawal:
 * ``raw-mode`` (default): instructed amount is what is subtracted from the 
reserve balance (i.e. it's the raw amount)
 * ``effective-mode``: instructed amount is what the user wants to have as 
material balance in the wallet
 
-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.
+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 (where there is no contract that already specifies an amount):
 

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