new configuration option: wallet balance threshold

3 files changed, 33 insertions, 0 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 59edb2a0..7f4f57c0 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -131,6 +131,12 @@ possibly by using HTTPS.
       // not signed (!), can change without notice.
       reserve_closing_delay: RelativeTime;
 
+      // Maximum amount that a wallet is allowed to hold without
+      // having to undergo the KYC process of the issuing
+      // exchange.  Optional option, if not given there is no limit.
+      // Currency must match ``currency``.
+      wallet_balance_limit_without_kyc?: Amount;
+
       // Denominations offered by this exchange.
       denoms: Denom[];
 
diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst
index 3e67bff2..a2fc3c75 100644
--- a/design-documents/023-taler-kyc.rst
+++ b/design-documents/023-taler-kyc.rst
@@ -87,6 +87,27 @@ The aggregator is modified to only SELECT deposits where the ``wire_target``
 has the KYC status set to positive (unless KYC is disabled in the exchange
 configuration).
 
+To allow the wallet to do the KYC check if it is about to exceed a set balance
+threshold, we modify the ``/keys`` response to add a optional field
+``wallet_balance_limit_without_kyc`` the wallet is allowed to hold in coins
+from this exchange without KYC.  If this field is absent, there is no limit.
+If the field is provided, a correct wallet must create a long-term
+account-reserve key pair. This should be the same key that is also used to
+receive wallet-to-wallet payments. Then, before a wallet performs an operation
+that would cause it to exceed the balance threshold in terms of funds held
+from a particular exchange, it must first request the user to complete the KYC
+process.
+
+For that, it should POST to the new ``/wallet-kyc`` endpoint, providing its
+long-term reserve-account public key and a signature requesting permission to
+exceed the account limit.  The exchange will respond with a wire target
+UUID. The wallet can then use this UUID to being the KYC process at
+``/kyc-check/``. The wallet must only proceed to obtain funds exceeding the
+threshold after the KYC process has concluded. While wallets could be "hacked"
+to bypass this measure (we cannot cryptographically enforce this), such
+modifications are a terms of service violation which may have legal
+consequences for the user.
+
 
   ..note::
 
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 79ca6d7a..c148d33f 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -188,6 +188,12 @@ KYC_WITHDRAW_PERIOD
   are considered for the KYC_WITHDRAW_LIMIT.
   Only used if KYC_MODE is not "NONE".
 
+KYC_WALLET_BALANCE_LIMIT
+  Maximum amount that a wallet is allowed to hold without
+  having to undergo the KYC process of the issuing
+  exchange.  Optional option, if not given there
+  is no limit.
+
 
 EXCHANGE KYC OAUTH2 OPTIONS
 ---------------------------