013-peer-to-peer-payments.rst (53909B)
1 .. _dd-13: 2 3 DD 13: Wallet-to-Wallet Payments 4 ################################ 5 6 :Design status: Accepted 7 :Implementation status: Implemented 8 :DD shepherd: TBD 9 :Historical contributors: Florian Dold, Christian Grothoff, Sebastian 10 :First published: 2021-01-18 11 :Last substantive change: 2022-06-03 12 :Implementation evidence: exchange (2022-03-20, 2022-03-24), taler-typescript-core (2022-07-12, 2022-08-23) 13 :Normative references: :doc:`../core/api-exchange`, :doc:`../wallet/wallet-core`, :doc:`037-wallet-transactions-lifecycle` 14 15 Summary 16 ======= 17 18 .. note:: 19 20 This document includes historical protocol sketches followed by later 21 refinements. The current exchange and wallet APIs are authoritative. 22 23 This design document proposes an extension of the Taler protocol that allows 24 payments from wallet-to-wallet without a merchant. 25 26 27 Motivation 28 ========== 29 30 To be usable as an electronic payment system with cash-like properties, 31 customers should be able to transfer money between themselves without 32 needing to setup anything beyond their wallet(s). 33 34 This will be used for payments via e-mail and other messaging apps, as well as 35 possibly for transfers via NFC/QR code between mobile phones. 36 37 Invoice Flow User Experience 38 ---------------------------- 39 40 .. graphviz:: 41 42 digraph invoice { 43 ranksep="0.5" 44 { rank = same; "inbox"; "begin"; } 45 { rank = same; "sending"; "receiving2"; } 46 { rank = same; "receiving"; "paying"; } 47 { rank = same; "mid"; "midbox"; } 48 { rank = same; "body"; "amount"; } 49 begin [label="Payer Inbox",shape=box]; 50 body [label="compose\nE-mail message"]; 51 amount [label="specify\ninvoice details"]; 52 receiving [label="receiving...",shape=diamond]; 53 sending [label="transmitting...",shape=diamond]; 54 mid [label="Payee Inbox",shape=box]; 55 notified [label="Notification:\npayment received"]; 56 end [label="Payee Inbox",shape=box]; 57 begin -> body [label="(1) new"]; 58 body -> amount [label="(2) attach invoice"]; 59 amount -> body [label="(3) Ok"]; 60 body -> sending [label="(4) send"]; 61 sending -> mid [style=dashed]; 62 mid -> receiving [style=dashed]; 63 receiving -> notified [style=dashed]; 64 notified -> end [label="(9) Acknowledge"]; 65 inbox [label="Payer Inbox",shape=box]; 66 receiving2 [label="receiving...",shape=diamond]; 67 midbox [label="Payer Inbox",shape=box]; 68 open [label="message with\nattached invoice"]; 69 confirm [label="review invoice"]; 70 paying [label="paying...", shape=diamond]; 71 paid [label="message with\npaid invoice"]; 72 finbox [label="Payer Inbox",shape=box]; 73 inbox -> receiving2 [style=dashed]; 74 receiving2 -> sending [label="Internet\n(pEp)",style=dashed,dir=back]; 75 receiving2 -> midbox [style=dashed]; 76 midbox -> open [label="(5) select message"]; 77 open -> confirm [label="(6) view invoice"]; 78 confirm -> paying [label="(7) pay"]; 79 paying -> paid [style=dashed]; 80 paid -> finbox [label="(8) back"]; 81 paying -> receiving [style=dashed, label="Internet\n(Taler)"]; 82 } 83 84 Donation Flow User Experience 85 ----------------------------- 86 87 .. graphviz:: 88 89 digraph donation { 90 ranksep="0.5" 91 { rank = same; "inbox"; "begin"; } 92 { rank = same; "sending"; "receiving2"; } 93 { rank = same; "body"; "amount"; } 94 { rank = same; "mid"; "midbox"; } 95 { rank = same; "accepting"; "timeout"; "receiving"; } 96 begin [label="Donor Inbox",shape=box]; 97 body [label="compose\nE-mail message"]; 98 amount [label="specify\npayment details"]; 99 receiving [label="receiving...",shape=diamond]; 100 timeout [label="timeout...",shape=diamond]; 101 sending [label="transmitting...",shape=diamond]; 102 mid [label="Donor Inbox",shape=box]; 103 notified [label="Notification:\npayment confirmed"]; 104 notified2 [label="Notification:\npayment refunded"]; 105 end [label="Donor Inbox",shape=box]; 106 begin -> body [label="(1) new"]; 107 body -> amount [label="(2) attach payment"]; 108 amount -> body [label="(3) Ok"]; 109 body -> sending [label="(4) send"]; 110 sending -> mid [style=dashed]; 111 mid -> receiving [style=dashed]; 112 receiving -> notified [style=dashed]; 113 mid -> timeout [style=dashed]; 114 timeout -> notified2 [style=dashed]; 115 notified -> end [label="(9a) Acknowledge"]; 116 notified2 -> end [label="(9b) Acknowledge"]; 117 inbox [label="Recipient Inbox",shape=box]; 118 receiving2 [label="receiving...",shape=diamond]; 119 midbox [label="Recipient Inbox",shape=box]; 120 open [label="message with\nattached payment"]; 121 confirm [label="accept payment?"]; 122 accepting [label="accepting...", shape=diamond]; 123 paid [label="message with\naccepted payment"]; 124 finbox [label="Recipient Inbox",shape=box]; 125 inbox -> receiving2 [style=dashed]; 126 receiving2 -> sending [label="Internet\n(pEp)",style=dashed,dir=back]; 127 receiving2 -> midbox [style=dashed]; 128 midbox -> open [label="(5) select message"]; 129 open -> confirm [label="(6) review payment details"]; 130 confirm -> accepting [label="(7) yes"]; 131 accepting -> paid [style=dashed]; 132 paid -> finbox [label="(8) back"]; 133 accepting -> receiving [style=dashed, label="Internet\n(Taler)"]; 134 } 135 136 Requirements 137 ============ 138 139 * The protocol must permit transacting arbitrary amounts in any currency, 140 as long as the exchanges involved support the necessary purse and partner 141 operations. 142 * The control data for wallet-to-wallet payments should be small 143 enough to fit into a QR code or short message (so ideally less than 64 bytes). 144 * No other direct communication channel between payer and payee should 145 be required. 146 * The wallet-to-wallet payment must be possible without trusting the other 147 party beyond the point where the money has been received by the payee. Thus, 148 sharing of coin private keys is not sufficient, we need transactional semantics 149 resulting in exclusive control over the funds by the recipient. 150 * The wallet-to-wallet payment protocol must not allow users to circumvent income 151 transparency. That is, each wallet-to-wallet transaction must be visible 152 on a KYCed transaction ledger (such as a bank account). 153 * The money received via a wallet-to-wallet payment must be usable for 154 further Taler payments with minimal delay (after KYC). 155 * It must still be possible to associate payments with a contract that is 156 effectively (alas not necessarily directly) signed by both parties: 157 the payer with the coin private keys, and the payee with their KYC'ed 158 account private key. 159 * The contract must be able to satisfy laws like the German TSE law, 160 which implies that the payer must be able to obtain a payment receipt. 161 * Two payment scenarios must be possible: (1) one where the payee first 162 transmits a proposal to the payer (request-to-pay) that the payer 163 accepts by making the payment, and (2) completely uni-directional 164 payments where the payer includes a proposal with the payment and the 165 payee accepts the proposal by taking the offered payment. 166 * If the payment fails (i.e. the receiver refuses to accept the money 167 or the message is lost), the payer must automatically recover the 168 funds (minus applicable fees) without the need for further communication. 169 * If funds flow back to the payer due to an aborted payment, it must be 170 provable for the payer that these funds were not income but merely an aborted 171 transaction. Furthermore, in this case, no KYC should be required from the 172 payer. 173 * If a payment would partially succeed, i.e. because the payer inadvertently 174 used some double-spent coins and some valid coins, this must fail before the 175 uni-directional communication and be correctable payer-side. In other words, 176 the actual payment must be atomic. 177 * The usual properties of Taler (everything auditable, unlinkability, 178 high-performance in terms of CPU, bandwidth, latency, storage 179 requirements, and the ability to levy fees on every operation that 180 is costly for the exchange) need to be preserved. 181 * The system must handle the case where a customer no longer intends to 182 use the KYCed account (due to disuse, death, or key compromise). 183 184 185 186 New Terminology 187 =============== 188 189 * An ``account`` is a non-expiring reserve for which entity knowing the 190 reserve private key has completed a KYC procedure sufficient to enable 191 receiving income under that address. 192 * A ``purse`` is a public-private key pair where the public key is 193 an exchange address from which any owners of an account 194 can ``merge`` the amount left at a ``purse`` into their 195 account balance assuming they know the purse private key. 196 * A ``wad`` is an exchange-to-exchange wire transfer that wires money 197 into a group of accounts at the target exchange. 198 199 200 Proposed Solution 201 ================= 202 203 Principles 204 ---------- 205 206 * Purses are ephemeral and only serve for one transaction. 207 * The purse's transaction amount is fixed when the purse is created, and 208 specified together with the maximum deposit fee acceptable to the payee. 209 Deposit fees exceeding this limit must be paid by the payer. 210 * Each purse is associated with a contract terms hash and an expiration date. 211 * The contract is optionally stored encrypted at the exchange. 212 The contract must be encrypted to the purse private key. 213 An additional ephemeral public key (for DH encryption) should be 214 part of the POSTed payload. 215 * The exchange deletes the encrypted contract at this expiration date. 216 * The exchange may limit the encrypted contract size and storage duration. 217 * Either payer or payee can create the purse and associate it with the contract. 218 * By merging the purse into the account, the payee accepts the contract. 219 * By paying the purse to the designated amount, the payer accepts the contract. 220 * Until the purse is fully paid, the payer can abort the payment. 221 * The exchange may charge a **purse fee** for managing the purse, but we 222 want most scenarios to not require it to be effectively charged. 223 * By associating a purse with an account upon creation, the purse fee can be 224 made optional for account holders as long as the number of purses created 225 per account is below a configurable threshold. 226 * By charging the purse fee only in case the payee did **not** merge the 227 purse into their account, the purse fee can be limited for payers to 228 the case where they are receiving a refund. 229 230 231 W2W Payment Metadata 232 -------------------- 233 234 The standard Taler Customer-to-Merchant payments always use a contract terms 235 JSON object to record the modalities of the payment and the resulting 236 obligations of a successful payment. 237 238 The contract terms concept does not directly carry over to W2W payments, 239 because: 240 241 * Either party may initiate the payment. 242 * The payee does not have a merchant public key, and 243 at the time of payment initiation, the payee account might not yet 244 be known. 245 * There is no nonce that the customer generates and uses to prove that they 246 uniquely "own" the contract terms. 247 * There is no negotiation of trusted auditors / exchanges possible. 248 249 As a result, some of the existing fields of the contract terms no longer apply 250 to wallet-to-wallet payments. 251 252 Contract metadata for W2W payments can be exchanged in three ways: 253 254 1. Inline, as part of the payment request / payment offer. In this case, 255 both parties are already aware of the contract's contents and 256 the exchange's contract exchange facility is simply not used. 257 2. The payee can create a **purse** and immediately associate it with 258 an **account** by sending a signed **merge** request together with 259 the (encrypted) contract. 260 261 a. The purse creation request created by the payee must include a 262 signature with the account private key of the payee signing the purse 263 public key and the hash of the contract, thereby affirming that 264 the contract was pre-approved by the account owner. 265 b. The exchange may wave the purse fee for a certain number of 266 active purses per account. Additional purses can be purchased 267 by paying the **purse fee**. 268 3. The payer can store a contract with the exchange by POSTing 269 an encrypted contract to the exchange as part of creating a **purse**. 270 271 a. The exchange charges the **purse fee** to payers for purses that 272 are refunded after not being **merged**. 273 b. When paying into a purse, the coin signature includes the purse 274 public key, the contract hash and the desired expiration date 275 (how long a merge is allowed). 276 c. Payment offers are not allowed if the amount transacted is below 277 the purse fee. 278 d. The exchange auto-refunds coins in **purses** with deposits 279 matching expired contracts. 280 281 .. note:: 282 283 Expiry or DELETEing a purse restores each coin's full contribution, 284 including its deposit fee. The exchange signs a ``PURSE-REFUND`` 285 coin history entry with a zero refund fee. 286 287 288 Account creation 289 ---------------- 290 291 An account is simply a reserve that has been subjected to 292 KYC. A reserve that has seen a purse merged into it must 293 be upgraded to an account before further withdraw (or close) 294 operations are allowed. The usual closure deadline for a 295 reserve is extended to the KYC deadline. 296 297 1. The payee generates a reserve key, which also yields a 298 ``payto://taler/$EXCHANGE_BASE_URL/$RESERVE_PUB`` 299 target address (for which the payee knows the corresponding 300 reserve private key). 301 2. When withdrawing from a reserve that has experienced 302 merge operations and thus must be an account, the exchange 303 first checks if the customer has satisfied the KYC requirements. 304 If not, the customer is redirected to a Web page where they 305 can perform the necessary KYC operation. 306 3. For this, the exchange wire gateway is extended with a request to 307 check the KYC status of a customer based on an ``RESERVE_PUB``. 308 Possible replies are ``in-progress`` and ``succeeded``. 309 An ``in-progress`` status should be accompanied with 310 information how the customer may complete the KYC check. 311 4. A new exchange endpoint ``/reserves/$RESERVE_PUB/kyc`` 312 allows wallets to request a KYC for a 313 ``$RESERVE_PUB``. Such a request may include the requirement to pay 314 a **KYC fee**. 315 The KYC fee may be charged to the reserve (a sufficient 316 balance can be provided by the wallet by creating a purse 317 and merging the purse with the reserve, if needed), 318 or could be waved if the reserve was established via a wire transfer 319 from a partner bank where KYC is free. For this, the Wire 320 gateway API is extended with a flag that informs the exchange 321 that the incoming wire transfer implies a free KYC check. 322 5. If the account owner fails to perform the KYC check, all funds 323 in a reserve remain inaccessible. After a configurable duration, 324 the funds may be considered forfeit and become the property of 325 the exchange where the reserve is located. 326 6. The exchange may charge an annual **account fee**, and can 327 close accounts where the account balance is insufficient to 328 cover the account fee. 329 330 331 Withdrawing from accounts 332 ------------------------- 333 334 1. When requesting an account's history (which can get quite long), 335 the exchange only returns the last 3 months of data. Requesting 336 the full history requires paying an **account history fee** 337 (which is not done via a 402, but simply charged to the account 338 when requested; full account histories for accounts with an 339 insufficient balance cannot be requested -- except of course 340 the wallet could simply top up the account balance first, see below). 341 2. If the exchange has **merged** a **purse** into an account, or 342 received an inbound wire transfer from a **wad** matching the 343 account (see below), it adds the respective amount(s) to the 344 account's balance, allowing the KYC'ed customer to withdraw the funds, 345 similar to withdrawals from a reserve. 346 3. The account history endpoint should also allow long-polling. 347 Note that long-polling should be limited to short durations, 348 as inbound transfers via ``taler-exchange-wirewatch`` cannot cause the long 349 polling to be resumed, only transfers within the same exchange can benefit 350 from long-polling acceleration. 351 352 353 Account deletion 354 ---------------- 355 356 1. A reserve owner can delete a reserve by signing a deletion message 357 with the reserve private key. 358 2. This basically resets the KYC data at the exchange, preventing 359 further use of the account. This is helpful in case a user is 360 concerned about having 361 accidentally disclosed the reserve private key to a third party. 362 3. If funds remain in the reserve, the exchange will close the 363 reserve and wire the funds to the associated bank account. 364 If no bank account is associated with the reserve, 365 an error message is generated instead. The 366 user can pass an extra override parameter to delete reserves 367 even if they still contain funds. 368 4. A related endpoint should exist for the exchange operator, possibly 369 using messages signed with a new exchange management key. 370 This could be useful in case customers die or are otherwise 371 in need for manual intervention that requires an account to 372 be deleted. In this case, 373 remaining funds in the account should be wired to a bank account 374 designated in the message with the management signature. The audit 375 report should contain a special note for all of these types of 376 account deletions. 377 378 379 380 Payment offers 381 -------------- 382 383 In this protocol variant, the payer is initiating the process. 384 385 1. The payer creates a **purse** by computing a public-private key pair. 386 2. The payer POSTs to the ``/purses/$PURSE_PUB/create`` endpoint to create the 387 purse, deposit coins and optionally upload the encrypted contract terms. 388 The deposit signatures should use ``payto://taler/$PURSE_PUB`` 389 as the target address and signing over the ``$CONTRACT_HASH`` as 390 usual in deposit operations. Note that the lack of a hostname 391 indicates that the target address is a local purse. 392 3. The payer shares the contract private key and the base URL 393 of the exchange where the purse was created with the payee. 394 This is represented by a 395 ``taler://pay-push/$BASE_URL/$CONTRACT_PRIV`` URI in the implemented 396 protocol. 397 The chapter on ``Refinements`` below clarifies why this 398 step is not quite OK and was modified when implementing the design. 399 4. The payee uses ``/contracts/$CONTRACT_PUB`` to retrieve the encrypted 400 contract and ``/purses/$PURSE_PUB/deposit`` to retrieve the purse status, 401 including its balance. 402 5. The payee's wallet must ensure that either: 403 404 a. The purse has an attached encrypted contract terms, the contract 405 terms can be decrypted and are valid, and their hash matches the contract 406 terms hash of the purse. 407 b. The wallet received detached contract terms, and their hash matches 408 contract terms of the purse. 409 410 If neither case applies, the payee's wallet must reject the payment. 411 6. The payee can then POST to ``/purses/$PURSE_PUB/merge`` a 412 request signed by the merge private key to **merge** the 413 funds into an account. A second signature must be provided 414 by the account private key, signing the ``$CONTRACT_HASH`` thereby 415 affirming that the payee accepted the contract. 416 The account is of the form ``payto://taler/$EXCHANGE_BASE_URL/$ACCOUNT_PUB``. 417 7. Processing continues depending on the location of the account: 418 419 a. If the ``$EXCHANGE_BASE_URL`` matches the local exchange, then 420 the exchange processes the **merge** request akin to the logic 421 for payments into known accounts, as detailed above. 422 b. If the ``$EXCHANGE_BASE_URL`` does not match the local exchange, 423 a **wad fee** is charged, and the remaining amount is placed into a **wad** 424 to inform the target exchange, as detailed below. Wad fees may be covered 425 by the merchant, just like deposit fees, depending on the contract. 426 8. The exchange confirms the merge (per response to the **merge** request). 427 This allows the payee software to instantly 428 affirm to the users that the transaction is final (even if it may not 429 be instantly available to the payee if the payee did not complete the 430 KYC process for the account). 431 9. The payer uses the GET ``/purses/$PURSE_PUB/merge`` endpoint 432 to obtain the receipt from the payee (in the form of the 433 **merge** signature). Query parameters are used to avoid 434 downloading the (already known) encrypted contract and the 435 deposit operations. Long-polling must also be possible for 436 this request. 437 438 439 440 Payment requests 441 ---------------- 442 443 1. The payee creates a **purse** by computing a public-private key pair. 444 2. The payee POSTs to the ``/reserves/$RESERVE_PUB/purse`` endpoint to 445 create the purse, upload the encrypted contract, associate it with the 446 payee's account and signal its agreement to the contract. The request 447 includes signatures made with the purse, merge and account private keys. 448 3. The payee provides a 449 ``taler://pay-pull/$BASE_URL/$CONTRACT_PRIV`` URI to the payer. 450 4. The payer computes the corresponding public keys and uses 451 ``/contracts/$CONTRACT_PUB`` to retrieve the encrypted contract and 452 ``/purses/$PURSE_PUB/merge`` to retrieve the merge status, which signifies 453 that the payee would agree to the contract. 454 5. The payer software decrypts the encrypted contract using the purse private 455 key and the payer accepts the contract in the user interface. 456 6. Processing continues depending on the source of the coins: 457 458 a. If the payer's coins originate from the same exchange, the 459 payer software POSTs to the ``/purses/$PURSE_PUB/deposit`` endpoint to 460 deposit coins into the purse. The deposit signatures should use 461 ``payto://taler/$PURSE_PUB`` 462 as the target address and signing over the ``$CONTRACT_HASH`` as 463 usual in deposit operations. Note that the lack of a hostname 464 indicates that the target address is a local purse. 465 b. If the payer's coins originate from another exchange, the 466 payer software deposits the coins at the originating exchange 467 using the traditional ``/deposit`` endpoint and a target account of the form 468 ``payto://taler/$EXCHANGE_BASE_URL/$ACCOUNT_PUB``. In this case, 469 the remote exchange charges a **wad fee** and places the remaining 470 amount into a **wad** to inform the target exchange, as detailed below. 471 7. The exchange confirms the deposit. This allows the payer software to instantly 472 affirm to the users that the transaction is final, or to abort or try again 473 in case of errors. 474 8. The payee uses the GET ``/purses/$PURSE_PUB/deposit`` endpoint (possibly with long-polling) 475 to be notified about the successful deposit and subsequent completion of the 476 **merge** request. 477 478 479 Payment into accounts at remote exchanges 480 ----------------------------------------- 481 482 In case the coins and the accounts in the transaction flows above are at 483 different exchanges, an aggregated exchange-to-exchange payment (short 484 **wad**) is used. 485 486 1. Exchanges specify a new **wad fee** that they charge for exchange-to-exchange 487 payments. They also specify their wad policy, that is how often they 488 perform exchange-to-exchange transfers. 489 490 .. note:: 491 492 We may want to consider allowing for different wad-speed levels, where 493 express payments (without aggregation) are allowed in return for higher 494 wad fees. 495 496 2. The payer's exchange creates a **wad** by grouping all wad requests 497 to the same target exchange. It executes 498 the transaction when either the **wad threshold** (maximum number 499 of transactons aggregated per wad) or the **wad delay** (maximum 500 delay for transfers) has been reached. 501 3. If the (aggregated) wire transfer fails (say the 502 ``/wire`` endpoint of the payee exchange does not 503 resolve to a valid bank account), the 504 originating exchange automatically creates a full refund for 505 all involved coins (**refund fees** apply). 506 507 .. note:: 508 509 While the **refund fee** amount can be reused, these types of refunds 510 are not approved by a merchant's signature. Thus, we will need 511 a new message type in the coin history to represent these events. 512 513 4. The payee's exchange observes the wire transfer with a wire transfer 514 subject with the originating exchange base URL and a ``$WATID``, 515 and uses a GET ``/wad/$WATID`` request to obtain 516 details about the target accounts. 517 5. When the payer's exchange is requested to provide information about 518 aggregated transfers under the ``$WATID``, it provides a signed list of 519 account public keys and associated amounts that must add up to an 520 amount below the total amount transferred. If they do not, the 521 payee's exchange does not credit any of the accounts and instead 522 preserves the bogus reply (to justify its inaction with its own 523 auditor) and reports the issue to the auditor of the payer's exchange 524 (keeping the received funds for future manual resolution). 525 6. ``taler-exchange-wirewatch`` and the Taler wire gateway API will 526 need to be extended to allow passing inbound wire transfers with ``$WATID`` 527 and exchange base URL to the exchange. Furthermore, another tool 528 is needed to lookup the **wad** data at remote exchanges. 529 7. If the payee trusts the originating exchange, it may consider the 530 transaction ``final`` once the originating exchange has affirmed the 531 deposit (assuming the payer has a way to submit the evidence of that 532 payment, which may not apply in uni-directional scenarios). 533 Otherwise, the payee may simply only trust its own exchange, 534 resulting in the transfer only being considered final after the 535 receiving exchange has confirmed that the **wad** has arrived. 536 537 538 Examples 539 --------- 540 541 Cross-exchange W2W payment request: 542 543 * Bob borrowed 15 EUR from Alice to buy a train ticket. A few days later, 544 Alice wants her money back. She creates a request for payment in her wallet. 545 The wallet creates a purse for 15 EUR at the only exchange that Alice is currently 546 using. The wallet shows her a 547 ``taler://pay-pull/{EXCHANGE_URL}/{CONTRACT_PRIV}`` 548 link that she can share with Bob. Bob receives the link and opens it with 549 his Taler wallet. Bob is using a different EUR exchange than Alice. Bob's 550 wallet makes a ``/deposit`` request to his own exchange. Shortly after, Alice's 551 exchange receives the wad from Bob's exchange, and credits the money into 552 Alice's purse. 553 554 * Q: How does Bob find out if Alice's exchange supports a wad transfer from 555 Bob's exchange? A: This needs to be part of the wad policy. 556 * Q: How does Bob get a "receipt" to prove that he paid Alice? 557 A: He has Alice's account public key and the associated signature 558 chain leading to her payment request. If he paid someone else by accident, 559 the KYC of Alice's exchange could be used to find out who received the funds. 560 561 Cross-exchange W2W payment offer: 562 563 * Carol wants to send some money to Dave as a birthday gift. Carol knows that 564 Dave is using Taler, but she does not know which exchange he is using. She 565 opens her Taler wallet and initiates a P2P payment. She sends the resulting 566 ``taler://pay-push/{EXCHANGE_URL}/{CONTRACT_PRIV}`` in an e-mail to Dave. 567 Dave opens the link in the e-mail with his Taler wallet. 568 Since Dave is using a different exchange than Carol, Dave's wallet 569 issues a **merge** request to Carol's exchange pointing Carol's exchange 570 to Dave's account at his exchange. Shortly after, 571 Dave's exchange receives a **wad** from Carol's exchange, 572 and credits Dave's account with the money. 573 574 575 State machine for Purses 576 ------------------------ 577 578 .. code-block:: none 579 580 // The "OPEN-ACCOUNT" start state implies that the purse is associated 581 // with an account and a merge request for that account. 582 -> OPEN-ACCOUNT 583 584 // "Partial" means that it is filled with a fraction of the coins 585 // indicated in the creation request. 586 OPEN-ACCOUNT -> PARTIAL 587 588 // The purse was filled with as many coins 589 // as indicated in the creation request, resulting in the transaction to complete. 590 OPEN-ACCOUNT -> ACCEPTED 591 592 // The offer expired before any payment was received. 593 OPEN-ACCOUNT -> CLOSED 594 595 // The purse was filled with as many coins 596 // as indicated in the creation request, resulting in the transaction to complete. 597 PARTIAL -> ACCEPTED 598 599 // During an abort, already deposited coins are being taken out of the purse. 600 PARTIAL -> OPEN-ACCOUNT 601 602 // All coins put into the purse are refunded because the 603 // payer never completed the purchase before the timeout. 604 PARTIAL -> CLOSED 605 606 // The "OPEN-DEPOSIT" start state implies that the purse is filled with 607 // deposited coins. 608 -> OPEN-DEPOSIT 609 610 // Paid and merged with an account (locally or via a wad) 611 OPEN-DEPOSIT -> ACCEPTED 612 613 // The offer expired without a merge request. 614 OPEN-DEPOSIT -> CLOSED 615 616 617 Additional considerations 618 ------------------------- 619 620 * Creation of additional accounts per customer can 621 be discouraged by asking for higher fees. 622 * The global transaction volume of one customer can be easily 623 determined by authorities, which can then trigger further audits 624 of the customer 625 * As a technically expensive but more water-tight measure, normal 626 withdrawals from reserves could be disallowed. Instead, 627 a modified refresh protocol could ensure that whoever has knowledge 628 of the account private key can also learn the private keys 629 of coins withdrawn from that account, thereby removing 630 Taler's "one-hop withdrawal loophole". 631 632 633 Exchange database schema changes 634 -------------------------------- 635 636 We need to exchange the existing reserves table to include bits for KYC-needed 637 and KYC-passed. Also, we need to store the payto://-URI of the bank account. 638 639 Finally, we may need to keep some link to the KYC data, even though the 640 exchange technically does not need it, but likely there might be regulatory 641 reasons to have that association for legal inquiries. (However, it would 642 also be possible to keep that link only in the external KYC service's 643 database.) 644 645 .. sourcecode:: sql 646 647 -- Everything in one big transaction 648 BEGIN; 649 -- Check patch versioning is in place. 650 SELECT _v.register_patch('exchange-TBD', NULL, NULL); 651 -- 652 CREATE TABLE IF NOT EXISTS partners 653 (partner_serial_id BIGSERIAL UNIQUE 654 ,partner_master_pub BYTEA NOT NULL CHECK(LENGTH(partner_master_pub)=32) 655 ,start_date INT8 NOT NULL 656 ,end_date INT8 NOT NULL 657 ,wad_frequency INT8 NOT NULL 658 ,wad_fee_val INT8 NOT NULL 659 ,wad_fee_frac INT4 NOT NULL 660 ,master_sig BYTEA NOT NULL CHECK (LENGTH(master_sig)=64)) 661 ,partner_base_url TEXT NOT NULL 662 ); 663 COMMENT ON TABLE partners 664 IS 'exchanges we do wad transfers to'; 665 COMMENT ON COLUMN partners.partner_master_pub 666 IS 'offline master public key of the partner'; 667 COMMENT ON COLUMN partners.start_date 668 IS 'starting date of the partnership'; 669 COMMENT ON COLUMN partners.end_date 670 IS 'end date of the partnership'; 671 COMMENT ON COLUMN partners.wad_frequency 672 IS 'how often do we promise to do wad transfers'; 673 COMMENT ON COLUMN partners.wad_fee_val 674 IS 'how high is the fee for a wallet to be added to a wad to this partner'; 675 COMMENT ON COLUMN partners.partner_base_url 676 IS 'base URL of the REST API for this partner'; 677 COMMENT ON COLUMN partners.master_sig 678 IS 'signature of our master public key affirming the partnership, of purpose TALER_SIGNATURE_MASTER_PARTNER_DETAILS'; 679 -- 680 ALTER TABLE reserves 681 ADD COLUMN kyc_needed BOOLEAN NOT NULL DEFAULT (false) 682 ADD COLUMN kyc_passed BOOLEAN NOT NULL DEFAULT (false) 683 ADD COLUMN payto_uri TEXT DEFAULT (NULL) 684 ADD COLUMN kyc_link TEXT DEFAULT (NULL); 685 COMMENT ON COLUMN reserves.kyc_needed 686 IS 'set to true once a reserve was merged with a purse'; 687 COMMENT ON COLUMN reserves.kyc_passed 688 IS 'set to true once the user performed the KYC check'; 689 COMMENT ON COLUMN reserves.payto_uri 690 IS 'bank account details to use in case reserve is closed'; 691 COMMENT ON COLUMN reserves.kyc_link 692 IS 'optional link to KYC data'; 693 -- 694 CREATE TABLE IF NOT EXISTS kyc_requests 695 (kyc_request_serial_id BIGSERIAL UNIQUE 696 ,reserve_uuid INT8 NOT NULL REFERENCES reserves (reserve_uuid) ON DELETE CASCADE 697 ,kyc_date INT8 NOT NULL 698 ,kyc_retry INT8 NOT NULL 699 ,kyc_fee_val INT8 NOT NULL 700 ,kyc_fee_frac INT4 NOT NULL 701 ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64)) 702 ,kyc_id TEXT NOT NULL 703 ,PRIMARY KEY (reserve_uuid, kyc_date) 704 ); 705 COMMENT ON TABLE kyc_requests 706 IS 'KYC processes initiated by the owner of a reserve'; 707 COMMENT ON COLUMN kyc_requests.reserve_uuid 708 IS 'Reserve for which the KYC request was triggered.'; 709 COMMENT ON COLUMN kyc_requests.reserve_sig 710 IS 'Signature affirming the KYC request'; 711 COMMENT ON COLUMN kyc_requests.kyc_fee_val 712 IS 'Amount paid by the reserve for the KYC process.'; 713 COMMENT ON COLUMN kyc_requests.kyc_date 714 IS 'When was the KYC process originally initiated.'; 715 COMMENT ON COLUMN kyc_requests.kyc_retry 716 IS 'Timestamp when we should next query the KYC backend for the KYC status. The maximum possible numeric value indicates that we do not need to ever check the status of this KYC process again.'; 717 COMMENT ON COLUMN kyc_requests.kyc_id 718 IS 'ID of the KYC process, used to compute the URL returned to the client as well as for the exchange to check if the KYC has completed. Format depends on the KYC process of the bank.'; 719 -- 720 CREATE TABLE IF NOT EXISTS mergers 721 (merge_request_serial_id BIGSERIAL UNIQUE 722 ,reserve_uuid BYTEA NOT NULL REFERENCES reserves (reserve_uuid) ON DELETE CASCADE 723 ,partner_serial_id INT8 REFERENCES partners(partner_serial_id) ON DELETE CASCADE, 724 ,reserve_pub BYTEA NOT NULL CHECK (LENGTH(reserve_pub)=32), 725 ,purse_pub BYTEA NOT NULL CHECK (LENGTH(purse_pub)=32), 726 ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64)) 727 ,purse_sig BYTEA NOT NULL CHECK (LENGTH(purse_sig)=64)) 728 ,merge_timestamp INT8 NOT NULL 729 ,purse_expiration INT8 NOT NULL 730 ,h_contract_terms BYTEA NOT NULL CHECK (LENGTH(h_contract_terms)=64)) 731 ,purse_val INT8 NOT NULL 732 ,purse_frac INT4 NOT NULL 733 ,PRIMARY KEY (purse_pub) 734 ); 735 COMMENT ON TABLE mergers 736 IS 'Merge requests where a purse- and account-owner requested merging the purse into the account'; 737 COMMENT ON COLUMN mergers.reserve_uuid 738 IS 'identifies the reserve'; 739 COMMENT ON COLUMN mergers.partner_serial_id 740 IS 'identifies the partner exchange, NULL in case the target reserve lives at this exchange'; 741 COMMENT ON COLUMN mergers.reserve_pub 742 IS 'public key of the target reserve'; 743 COMMENT ON COLUMN mergers.purse_pub 744 IS 'public key of the purse'; 745 COMMENT ON COLUMN mergers.reserve_sig 746 IS 'signature by the reserve private key affirming the merge'; 747 COMMENT ON COLUMN mergers.purse_sig 748 IS 'signature by the purse private key affirming the merge'; 749 COMMENT ON COLUMN mergers.merge_timestamp 750 IS 'when was the merge message signed'; 751 COMMENT ON COLUMN mergers.purse_expiration 752 IS 'when is the purse set to expire'; 753 COMMENT ON COLUMN mergers.h_contract_terms 754 IS 'hash of the contract terms both sides are to agree upon'; 755 COMMENT ON COLUMN mergers.purse_val 756 IS 'amount to be transferred from the purse to the reserve (excludes deposit fees)'; 757 CREATE INDEX IF NOT EXISTS mergers_reserve_uuid 758 ON mergers (reserve_uuid); 759 COMMENT ON INDEX mergers_reserve_uuid 760 IS 'needed in reserve history computation'; 761 -- 762 CREATE TABLE IF NOT EXISTS contracts 763 (contract_serial_id BIGSERIAL UNIQUE 764 ,purse_pub BYTEA NOT NULL CHECK (LENGTH(purse_pub)=32), 765 ,pub_ckey BYTEA NOT NULL CHECK (LENGTH(pub_ckey)=32)), 766 ,e_contract BYTEA NOT NULL, 767 ,PRIMARY KEY (purse_pub) 768 ); 769 COMMENT ON TABLE contracts 770 IS 'encrypted contracts associated with purses'; 771 COMMENT ON COLUMN contracts.purse_pub 772 IS 'public key of the purse that the contract is associated with'; 773 COMMENT ON COLUMN contracts.pub_ckey 774 IS 'Public ECDH key used to encrypt the contract, to be used with the purse private key for decryption'; 775 COMMENT ON COLUMN contracts.e_contract 776 IS 'AES-GCM encrypted contract terms (contains gzip compressed JSON after decryption)'; 777 -- 778 CREATE TABLE IF NOT EXISTS history_requests 779 (reserve_uuid INT8 NOT NULL REFERENCES reserves(reserve_uuid) ON DELETE CASCADE, 780 ,request_timestamp INT8 NOT NULL 781 ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64)) 782 ,history_fee_val INT8 NOT NULL 783 ,history_fee_frac INT4 NOT NULL 784 ,PRIMARY KEY (reserve_uuid,request_timestamp) 785 ); 786 COMMENT ON TABLE history_requests 787 IS 'Paid history requests issued by a client against a reserve'; 788 COMMENT ON COLUMN history_requests.request_timestamp 789 IS 'When was the history request made'; 790 COMMENT ON COLUMN history_requests.reserve_sig 791 IS 'Signature approving payment for the history request'; 792 COMMENT ON COLUMN history_requests.history_fee_val 793 IS 'History fee approved by the signature'; 794 -- 795 CREATE TABLE IF NOT EXISTS close_requests 796 (reserve_uuid INT8 NOT NULL REFERENCES reserves(reserve_uuid) ON DELETE CASCADE, 797 ,close_timestamp INT8 NOT NULL 798 ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64)) 799 ,close_val INT8 NOT NULL 800 ,close_frac INT4 NOT NULL 801 ,PRIMARY KEY (reserve_uuid,close_timestamp) 802 ); 803 COMMENT ON TABLE close_requests 804 IS 'Explicit requests by a reserve owner to close a reserve immediately'; 805 COMMENT ON COLUMN close_requests.close_timestamp 806 IS 'When the request was created by the client'; 807 COMMENT ON COLUMN close_requests.reserve_sig 808 IS 'Signature affirming that the reserve is to be closed'; 809 COMMENT ON COLUMN close_requests.close_val 810 IS 'Balance of the reserve at the time of closing, to be wired to the associated bank account (minus the closing fee)'; 811 812 -- 813 CREATE TABLE IF NOT EXISTS purse_requests 814 (purse_deposit_serial_id BIGSERIAL UNIQUE 815 ,purse_pub BYTEA NOT NULL CHECK (LENGTH(purse_pub)=32), 816 ,purse_expiration INT8 NOT NULL 817 ,h_contract_terms BYTEA NOT NULL CHECK (LENGTH(h_contract_terms)=64) 818 ,amount_with_fee_val INT8 NOT NULL 819 ,amount_with_fee_frac INT4 NOT NULL 820 ,purse_sig BYTEA NOT NULL CHECK(LENGTH(purse_sig)=64) 821 ,PRIMARY KEY (purse_pub,coin_pub) 822 ); 823 COMMENT ON TABLE purse_requests 824 IS 'Requests establishing purses, associating them with a contract but without a target reserve'; 825 COMMENT ON COLUMN purse_requests.purse_pub 826 IS 'Public key of the purse'; 827 COMMENT ON COLUMN purse_requests.purse_expiration 828 IS 'When the purse is set to expire'; 829 COMMENT ON COLUMN purse_requests.h_contract_terms 830 IS 'Hash of the contract the parties are to agree to'; 831 COMMENT ON COLUMN purse_requests.amount_with_fee_val 832 IS 'Total amount expected to be in the purse'; 833 COMMENT ON COLUMN purse_requests.purse_sig 834 IS 'Signature of the purse affirming the purse parameters, of type TALER_SIGNATURE_PURSE_REQUEST'; 835 -- 836 CREATE TABLE IF NOT EXISTS purse_deposits 837 (purse_deposit_serial_id BIGSERIAL UNIQUE 838 ,purse_pub BYTEA NOT NULL CHECK (LENGTH(purse_pub)=32), 839 ,coin_pub BYTEA NOT NULL REFERENCES known_coins (coin_pub) ON DELETE CASCADE 840 ,amount_with_fee_val INT8 NOT NULL 841 ,amount_with_fee_frac INT4 NOT NULL 842 ,coin_sig BYTEA NOT NULL CHECK(LENGTH(coin_sig)=64) 843 ,PRIMARY KEY (purse_pub,coin_pub) 844 ); 845 COMMENT ON TABLE purse_deposits 846 IS 'Requests depositing coins into a purse'; 847 COMMENT ON COLUMN purse_deposits.purse_pub 848 IS 'Public key of the purse'; 849 COMMENT ON COLUMN purse_deposits.coin_pub 850 IS 'Public key of the coin being deposited'; 851 COMMENT ON COLUMN purse_deposits.amount_with_fee_val 852 IS 'Total amount being deposited'; 853 COMMENT ON COLUMN purse_deposits.coin_sig 854 IS 'Signature of the coin affirming the deposit into the purse, of type TALER_SIGNATURE_PURSE_DEPOSIT'; 855 -- 856 CREATE TABLE IF NOT EXISTS wads_out 857 (wad_out_serial_id BIGSERIAL UNIQUE 858 ,wad_id BYTEA PRIMARY KEY CHECK (LENGTH(wad_id)=24) 859 ,partner_serial_id INT8 NOT NULL REFERENCES partners(partner_serial_id) ON DELETE CASCADE, 860 ,amount_val INT8 NOT NULL 861 ,amount_frac INT4 NOT NULL 862 ,execution_time INT8 NOT NULL 863 ,UNIQUE (exchange_url, execution_time) 864 ); 865 COMMENT ON TABLE wads_out 866 IS 'Wire transfers made to another exchange to transfer purse funds'; 867 COMMENT ON COLUMN wads_out.wad_id 868 IS 'Unique identifier of the wad, part of the wire transfer subject'; 869 COMMENT ON COLUMN wads_out.partner_serial_id 870 IS 'target exchange of the wad'; 871 COMMENT ON COLUMN wads_out.amount_val 872 IS 'Amount that was wired'; 873 COMMENT ON COLUMN wads_out.execution_time 874 IS 'Time when the wire transfer was scheduled'; 875 -- 876 CREATE TABLE IF NOT EXISTS wad_out_entries 877 (wad_out_entry_serial_id BIGSERIAL UNIQUE 878 ,wad_out_serial_id INT8 REFERENCES wads_out (wad_out_serial_id) ON DELETE CASCADE 879 ,reserve_pub BYTEA NOT NULL CHECK(LENGTH(reserve_pub)=32) 880 ,purse_pub BYTEA PRIMARY KEY CHECK(LENGTH(purse_pub)=32) 881 ,h_contract BYTEA NOT NULL CHECK(LENGTH(h_contract)=64) 882 ,purse_expiration INT8 NOT NULL 883 ,merge_timestamp INT8 NOT NULL 884 ,amount_with_fee_val INT8 NOT NULL 885 ,amount_with_fee_frac INT4 NOT NULL 886 ,wad_fee_val INT8 NOT NULL 887 ,wad_fee_frac INT4 NOT NULL 888 ,deposit_fees_val INT8 NOT NULL 889 ,deposit_fees_frac INT4 NOT NULL 890 ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64)) 891 ,purse_sig BYTEA NOT NULL CHECK (LENGTH(purse_sig)=64)) 892 ); 893 CREATE INDEX IF NOT EXISTS wad_out_entries_index_by_wad 894 ON wad_out_entries (wad_out_serial_id); 895 COMMENT ON TABLE wad_out_entries 896 IS 'Purses combined into a wad'; 897 COMMENT ON COLUMN wad_out_entries.wad_out_serial_id 898 IS 'Wad the purse was part of'; 899 COMMENT ON COLUMN wad_out_entries.reserve_pub 900 IS 'Target reserve for the purse'; 901 COMMENT ON COLUMN wad_out_entries.purse_pub 902 IS 'Public key of the purse'; 903 COMMENT ON COLUMN wad_out_entries.h_contract 904 IS 'Hash of the contract associated with the purse'; 905 COMMENT ON COLUMN wad_out_entries.purse_expiration 906 IS 'Time when the purse expires'; 907 COMMENT ON COLUMN wad_out_entries.merge_timestamp 908 IS 'Time when the merge was approved'; 909 COMMENT ON COLUMN wad_out_entries.amount_with_fee_val 910 IS 'Total amount in the purse'; 911 COMMENT ON COLUMN wad_out_entries.wad_fee_val 912 IS 'Wat fee charged to the purse'; 913 COMMENT ON COLUMN wad_out_entries.deposit_fees_val 914 IS 'Total deposit fees charged to the purse'; 915 COMMENT ON COLUMN wad_out_entries.reserve_sig 916 IS 'Signature by the receiving reserve, of purpose TALER_SIGNATURE_ACCOUNT_MERGE'; 917 COMMENT ON COLUMN wad_out_entries.purse_sig 918 IS 'Signature by the purse of purpose TALER_SIGNATURE_PURSE_MERGE'; 919 -- 920 CREATE TABLE IF NOT EXISTS wads_in 921 (wad_in_serial_id BIGSERIAL UNIQUE 922 ,wad_id BYTEA PRIMARY KEY CHECK (LENGTH(wad_id)=24) 923 ,origin_exchange_url TEXT NOT NULL 924 ,amount_val INT8 NOT NULL 925 ,amount_frac INT4 NOT NULL 926 ,arrival_time INT8 NOT NULL 927 ,UNIQUE (wad_id, origin_exchange_url) 928 ); 929 COMMENT ON TABLE wads_in_entries 930 IS 'Incoming exchange-to-exchange wad wire transfers'; 931 COMMENT ON COLUMN wads_in.wad_id 932 IS 'Unique identifier of the wad, part of the wire transfer subject'; 933 COMMENT ON COLUMN wads_in.origin_exchange_url 934 IS 'Base URL of the originating URL, also part of the wire transfer subject'; 935 COMMENT ON COLUMN wads_in.amount_val 936 IS 'Actual amount that was received by our exchange'; 937 COMMENT ON COLUMN wads_in.arrival_time 938 IS 'Time when the wad was received'; 939 -- 940 CREATE TABLE IF NOT EXISTS wad_in_entries 941 (wad_in_entry_serial_id BIGSERIAL UNIQUE 942 ,wad_in_serial_id INT8 REFERENCES wads_in (wad_serial_id) ON DELETE CASCADE 943 ,reserve_pub BYTEA NOT NULL CHECK(LENGTH(reserve_pub)=32) 944 ,purse_pub BYTEA PRIMARY KEY CHECK(LENGTH(purse_pub)=32) 945 ,h_contract BYTEA NOT NULL CHECK(LENGTH(h_contract)=64) 946 ,purse_expiration INT8 NOT NULL 947 ,merge_timestamp INT8 NOT NULL 948 ,amount_with_fee_val INT8 NOT NULL 949 ,amount_with_fee_frac INT4 NOT NULL 950 ,wad_fee_val INT8 NOT NULL 951 ,wad_fee_frac INT4 NOT NULL 952 ,deposit_fees_val INT8 NOT NULL 953 ,deposit_fees_frac INT4 NOT NULL 954 ,reserve_sig BYTEA NOT NULL CHECK (LENGTH(reserve_sig)=64)) 955 ,purse_sig BYTEA NOT NULL CHECK (LENGTH(purse_sig)=64)) 956 ); 957 COMMENT ON TABLE wad_in_entries 958 IS 'list of purses aggregated in a wad according to the sending exchange'; 959 COMMENT ON COLUMN wad_in_entries.wad_in_serial_id 960 IS 'wad for which the given purse was included in the aggregation'; 961 COMMENT ON COLUMN wad_in_entries.reserve_pub 962 IS 'target account of the purse (must be at the local exchange)'; 963 COMMENT ON COLUMN wad_in_entries.purse_pub 964 IS 'public key of the purse that was merged'; 965 COMMENT ON COLUMN wad_in_entries.h_contract 966 IS 'hash of the contract terms of the purse'; 967 COMMENT ON COLUMN wad_in_entries.purse_expiration 968 IS 'Time when the purse was set to expire'; 969 COMMENT ON COLUMN wad_in_entries.merge_timestamp 970 IS 'Time when the merge was approved'; 971 COMMENT ON COLUMN wad_in_entries.amount_with_fee_val 972 IS 'Total amount in the purse'; 973 COMMENT ON COLUMN wad_in_entries.wad_fee_val 974 IS 'Total wad fees paid by the purse'; 975 COMMENT ON COLUMN wad_in_entries.deposit_fees_val 976 IS 'Total deposit fees paid when depositing coins into the purse'; 977 COMMENT ON COLUMN wad_in_entries.reserve_sig 978 IS 'Signature by the receiving reserve, of purpose TALER_SIGNATURE_ACCOUNT_MERGE'; 979 COMMENT ON COLUMN wad_in_entries.purse_sig 980 IS 'Signature by the purse of purpose TALER_SIGNATURE_PURSE_MERGE'; 981 CREATE INDEX IF NOT EXISTS wad_in_entries_wad_in_serial 982 ON wad_in_entries (wad_in_serial_id); 983 CREATE INDEX IF NOT EXISTS wad_in_entries_reserve_pub 984 ON wad_in_entries (reserve_pub); 985 COMMENT ON INDEX wad_in_entries_wad_in_serial 986 IS 'needed to lookup all transfers associated with a wad'; 987 COMMENT ON INDEX wad_in_entries_reserve_pub 988 IS 'needed to compute reserve history'; 989 -- 990 CREATE TABLE IF NOT EXISTS p2pfees 991 (p2pfees_serial_id BIGSERIAL UNIQUE 992 ,start_date INT8 NOT NULL 993 ,end_date INT8 NOT NULL 994 ,kyc_timeout INT8 NOT NULL 995 ,purse_timeout INT8 NOT NULL 996 ,history_retention INT8 NOT NULL 997 ,purse_account_limit INT NOT NULL 998 ,kyc_fee_val INT8 NOT NULL 999 ,kyc_fee_frac INT4 NOT NULL 1000 ,history_fee_val INT8 NOT NULL 1001 ,history_fee_frac INT4 NOT NULL 1002 ,account_fee_val INT8 NOT NULL 1003 ,account_fee_frac INT4 NOT NULL 1004 ,purse_fee_val INT8 NOT NULL 1005 ,purse_fee_frac INT4 NOT NULL 1006 ,master_sig BYTEA NOT NULL CHECK (LENGTH(master_sig)=64)) 1007 ); 1008 -- 1009 CREATE TABLE IF NOT EXISTS partner_accounts 1010 (payto_uri VARCHAR PRIMARY KEY 1011 ,partner_serial_id INT8 REFERENCES partners(partner_serial_id) ON DELETE CASCADE, 1012 ,partner_master_sig BYTEA CHECK (LENGTH(partner_master_sig)=64) 1013 ,last_seen INT8 NOT NULL 1014 ); 1015 CREATE INDEX IF NOT EXISTS partner_accounts_index_by_partner_and_time 1016 ON partner_accounts (partner_serial_id,last_seen); 1017 COMMENT ON TABLE partner_accounts 1018 IS 'Table with bank accounts of the partner exchange. Entries never expire as we need to remember the signature for the auditor.'; 1019 COMMENT ON COLUMN wire_accounts.payto_uri 1020 IS 'payto URI (RFC 8905) with the bank account of the partner exchange.'; 1021 COMMENT ON COLUMN wire_accounts.partner_master_sig 1022 IS 'Signature of purpose TALER_SIGNATURE_MASTER_WIRE_DETAILS by the partner master public key'; 1023 COMMENT ON COLUMN wire_accounts.last_seen 1024 IS 'Last time we saw this account as being active at the partner exchange. Used to select the most recent entry, and to detect when we should check again.'; 1025 -- Complete transaction 1026 COMMIT; 1027 1028 1029 1030 Alternatives 1031 ============ 1032 1033 * The payer could directly give deposit permissions to the payee. 1034 This has two problems: 1035 1036 1. The payer does not know the wire details of the payee. 1037 Thus we would need to introduce some "wildcard deposit permission", 1038 where the exchange allows any wire details on ``/deposit``. 1039 2. The payment information would be rather large, making it difficult 1040 to transfer via a QR code or short text message. 1041 1042 * Account history exceeding a configurable time limit (like 6 years) 1043 could be subject to garbage collection. However, doing so may be difficult to 1044 square with onboarding new auditors in the presence of existing 1045 accounts, as the auditors could then not reconstruct the account 1046 balances from cryptographic proofs. 1047 1048 * Accounts without KYC check could be eventually closed. However, 1049 even if the coins used to fill the account are refunded, it 1050 would be difficult to inform the originating wallet that the 1051 coins have received a refund. This applies even more strongly 1052 in case of accounts filled via wads, where in theory the 1053 originating exchange may not even be in business anymore. 1054 Thus, it is cleaner and simpler to declare such funds forfeit. 1055 1056 1057 Drawbacks 1058 ========= 1059 1060 The overall changes required are not small: 1061 1062 * New **KYC fee**, **wad fee** and **account history fee** 1063 required in ``/keys`` endpoint (similar to closing and wire fees), 1064 requires some work across toolchain (offline signature, etc.) 1065 * New ``taler`` wire method needs special case to possibly bypass 1066 (same exchange scenario, with long-poll trigger) the usual aggregation logic. 1067 * New exchange table(s) required to store inbound amounts by account. 1068 Likely two tables, one for local exchange p2p and one for remote exchange p2p 1069 payments. 1070 * New exchange table for purses required (for remote p2p payments). 1071 * New exchange logic required to make ``transfers`` requests for purses 1072 (another separate process). 1073 * New ``/account/$ACCOUNT_PUB/kyc`` endpoint required. 1074 * New ``/purses/$PURSE_PUB/merge`` endpoint required. 1075 * Additional tables to be verified by the auditor. 1076 * ``taler-exchange-wirewatch`` needs to support receiving purses closures 1077 and exchange-to-exchange wire transfers with WTIDs. 1078 1079 Aside from implementation complexity, the solution has the following drawbacks: 1080 1081 * If a W2W payment failed (say the receiver lost the account private key), 1082 the customer's money can be forfeit. Alas, this should be very, very rare 1083 as the wallet software can trivially ensure that a backup was made of the 1084 account private key before initiating the KYC process. 1085 1086 1087 Refinements 1088 =========== 1089 1090 In the original design, a payer making a payment offer sends the purse private 1091 key to the payee, so that the payee can sign the merge request with it. This 1092 creates a security issue, as theoretically the payee could sign a different 1093 contract with the purse private key, and conspire with the exchange to replace 1094 the original contract. In this case, the payer would be making a payment to 1095 the "wrong" contract, and have no proof of the exchange and payee conspiring 1096 against it. 1097 1098 A simple fix seems possible: instead of having simply one public-private key 1099 pair for a purse, we have a PayerContractKey and a PurseMergeKey pair. The payer 1100 would pay into a purse identified by the PayerContractKey and associate a 1101 PurseMergeKey with the purse. The payer can then safely share the 1102 PayeeMergeKey with the payee, as it is ONLY useful for the merge and not to 1103 sign the contract. Payments would be made into a purse identified by the 1104 PurseContractKey. 1105 1106 When payments flow in the other direction, the split of the keys seems 1107 unnecessary (as only a public key is transmitted anyway. However, schema-wise, 1108 signing the contract with the PurseContractKey and the merge with the 1109 PurseMergeKey would still work. Only the public PurseContractKey would need 1110 to be sent to the payer. 1111 1112 1113 1114 Q / A 1115 ===== 1116 1117 * Q: Why are direct payments into accounts allowed? 1118 1119 * A: Direct payments into accounts may be used by the customer 1120 to fund the expenses for using the account. They should not 1121 be used for payments between customers, as contract terms for 1122 the ``/deposit`` of coins cannot be negotiated. Furthermore, 1123 the sender of the payment cannot be sure that the account of 1124 the sender is still valid. 1125 1126 * Q: Who "owns" a purse? The payer or payee? 1127 1128 * Both. Ownership is shared. Either the payer issues 1129 a refund on the purse, or the payee claims it by merging 1130 it with one of their accounts. 1131 1132 * Q: Are purses created with a pre-determined "capacity"? 1133 1134 * A: Yes. Otherwise there would be weird failure modes when the payee 1135 merges the purse before the payer fully deposited into it. 1136 1137 * Q: Are account public keys considered private or public data? 1138 1139 * A: Public. The payer needs a signature from the payee affirming 1140 that they accepted the contract, and this requires a key that 1141 is linked to the KYC process to be meaningful. However, the 1142 software should NOT permit direct payments into foreign accounts 1143 because it would be too easy to accidentally send payments that 1144 nobody can receive, because the account public key is wrong/lost. 1145 1146 * Q: Why do traditional merchant payments not use purses? 1147 1148 * Refunds are not possible with purses after they are closed. 1149 * The customer cannot prove that they own the contract terms 1150 (Contract terms claiming requires interactivity that is not 1151 possible in all W2W scenarios.) Thus, while payers can prove 1152 that they paid, the payee may claim someone else also 1153 bought the same product. A secure channel must thus be used to 1154 exchange the purchase offer. 1155 1156 * Q: What determines when a wad transfer can happen between two exchanges? 1157 1158 * Exchanges explicitly state which other exchanges they are willing 1159 to do wad transfers with (and how often, at what cost). This may involve 1160 abstract policies like sharing an auditor, using the same currency and the 1161 same (banking) protocol, or other constraints (like a specific list of 1162 exchanges). 1163 1164 * Q: What happens if the owner of a reserve never drains it? 1165 1166 * Reserves are eventually closed. If the reserve is associated 1167 with a bank account, the remaining funds are sent to that bank 1168 account. If the reserve was created via a merge, and the owner 1169 failed to associate a bank account with it (say because the 1170 KYC step never happened), then the reserve balance is forfeit 1171 to the exchange upon expiration.