commit 55bdee102df66c4243cefb47de8f8e08c884f5ef
parent aea989cc961d009c914258ab750a4eb639c354bd
Author: Antoine A <>
Date: Tue, 17 Jun 2025 19:28:58 +0200
corebank: update DD63 and API
Diffstat:
4 files changed, 165 insertions(+), 161 deletions(-)
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -332,7 +332,7 @@ Account Management
// If present, set the user conversion rate class
// Only admin can set this property.
// @since **v9**
- conversion_rate_class_id?: Number;
+ conversion_rate_class_id?: Integer;
// If present, enables 2FA and set the TAN channel used for challenges
// Only admin can set this property, other user can reconfig their account
@@ -423,7 +423,7 @@ Account Management
// If present, set the user conversion rate class
// Only admin can set this property.
// @since **v9**
- conversion_rate_class_id?: Number
+ conversion_rate_class_id?: Integer;
// If present, enables 2FA and set the TAN channel used for challenges
tan_channel?: TanChannel;
@@ -760,6 +760,8 @@ Account Management
// @since **v9**
conversion_rate_class?: AccountConversionRateClass;
}
+
+ .. ts:def:: AccountConversionRateClass
interface AccountConversionRateClass {
// Class unique ID
@@ -1445,6 +1447,8 @@ Conversion rate class
Missing rights.
:http:statuscode:`404 Not Found`:
The conversion rate class was not found.
+ :http:statuscode:`409 Conflict`:
+ * ``TODO_LINKED_ACCOUNT`` : some accounts belongs to this class.
:http:statuscode:`501 Not implemented`:
This server does not support conversion, client should check config response.
@@ -1809,6 +1813,7 @@ Endpoints for Integrated Sub-APIs
.. http:any:: /conversion-info/*
Global conversion rate infos.
+ Deprecated since **v9**
All endpoints under this prefix are specified
by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`.
\ No newline at end of file
diff --git a/design-documents/063-libeufin-conversion-rate-classes.rst b/design-documents/063-libeufin-conversion-rate-classes.rst
@@ -0,0 +1,156 @@
+DD 63: LibEufin Conversion Rate Class
+#####################################
+
+Summary
+=======
+
+We need an efficient solution to set specific conversion rates for some users. By efficient this means you do not have to set or update them manually for all accounts and a good way to see what are the current rates and which accounts use them.
+
+Proposed Solution
+=================
+
+The current global conversion rate schema is:
+
+.. ts:def:: ConversionRate
+
+ interface ConversionRate {
+ // Minimum fiat amount authorised for cashin before conversion
+ cashin_min_amount: Amount;
+
+ // Exchange rate to buy regional currency from fiat
+ cashin_ratio: DecimalNumber;
+
+ // Regional amount fee to subtract after applying the cashin ratio.
+ cashin_fee: Amount;
+
+ // Rounding mode used during cashin conversion
+ cashin_rounding_mode: "zero" | "up" | "nearest";
+
+ // Minimum regional amount authorised for cashout before conversion
+ cashout_min_amount: Amount;
+
+ // Exchange rate to sell regional currency for fiat
+ cashout_ratio: DecimalNumber;
+
+ // Fiat amount fee to subtract after applying the cashout ratio.
+ cashout_fee: Amount;
+
+ // Rounding mode used during cashout conversion
+ cashout_rounding_mode: "zero" | "up" | "nearest";
+ }
+
+This would become the ``default`` class, that will be used by all created users. The administrator would be able to create new classes that override some of the default properties:
+
+.. ts:def:: ConversionRateClassRequest
+
+ interface ConversionRateClassRequest {
+ // The name of this class
+ name: string;
+
+ // A description of the class
+ description?: string;
+
+ // Minimum fiat amount authorised for cashin before conversion
+ cashin_min_amount?: Amount;
+
+ // Exchange rate to buy regional currency from fiat
+ cashin_ratio?: DecimalNumber;
+
+ // Regional amount fee to subtract after applying the cashin ratio.
+ cashin_fee?: Amount;
+
+ // Rounding mode used during cashin conversion
+ cashin_rounding_mode?: "zero" | "up" | "nearest";
+
+ // Minimum regional amount authorised for cashout before conversion
+ cashout_min_amount?: Amount;
+
+ // Exchange rate to sell regional currency for fiat
+ cashout_ratio?: DecimalNumber;
+
+ // Fiat amount fee to subtract after applying the cashout ratio.
+ cashout_fee?: Amount;
+
+ // Rounding mode used during cashout conversion
+ cashout_rounding_mode?: "zero" | "up" | "nearest";
+ }
+
+.. ts:def:: ConversionRateClass
+
+ interface ConversionRateClass {
+ // The name of this class
+ name: string;
+
+ // A description of the class
+ description?: string;
+
+ // Class unique ID
+ conversion_rate_class_id: Integer;
+
+ // Number of users affected to this class
+ num_users: Integer;
+
+ // Applied conversion rate
+ conversion_rate: ConversionRate;
+
+ // Minimum fiat amount authorised for cashin before conversion
+ cashin_min_amount?: Amount;
+
+ // Exchange rate to buy regional currency from fiat
+ cashin_ratio?: DecimalNumber;
+
+ // Regional amount fee to subtract after applying the cashin ratio.
+ cashin_fee?: Amount;
+
+ // Rounding mode used during cashin conversion
+ cashin_rounding_mode?: "zero" | "up" | "nearest";
+
+ // Minimum regional amount authorised for cashout before conversion
+ cashout_min_amount?: Amount;
+
+ // Exchange rate to sell regional currency for fiat
+ cashout_ratio?: DecimalNumber;
+
+ // Fiat amount fee to subtract after applying the cashout ratio.
+ cashout_fee?: Amount;
+
+ // Rounding mode used during cashout conversion
+ cashout_rounding_mode?: "zero" | "up" | "nearest";
+ }
+
+.. ts:def:: ConversionRateClasses
+
+ interface ConversionRateClasses {
+ default: ConversionRate;
+ classes: ConversionRateClass[];
+ }
+
+When we run the conversion logic we take values from the user class and fallback to the default values when they are null. If the ratio is zero it disable the conversion.
+
+Taler Conversion Info API
+-------------------------
+
+We need to move the current conversion-info API from ``/conversion-info/*`` to ``/accounts/$USERNAME/conversion-info/*`` to take into account user specific conversion rate.
+
+We keep the current API to only show the default rate for retro compatibility.
+
+A ``/rate`` to get, the potentially private, user specific conversion rate.
+
+Taler Core Bank API
+-------------------
+
+We add new admin only conversion rate class management endpoints:
+
+POST ``/conversion-rate-classes``
+GET ``/conversion-rate-classes``
+GET ``/conversion-rate-classes/$CLASS-ID``
+PATCH ``/conversion-rate-classes/$CLASS-ID``
+DELETE ``/conversion-rate-classes/$CLASS-ID``
+
+Add ``/conversion-rate-class/$CLASS-ID/conversion-info/*``
+Add ``/accounts/$USERNAME/conversion-info/*``
+
+We add admin only ``conversion_rate_class_id`` `Integer` optional field to POST ``/accounts`` and PATCH ``/accounts/$USERNAME`` and remove ``min_cashout``.
+
+We add ``conversion_rate_class_id`` `Integer` optional field and query filter to GET /accounts
+We add ``conversion_rate_class`` `AccountConversionRateClass` field of GET ``/accounts/$USERNAME``
+\ No newline at end of file
diff --git a/design-documents/063-libeufin-conversion-rate-group.rst b/design-documents/063-libeufin-conversion-rate-group.rst
@@ -1,157 +0,0 @@
-DD 63: LibEufin Conversion Rate Class
-#####################################
-
-Summary
-=======
-
-We need an efficient solution to set specific conversion rates for some users. By efficient this means you do not have to set or update them manually for all accounts and a good way to see what are the current rates and which accounts use them.
-
-Proposed Solution
-=================
-
-The current global conversion rate schema is:
-
-.. ts:def:: ConversionRate
-
- interface ConversionRate {
- // Minimum fiat amount authorised for cashin before conversion
- cashin_min_amount: Amount;
-
- // Exchange rate to buy regional currency from fiat
- cashin_ratio: DecimalNumber;
-
- // Regional amount fee to subtract after applying the cashin ratio.
- cashin_fee: Amount;
-
- // Rounding mode used during cashin conversion
- cashin_rounding_mode: "zero" | "up" | "nearest";
-
- // Minimum regional amount authorised for cashout before conversion
- cashout_min_amount: Amount;
-
- // Exchange rate to sell regional currency for fiat
- cashout_ratio: DecimalNumber;
-
- // Fiat amount fee to subtract after applying the cashout ratio.
- cashout_fee: Amount;
-
- // Rounding mode used during cashout conversion
- cashout_rounding_mode: "zero" | "up" | "nearest";
- }
-
-This would become the ``default`` class, that will be used by all created users. The administrator would be able to create new classes that override some of the default properties:
-
-.. ts:def:: ConversionRateClassRequest
-
- interface ConversionRateClassRequest {
- // The name of this class
- name: string;
-
- // A description of the class
- description?: string;
-
- // Minimum fiat amount authorised for cashin before conversion
- cashin_min_amount?: Amount;
-
- // Exchange rate to buy regional currency from fiat
- cashin_ratio?: DecimalNumber;
-
- // Regional amount fee to subtract after applying the cashin ratio.
- cashin_fee?: Amount;
-
- // Rounding mode used during cashin conversion
- cashin_rounding_mode?: "zero" | "up" | "nearest";
-
- // Minimum regional amount authorised for cashout before conversion
- cashout_min_amount?: Amount;
-
- // Exchange rate to sell regional currency for fiat
- cashout_ratio?: DecimalNumber;
-
- // Fiat amount fee to subtract after applying the cashout ratio.
- cashout_fee?: Amount;
-
- // Rounding mode used during cashout conversion
- cashout_rounding_mode?: "zero" | "up" | "nearest";
- }
-
-.. ts:def:: ConversionRateClass
-
- interface ConversionRateClass {
- // The name of this class
- name: string;
-
- // A description of the class
- description?: string;
-
- // Class unique ID
- row_id: Integer;
-
- // Number of users affected to this class
- num_users: Integer;
-
- // Applied conversion rate
- conversion_rate: ConversionRate;
-
- // Minimum fiat amount authorised for cashin before conversion
- cashin_min_amount?: Amount;
-
- // Exchange rate to buy regional currency from fiat
- cashin_ratio?: DecimalNumber;
-
- // Regional amount fee to subtract after applying the cashin ratio.
- cashin_fee?: Amount;
-
- // Rounding mode used during cashin conversion
- cashin_rounding_mode?: "zero" | "up" | "nearest";
-
- // Minimum regional amount authorised for cashout before conversion
- cashout_min_amount?: Amount;
-
- // Exchange rate to sell regional currency for fiat
- cashout_ratio?: DecimalNumber;
-
- // Fiat amount fee to subtract after applying the cashout ratio.
- cashout_fee?: Amount;
-
- // Rounding mode used during cashout conversion
- cashout_rounding_mode?: "zero" | "up" | "nearest";
- }
-
-.. ts:def:: ConversionRateClasses
-
- interface ConversionRateClasses {
- default: ConversionRate;
- classes: ConversionRateClass[];
- }
-
-When we run the conversion logic we take values from the user class and fallback to the default values when they are null. If the ratio is zero it disable the conversion.
-
-Taler Conversion Info API
--------------------------
-
-We need to move the current conversion-info API from ``/conversion-info/*`` to ``/accounts/$USERNAME/conversion-info/*``. We keep the current API to only show the default rate for retro compatibility.
-
-We deprecate ``POST /conversion-rate`` to make the API readonly (the Info in the name was a hint).
-
-TODO: How hard is it to migrate to this in the wallets ?
-
-Taler Core Bank API
--------------------
-
-We migrate ``POST /conversion-rate`` here to set the default conversion rate class value.
-
-We add new admin only conversion rate class management endpoints:
-
-POST /conversion-rate-class
-GET /conversion-rate-class
-GET /conversion-rate-class/$CLASS-ID
-PATCH /conversion-rate-class/$CLASS-ID
-DELETE /conversion-rate-class/$CLASS-ID
-
-add /conversion-rate-class/$CLASS-ID/conversion-info/*
-
-We add admin only ``conversion_rate_class`` `Integer` optional field to POST /accounts and PATCH /accounts/$USERNAME.
-
-We add ``conversion_rate_class`` `Integer` optional field and query filter to GET /accounts
-We add ``conversion_rate_class`` `ConversionRateClass` field of GET /accounts/$USERNAME
-\ No newline at end of file
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -74,6 +74,6 @@ Design documents that start with "XX" are considered deprecated.
060-clause-schnorr.rst
061-batched-withdraw.rst
062-pq-refresh.rst
- 063-libeufin-conversion-rate-group
+ 063-libeufin-conversion-rate-classes
064-kyc-operation-algo
999-template
