[taler-docs] branch master updated: Added DD 028 - proof of escrow service

[gnunet]

This is an automated email from the git hooks/post-receive script.

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 0c42e85  Added DD 028 - proof of escrow service
0c42e85 is described below

commit 0c42e85aba06d60baac0b44a3259a8781e10d3c3
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Mon May 2 15:22:01 2022 +0200

    Added DD 028 - proof of escrow service
---
 design-documents/028-proof-of-escrow.rst | 128 +++++++++++++++++++++++++++++++
 design-documents/_svgs/escrow-flow.svg   |   1 +
 design-documents/index.rst               |   1 +
 3 files changed, 130 insertions(+)

diff --git a/design-documents/028-proof-of-escrow.rst 
b/design-documents/028-proof-of-escrow.rst
new file mode 100644
index 0000000..113d274
--- /dev/null
+++ b/design-documents/028-proof-of-escrow.rst
@@ -0,0 +1,128 @@
+DD 028: Proof of escrow in the exchange
+#######################################
+
+.. note::
+
+  This design document is currently a draft, it
+  does not reflect any implementation decisions yet.
+
+
+Summary
+=======
+
+We propose here an extension to the exchange: An escrow service that can be
+used by other, separate trading services f.e. for online auctions.
+
+
+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.
+
+We want to extend GNU Taler to support trades such as anonymous sealed-bid
+auctions.  While the auction service will be a separate (from the exchange)
+entity, behaving in parts like a normal merchant in the GNU Taler sense, the
+exchange itself can provide an escrow services.
+
+Background and Requirements
+===========================
+
+An escrow service is a intermediary between two parties and must trusted by
+both.  In the GNU Taler payment system, this role is per definition played by
+the exchange for buyers and sellers during purchases.  The auditor controls the
+exchange and is also a mediator between buyers and selles.
+
+The role of the exchange can be therefore extended to the specific needs of
+escrow.  In contrast to purchase/deposit, for escrow, particular coins are
+locked, but not spent. This prohibits their spending for a specific timespan
+and until a valid order of release is provided.
+
+However, in the context of auctions, we want the parties to be able to verify
+the fairness of the participants.  For example, a seller of goods during an
+auction shall only be able to relase the money for the winning bidder and not
+for the others.  On the other hand, both, sellers and bidders should be able
+provide evidence to the exchange and auditor if the other party wasn't honest,
+f.e. if the winning bidder hasn't released the money.
+
+
+
+Proposed Solution
+=================
+
+We propose a the following endpoints
+
+
+- ``POST /escrows/$ESCROW_ID/register``:  Register an escrow account under the
+  provided EdDSA public key ``$ESCROW_ID``.  The required parameters are:
+
+  - a starttime
+  - an endttime
+  - an interval ``[m, M]`` of minimum and maximum amounts, where ``M`` can 
also be ``∞``.
+
+- ``GET /escrows/$ESCROW_ID``: Return the terms of the escrow and the current
+  list of depositor IDs.
+
+- ``POST /escrows/$ESCROW_ID/deposit/$DEPOSIT_ID``: Deposit a specific amount
+  with a particular list of coins. The required parameters are:
+
+  - the amount ``a`` to be deposited (must lie in ``[m, M]``)
+  - the list of coins to be used for the deposit (the sum of the values must be
+    at least ``a``)
+  - signatures from each coin over the SHA512 hash of the amount ``a``, the
+    ``$DEPOSIT_ID`` and the ``$ESCROW_ID``.
+
+  The ``$DEPOSIT_ID`` is the SHA512 hash over all the coins.
+  
+
+- ``POST /escrows/$ESCROW_ID/claim/$DEPOSIT_ID``:  The owner of the private 
key for
+  ``$ESCROW_ID`` can claim the deposited coins.  It has to provide 
+  
+  - the particular amount ``a'`` to be claimed
+  - the list of coins to be claimed from the deposit
+  - signatures over the SHA512 hash of the amount ``a'``, ``$ESCROW_ID`` and
+    the ``$DEPOSIT_ID``, signed by each coin
+
+The following diagram gives an overview of the flow:
+
+.. image:: _svgs/escrow-flow.svg
+
+
+When the ``endtime`` of an escrow has arrived on the exchange, an amount ``a``
+of a deposit of amount ``b ≥ a`` can be claimed by the originator of the escrow
+account.  Only *one* succesfull claim can be made for a particular escrow
+account.  After a claim has been made, the remaining coins in the remaining
+deposits are released by the exchange.  If no claim is made within a specific
+time inverval after ``endtime``, all coins of *all* deposits are released.
+
+The ``GET /escrows/$ESCROWS_ID`` allows to depositors and auditors to confirm
+their deposit.  It also allows depositors to compare the list with their
+mentioning at other services, such as the list of bidders in an online auction.
+
+TODOs: Specify
+
+- data structures
+- signatures
+- return values
+- errors
+- terms of contracts
+- default time intervals
+
+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/_svgs/escrow-flow.svg 
b/design-documents/_svgs/escrow-flow.svg
new file mode 100644
index 0000000..cd0b2c9
--- /dev/null
+++ b/design-documents/_svgs/escrow-flow.svg
@@ -0,0 +1 @@
+<svg aria-labelledby="chart-title-graph-div chart-desc-graph-div" role="img" 
viewBox="-111 -10 1273 1070" style="max-width: 1273px;" height="1070" 
xmlns="http://www.w3.org/2000/svg"; width="100%" id="graph-div"><title 
id="chart-title-graph-div"></title><desc 
id="chart-desc-graph-div"></desc><style>#graph-div {font-family:"trebuchet 
ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#graph-div 
.error-icon{fill:#552222;}#graph-div 
.error-text{fill:#552222;stroke:#552222;}#graph-div .edg [...]
diff --git a/design-documents/index.rst b/design-documents/index.rst
index 11cf13f..f0c1d3e 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -35,4 +35,5 @@ and protocol.
   024-age-restriction
   025-withdraw-from-wallet
   026-refund-fees
+  028-proof-of-escrow
   999-template

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.