[taler-docs] branch master updated: drafting x-libeufin-bank how-to

[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 9185a1b  drafting x-libeufin-bank how-to
9185a1b is described below

commit 9185a1bb40c33c14230bd7ab2dd4f11af201d589
Author: MS <ms@taler.net>
AuthorDate: Mon Apr 3 17:08:09 2023 +0200

    drafting x-libeufin-bank how-to
---
 libeufin/nexus-tutorial.rst | 148 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 121 insertions(+), 27 deletions(-)

diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index fc7b9f0..64f4a69 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -425,28 +425,6 @@ Now the list of transactions has grown by several entries:
      } ]
    }
 
-Lastly, you will want to schedule some tasks to run
-periodically in the background.
-This enables the Nexus to interact in (almost) real-time with the bank.
-
-.. code-block:: console
-
-   $ libeufin-cli accounts task-schedule jrluser \
-       --task-type submit \
-       --task-name submit-payments-each-second \
-       --task-cronspec "* * *"
-   $ libeufin-cli accounts task-schedule jrluser \
-       --task-type fetch \
-       --task-name fetch-reports-each-second \
-       --task-cronspec "* * *" \
-       --task-param-level report \
-       --task-param-range-type latest
-
-The first task submits payments and the second fetches reports.
-Both are specified to run every second (cronspec ``"* * *"``).
-To reduce the frequency to every five seconds, use the cronspec ``"*/5 * *"``
-(remember to quote, to protect from shell filename expansion).
-
 .. note::
 
    The sandbox is intended as a testing tool and thus not stable.
@@ -464,8 +442,8 @@ For more information on the available commands, use the 
built-in ``--help`` flag
 The full functionality of the sandbox is available via
 the :ref:`Sandbox API <sandbox-api>`.
 
-Connect Nexus with an EBICS account
-===================================
+Connect Nexus with the bank.
+============================
 
 Nexus relies on a database, which you must specify using a JDBC
 connection URI with the ``LIBEUFIN_NEXUS_DB_CONNECTION`` environment
@@ -518,7 +496,13 @@ set to ``foo``, and ``LIBEUFIN_NEXUS_PASSWORD`` to the 
value given for its passw
 in the previous step (with the ``libeufin-nexus superuser`` command).  The
 ``LIBEUFIN_NEXUS_URL`` could be given as ``http://localhost:5017``.
 
-Next, we create a EBICS *bank connection* that Nexus can use to communicate 
with the bank.
+Nexus speaks two protocols to reach the bank: EBICS and x-libeufin-bank.
+In Nexus speech, each protocol is also known as a *bank connection*.
+The following two sections show how to setup such bank connections.  Note:
+only one is needed to operate!
+
+EBICS
+-----
 
 .. note::
 
@@ -562,8 +546,8 @@ a backup copy* of such keys.
           $CONNECTION_NAME
 
 At this point, Nexus needs to both communicate its keys to the bank, and
-download the bank's keys.  This synchronization happens through the INI, HIA, 
and
-finally, HPB message types.
+download the bank's keys.  This synchronization happens through the INI,
+HIA, and finally, HPB message types.
 
 After the electronic synchronization, the subscriber must confirm their keys
 by sending a physical mail to the bank.  The following command helps generating
@@ -598,6 +582,8 @@ The command below downloads the list of the bank accounts 
offered by ``$CONNECTI
 
 It is now possible to list the accounts offered by the connection.
 
+.. _list-connections:
+
 .. code-block:: console
 
   $ libeufin-cli \
@@ -628,6 +614,114 @@ under a certain connection (``$CONNECTION_NAME``), it is 
possible
 to accomplish the usual operations for any bank account: asking for the
 list of transactions, and making a payment.
 
+The last step is to create background tasks that fetch and submit
+the information from and to the bank.  The following command submits
+the prepared payments to the bank each second.
+
+.. _submit-task:
+
+.. code-block:: console
+
+  $ libeufin-cli accounts task-schedule $LOCAL_ACCOUNT_NAME \
+      --task-type submit \
+      --task-name submit-payments-each-second \
+      --task-cronspec "* * *"
+
+The following step downloads from the bank all the new transactions,
+each second.  The ``report`` value indicates that Nexus is interested
+in the transactions which did reach already the booked state, in order
+to provide faster times to its users.
+
+.. code-block:: console
+
+  $ libeufin-cli accounts task-schedule $LOCAL_ACCOUNT_NAME \
+      --task-type fetch \
+      --task-name fetch-reports-each-second \
+      --task-cronspec "* * *" \
+      --task-param-level report \
+      --task-param-range-type latest
+
+For example, the cronspec can be changed to every five seconds by the
+following value: ``"*/5 * *"`` (remember to quote, to protect from shell
+filename expansion).
+
+x-libeufin-bank
+---------------
+
+This is a faster bank connection, because it relies on JSON and HTTP basic
+auth, as oppsed to EBICS XML and RSA cryptography.  It is also planned to equip
+the server side with long-polling, in order to loop more slowly when asking
+for new data.
+
+The first step is to create one x-libeufin-bank connection.  Make sure that
+the usual env variables LIBEUFIN_NEXUS_USERNAME, LIBEUFIN_NEXUS_PASSWORD, and
+LIBEUFIN_NEXUS_URL are set.  The following command instructs Nexus about
+the bank URL and the credentials it needs
+
+.. code-block:: console
+
+  libeufin-cli connections new-xlibeufinbank-connection \
+    --bank-url "http://localhost:5016/demobanks/default/access-api"; \
+    --username jrluser \
+    --password easy \
+    $CONNECTION_NAME
+
+The ``--password`` option can be omitted, and in this case the CLI will
+prompt to collect it.
+
+  The credentials are exactly the same as the ones used to register a
+  new bank account at Sandbox.
+
+Once the connection is created, we need -- just as in the EBICS case --
+the "connect" step.  In this case, the connect step will check if the
+credentials and URL are correct and (as a side effect) download basic
+information about the bank account.
+
+.. code-block:: console
+
+  libeufin-cli connections connect $CONNECTION_NAME
+
+As a proof, you can `list <list-connections_>`_ which bank account
+arrived at Nexus after the connect command succeeds.  Now the bank
+account can be imported under a local name at Nexus, just as it was
+in the EBICS case.
+
+.. note::
+
+  One main difference with EBICS is that now we don't need the
+  ``download-bank-accounts`` step, because ``connect`` carried
+  it out as a side effect of checking the credentials.
+
+
+.. code-block:: console
+
+  libeufin-cli connections import-bank-account \
+    --offered-account-id jrluser \
+    --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \
+    $CONNECTION_NAME
+
+
+Now that the account is imported, the background tasks need to
+be setup, to provide always the most updated information from the
+bank.
+
+The submit task can be `the same <submit-task_>`_ as EBICS.  The fetch
+task however needs one different setting, and namely it has to require
+``statement`` instead of 'report' because x-libeufin-bank has only the
+booked state for transactions.  The time range is also different, because
+x-libeufin-bank does NOT offer ``latest``.  Any unsupported setting should
+however generate one error and therefore not create wrong background tasks.
+
+.. code-block:: console
+
+  libeufin-cli accounts task-schedule \
+    --task-type fetch \
+    --task-name fetch-every-second \
+    --task-cronspec "* * *" \
+    --task-param-level statement \
+    --task-param-range-type since-last \
+    $LOCAL_ACCOUNT_NAME
+
 Request history of transactions
 ===============================
 

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