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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
DD28: Deposit Policy Extensions
###############################
.. note::
This is Work-In-Progress.
Summary
*******
We will propose here a plugable mechanism in the exchange to support deposits
with associated policy. An exchange can enable support for such policies via
configuration.
The inital set of policy extensions that an exchange might provide consists of
Merchant refunds
Merchant can grant customers refundable payments. In this case, the
amount of the deposit is put into escrow by the exchange for a certain
period until which the customer can claim a refund.
Escrowed payments
A trustor puts coins into escrow with the exchange. It can be claimed
by a beneficiary until a certain deadline, when the claim is signed by
both, the beneficiary's and the trustor's keys.
Brandt-Vickrey auctions
A bidder puts coins into escrow with the exhange in order to
participate in an Brandt-Vickrey auction. The deposit confirmation is
proof to the seller for the escrow and contains a hash of the auction
meta-data and a deadline. After successfull execution of the auction,
the seller provides a valid transcript to the exchange from which the
exchange learns which bidder(s) won the auction for which prices. It
then transfers the amounts from the winners' coins to the seller. In
case of a timeout and for all losing bidders, the coins can be
refreshed.
The policies shall be implemented as *extensions* to the exchange (see
:doc:`006-extensions`).
Motivation
**********
TODO
Background and Requirements
***************************
TODO
Proposed Solution
*****************
TODO, explain:
- C-structs for policy extensions (esp. the handlers)
- Naming conventions for policy extensions
- Deadlines and -handling
- API-endpoints (``/extensions/policy_...``)
- Typical choreography of a deposit with policy and its fulfillment
Database-schema
===============
TODO: Description
.. graphviz::
digraph deposit_policies {
rankdir = LR;
splines = false;
fontname="monospace"
node [
fontname="monospace"
shape=record
]
subgraph cluster_deposits {
label=<<B>deposits</B>>
margin=20
deposits [
label="...|<ref>policy_details_id (null)\l|...|timestamp\l|..."
]
}
subgraph cluster_policy_details {
label=<<B>policy_details</B>>
margin=20
policy_details [
label="<id>id\l|<hash>policy_hash_code (unique)\l|deadline\l|commitment (amount)\l|accumulated_total (amount)\l|fee (amount)\l|transferable (amount)\l|fulfillment_state\l|<fid>fulfillment_id (null)\l"
]
}
subgraph cluster_policy_fulfillments {
label=<<B>policy_fulfillments</B>>
margin=20
rank=min;
policy_fulfillments [
label="<id>id\l|proof\l|timestamp\l|<codes>policy_hash_codes (blob)\l"
]
}
deposits:ref->policy_details:id [ label="n:1"; fontname="monospace" ];
policy_details:fid->policy_fulfillments:id [label="n:1"; fontname="monospace" ];
}
The field ``policy_hash_codes`` in table ``policy_fulfillments`` is a binary
blob that consists of the concatenation of the sorted
``policy_details.policy_hash_code`` entries from all policies that are fulfilled by
this proof.
Policy Fulfillment States
=========================
The fulfillment of a policy can be in one of the following five states:
Ready
The policy is funded and ready. The exchange is waiting for a proof of
fulfillment to arrive before the deadline.
Insufficient
The policy lacks funding, that is ``accumulated_total`` <
``commitment``, but has otherwise been accepted. Funding can be
continued by calling ``/deposit`` or ``/batch-deposit`` with more coins
and the same policy details.
Success
The policy is provably fulfilled. The amounts for payout, fees and
refresh are transfered/can be claimed. Note that a policy fulfillment
handler can change the values for the amounts for payout, fees and
refresh.
Timeout
The policy has timed out. The amounts for payout and refresh are
transfered/can be claimed.
Failure
The policy is in an failure state. Payouts and refreshes are
blocked, timeouts are ignored.
Invariants
^^^^^^^^^^
The following invariants need to be fulfilled and be checked by the auditor:
- The fulfillment state of a policy is **Insufficient** IF AND ONLY IF the
amount in ``policy_details.commitment`` is equal or larger than the amount in
``policy_details.accumulated_total``.
- The sum of amounts in ``policy_details.fee`` and
``policy_details.transferable`` MUST be equal or less than the amount in
``policy_details.accumulated_total``.
- The amount in ``policy_details.accumulated_total`` MUST be equal to the total
sum of contributions of the individual coins of the deposits that reference
this policy.
- Each hash code encoded in ``policy_fulfillments.policy_hash_codes`` MUST
refer to an existing ``policy_details.hash_code`` AND its ``.fulfillment_id``
MUST point to the same ``policy_fulfillments.id``.
- Conversely: If a ``policy_details.fulfillment_id`` points to an entry in
``policy_fulfillment``, the ``policy_details.policy_hash_code`` MUST be
present in that entry's ``.policy_hash_codes``.
Alternatives
============
TODO
Drawbacks
=========
TODO
Discussion / Q&A
================
TODO
(This should be filled in with results from discussions on mailing lists / personal communication.)
|
