12.28. DD 28: Deposit Policy Extensions¶
Note
This is Work-In-Progress.
12.28.1. 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 DD 06: Extensions for GNU Taler).
12.28.2. Motivation¶
GNU Taler’s initial set of API’s (withdraw, deposit, refresh) support most payment situations in which customers pay for goods and services within an otherwise unconditioned transaction. (A notable exception from this the ability to provide refunds, which will be re-factored into a policy extension).
However, in many payments depend on additional conditions to be met. GNU Taler already supports payments with age restriction applied, but there are other scenarious that we want to support.
Our aim is to provide an API for extensions of GNU Taler that implement particular policies and policy-handling for payments (also called conditioned payments).
12.28.3. Background and Requirements¶
TODO
12.28.4. Proposed Solution¶
TODO, explain:
C-structs for policy extensions (esp. the handlers)
Naming conventions for policy extensions
Deadlines and -handling
Typical choreography of a deposit with policy and its fulfillment
12.28.4.1. API-Endpoints of the Exchange¶
TODO
12.28.4.2. Database-schema¶
TODO: Description
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.
12.28.4.3. 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.
12.28.4.3.1. 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 inpolicy_details.accumulated_total
.The sum of amounts in
policy_details.fee
andpolicy_details.transferable
MUST be equal or less than the amount inpolicy_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 existingpolicy_details.hash_code
AND its.fulfillment_id
MUST point to the samepolicy_fulfillments.id
.Conversely: If a
policy_details.fulfillment_id
points to an entry inpolicy_fulfillment
, thepolicy_details.policy_hash_code
MUST be present in that entry’s.policy_hash_codes
.
12.28.4.4. Alternatives¶
TODO
12.28.4.5. Drawbacks¶
TODO
12.28.4.6. Discussion / Q&A¶
TODO
(This should be filled in with results from discussions on mailing lists / personal communication.)