[taler-docs] branch master updated: Addressing NLnet review.

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 4e76623  Addressing NLnet review.
4e76623 is described below

commit 4e76623790cd7a2c8190e6396750844b868e189c
Author: MS <ms@taler.net>
AuthorDate: Thu Mar 2 11:16:10 2023 +0100

    Addressing NLnet review.
---
 libeufin/api-sandbox.rst               |  34 ++++++++
 libeufin/circuit-cli-commands.rst      | 149 +++++++++++++++++++++++++++++++++
 libeufin/local-currencies-tutorial.rst |  28 +++++--
 3 files changed, 203 insertions(+), 8 deletions(-)

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 847d260..94cc0c8 100644
--- 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
new file mode 100644
index 0000000..7ce5e46
--- /dev/null
+++ 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
index 84ab48a..1c44225 100644
--- 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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.