commit e36b44842903bac92f9caadc30504742efb263ee
parent b4330e384ed3254bf6aa9b13d1f16d2ab7866683
Author: Antoine A <>
Date: Mon, 12 May 2025 14:44:42 +0200
[dd:libeufin-conversion-rate-group] fix number and index
Diffstat:
3 files changed, 143 insertions(+), 142 deletions(-)
diff --git a/design-documents/063-libeufin-conversion-rate-group.rst b/design-documents/063-libeufin-conversion-rate-group.rst
@@ -0,0 +1,141 @@
+DD 63: LibEufin Conversion Rate Group
+#####################################
+
+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;
+
+ // Smallest possible regional amount, converted amount is rounded to this amount
+ cashin_tiny_amount: 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;
+
+ // Smallest possible fiat amount, converted amount is rounded to this amount
+ cashout_tiny_amount: Amount;
+
+ // Rounding mode used during cashout conversion
+ cashout_rounding_mode: "zero" | "up" | "nearest";
+ }
+
+This would become the ``default`` group, that will be used by all created users. The administrator would be able to create new groups that override some of the default properties:
+
+.. ts:def:: ConversionRateGroupRequest
+
+ interface ConversionRateGroupRequest {
+ // The name of this group
+ name: string;
+
+ // A description of the group
+ 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;
+
+ // 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;
+ }
+
+.. ts:def:: ConversionRateGroup
+
+ interface ConversionRateGroup {
+ // The name of this group, null if default group
+ name?: string;
+
+ // A description of the group
+ description?: string;
+
+ // Group unique ID
+ row_id: Integer;
+
+ // Number of users affected to this group
+ num_users: Integer;
+
+ // 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;
+
+ // 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;
+ }
+
+When we run the conversion logic we take values from the user group 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/taler-revenue/*``. 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.
+
+We add new conversion rate group management endpoints:
+
+POST conversion-rate-group: create a new rate group
+GET conversion-rate-group: pagination over rate groups
+GET conversion-rate-group/$GROUP-ID:
+PATCH conversion-rate-group/$GROUP-ID:
+DELETE conversion-rate-group/$GROUP-ID:
+
+We add admin only ``conversion_rate_group`` optional field to POST /accounts and PATCH /accounts/$USERNAME.
+
+We add ``conversion_rate_group`` optional field and query filter to GET /accounts
+We add ``conversion_rate_group`` optional field to GET /accounts/$USERNAME
+
+TODO: should GET /accounts/$USERNAME return the conversion rate group and/or the conversion rate? (reduce the number of fetch for the SPA and improve consistency)
+\ No newline at end of file
diff --git a/design-documents/064-libeufin-conversion-rate-group.rst b/design-documents/064-libeufin-conversion-rate-group.rst
@@ -1,141 +0,0 @@
-DD 64: LibEufin Conversion Rate Group
-#####################################
-
-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;
-
- // Smallest possible regional amount, converted amount is rounded to this amount
- cashin_tiny_amount: 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;
-
- // Smallest possible fiat amount, converted amount is rounded to this amount
- cashout_tiny_amount: Amount;
-
- // Rounding mode used during cashout conversion
- cashout_rounding_mode: "zero" | "up" | "nearest";
- }
-
-This would become the ``default`` group, that will be used by all created users. The administrator would be able to create new groups that override some of the default properties:
-
-.. ts:def:: ConversionRateGroupRequest
-
- interface ConversionRateGroupRequest {
- // The name of this group
- name: string;
-
- // A description of the group
- 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;
-
- // 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;
- }
-
-.. ts:def:: ConversionRateGroup
-
- interface ConversionRateGroup {
- // The name of this group, null if default group
- name?: string;
-
- // A description of the group
- description?: string;
-
- // Group unique ID
- row_id: Integer;
-
- // Number of users affected to this group
- num_users: Integer;
-
- // 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;
-
- // 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;
- }
-
-When we run the conversion logic we take values from the user group 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/taler-revenue/*``. 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.
-
-We add new conversion rate group management endpoints:
-
-POST conversion-rate-group: create a new rate group
-GET conversion-rate-group: pagination over rate groups
-GET conversion-rate-group/$GROUP-ID:
-PATCH conversion-rate-group/$GROUP-ID:
-DELETE conversion-rate-group/$GROUP-ID:
-
-We add admin only ``conversion_rate_group`` optional field to POST /accounts and PATCH /accounts/$USERNAME.
-
-We add ``conversion_rate_group`` optional field and query filter to GET /accounts
-We add ``conversion_rate_group`` optional field to GET /accounts/$USERNAME
-
-TODO: should GET /accounts/$USERNAME return the conversion rate group and/or the conversion rate? (reduce the number of fetch for the SPA and improve consistency)
-\ No newline at end of file
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -74,4 +74,5 @@ 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
999-template
