commit d50b749673f5e60e8373f8ee1aae1d086be59817
parent 3fe9d2ebaaa39a877d773e0cb02556c1c47ee5f5
Author: Sebastian <sebasjm@gmail.com>
Date: Mon, 12 Jun 2023 22:50:27 -0300
better description of fees
Diffstat:
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
@@ -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
