update spec for W2W

1 files changed, 53 insertions, 32 deletions

diff --git a/design-documents/013-peer-to-peer-payments.rst b/design-documents/013-peer-to-peer-payments.rst
index 914d87fe..0d3a767c 100644
--- a/design-documents/013-peer-to-peer-payments.rst
+++ b/design-documents/013-peer-to-peer-payments.rst
@@ -278,29 +278,44 @@ Contract metadata for W2W payments can be exchanged in three ways:
 Account creation
 ----------------
 
-1. The payee generates an account key, which also yields a
-   ``payto://taler/$EXCHANGE_BASE_URL/$ACCOUNT_PUB``
+An account is simply a reserve that has been subjected to
+KYC. A reserve that has seen a purse merged into it must
+be upgraded to an account before further withdraw (or close)
+operations are allowed.  The usual closure deadline for a
+reserve is extended to the KYC deadline.
+
+1. The payee generates a reserve key, which also yields a
+   ``payto://taler/$EXCHANGE_BASE_URL/$RESERVE_PUB``
    target address (for which the payee knows the corresponding
-   account private key).
-2. When withdrawing from an account, the exchange first checks if the
-   customer has satisfied the KYC requirements. If not, the customer
-   is redirected to a Web page where they can perform the necessary
-   KYC operation.
+   reserve private key).
+2. When withdrawing from a reserve that has experienced
+   merge operations and thus must be an account, the exchange
+   first checks if the customer has satisfied the KYC requirements.
+   If not, the customer is redirected to a Web page where they
+   can perform the necessary KYC operation.
 3. For this, the exchange wire gateway is extended with a request to
-   check the KYC status of a customer based on an ``ACCOUNT_PUB``.
-   Possible replies are ``in-progress`` and ``succeeded``. An ``in-progress``
-   status should be accompanied with
+   check the KYC status of a customer based on an ``RESERVE_PUB``.
+   Possible replies are ``in-progress`` and ``succeeded``.
+   An ``in-progress`` status should be accompanied with
    information how the customer may complete the KYC check.
-4. A new exchange endpoint ``/account/$ACCOUNT_PUB/kyc``
-   allows wallets to request a KYC for an
-   ``$ACCOUNT_PUB``.  Such a request may include the requirement to pay
-   a **KYC fee**.  The KYC fee may be charged to that account (if it exists),
-   or could be waved if the account was established via a wire transfer
-   from a partner bank.
-5. If the account owner fails to perform the KYC check, the funds
-   in an account remain inaccessible.  After a configurable duration,
+4. A new exchange endpoint ``/reserves/$RESERVE_PUB/kyc``
+   allows wallets to request a KYC for a
+   ``$RESERVE_PUB``.  Such a request may include the requirement to pay
+   a **KYC fee**.
+   The KYC fee may be charged to the reserve (a sufficient
+   balance can be provided by the wallet by creating a purse
+   and merging the purse with the reserve, if needed),
+   or could be waved if the reserve was established via a wire transfer
+   from a partner bank where KYC is free.  For this, the Wire
+   gateway API is extended with a flag that informs the exchange
+   that the incoming wire transfer implies a free KYC check.
+5. If the account owner fails to perform the KYC check, all funds
+   in an reserve remain inaccessible.  After a configurable duration,
    the funds may be considered forfeit and become the property of
-   the exchange where the account is located.
+   the exchange where the reserve is located.
+6. The exchange may charge an annual **account fee**, and can
+   close accounts where the account balance is insufficient to
+   cover the account fee.
 
 
 Withdrawing from accounts
@@ -328,21 +343,27 @@ Withdrawing from accounts
 Account deletion
 ----------------
 
-1. The account owner can delete an account by signing a deletion message
-   with the account private key.
-2. This basically resets the KYC data at the exchange, preventing further use of
-   the account. This is helpful in case a user is concerned about having
-   accidentally disclosed the account private key to a third party.
-3. If funds remain in the account, an error message is generated instead.  The
-   user can pass an extra override parameter to delete accounts even if
-   they still contain funds.
+1. A reserve owner can delete a reserve by signing a deletion message
+   with the reserve private key.
+2. This basically resets the KYC data at the exchange, preventing
+   further use of the account. This is helpful in case a user is
+   concerned about having
+   accidentally disclosed the reserve private key to a third party.
+3. If funds remain in the reserve, the exchange will close the
+   reserve and wire the funds to the associated bank account.
+   If no bank account is associated with the reserve,
+   an error message is generated instead.  The
+   user can pass an extra override parameter to delete reserves
+   even if they still contain funds.
 4. A related endpoint should exist for the exchange operator, possibly
-   using messages signed with the exchange offline key. This could be
-   useful in case customers die or are otherwise in need for manual
-   intervention that requires an account to be deleted. In this case,
+   using messages signed with a new exchange management key.
+   This could be useful in case customers die or are otherwise
+   in need for manual intervention that requires an account to
+   be deleted. In this case,
    remaining funds in the account should be wired to a bank account
-   designated in the message with the offline signature. The audit
-   report should contain a special note for all of these account deletions.
+   designated in the message with the management signature. The audit
+   report should contain a special note for all of these types of
+   account deletions.