diff options
-rw-r--r-- | design-documents/028-proof-of-escrow.rst | 88 |
1 files changed, 4 insertions, 84 deletions
diff --git a/design-documents/028-proof-of-escrow.rst b/design-documents/028-proof-of-escrow.rst index 402ddd2c..93950c2a 100644 --- a/design-documents/028-proof-of-escrow.rst +++ b/design-documents/028-proof-of-escrow.rst @@ -3,15 +3,12 @@ DD28: Proof of escrow in the exchange .. note:: - This design document is currently a draft, it - does not reflect any implementation decisions yet. - + The previous version of this design document has been retracted. 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. +We will propose here an extension to the exchange that implements an escrow policy. Motivation @@ -21,93 +18,16 @@ 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 release 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. - - +TODO 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* successful 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 interval 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 +TODO Alternatives ============ |