[taler-docs] 02/06: circuit API: define /config

[gnunet]

This is an automated email from the git hooks/post-receive script.

oec pushed a commit to branch master
in repository docs.

commit 4355a59c0fb5296add856403e4fc398f5180608e
Author: MS <ms@taler.net>
AuthorDate: Tue Dec 20 14:55:25 2022 +0100

    circuit API: define /config
---
 libeufin/api-sandbox.rst | 63 +++++++++++++++++++++++++-----------------------
 1 file changed, 33 insertions(+), 30 deletions(-)

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 75b4bcf..fff8119 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -367,44 +367,47 @@ Cashouts
 
 .. _cashout-rates:
 
-.. http:get:: /cashout-rates
+.. http:get:: /config
 
-   Informs about the rates that apply to cashouts:
-   *loss* rate and *exchange* rate.
-
-   The loss rate affects always negatively the amount
-   to cashout, and it is employed to discourage such
-   operation.  It is applied to the amount expressed
-   in the circuit currency, and outputs a new amount
-   in the same currency.
+   **Response:**
 
-   The exchange rate is then the actual conversion rate
-   from the circuit's to the fiat currency.  Therefore
-   it is applied to the amount expressed in the circuit
-   currency and outputs a new amount *in fiat currency*.
+   .. ts:def:: Config
 
-   The following calculation shows how to use those values.
+     interface Config {
+       // Name of this API, always "circuit".
+       name: string;
+       // API version in the form $n:$n:$n
+       version: string;
+       // Contains ratios and fees related to buying
+       // and selling the circuit currency.
+       ratios_and_fees: RatiosAndFees;
+     }
 
-   Given a wanted cashout amount of 10 units of the circuit
-   currency, a loss rate of 0.05, and an exchange rate of 0.9,
-   then the final amount in fiat currency that will be
-   transferred to the user's external bank account would be:
-   
-     (10 - (10 * 0.05)) * 0.9 = 8.55
+   .. ts:def:: RatiosAndFees
+
+     interface RatiosAndFees {
+       // Exchange rate to buy the circuit currency from fiat.
+       buy_at_ratio: float; 
+       // Exchange rate to sell the circuit currency for fiat.
+       sell_at_ratio: float; 
+       // Fee to subtract after applying the buy ratio.
+       buy_in_fee: float;
+       // Fee to subtract after applying the sell ratio.
+       sell_out_fee: float;
+     }
 
-   **Response:**
 
-   .. ts:def:: CashoutRates
+   Example.  Given a circuit currency CC, a fiat currency FC,
+   a *sell_at_ratio* = 0.9 and *sell_out_fee* = 0.03, selling
+   10 CC would result in the following FC: (10 * 0.9) - 0.03
+   = 8.97 FC.  On the other hand, given *buy_at_ratio* = 1.1
+   and *buy_in_fee* = 0.01, a user wanting to spend 10 FC to
+   buy the CC would result in the following CC: (10 * 1.1) -
+   0.01 = 10.99 CC.
 
-     interface CashoutRates {
-       
-       // A stringified float indicating the cashout loss rate.
-       loss_rate: string;
-       // A stringified float indicating the conversion rate
-       // from the circuit to the fiat currency.
-       exchange_rate: string;
-     }
+   .. note::
 
+     the terms 'sell out' and 'cashout' may be used interchangeably.
 
 .. http:get:: /cashouts/$cashoutId
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.