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.)