path: root/design-documents
diff options
authorFlorian Dold <>2021-04-19 14:42:13 +0200
committerFlorian Dold <>2021-04-19 14:42:13 +0200
commitfb9a5e4d286058d4ce4ad82949bdc0455c6e5d5d (patch)
tree2759455d1b0864c92f19ab9b80c3e9a29d974a52 /design-documents
parentca6c47313cb010448a6881a94d183cad1ed94337 (diff)
pass over DD13
Diffstat (limited to 'design-documents')
1 files changed, 115 insertions, 6 deletions
diff --git a/design-documents/013-peer-to-peer-payments.rst b/design-documents/013-peer-to-peer-payments.rst
index 4bdd492..5797a72 100644
--- a/design-documents/013-peer-to-peer-payments.rst
+++ b/design-documents/013-peer-to-peer-payments.rst
@@ -61,9 +61,9 @@ New Terminology
* An ``account`` is a non-expiring reserve for which entity knowing the
reserve private key has completed a KYC procedure sufficient to enable
receiving income under that address.
-* A ``pouch`` is a public-private key pair where the public key is
+* A ``purse`` is a public-private key pair where the public key is
an exchange address from which any owners of an account
- can pick up an amount left at a ``pouch`` assuming they know the pouches
+ can pick up an amount left at a ``purse`` assuming they know the purse
private key.
* A ``wad`` is an exchange-to-exchange wire transfer that wires money
into a group of accounts at the target exchange.
@@ -84,7 +84,7 @@ Account creation and withdrawal
target address (for which the payee knows the corresponding
account private key).
2. When withdrawing from an account, the exchange first checks if the
- customer has satisfied the KYC requirements. If not, the consumer
+ customer has satisfied the KYC requirements. If not, the customer
is redirected to a Web page where they can perform the necessary
KYC operation.
3. For this, the exchange wire gateway is extended with a request to
@@ -203,6 +203,72 @@ Payment into known account at a remote exchange
is needed to lookup the **wad** data at remote exchanges.
+C2C Payment Metadata
+The standard Taler Customer-to-Merchant payments always use a contract terms
+JSON object to record the modalities of the payment and the resulting
+obligations of a successful payment.
+The contract terms concept does not directly carry over to
+C2C payments, because:
+* Either party may initiate the payment
+* The payee does not have a merchant public key, and
+ at the time of payment initiation, the payee account might not yet
+ be known.
+* There is no nonce that the customer generates and uses to prove that they
+ uniquely "own" the contract terms.
+* There is no negotiation of trusted auditors / exchanges possible or necessary.
+Metadata for C2C payments can be exchanged in two ways:
+1. Inline, as part of the payment request / payment offer.
+2. As an annotation on the purse, encrypted with the purse's public key. The
+ exchange may charge for storing the annotation.
+ In case of a "payment request purse", the fee should be
+ taken from an account provided by the payee (which may even
+ offer a limited number of free P2P payment initiations per time period).
+ In case of a "payment offer purse", the fee should be taken from the
+ coins deposited into the purse.
+Cross-exchange C2C payment request:
+* Bob borrowed 15 Eur from Alice to buy a train ticket. A few days later,
+ Alice wants her money back. She creates a request for payment in her wallet.
+ The wallet creates a pouch for 15 Eur at the only exchange that Alice is currently
+ using. The wallet shows her a
+ ``taler://payment-request/{EXCHANGE_URL}/{POUCH_PRIV}?i=Please+pay+me+Bob``
+ link that she can share with Bob. Bob receives the link and opens it with
+ his Taler wallet. Bob is using a different EUR exchange than Alice. Bob's
+ wallet makes a ``/wad`` request to his own exchange. Shortly after, Alice's
+ exchange receives the wad from Bob's exchange, and credits the money into
+ Alice's pouch.
+ * How does Bob find out if Alices exchange supports a wad transfer from
+ Bob's exchange?
+ * How does Bob get a "receipt" to prove that he paid Alice? Is some signature
+ from Bob's exchange enough, or should Bob also request a signature for Alice's
+ exchange once the money has arrived? Bob's wallet could poll
+ the purse at Alice's exchange for a receipt.
+Cross-exchange payment offer:
+* Carol wants to send some money to Dave as a birthday gift. Carol knows that
+ Dave is using Taler, but she doesn't know which exchange he is using. She
+ opens her Taler wallet and initiates a P2P payment. She sends the
+ ``taler://payment-offer/{EXCHANGE_URL}/{POUCH_PRIV}?i=Happy+Birthday+from+Alice`` in an e-mail to Dave.
+ Dave opens they link in the e-mail with his Taler wallet.
+ Since Dave is using a different exchange than Alice, Dave's wallet
+ issues a ``/wad`` request to Alice's exchange. Shortly after,
+ Dave's exchange receives the wad, and credits Dave's account with the money.
Additional considerations
@@ -257,16 +323,59 @@ The overall changes required are not small:
* New exchange table(s) required to store inbound amounts by account.
Likely 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
+* New exchange table for purses required (for remote p2p payments).
+* New exchange logic required to make ``transfers`` requests for purses
(another separate process).
* New ``/account/$ACCOUNT_PUB/kyc`` endpoint required.
* New ``/purse/$PURSE_PUB/merge`` endpoint required.
* Additional tables to be verified by the auditor.
-* ``taler-exchange-wirewatch`` needs to support receiving pouch closures
+* ``taler-exchange-wirewatch`` needs to support receiving purses closures
and exchange-to-exchange wire transfers with WTIDs.
Aside from implementation complexity, the solution has the following drawbacks:
* If a p2p payment failed (say the receiver lost the account private key),
the customer's money can be forfeit.
+Q / A
+* Q: Why are direct payments into accounts allowed?
+ * A: Direct payments into accounts are used by the customer
+ to fund the expenses for using the account. They should not
+ be used for payments between customers, as contract terms for
+ the ``/deposit`` of coins can't be negotiated. Furthermore,
+ the sender of the payment can't be sure that the account of
+ the sender is still valid.
+* Q: Who "owns" a purse? The payer of payee?
+ * Both. Ownership is shared. Either the payer issues
+ a refund on the purse, or the payee claims it by merging
+ it with one of their accounts.
+* Q: Are purses created with a pre-determined "capacity"?
+ * A: Yes. Otherwise there would be weird failure modes when the payee
+ merges the purse before the payer fully deposited into it.
+* Q: Are account public keys considered private or public data?
+ * A: Private. Making it public would make it too easy
+ to accidentally send payments that nobody can receive, because
+ the account is wrong/lost. Furthermore, making the account
+ public makes it easy to receive unsolicited payments without
+ consent from the payee. Since Taler should be as cash-like
+ as possible, we might want to avoid that, especially
+ for payees who aren't merchant.
+* Q: Why do merchant payments not use purses?
+ * A: Refunds aren't possible with purses, the customer can't prove that
+ they own the contract terms (contract terms claiming isn't interactive).
+ * All these issues could be addressed though. But that
+ would be a major "Taler 2.0 / 3.0" protocol change