path: root/design-documents/013-peer-to-peer-payments.rst

Design Doc 013: Customer-to-Customer Payments
#############################################

Summary
=======

This design document proposes an extension of the Taler protocol that allows
payments from customer-to-customer without a merchant.

Motivation
==========

To be usable as an electronic payment system with cash-like properties,
customers should be able to transfer money between themselves without
needing to setup anything beyond their wallet(s).


Requirements
============

* The control data for customer-to-customer payments should be small
  enough to fit into a QR code or short message.  No other
  direct communication channel between payer and payee should be required.
* This customer-to-customer payment must be possible without trusting the other
  party beyond the point where the money has been received by the payee.  Thus,
  sharing of coin private keys is not sufficient, we need transactional semantics
  resulting in exclusive control over the funds by the recipient.
* The P2P payment protocol must not allow users to circumvent income
  transparency.  That is, each P2P transaction must be visible
  on a KYCed transaction ledger (such as a bank account).
* The money received via a P2P payment must be usable for
  further Taler payments with minimal delay.

Proposed Solution (CG)
======================

.. note::

   The notion of ``pouch`` used in this proposal differs completely from
   the notion of ``pouch`` in the Dold approach.  In this proposal,
   pouches are used to represent aggregated wire transfers combining
   multiple p2p payments between pairs of exchanges.  WE NEED A BETTER
   WORD.

A complete solution for customer-to-customer payments consists of three
separate parts:

1. The payee generates a ``payto://taler/$EXCHANGE_BASE_URL/$RESERVE_PUB``
   target address for which the payee knows the corresponding reserve
   private key.  The parties must also create a fixed-form contract.
   The the contract must specify the amount, a nonce, the reserve public key,
   and may include further a **forgettable** details like a subject.
   The required information should still be sufficiently compact for a
   small QR code or NFC transmission.
2. The payer then performs an ordinary ``/deposit`` operation.
3. The exchange detects the use of the ``taler`` wire method, and if the base
   URL of the target exchange differs, initiates a wire transfer to the
   ``/wire`` endpoint of the target exchange.  For this wire transfer,
   the wire transfer subject is set to provide the exchange base URL and
   a WTID as with other outgoing wire transfers. Aggregation is possible.
   An inbound wire transfer of this type creates a **pouch**.
4. If the (aggregated) wire transfer fails (say the
   ``/wire`` endpoint does not resolve to a valid bank account, or
   the target exchange closed the pouch), the originating exchange
   automatically creates a full refund for the deposit (refund fees still
   apply).

   .. note::

      While the refund **fee** can be reused, these types of refunds
      are not approved by a merchant's signature. Thus, we will need
      a new message type in the coin history to represent these events.

5. When the exchange is requested to provide information about
   aggregated transfers under the WTID, it provides the contract's
   512-bit hash and the amount.
6. The exchange wire gateway is extended with a request to check the KYC
   status of a customer based on a RESERVE_PUB.  Possible replies are
   in-progress, failed and succeeded.  Failed KYCs ultimately result in
   pouches being closed.  An in-progress status should be accompanied with
   information how the customer may complete the KYC check.

   .. note::

      If a target exchange closes a pouch, the closing fee
      applies for every non-merged contract hash associated with the pouch.
      Closing a pouch requires the target exchange to perform
      a wire transfer for each (non-merged) contract hash, using
      a truncated 256-bit contract hash for the wire transfer subject.
      That way, the originating exchange can refund the respective
      coins.

7. A new exchange endpoint allows wallets to request a KYC for a
   RESERVE_PUB.  Such a request may include the requirement to pay
   a KYC fee.  The KYC fee may be charged to that reserve (if it exists),
   or could be waved if the reserve was established via a wire transfer
   from a partner bank.
8. When an exchange receives a wire transfer with an exchange base URL
   and a WTID (instead of a RESERVE_PUB), it performs a request to the
   ``/transfers/$WTID`` API of the originating exchange to obtain a
   list of contract hashes.
9. The payee can try to merge incoming payments into a KYC'ed reserve by
   POSTing to a new ``/reserve/$RESERVE_PUB/merge`` endpoint.
   The POSTing must include a signature by the reserve private key
   over the 512-bit contract hash and the (maximally ``forgotten``)
   contract (so only nonce, amount and RESERVE_PUB are in the clear).
   By doing so, the receiver demonstrates knowledge of the full contract
   (the ``forgotten`` fields provide privacy for details irrelevant to
   the exchange).

   .. note::

      A possible optimization is to forgo including the reserve public key
      field in the transmitted exchange contract, as it is already in the URL;
      however, the RESERVE_PUB MUST be in a well-defined
      field of the contract when hashing the contract.

10. If the exchange has received a matching inbound wire transfer, it adds the
   respective balance to the reserve's balance, allowing the KYC'ed customer
   to withdraw the funds.  The new ``merge`` endpoint should also allow
   long-polling. Note that long-polling should be limited to short durations,
   as inbound transfers via ``taler-exchange-wirewatch`` cannot cause the long
   polling to be resumed, only transfers within the same exchange can benefit
   from long polling acceleration.


