028-deposit-policies.rst (6557B)
1 DD 28: Deposit Policy Extensions 2 ################################ 3 4 .. note:: 5 6 This is Work-In-Progress. 7 8 Summary 9 ******* 10 11 We will propose here a plugable mechanism in the exchange to support deposits 12 with associated policy. An exchange can enable support for such policies via 13 configuration. 14 15 The inital set of policy extensions that an exchange might provide consists of 16 17 Merchant refunds 18 Merchant can grant customers refundable payments. In this case, the 19 amount of the deposit is put into escrow by the exchange for a certain 20 period until which the customer can claim a refund. 21 22 Escrowed payments 23 A trustor puts coins into escrow with the exchange. It can be claimed 24 by a beneficiary until a certain deadline, when the claim is signed by 25 both, the beneficiary's and the trustor's keys. 26 27 Brandt-Vickrey auctions 28 A bidder puts coins into escrow with the exhange in order to 29 participate in an Brandt-Vickrey auction. The deposit confirmation is 30 proof to the seller for the escrow and contains a hash of the auction 31 meta-data and a deadline. After successfull execution of the auction, 32 the seller provides a valid transcript to the exchange from which the 33 exchange learns which bidder(s) won the auction for which prices. It 34 then transfers the amounts from the winners' coins to the seller. In 35 case of a timeout and for all losing bidders, the coins can be 36 refreshed. 37 38 The policies shall be implemented as *extensions* to the exchange (see 39 :doc:`006-extensions`). 40 41 Motivation 42 ********** 43 44 GNU Taler's initial set of API's (withdraw, deposit, refresh) support most 45 payment situations in which customers pay for goods and services within an 46 otherwise unconditioned transaction. (A notable exception from this the 47 ability to provide refunds, which will be re-factored into a policy extension). 48 49 However, in many payments depend on additional conditions to be met. GNU Taler 50 already supports payments with age restriction applied, but there are other 51 scenarious that we want to support. 52 53 Our aim is to provide an API for extensions of GNU Taler that implement 54 particular policies and policy-handling for payments (also called *conditioned 55 payments*). 56 57 58 Background and Requirements 59 *************************** 60 61 TODO 62 63 Proposed Solution 64 ***************** 65 66 TODO, explain: 67 68 - C-structs for policy extensions (esp. the handlers) 69 - Naming conventions for policy extensions 70 - Deadlines and -handling 71 - Typical choreography of a deposit with policy and its fulfillment 72 73 74 API-Endpoints of the Exchange 75 ============================= 76 77 TODO 78 79 80 81 Database-schema 82 =============== 83 84 TODO: Description 85 86 .. graphviz:: 87 88 digraph deposit_policies { 89 rankdir = LR; 90 splines = false; 91 fontname="monospace" 92 node [ 93 fontname="monospace" 94 shape=record 95 ] 96 97 subgraph cluster_deposits { 98 label=<<B>deposits</B>> 99 margin=20 100 deposits [ 101 label="...|<ref>policy_details_id (null)\l|...|timestamp\l|..." 102 ] 103 } 104 105 subgraph cluster_policy_details { 106 label=<<B>policy_details</B>> 107 margin=20 108 policy_details [ 109 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" 110 ] 111 } 112 113 subgraph cluster_policy_fulfillments { 114 label=<<B>policy_fulfillments</B>> 115 margin=20 116 rank=min; 117 policy_fulfillments [ 118 label="<id>id\l|proof\l|timestamp\l|<codes>policy_hash_codes (blob)\l" 119 ] 120 } 121 122 deposits:ref->policy_details:id [ label="n:1"; fontname="monospace" ]; 123 policy_details:fid->policy_fulfillments:id [label="n:1"; fontname="monospace" ]; 124 } 125 126 127 The field ``policy_hash_codes`` in table ``policy_fulfillments`` is a binary 128 blob that consists of the concatenation of the sorted 129 ``policy_details.policy_hash_code`` entries from all policies that are fulfilled by 130 this proof. 131 132 133 Policy Fulfillment States 134 ========================= 135 136 The fulfillment of a policy can be in one of the following five states: 137 138 Ready 139 The policy is funded and ready. The exchange is waiting for a proof of 140 fulfillment to arrive before the deadline. 141 142 Insufficient 143 The policy lacks funding, that is ``accumulated_total`` < 144 ``commitment``, but has otherwise been accepted. Funding can be 145 continued by calling ``/deposit`` or ``/batch-deposit`` with more coins 146 and the same policy details. 147 148 Success 149 The policy is provably fulfilled. The amounts for payout, fees and 150 refresh are transfered/can be claimed. Note that a policy fulfillment 151 handler can change the values for the amounts for payout, fees and 152 refresh. 153 154 Timeout 155 The policy has timed out. The amounts for payout and refresh are 156 transfered/can be claimed. 157 158 Failure 159 The policy is in an failure state. Payouts and refreshes are 160 blocked, timeouts are ignored. 161 162 163 164 Invariants 165 ^^^^^^^^^^ 166 167 The following invariants need to be fulfilled and be checked by the auditor: 168 169 - The fulfillment state of a policy is **Insufficient** IF AND ONLY IF the 170 amount in ``policy_details.commitment`` is equal or larger than the amount in 171 ``policy_details.accumulated_total``. 172 173 - The sum of amounts in ``policy_details.fee`` and 174 ``policy_details.transferable`` MUST be equal or less than the amount in 175 ``policy_details.accumulated_total``. 176 177 - The amount in ``policy_details.accumulated_total`` MUST be equal to the total 178 sum of contributions of the individual coins of the deposits that reference 179 this policy. 180 181 - Each hash code encoded in ``policy_fulfillments.policy_hash_codes`` MUST 182 refer to an existing ``policy_details.hash_code`` AND its ``.fulfillment_id`` 183 MUST point to the same ``policy_fulfillments.id``. 184 185 - Conversely: If a ``policy_details.fulfillment_id`` points to an entry in 186 ``policy_fulfillment``, the ``policy_details.policy_hash_code`` MUST be 187 present in that entry's ``.policy_hash_codes``. 188 189 190 191 Alternatives 192 ============ 193 194 TODO 195 196 Drawbacks 197 ========= 198 199 TODO 200 201 202 Discussion / Q&A 203 ================ 204 205 TODO 206 207 (This should be filled in with results from discussions on mailing lists / personal communication.)