1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
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.)
|
