From 2f7271352d8a39ff4693fc41dc8981035f566f08 Mon Sep 17 00:00:00 2001 From: MS Date: Wed, 11 Jan 2023 10:55:45 +0100 Subject: local currency tutorial --- libeufin/local-currencies-tutorial.rst | 235 +++++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 libeufin/local-currencies-tutorial.rst (limited to 'libeufin') 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 `. + +After having built libEufin (see :ref:`dedicate section `), +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 `_, +and try again to delete the account `like already done `_ + +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" + } + } -- cgit v1.2.3