circuit API tutorial

Adding section about using the SMS/e-mail provider.

2 files changed, 48 insertions, 1 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 96ca0e0c..88e1bdcd 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -20,6 +20,9 @@ only one demobank, named ``default``, is supported.  Such demobank
 activates the API segment ``/demobanks/default``, under which several
 APIs are then served.  The following sections describe all such APIs.
 
+
+.. _circuit-api:
+
 Circuit API
 ^^^^^^^^^^^
 
diff --git a/libeufin/local-currencies-tutorial.rst b/libeufin/local-currencies-tutorial.rst
index 743c91d6..e09a622d 100644
--- a/libeufin/local-currencies-tutorial.rst
+++ b/libeufin/local-currencies-tutorial.rst
@@ -1,7 +1,8 @@
 Create a local currency (experimental)
 ######################################
 
-This feature allows to register merchants to participate
+The following commands are based on the :ref:`Circuit API <circuit-api>`,
+that 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
@@ -40,6 +41,13 @@ to serve the bank for a currency named `NB`.
 In following step, we launch Sandbox by setting the administrator
 password as ``secret``.
 
+.. note::
+
+   The following command launches Sandbox so that it writes
+   TANs on the filesystem to ease the cash-out operations without
+   relying on an actual e-mail or SMS provider.  See section
+   FIXME for e-mail or SMS based TANs.
+
 .. code-block:: console
 
    $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret
@@ -233,3 +241,39 @@ again the balance, and expect one error like the following:
        "description" : "Customer 'circuit-shop' not found"
      }
    }
+
+
+E-mail or SMS TAN setup
+-----------------------
+
+SMS and E-mail TANs get sent via commands that
+are invoked by the Sandbox.  Sandbox learns about those commands
+via optional parameters to the ``serve`` command.
+
+.. note::
+
+  Future versions will allow setting the external commands
+  via the configuration; follow `#7527 <https://bugs.gnunet.org/view.php?id=7527>`_.
+
+Hence, starting Sandbox as shown in the following commands is
+the **only** requirement to use the aforementioned TAN channels.
+
+For the SMS TAN:
+
+.. code-block:: console
+
+   libeufin-sandbox serve --sms-tan sms_provider_command
+
+Alternatively, for the e-mail TAN:
+
+.. code-block:: console
+
+   libeufin-sandbox serve --email-tan email_provider_command
+
+Both commands will be passed the TAN to STDIN and the target
+phone number / e-mail address as their first command line argument.
+
+.. note::
+
+   The way the invoked commands interact with their providers
+   is out of the Sandbox scope.