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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
DD 48: Wallet Exchange Lifecycle and Management
###############################################
Summary
=======
This design document covers the lifecycle and management
of exchanges in the wallet.
Motivation
==========
The current wallet implementation lacks requests to manage exchanges.
It also always fetches the /keys info of all exchanges, because it doens't
distinguish between used and preset/added exchanges.
Requirements
============
The following properties of of exchanges managed by the wallet
are important:
* is the exchange used for something (coins, (account-)reserves, purses, ...)
* did the user (ever) accept the ToS?
* does the exchange have newer ToS available?
* is a current version of /keys (including former /wire) downloaded?
* were there errors downloading or checking the keys info?
* is the exchange permanently added or ephemeral?
* ephemeral exchange records are created when the user
checks fees of an exchange but doesn't use it,
they would typically be hidden in the UI
Proposed Solution
=================
Exchange Entry Status
---------------------
The wallet exposes three separate status fields for each exchange entry:
* the entry status
* the update status
* the ToS status
Entry Status
~~~~~~~~~~~~
* ``preset``: Exchange record has been added to the exchange (typically as
a hardcoded preset in wallet-core). While the exchange can be selected for operations,
the wallet doesn't update the status yet, i.e. no /keys queries are done.
* ``ephemeral``: Exchange has been updated (or update has been attempted) at
least once (for example as part of checking the fees for a transaction using
the exchange). However, the exchange is not yet used for any resource in the wallet.
In this state, the exchange record will be garbage-collected eventually.
* ``used``: The exchange is known and used, the wallet regularly queries /keys.
Transitions:
* A transition from ``used`` to ``ephemeral`` is not possible,
since this would eventually remove preset exchanges and likely confuse
the user.
Update Status
~~~~~~~~~~~~~
* ``initial``: Not updated, no need to update
* ``initial-update``: Update pending, possibly with error
* ``suspended``: Exchange was manually disabled, should not be contacted
anymore, but record is kept in the wallet. Mostly useful for testing.
* ``unavailable-update``: The exchange is currently unavailable to be used for withdrawals,
but it is possible that the exchange starts working again in the future.
The wallet will re-try contacting the exchange. The wallet will still try
operations that *spend* coins, but the user might be warned about the bad
exchange status.
Examples:
* The exchange updated to a new protocol version that is incompatible with the wallet
* The exchange advertises a new master public key. This might be a temporary
configuration issue or malicious attack.
* The exchange only advertises outdated denomination keys, making new withdrawals
impossible.
* ``ready``: Exchange is useable.
* ``ready-update``: Exchange is useable, but currently being updated.
ToS Status
~~~~~~~~~~
* ``pending``: The wallet is still trying to download the ToS.
Possibly the last download attempt failed, will be reflected in an
error details object.
* ``proposed``: The user needs to accept the current ToS.
* ``accepted``: The user has accepted the latest version of the ToS.
Management Requests
-------------------
* ``listExchanges``: List exchanges with their status info.
* ``addExchange``: Adds an exchange, entry status will be ``ephemeral``
until the user actually uses the exchange.
* ``getExchangeResources``: List resources (number of coins, reserves, ...) associated
with the exchange.
* ``deleteExchange({exchangeUrl: string, purge: boolean})``: Removes an exchange.
Unless ``purge: true`` is specified, only an exchange without any associated
resources can be deleted.
* ``getExchangeTos({exchangeUrl: string, acceptLanguage?: string[], acceptFormat?: string[]}) => { language: string, mime: string, content: string, altLanguages: string[] }``
FIXME: Purging should probably delete *all* resources associated with the exchange.
But does it also remove the associated transactions?
ToS Management
--------------
The wallet only stores the last accepted ToS ETag and the ETag last offered by
the exchange. The ToS contents are not stored by the wallet database (and thus
not included in backups). However, the wallet implementation may cache the
``/terms`` response on the level of the HTTP client.
In future iterations, the UI might specify the prefered language and content type
for ``/terms``, so that the wallet can already download the full response (not just ``HEAD``).
Definition of Done
==================
* states implemented in wallet-core
* exchange management specified on a UI level
* webex implemented
* android wallet implemented
* ios wallet implemented
Discussion / Q&A
================
* Should there be a "permanently failed" update state?
* dold => I don't think so, as it means that temporary configuration issues on the side of the
exchange might *permanently* brick users' wallets.
The wallet should always re-try contacting the exchange and of course possibly report
information to the auditor.
|
