[taler-docs] branch master updated: DD 41

[gnunet]

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

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 4c561d4  DD 41
4c561d4 is described below

commit 4c561d43e6d2e58a4c011ebb19b73add2e49b986
Author: Florian Dold <florian@dold.me>
AuthorDate: Thu Mar 30 12:14:00 2023 +0200

    DD 41
---
 .../041-wallet-balance-amount-definitions.rst      | 114 +++++++++++++++++++++
 design-documents/index.rst                         |   1 +
 2 files changed, 115 insertions(+)

diff --git a/design-documents/041-wallet-balance-amount-definitions.rst 
b/design-documents/041-wallet-balance-amount-definitions.rst
new file mode 100644
index 0000000..8784888
--- /dev/null
+++ b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -0,0 +1,114 @@
+DD 41: Wallet Balance and Amount Definitions
+############################################
+
+Summary
+=======
+
+This design document discusses terminology and concepts used in the wallet
+for balances and amounts.
+
+Motivation
+==========
+
+There are many different types of balances and amounts, and they need
+to have a clear definition.
+
+Furthermore, the user in some situations needs to know/decide whether
+an amount that the user chooses includes fees or not.
+
+
+Proposed Solution
+=================
+
+Amounts
+-------
+
+* "effective amount": An effective amount always represents the direct effect 
on the
+  wallet's balance of the same currency.
+* "raw amount": The raw amount always refers to the amount with fees applied.
+  The exact interpretation of that depends on the transaction type.
+* "instructed amount": An instructed amount always refers to the amount that
+  a user has explicitly specified as an input.  It is not directly a property
+  of transactions, but might be added as metadata to transactions for
+  informational purpuses.  How the instructed amount is interpreted
+  differs based on the "instructed amount mode" that is specified
+  together with the amount.  By default, the instructed amount
+  is assumed to translate to the raw amount of the corresponding transaction.
+
+Instructed Amount Modes
+-----------------------
+
+The interpretation and possible choices of the instructed amount mode
+depends on which transaction is initiated.
+
+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.
+
+For deposits:
+
+* ``max-mode``: The instructed amount is ignored (can be zero in the request), 
and all coins are spent
+* ``raw-mode`` (default): The instructed amount is what will be paid to the 
"merchant" (or the customer's bank account), ignoring wire fees
+* ``effective-mode``: The instructed amount is how the wallet's balance will 
be affected. Difficult to compute accurately because refresh is involved.
+
+For peer-push-debit:
+
+* ``raw-mode`` (default): The instructed amount is what will be paid, deposit 
fees are covered by the sender, withdrawal fees from the reserve by the receiver
+* ``effective-mode``: Instructed amount is the effect on the material balance. 
Difficult to compute accurately because refresh is involved.
+
+FIXME(dold): Should we also have a mode where withdrawal fees are covered by 
the side that does peer-push-debit? However, that assumes the other party has 
the same withdrawal coin selection algorithm
+
+For peer-pull-credit:
+
+* ``raw-mode`` (default): Amount that the other party has to put in the 
reserve, where the other party has to pay deposit fees
+* ``effective-mode``: Amount that be added to on the initiator's balance
+
+Balances
+--------
+
+The following types of balances are defined:
+
+- ``available``: Balance that the wallet believes will certainly be available
+  for spending, modulo any failures of the exchange or double spending issues.
+  This includes available coins *not* allocated to any
+  spending/refresh/... operation. Pending withdrawals are *not* counted
+  towards this balance, because they are not certain to succeed.
+  Pending refreshes *are* counted towards this balance.
+  This balance type is nice to show to the user, because it does not
+  temporarily decrease after payment when we are waiting for refreshes
+
+- ``material``: Balance that the wallet believes it could spend *right now*,
+  without waiting for any operations to complete.
+  This balance type is important when showing "insufficient balance" error 
messages.
+
+- ``age-acceptable``: Subset of the material balance that can be spent
+  with age restrictions applied.
+
+- ``merchant-acceptable``: Subset of the material balance that can be spent 
with a particular
+  merchant (restricted via min age, exchange, auditor, wire_method).
+
+- ``merchant-depositable``: Subset of the merchant-acceptable balance that the 
merchant
+  can accept via their supported wire methods.
+
+Balance Mismatch
+----------------
+
+The wallet uses the following terminology when an operation can't succeed
+because the balance is too low, even though the instructed amount 
+
+- "fee-gap-estimate": Additional (material) balance that the wallet estimates 
it
+  still needs for the operation to succeed.
+
+  - This value is an estimated, because newly withdrawn coins might have 
different fees.
+  - This value is specified *per exchange*, because each exchange has 
different fees.
+
+FIXME(dold): Should we specify an upper-bound fee-gap-estimate to simplify it 
for the UIs?
+
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / 
personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
index a53f814..aee3af4 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -49,4 +49,5 @@ and protocol.
   038-demobanks-protocol-suppliers.rst
   039-taler-browser-integration.rst
   040-distro-packaging.rst
+  041-wallet-balance-amount-definitions.rst
   999-template

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