taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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.