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.