Design Doc 013: Customer-to-Customer Payments
This design document proposes an extension of the Taler protocol that allows
payments from customer-to-customer without a merchant.
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).
* 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)
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
A complete solution for customer-to-customer payments consists of three
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
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.
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
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
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
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.
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
The exchange needs a new endpoint for this:
Note that the bound reserve might exist at a different exchange.
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
* 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
* 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.
* 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
* 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)?
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
* 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.