[taler-docs] 02/02: more info

[gnunet]

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

sebasjm pushed a commit to branch master
in repository docs.

commit 0ea38708ceb2e257cdcd6d0e07dedc4e4c8b0ab7
Author: Sebastian <sebasjm@gmail.com>
AuthorDate: Tue Jun 13 13:24:25 2023 -0300

    more info
---
 .../041-wallet-balance-amount-definitions.rst      | 64 ++++++++--------------
 1 file changed, 24 insertions(+), 40 deletions(-)

diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
index e2da9865..eb6c3d90 100644
--- a/design-documents/041-wallet-balance-amount-definitions.rst
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -49,7 +49,7 @@ MANUAL_WITHDRAW
   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
@@ -66,7 +66,7 @@ DEPOSIT
   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
@@ -84,7 +84,7 @@ PULL CREDIT (creating an 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
@@ -123,7 +123,7 @@ PUSH DEBIT (creating a 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
@@ -163,7 +163,7 @@ BANK_WITHDRAW
   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
@@ -190,7 +190,7 @@ PAYMENT
 
   ``instructed_amount`` = contractTerms.amount
 
-  ``coins`` = select-coin(deposit, mode, raw_amount)
+  ``coins`` = select-coin-for-operation(debit, mode, raw_amount)
 
   ``raw_amount`` = instructed_amount - merchant_deposit_fee
 
@@ -207,7 +207,7 @@ PUSH CREDIT (getting the transfer)
 
   ``instructed_amount`` = p2pContract.amount
 
-  ``coins`` = select-coin(withdraw, mode, raw_amount)
+  ``coins`` = select-coin-for-operation(credit, mode, raw_amount)
 
   ``raw_amount`` = instructed_amount
 
@@ -223,7 +223,7 @@ PULL DEBIT (paying an invoice)
 
   ``instructed_amount`` = p2pContract.amount
 
-  ``coins`` = select-coin(deposit, mode, raw_amount)
+  ``coins`` = select-coin-for-operation(debit, mode, raw_amount)
 
   ``raw_amount`` = instructed_amount
 
@@ -262,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.
+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.
 
-``select-coin`` will receive 3 parameters:
-  * fee set: tell for which fee is doing the optimization (can be withdraw, 
deposit, push, pull)
+``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 and affect the denom 
selection
+  * mode: the interpretation of the amount parameter
+    - net: the amount does not include the operation fee
+    - gross: the amount include the operation fee
 
-    - 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 
+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
 
@@ -320,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.