063-libeufin-conversion-rate-classes.rst (6875B)
1 DD 63: LibEufin Conversion Rate Class 2 ##################################### 3 4 Summary 5 ======= 6 7 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. 8 9 Proposed Solution 10 ================= 11 12 The current global conversion rate schema is: 13 14 .. ts:def:: ConversionRate 15 16 interface ConversionRate { 17 // Minimum fiat amount authorised for cashin before conversion 18 cashin_min_amount: Amount; 19 20 // Exchange rate to buy regional currency from fiat 21 cashin_ratio: DecimalNumber; 22 23 // Regional amount fee to subtract after applying the cashin ratio. 24 cashin_fee: Amount; 25 26 // Rounding mode used during cashin conversion 27 cashin_rounding_mode: "zero" | "up" | "nearest"; 28 29 // Smallest possible fiat amount, converted amount is rounded to this amount 30 cashin_tiny_amount: Amount; 31 32 // Minimum regional amount authorised for cashout before conversion 33 cashout_min_amount: Amount; 34 35 // Exchange rate to sell regional currency for fiat 36 cashout_ratio: DecimalNumber; 37 38 // Fiat amount fee to subtract after applying the cashout ratio. 39 cashout_fee: Amount; 40 41 // Rounding mode used during cashout conversion 42 cashout_rounding_mode: "zero" | "up" | "nearest"; 43 44 // Smallest possible fiat amount, converted amount is rounded to this amount 45 cashout_tiny_amount: Amount; 46 47 } 48 49 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: 50 51 .. ts:def:: ConversionRateClassRequest 52 53 interface ConversionRateClassRequest { 54 // The name of this class 55 name: string; 56 57 // A description of the class 58 description?: string; 59 60 // Minimum fiat amount authorised for cashin before conversion 61 cashin_min_amount?: Amount; 62 63 // Exchange rate to buy regional currency from fiat 64 cashin_ratio?: DecimalNumber; 65 66 // Regional amount fee to subtract after applying the cashin ratio. 67 cashin_fee?: Amount; 68 69 // Rounding mode used during cashin conversion 70 cashin_rounding_mode?: "zero" | "up" | "nearest"; 71 72 // Minimum regional amount authorised for cashout before conversion 73 cashout_min_amount?: Amount; 74 75 // Exchange rate to sell regional currency for fiat 76 cashout_ratio?: DecimalNumber; 77 78 // Fiat amount fee to subtract after applying the cashout ratio. 79 cashout_fee?: Amount; 80 81 // Rounding mode used during cashout conversion 82 cashout_rounding_mode?: "zero" | "up" | "nearest"; 83 } 84 85 .. ts:def:: ConversionRateClass 86 87 interface ConversionRateClass { 88 // The name of this class 89 name: string; 90 91 // A description of the class 92 description?: string; 93 94 // Class unique ID 95 conversion_rate_class_id: Integer; 96 97 // Number of users affected to this class 98 num_users: Integer; 99 100 // Applied conversion rate 101 conversion_rate: ConversionRate; 102 103 // Minimum fiat amount authorised for cashin before conversion 104 cashin_min_amount?: Amount; 105 106 // Exchange rate to buy regional currency from fiat 107 cashin_ratio?: DecimalNumber; 108 109 // Regional amount fee to subtract after applying the cashin ratio. 110 cashin_fee?: Amount; 111 112 // Rounding mode used during cashin conversion 113 cashin_rounding_mode?: "zero" | "up" | "nearest"; 114 115 // Minimum regional amount authorised for cashout before conversion 116 cashout_min_amount?: Amount; 117 118 // Exchange rate to sell regional currency for fiat 119 cashout_ratio?: DecimalNumber; 120 121 // Fiat amount fee to subtract after applying the cashout ratio. 122 cashout_fee?: Amount; 123 124 // Rounding mode used during cashout conversion 125 cashout_rounding_mode?: "zero" | "up" | "nearest"; 126 } 127 128 .. ts:def:: ConversionRateClasses 129 130 interface ConversionRateClasses { 131 default: ConversionRate; 132 classes: ConversionRateClass[]; 133 } 134 135 136 After creating a new converion class, that needs to be associated with the user. 137 138 When we run the conversion logic we take values from the user class and fallback to the default values when they are ``null``. 139 140 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. 141 142 143 Taler Conversion Info API 144 ------------------------- 145 146 The version changes to v2. 147 148 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. 149 150 A ``/rate`` to get, the potentially private, user specific conversion rate. 151 152 Taler Core Bank API 153 ------------------- 154 155 The version changes to v9. 156 157 Deprecated API that should not longer be used: 158 159 160 Removed the field ``min_cashout``, not longer used. Replaced by a convertion rate class reference. 161 162 Removed sub-api ``/conversion-info/*`` 163 164 165 We added new endpoints for conversion rate class management, only accesible by the admin user: 166 167 POST ``/conversion-rate-classes`` 168 169 GET ``/conversion-rate-classes`` 170 171 GET ``/conversion-rate-classes/$CLASS-ID`` 172 173 PATCH ``/conversion-rate-classes/$CLASS-ID`` 174 175 DELETE ``/conversion-rate-classes/$CLASS-ID`` 176 177 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). 178 179 180 181 Added query filter to GET ``/accounts`` (listing accounts) 182 183 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. 184 185 186 187 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. 188 189 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. 190 191 192 193 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. 194 195 TODO: Add to the spec 196 ^^^^^^^^^^^^^^^^^^^^^ 197 198 * Add missing error code so the client can create better error message for those 199