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