From 20d68685eee8a3e99b59ed913ad3389f487e3e4b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 5 May 2021 17:45:09 +0200 Subject: update spec for W2W --- design-documents/013-peer-to-peer-payments.rst | 85 ++++++++++++++++---------- 1 file changed, 53 insertions(+), 32 deletions(-) (limited to 'design-documents') 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. -- cgit v1.2.3