local currency tutorial

1 files changed, 235 insertions, 0 deletions

diff --git a/libeufin/local-currencies-tutorial.rst b/libeufin/local-currencies-tutorial.rst
new file mode 100644
index 00000000..e3ff3f06
--- /dev/null
+++ b/libeufin/local-currencies-tutorial.rst
@@ -0,0 +1,235 @@
+Create a local currency (experimental)
+######################################
+
+This feature allows to register merchants to participate
+in a local currency circuit.  The main difference with ordinary
+registrations is that this API offers to associate a `cash-out`
+address to the account, so that merchants can convert the local
+currency back to their fiat bank account.
+
+The following commands show a minimal use case where the
+administrator adds a merchant to the circuit, then this latter
+would cash-out their assets, and finally the administrator
+deletes the merchant account.
+
+More general information about libEufin can be found in the
+:doc:`How-To page </libeufin/nexus-tutorial>`.
+
+After having built libEufin (see :ref:`dedicate section <building-from-source>`),
+configure *Sandbox* (= the service acting as the bank) with the following command.
+
+.. code-block:: console
+
+   $ export LIBEUFIN_SANDBOX_DB_CONNECTION=jdbc:sqlite:/tmp/libeufin.sqlite3
+   $ libeufin-sandbox config --currency NB --without-registrations default
+
+.. note::
+
+   The ``--without-registrations`` option allows *only the administrator*
+   to add new accounts.
+
+.. note::
+
+   All the commands mentioned in the following steps
+   support a ``--help`` option that lists all the available
+   options under such command.
+
+If the configuration step succeeded, Sandbox should be ready
+to serve the bank for a currency named `NB`.
+
+In following step, we launch Sandbox by setting the administrator
+password as ``secret``.
+
+.. code-block:: console
+
+   $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret
+   $ libeufin-sandbox serve
+
+Sandbox should now be listening on the port 5000.  Check it with:
+
+.. code-block:: console
+
+   $ curl http://localhost:5000
+
+If Sandbox is correctly running, it should respond with a greeting message.
+At this point, the administrator can add a new merchant to the bank with the
+following command.
+
+.. code-block:: console
+
+   export LIBEUFIN_SANDBOX_USERNAME=admin
+   export LIBEUFIN_SANDBOX_PASSWORD=secret
+   export LIBEUFIN_SANDBOX_URL=http://localhost:5000/
+   export LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD=shop-secret
+
+   libeufin-cli \
+     sandbox \
+     demobank \
+     circuit-register \
+       --name "Circuit Shop" \
+       --username circuit-shop \
+       --cashout-address payto://iban/FIATIBAN \
+       --internal-iban LOCALIBAN
+
+If the previous step succeeded, the merchant should have
+access to their bank account with the *circuit-shop* username
+and *shop-secret* password.
+
+Check it by asking the merchant balance with this command:
+
+.. _check-balance:
+
+.. code-block:: console
+
+   export LIBEUFIN_SANDBOX_USERNAME=circuit-shop
+   export LIBEUFIN_SANDBOX_PASSWORD=shop-secret
+
+   libeufin-cli sandbox demobank info --bank-account circuit-shop
+
+The expected response looks like the following one:
+
+
+.. code-block:: console
+
+   {
+     "balance" : {
+       "amount" : "NB:0",
+       "credit_debit_indicator" : "credit"
+     },
+     "paytoUri" : "payto://iban/SANDBOXX/LOCALIBAN?receiver-name=Circuit+Shop",
+     "iban" : "LOCALIBAN"
+   }
+
+In the following example, the merchant creates a cash-out operation,
+trying to convert 1 NB back to the fiat currency.  The ``--amount-debit``
+option takes the amount that the merchant wants to be debited
+in their local currency bank account, whereas the ``--amount-credit``
+option is the calculation of the conversion rates as expected
+by the merchant.  The two values will be checked by the bank along
+this request, to make sure that both parties agree.
+
+.. note::
+  
+   The current version has a fixed **0.95** conversion rate for cashing
+   out.  Future version will make this value configurable.
+
+.. code-block:: console
+
+  libeufin-cli \
+    sandbox \
+    demobank \
+    circuit-cashout \
+      --amount-debit=NB:1 \
+      --amount-credit=FIAT:0.95 \
+      --tan-channel=file
+
+If the previous command succeeded, it returned a JSON looking
+like the following, although most likely having a **different**
+UUID.
+
+.. code-block:: console
+
+   {
+     "uuid" : "de12389b-e477-4a0c-829e-f779c1cfb3a0"
+   }
+
+The *uuid* represents the cash-out operation being just created
+and waiting to be confirmed with a TAN.
+
+.. note::
+
+   The current version provides **only** the local currency
+   side of such operation.  In other words, the merchant can
+   now only see a deduction on their local currency bank account
+   but no incoming payment in their fiat bank account.  Future
+   versions will implement this.
+
+Confirm now the cash-out operation by sending to the
+bank the TAN found in the file ``/tmp/libeufin-cashout-tan.txt``.
+Assuming that the TAN for it is ``WXYZ``, the next command will confirm
+it to the bank (please, use **your** UUID).
+
+.. code-block:: console
+
+   libeufin-cli \
+     sandbox demobank circuit-cashout-confirm \
+       --uuid de12389b-e477-4a0c-829e-f779c1cfb3a0 \
+       --tan WXYZ
+
+Check now that the cash-out operation appears as a outgoing
+transaction for the merchant:
+
+.. code-block:: console
+
+  libeufin-cli \
+    sandbox demobank list-transactions \
+      --bank-account circuit-shop
+
+The expected output should contain one line like the
+following.  That witnesses that the cash-out was correctly
+confirmed and scheduled to be transferred to the fiat
+account.
+
+.. code-block:: console
+
+   "subject" : "Cash-out of NB:1 to FIAT:0.95"
+
+The next commands show how to delete one account from
+the local currency circuit.  For the deletion to succeed,
+the account must have a balance of zero NB.  Because
+of the cash-out operation, the merchant has now -1 NB
+to their account, therefore the deletion will fail.  Check
+it with the following command:
+
+
+.. _delete-account:
+
+.. code-block:: console
+   
+   export LIBEUFIN_SANDBOX_USERNAME=admin
+   export LIBEUFIN_SANDBOX_PASSWORD=secret
+  
+   libeufin-cli \
+     sandbox demobank \
+     circuit-delete-account --username circuit-shop
+
+The expected output is:
+
+.. code-block:: console
+
+   Unexpected response status: 412
+   Response: {
+     "error" : {
+       "type" : "sandbox-error",
+       "description" : "Account circuit-shop doesn't have zero balance.  Won't delete it"
+     }
+   }
+
+
+The bank may now award 1 NB to the merchant to bring their
+balance to zero and finally delete the account.  The following
+command awards 1 NB to the merchant.
+
+.. code-block:: console
+
+   libeufin-cli \
+     sandbox demobank new-transaction \
+       --bank-account admin \
+       --payto-with-subject "payto://iban/SANDBOXX/LOCALIBAN?message=bring-to-zero" \
+       --amount NB:1
+
+Check if the balance returned to zero with `this command <check-balance_>`_,
+and try again to delete the account `like already done <delete-account_>`_
+
+Now the deletion command should succeed!  Try asking
+again the balance, and expect one error like the following:
+
+
+.. code-block:: console
+
+   {
+     "error" : {
+       "type" : "util-error",
+       "description" : "Customer 'circuit-shop' not found"
+     }
+   }