diff options
Diffstat (limited to 'design-documents/028-deposit-policies.rst')
-rw-r--r-- | design-documents/028-deposit-policies.rst | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/design-documents/028-deposit-policies.rst b/design-documents/028-deposit-policies.rst new file mode 100644 index 00000000..1bdf4801 --- /dev/null +++ b/design-documents/028-deposit-policies.rst @@ -0,0 +1,207 @@ +DD 28: 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 +********** + +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*). + + +Background and Requirements +*************************** + +TODO + +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 + + +API-Endpoints of the Exchange +============================= + +TODO + + + +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.) |