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" } }