circuit API: second pass.

Informs about the loss and exchange rates.

1 files changed, 95 insertions, 48 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 1bbbec35..1bd3250b 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -157,10 +157,27 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
    .. ts:def:: CircuitAccounts
 
      interfaces CircuitAccounts {
-       customers: CircuitAccountData[]; 
+       customers: CircuitAccountMinimalData[]; 
      }
 
-   .. _circuit-account-data:
+   .. ts:def:: CircuitAccountMinimalData
+     
+     interface CircuitAccountMinimalData {
+       // Username
+       username: string;
+
+       // Legal subject owning the account.
+       name: string;
+
+     }
+
+.. http:get:: /accounts/$username
+
+   Obtains information relative to the account owned by
+   ``$username``.  The request is available to the administrator
+   and ``$username`` itself.
+
+   **Response:**
 
    .. ts:def:: CircuitAccountData
      
@@ -185,17 +202,6 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
        cashout_address: string;
      }
 
-
-.. http:get:: /accounts/$username
-
-   Obtains information relative to the account owned by
-   ``$username``.  The request is available to the administrator
-   and ``$username`` itself.
-
-   **Response:**
-
-   `CircuitAccountData <circuit-account-data_>`_
-
    :http:statuscode:`403 Forbidden`:
      Unallowed user tried the operation.
 
@@ -208,10 +214,10 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
    operation.  The request is only available to ordinary users, not
    to the administrator.
 
-   .. note:
-     Fees likely apply to this operation, in order to incentivize
-     the circulation of the local currency.  Please refer to the bank's
-     terms and conditions. 
+   .. note::
+     
+     Consult the `cashout rates call <cashout-rates_>`_ to learn
+     about any applicable fee or exchange rate.
 
    **Request:**
 
@@ -236,19 +242,19 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
        // the user's external bank account.
        subject?: string;
 
-       // That is the amount that the user specified
-       // to cashout.  It is therefore NOT affected by
-       // the exchange rate.
-       amount_before_conversion: string; 
+       // That is the plain amount that the user specified
+       // to cashout.  It has the $currency:$amount format,
+       // where $currency is the circuit currency.
+       amount_debit: string; 
 
        // That is the amount that will effectively be
        // transferred by the bank to the user's bank
-       // account external to the circuit.  It therefore
-       // must be affected by the exchange rate.  The
-       // reason to have it here is to force the UI to
-       // calculate this value and show it to the user
-       // before creating the cashout operation.
-       amount_after_conversion: string; 
+       // account, that is external to the circuit.
+       // It has the $currency:$amount format, where
+       // $currency is the fiat currency and $amount
+       // is calculated after the cashout fee and the
+       // exchange rate.  See the /cashout-rates call.
+       amount_credit: string; 
 
        // Which channel the TAN should be sent to.  If
        // this field is missing, it defaults to SMS.
@@ -322,40 +328,81 @@ The following endpoints are served under ``/demobanks/default/circuit-api``.
    :http:statuscode:`412 Precondition failed`:
      ``$cashoutId`` was already confirmed or aborted.
 
-.. http:get:: /cashouts/$cashoutId
+.. _cashout-rates:
 
-   Informs about the status of the ``$cashoutId`` operation.
-   The request is available to the administrator and the original author.
+.. http:get:: /cashout-rates
 
-   **Response:**
+   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.
 
-   `CashoutStatusResponse <cashout-status_>`_
+   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*.
 
-   .. _cashout-status:
+   The following calculation shows how to use those values.
 
-   .. ts:def:: CashoutStatus
+   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
+
+   **Response:**
 
-     interface CashoutStatusResponse {
+   .. ts:def:: CashoutRates
 
-       status: CashoutStatus;
+     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;
      }
 
-   .. ts:def:: CashoutStatus
+
+.. http:get:: /cashouts/$cashoutId
+
+  Informs about the status of the ``$cashoutId`` operation.
+  The request is available to the administrator and the original author.
+
+  **Response:**
+
+  `CashoutStatusResponse <cashout-status_>`_
+
+  .. _cashout-status:
+
+  .. ts:def:: CashoutStatus
+
+    interface CashoutStatusResponse {
+
+      status: CashoutStatus;
+    }
+
+  .. ts:def:: CashoutStatus
      
-     enum CashoutStatus {
+    enum CashoutStatus {
 
-       // The payment was initiated after a valid
-       // TAN was received by the bank.
-       CONFIRMED = "confirmed",
+      // The payment was initiated after a valid
+      // TAN was received by the bank.
+      CONFIRMED = "confirmed",
 
-       // The cashout was created and now waits
-       // for the TAN by the author.
-       PENDING = "pending",
+      // The cashout was created and now waits
+      // for the TAN by the author.
+      PENDING = "pending",
 
-       // The cashout was aborted before the
-       // confirmation.
-       ABORTED = "aborted"
-     }
+      // The cashout was aborted before the
+      // confirmation.
+      ABORTED = "aborted"
+    }
 
   **Response:**