commit 0ea38708ceb2e257cdcd6d0e07dedc4e4c8b0ab7
parent d50b749673f5e60e8373f8ee1aae1d086be59817
Author: Sebastian <sebasjm@gmail.com>
Date: Tue, 13 Jun 2023 13:24:25 -0300
more info
Diffstat:
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
@@ -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):
