commit 4e76623790cd7a2c8190e6396750844b868e189c
parent 2e03169b957084fcce18960d96ae2f0926df01c4
Author: MS <ms@taler.net>
Date: Thu, 2 Mar 2023 11:16:10 +0100
Addressing NLnet review.
Diffstat:
3 files changed, 203 insertions(+), 8 deletions(-)
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
@@ -40,9 +40,15 @@ For brevity, the list of response statuses for each endpoint may not be exhausti
The following endpoints are served under ``/demobanks/default/circuit-api``.
+The cliend side of this API is offered both along the
+:doc:`CLI <circuit-cli-commands>` and the SPA. The SPA is generally served
+along Sandbox ``/`` path.
+
Accounts
--------
+.. _circuit-register:
+
.. http:post:: /accounts
Create a new bank account. Only the administrator is allowed.
@@ -107,6 +113,9 @@ Accounts
At least one registration detail was not available,
the error message should inform about it.
+
+.. _circuit-delete-account:
+
.. http:delete:: /accounts/$username
Delete the account whose username is ``$username``. The deletion
@@ -126,6 +135,8 @@ Accounts
The balance was not zero.
+.. _circuit-reconfig:
+
.. http:patch:: /accounts/$username
Allows the administrator and the user to reconfigure
@@ -172,6 +183,9 @@ Accounts
The account pointed by ``$username``
was not found.
+
+.. _circuit-password-reconfig:
+
.. http:patch:: /accounts/$username/auth
Allows administrators *and* ordinary users to
@@ -192,6 +206,9 @@ Accounts
:http:statuscode:`204 No content`:
Operation successful.
+
+.. _circuit-account-list:
+
.. http:get:: /accounts
Obtains a list of the accounts registered at the bank.
@@ -239,6 +256,9 @@ Accounts
:http:statuscode:`403 Forbidden`:
A ordinary user invoked this call.
+
+.. _circuit-account-info:
+
.. http:get:: /accounts/$username
Obtains information relative to the account owned by
@@ -272,6 +292,8 @@ Accounts
Cashouts
--------
+.. _circuit-cashout:
+
.. http:post:: /cashouts
Initiates a conversion to fiat currency. The account to be
@@ -365,6 +387,9 @@ Cashouts
:http:statuscode:`503 Service unavailable`:
The bank does not support the TAN channel for this operation.
+
+.. _circuit-cashout-abort:
+
.. http:post:: /cashouts/$cashoutId/abort
Aborts the ``$cashoutId`` operation. Original author
@@ -381,6 +406,9 @@ Cashouts
:http:statuscode:`412 Precondition failed`:
``$cashoutId`` was already confirmed.
+
+.. _circuit-cashout-confirm:
+
.. http:post:: /cashouts/$cashoutId/confirm
Confirms the ``$cashoutId`` operation by accepting its
@@ -461,6 +489,9 @@ Cashouts
the terms 'sell out' and 'cashout' may be used interchangeably.
+
+.. _circuit-cashouts:
+
.. http:get:: /cashouts
Returns the list of all the (pending and confirmed) cash-out operations.
@@ -494,6 +525,9 @@ Cashouts
the ``account`` parameter or by passing to it someone
else's username.
+
+.. _circuit-cashout-details:
+
.. http:get:: /cashouts/$cashoutId
Informs about the status of the ``$cashoutId`` operation.
diff --git a/libeufin/circuit-cli-commands.rst b/libeufin/circuit-cli-commands.rst
@@ -0,0 +1,149 @@
+The following list shows all the CLI subcommands
+acting as the Circuit API's client side. Each section
+name is one subcommand available in this pattern:
+``libeufin-cli sandbox demobank $subcommand``.
+
+Finally, each section name links to the related API
+documentation of the endpoint being addressed.
+
+:ref:`circuit-account-info <circuit-account-info>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Retrieve Circuit information about one account. Useful to get cash-out
+ address and contact details.
+
+Options:
+ --username TEXT Username of the account to retrieve. It defaults to
+ LIBEUFIN_SANDBOX_USERNAME and doesn't accept 'admin'.
+ --help Show this message and exit.
+
+:ref:`circuit-accounts <circuit-account-list>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Gets the list of all the accounts managed by the Circuit. Only 'admin'
+ allowed
+
+Options:
+ --help Show this message and exit.
+
+:ref:`circuit-cashout <circuit-cashout>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Create a cash-out operation. If successful, the user gets a TAN.
+
+Options:
+ --subject TEXT Payment subject to associate to the outgoing and
+ incoming payments that are associated with this cash-
+ out operation.
+ --amount-debit TEXT Amount that will debited to the local currency
+ account, in the <currency>:X.Y format. [required]
+ --amount-credit TEXT Amount that will credited to the fiat currency
+ account, in the <currency>:X.Y format. [required]
+ --tan-channel TEXT Indicates how to send the TAN to the user: 'sms',
+ 'email' and 'file' are valid values. If missing, the
+ bank defaults to SMS. 'file' makes the server write
+ the TAN to /tmp/libeufin-cashout-tan.txt, normally
+ used for testing.
+ --help Show this message and exit.
+
+
+:ref:`circuit-cashout-abort <circuit-cashout-abort>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Abort a cash-out operation. Admin and author are allowed to request.
+
+Options:
+ --uuid TEXT UUID of the cash-out operation to abort. [required]
+ --help Show this message and exit.
+
+
+:ref:`circuit-cashout-confirm <circuit-cashout-confirm>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Confirm a cash-out operation. Only the author is allowed (no admin).
+
+Options:
+ --tan TEXT TAN that authorizes the cash-out operaion. [required]
+ --uuid TEXT UUID of the cash-out operation to confirm. [required]
+ --help Show this message and exit.
+
+
+:ref:`circuit-cashout-details <circuit-cashout-details>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Retrieve status information about one cash-out operation. Admin and author
+ are allowed to request.
+
+Options:
+ --uuid TEXT UUID of the cash-out operation to retrieve. [required]
+ --help Show this message and exit.
+
+
+:ref:`circuit-cashouts <circuit-cashouts>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Gets the list of all the pending and confirmed cash-out operations.
+
+Options:
+ --help Show this message and exit.
+
+
+:ref:`circuit-delete-account <circuit-delete-account>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Delete one account. Only available to the administrator and for accounts
+ with zero balance.
+
+Options:
+ --username TEXT account to delete [required]
+ --help Show this message and exit.
+
+
+:ref:`circuit-password-reconfig <circuit-password-reconfig>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Ask interactively to change the password. It needs administrator or owner
+ credentials
+
+Options:
+ --username TEXT Username whose password will change. Defaults to
+ LIBEUFIN_SANDBOX_USERNAME and doesn't accept 'admin' as a
+ value.
+ --help Show this message and exit.
+
+
+:ref:`circuit-reconfig <circuit-reconfig>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Reconfigure an account with cash-out capabilities. It needs administrator
+ or owner credentials
+
+Options:
+ --phone TEXT Phone number for the SMS TAN
+ --email TEXT E-mail address for receiving the TAN
+ --cashout-address TEXT Payto address where to send fiat payments on cash-
+ outs [required]
+ --username TEXT Username associated with the account to reconfigure.
+ It defaults to LIBEUFIN_SANDBOX_USERNAME and doesn't
+ accept 'admin'.
+ --help Show this message and exit.
+
+
+:ref:`circuit-register <circuit-register>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Register a new account with cash-out capabilities. It needs administrator
+ credentials, and the new account password exported in
+ LIBEUFIN_NEW_CIRCUIT_ACCOUNT_PASSWORD.
+
+Options:
+ --username TEXT new account username [required]
+ --cashout-address TEXT Payto address where to send fiat payments on cash-
+ outs [required]
+ --name TEXT Legal name associated to the account. [required]
+ --phone TEXT SMS where to send the cash-out TAN.
+ --email TEXT E-mail address where to send the cash-out TAN.
+ --internal-iban TEXT Which IBAN to associate to this account. The IBAN
+ participates only in the local currency circuit. If
+ missing, the bank generates one.
+ --help Show this message and exit.
diff --git a/libeufin/local-currencies-tutorial.rst b/libeufin/local-currencies-tutorial.rst
@@ -1,18 +1,20 @@
Create a local currency (experimental)
######################################
-This LibEuFin tutorial shows how to manage a bank account
-in the local currency, and how to convert assets from the
-local to the fiat currency. Such conversion is called *cash-out*.
+This tutorial shows how to setup LibEuFin to act as the
+bank of a local currency. The main features include the
+registration and removal of user accounts, and the possibility
+to convert the local currency into fiat.
-This tutorial is based on the :ref:`Circuit API <circuit-api>`,
-and more general information about libEufin can be found in the
-:doc:`How-To page </libeufin/nexus-tutorial>`.
+The banking capabilities used along the tutorial live in a
+LibEuFin service called *Sandbox*. In particular, we'll rely
+on the :ref:`Circuit API <circuit-api>`. More information
+about libEufin can be found in the :doc:`How-To page </libeufin/nexus-tutorial>`.
The first step is :ref:`building LibEuFin <building-from-source>`.
-If the installation succeeded, configure *Sandbox* (= the service
-acting as the bank) with the following command.
+If the installation succeeded, configure *Sandbox* with the
+following command.
.. code-block:: console
@@ -239,6 +241,16 @@ error like the following:
}
+.. note::
+
+ Every Circuit API endpoint is addressed by a CLI subcommand
+ whose name starts with ``circuit-``. The following command
+ shows them.
+
+ .. code-block:: console
+
+ libeufin-cli sandbox demobank | grep circuit
+
.. _email-sms-setup:
E-mail or SMS TAN setup
