diff options
| -rw-r--r-- | design-documents/041-wallet-balance-amount-definitions.rst | 114 | ||||
| -rw-r--r-- | design-documents/index.rst | 1 |
2 files changed, 115 insertions, 0 deletions
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 00000000..87848888 --- /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 a53f814b..aee3af42 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 |