commit 9185a1bb40c33c14230bd7ab2dd4f11af201d589
parent 7792e845d355a3c4e7e44b05cbb873054bb522cf
Author: MS <ms@taler.net>
Date: Mon, 3 Apr 2023 17:08:09 +0200
drafting x-libeufin-bank how-to
Diffstat:
1 file changed, 121 insertions(+), 27 deletions(-)
diff --git 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
===============================
