028 now about deposit policy extensions

3 files changed, 79 insertions, 49 deletions

diff --git a/design-documents/028-deposit-policies.rst b/design-documents/028-deposit-policies.rst
new file mode 100644
index 00000000..5a5bccdc
--- /dev/null
+++ b/design-documents/028-deposit-policies.rst
@@ -0,0 +1,78 @@
+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 can exchange 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:
+
+- DB-schema design 
+
+  - deposit
+  - policy_details
+  - policy_fulfiment
+
+- 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 fulfilment
+
+Alternatives
+============
+
+TODO
+
+Drawbacks
+=========
+
+TODO
+
+
+Discussion / Q&A
+================
+
+TODO
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/028-proof-of-escrow.rst b/design-documents/028-proof-of-escrow.rst
deleted file mode 100644
index 54df56a0..00000000
--- a/design-documents/028-proof-of-escrow.rst
+++ /dev/null
@@ -1,48 +0,0 @@
-DD28: Proof of escrow
-#####################
-
-.. note::
-
-  The previous version of this design document has been retracted.  
-
-Summary
-=======
-
-We will propose here an extension to the exchange that implements an escrow policy.
-
-
-Motivation
-==========
-
-Certain types of trade, such as auctions or trades with long phases of
-negotiation, require a proof of escrow of money as a guarantee in order to
-participate or perform the trade.
-
-
-Background and Requirements
-===========================
-
-TODO
-
-Proposed Solution
-=================
-
-TODO
-
-Alternatives
-============
-
-TODO
-
-Drawbacks
-=========
-
-TODO
-
-
-Discussion / Q&A
-================
-
-TODO
-
-(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
index 493fbfb5..2305bbea 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -36,7 +36,7 @@ and protocol.
   025-withdraw-from-wallet
   026-refund-fees
   027-sandboxing-taler.rst
-  028-proof-of-escrow
+  028-deposit-policies
   029-mobile-ui
   030-offline-payments
   031-invoicing