Proposed Solution (Dold)
========================

A complete solution for customer-to-customer payments consists of three
separate parts:

1. The mechanism whereby coins are deposited into some address
   associated with the receiver.
2. A mechanism to ensure that the receiver of a customer-to-customer
   payment has undergone a KYC check.
3. If more than once exchange is involved, there must be a real-time
   settlement layer between involved exchanges.


Customer-to-customer Deposits
-----------------------------

The payer deposits coins (via the existing /deposit protocol) into a
``payto://taler-p2p-pouch/$POUCH_PUB`` address.  The exchange handles this
deposit by internally transfering the money to a "pouch" identified by the
pouch public key (``$POUCH_PUB``).

Once a pouch has been funded, the payer can additionally attach some meta-data
(e.g. remittance information) to the pouch.

The payee claims the payment by transfering funds from the (anonymous) pouch
into a KYCed reserve (also called a "bound reserve", as it is bound to
personally identifying information of the owner") that belongs to the payee.

Alternatively the payee can also choose to receive the funds on their bank
account, simply by providing their bank account (as a payto URI) in the pouch
claiming request.

The exchange needs a new endpoint for this:

::

  POST {exchangeBaseUrl}/pouches/$POUCH_PUB/claim
  Request:
  {
    bound_reserve_exchange: "..."
    bound_reserve_pub: "..."
  }
  Response:
  {
    amount: "...",
  }

Note that the bound reserve might exist at a different exchange.

Bound Reserves
--------------

A bound reserve is a reserve that is associated with personally identifyable
information of the customer.

A bound reserve is created by depositing small cover fee into it and then going
through an exchange-specific KYC process.  If an exchange is operated by a bank
that a customer already has a business relationship with, the bank might
automatically provide a bound reserve for that customer.

To prevent abuse of bound reserves (in the form of multiple parties exchanging
funds via shared access to a bound reserve), the following measures can be
taken:

* Creation of additional bound reserves per customer can
  be discouraged by asking for higher fees.
* The global transaction volume of one customer can be easily
  determined by authorities, which can then trigger further audits
  of the customer
* As a technically expensive but more water-tight measure, normal
  withdrawals from bound reserves could be disallowed.  Instead,
  a modified refresh protocol could ensure that whoever has knowledge
  of the reserve private key can also learn the private keys
  of coins withdrawn from that reserve.

Bound reserves could also be used to remove Taler's "one-hop withdrawal
loohole".

Alternatives
============

* The payer could directly give deposit permissions to the payee.
  This has two problems:

  1. The payer doesn't know the wire details of the payee.
     Thus we would need to introduce some "wildcard deposit permission",
     where the exchange allows any wire details on ``/deposit``.
  2. The payment information would be rather large, making it difficult
     to transfer via a QR code or short text message.


Drawbacks (Dold)
================

* pouches introduce new 'pouch' loophole, which could allow a customer
  to collect 'income' into a pouch and then 'pay' a merchant by allowing
  the merchant to empty the pouches.
* The exchange needs to be extended with customer-to-customer pouches (probably
  the easy part) and bound reserves (possibly falls into the responsibility of
  LibEuFin).
* error handling (failure in exchange-to-exchange wire transfer,
  failure to drain reserve, etc) is unclear from the proposal. Can money get
  lost in the case of failures (bad keys, failed KYC)?



Drawbacks (Grothoff)
====================

The overall changes required are not small:

* New KYC fee required in ``/keys`` endpoint (similar to closing and wire fees),
  requires extensive work across toolchain (offline signature, etc.)
* New ``taler`` wire method needs special case to possibly bypass
  (same exchange scenario, with long-poll trigger) the usual aggregation logic.
* New exchange table(s) required to store inbound amounts by contract hash.
  Maybe two tables, one for local exchange p2p and one for remote exchange p2p
  payments.
* New exchange table for pouches required (for remote p2p payments).
* New exchange logic required to make ``transfers`` requests for pouches
  (another separate process).
* New ``/reserve/$RESERVE_PUB/kyc`` endpoint required.
* New ``/reserve/$RESERVE_PUB/merge`` endpoint required.
* New type of reserve history entries required (``merge``).
* Additional tables to be verified by the auditor.
* ``taler-exchange-closer`` needs additional logic to ``close`` pouches.
* ``taler-exchange-wirewatch`` needs to support receiving pouch closures
  and exchange-to-exchange wire transfers with WTIDs.
* A new type of ``refund`` (better name needed) is required to handle
  coins re-gaining value from closed pouches.

Aside from implementation complexity, the solution has the following drawbacks:

* We have no good way to determine that a p2p payment failed and that the
  wallets should try to refresh the spent coin to get the ``refund``.
  Wallets will have to basically 'probe' for a plausible time period to
  recover funds from failed p2p payments.  Alternatively, we may create a
  special URI that the payee wallet will generate to inform the payer
  about failed p2p payments. Alas, that seems to not be very user-friendly.