commit f4fc19824d0bd9510badb855b7a2138542a084a5
parent a34088e546379b628c317df9787136a344edc3ee
Author: Sebastian <sebasjm@gmail.com>
Date: Wed, 25 Jun 2025 12:59:14 -0300
added clarification
Diffstat:
2 files changed, 51 insertions(+), 15 deletions(-)
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -388,13 +388,13 @@ Account Management
* ``TALER_EC_BANK_UNALLOWED_DEBIT`` : admin account does not have sufficient funds to grant bonus.
* ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was attempted, like ``admin`` or ``bank``
* ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT`` : a non-admin user has tried to create an account with a customer debt limit.
- * ``TALER_EC_BANK_NON_ADMIN_SET_CONVERSION_RATE_CLASS`` : a non-admin user has tried to create an account with a conversion rate class.
+ * ``TALER_EC_BANK_NON_ADMIN_SET_CONVERSION_RATE_CLASS`` : a non-admin user has tried to create an account with a conversion rate class. Since **v9**
* ``TALER_EC_BANK_NON_ADMIN_SET_TAN_CHANNEL`` : a non-admin user has tried to create an account with 2fa.
* ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED``: ``tan_channel`` is not supported, check bank config to find supported ones.
* ``TALER_EC_BANK_MISSING_TAN_INFO``: the user did not share any contact data where to send the TAN via ``tan_channel``.
* ``TALER_EC_BANK_PASSWORD_TOO_SHORT``: password is shorter than 8 characters.
* ``TALER_EC_BANK_PASSWORD_TOO_LONG``: password is longer than 64 characters.
- * ``TALER_EC_BANK_CONVERSION_RATE_CLASS_UNKNOWN`` : no conversion rate class found for this id.
+ * ``TALER_EC_BANK_CONVERSION_RATE_CLASS_UNKNOWN`` : no conversion rate class found for this id. Since **v9**
**Details:**
@@ -465,10 +465,10 @@ Account Management
* ``TALER_EC_BANK_NON_ADMIN_PATCH_LEGAL_NAME`` : a non-admin user has tried to change their legal name.
* ``TALER_EC_BANK_NON_ADMIN_PATCH_CASHOUT`` : a non-admin user has tried to change their cashout account.
* ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT`` : a non-admin user has tried to change their debt limit.
- * ``TALER_EC_BANK_NON_ADMIN_SET_CONVERSION_RATE_CLASS`` : a non-admin user has tried to create an account with a conversion rate class.
+ * ``TALER_EC_BANK_NON_ADMIN_SET_CONVERSION_RATE_CLASS`` : a non-admin user has tried to create an account with a conversion rate class. Since **v9**
* ``TALER_EC_BANK_TAN_CHANNEL_NOT_SUPPORTED`` : ``tan_channel`` is not supported, check bank config to find supported ones.
* ``TALER_EC_BANK_MISSING_TAN_INFO`` : the user did not share any contact data where to send the TAN via ``tan_channel``.
- * ``TALER_EC_BANK_CONVERSION_RATE_CLASS_UNKNOWN`` : no conversion rate class found for this id.
+ * ``TALER_EC_BANK_CONVERSION_RATE_CLASS_UNKNOWN`` : no conversion rate class found for this id. Since **v9**
.. _account-password-reconfig:
@@ -1832,4 +1832,4 @@ Endpoints for Integrated Sub-APIs
Global conversion rate infos.
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
+ by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`.
diff --git a/design-documents/063-libeufin-conversion-rate-classes.rst b/design-documents/063-libeufin-conversion-rate-classes.rst
@@ -39,7 +39,7 @@ The current global conversion rate schema is:
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:
+This would become the ``default`` class with ``conversion_rate_class_id = 0``, that will be used by all new users that are created with ``conversion_rate_class_id = null`` or updated with a PATCH request with ``conversion_rate_class_id = null``. The administrator would be able to create new classes with values that override some of the default properties:
.. ts:def:: ConversionRateClassRequest
@@ -125,11 +125,19 @@ This would become the ``default`` class, that will be used by all created users.
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.
+
+After creating a new converion class, that needs to be associated with the user.
+
+When we run the conversion logic we take values from the user class and fallback to the default values when they are ``null``.
+
+If an admin want to prevent a group of user or exchanges from doing conversion between currencies then those users should be associated with a conversion class with ``cashin_ratio = 0`` to disable any cashin operation or ``cashout_ratio = 0`` to disable any cashout operation.
+
Taler Conversion Info API
-------------------------
+The version changes to v2.
+
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.
A ``/rate`` to get, the potentially private, user specific conversion rate.
@@ -137,18 +145,48 @@ 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:
+The version changes to v9.
+
+Deprecated API that should not longer be used:
+
+
+Removed the field ``min_cashout``, not longer used. Replaced by a convertion rate class reference.
+
+Removed sub-api ``/conversion-info/*``
+
+
+We added new endpoints for conversion rate class management, only accesible by the admin user:
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/*``
+Added an admin-only ``conversion_rate_class_id`` field of type `Integer`. It is optional field to POST ``/accounts`` requests (creating an account) and PATCH ``/accounts/$USERNAME`` requests (updating an account).
+
+
+
+Added query filter to GET ``/accounts`` (listing accounts)
+
+Added ``conversion_rate_class`` field of type `AccountConversionRateClass` of GET ``/accounts/$USERNAME`` request with all the information about the convertion rate. ``conversion_rate_class_id`` points to the class assigned to the user but the values of the fields could be from the default class if the assigned class is not completed.
+
+
+
+Added sub-api ``/conversion-rate-class/$CLASS-ID/conversion-info/*``. This is used by admin to run simulations to know how the conversion rate behaves regartherless of the user on the group.
+
+Added sub-api ``/accounts/$USERNAME/conversion-info/*``. This is used by normal users get the right convertion rate for it's own operations. For user with ``is_taler_exchange = true`` this sub-api will be public.
+
+
+
+There are also new error code reported by the API, like ``TALER_EC_BANK_CONVERSION_RATE_CLASS_UNKNOWN`` when the client is trying to create or update an account.
+
+TODO: Add to the spec
+^^^^^^^^^^^^^^^^^^^^^
-We add admin only ``conversion_rate_class_id`` `Integer` optional field to POST ``/accounts`` and PATCH ``/accounts/$USERNAME`` and remove ``min_cashout``.
+* Add missing error code so the client can create better error message for those
-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
