[taler-docs] branch master updated: libeufin howto

[gnunet]

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

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 7ec5e10  libeufin howto
7ec5e10 is described below

commit 7ec5e10ea0ea131b1ad966e093b910acd776d435
Author: Florian Dold <florian@dold.me>
AuthorDate: Wed Jan 13 23:41:34 2021 +0100

    libeufin howto
---
 libeufin/nexus-tutorial.rst | 264 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 222 insertions(+), 42 deletions(-)

diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index fd12ad2..d20fb7a 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -1,19 +1,37 @@
-Nexus How-To
-############
+LibEuFin How-To
+###############
 
 .. contents:: Table of Contents
 
-Nexus is a Web service that provides a JSON abstraction layer to
-access bank accounts.  It is **not** itself a bank, but a translator
-between JSON requests and more structured banking protocols (like
-EBICS, for example), that are offered by actual banks.
+The LibEuFin Nexus is a Web service that provides a JSON abstraction layer to
+access bank accounts.  It does **not** itself offer banking services, but is a
+translator between JSON requests and other banking protocols (such as EBICS),
+that are offered by banks.
 
 This document explains how to set up Nexus to access a bank account
-via the EBICS protocol.  In order to follow all the steps below, the
-reader should already have one EBICS subscriber activated at their bank.
+via the EBICS protocol.
+
+In order to follow all the steps below, the reader should either
+have access to a bank account with EBICS support or follow the
+steps in "Setting up the Sandbox".
+
+
+Installing LibEuFin
+===================
+
+Downloading prebuilt binaries
+-----------------------------
+
+Pre-built packages can be obtained from the `taler.net website
+<https://taler.net/files/libeufin>`__.
+
+Unpack the ``libeufin-$version.zip `` file to
+your desired location (typically ``/opt`` or ``~/opt``) and make sure that 
your ``$PATH``
+variable contains the ``bin/`` directory of the unpacked archive.
+
+Building from source
+--------------------
 
-Obtain Nexus
-============
 Nexus belongs to the LibEuFin project, and can be downloaded via Git:
 
 .. code-block:: console
@@ -22,8 +40,6 @@ Nexus belongs to the LibEuFin project, and can be downloaded 
via Git:
 
 Note that Kotlin+Gradle should already work on the host system.
 
-Install Nexus
-=============
 Navigate into the *libeufin* local repository, and from top-level run:
 
 .. code-block:: console
@@ -32,6 +48,9 @@ Navigate into the *libeufin* local repository, and from 
top-level run:
   $ ./configure --prefix=$PREFIX
   $ make install
 
+Verifying your installation
+---------------------------
+
 In case of success, the two following commands should be found:
 
 .. code-block:: console
@@ -39,19 +58,109 @@ In case of success, the two following commands should be 
found:
   $ which libeufin-nexus
   $ which libeufin-cli
 
-Connect Nexus with a EBICS account
+
+(Optional) Configuring the Sandbox
 ==================================
 
-Use the following command to *(1) run the nexus service*:
+If you don't have access to a real bank account with an EBICS API, you can set
+up the sandbox.  The sandbox is a simplistic and incomplete implementation of a
+core banking system with EBICS access to bank accounts.
+
+For the following commands, the sandbox service must be running.
+The sandbox service is started with the following command:
+
+.. code-block:: console
+
+   $ libeufin-sandbox serve --port 5000
+
+To reset the state of the sandbox, delete the database.  By default,
+the database is a SQLite3 file in ``/tmp/libeufin-sandbox.sqlite3``.
+
+For invocations of the LibEuFin command line interface tool (``libeufin-cli``),
+the following environment variable must be set to the URL of the sandbox
+service:
+
+.. code-block:: console
+
+   export LIBEUFIN_SANDBOX_URL=http://localhost:5000/
+
+Verify that the sandbox is running:
+
+.. code-block:: console
+
+   $ libeufin-cli sandbox check
+
+Now an EBICS host can be created:
+
+.. code-block:: console
+
+   $ libeufin-cli sandbox ebicshost create --host-id testhost
+
+Note that most ``libeufin-cli`` subcommands will ask for input interactively if
+the respective value is not specified as a command line option.
+
+Next, create an EBICS subscriber (identified by the partner ID and user ID) 
for the host:
+
+.. code-block:: console
+
+   $ libeufin-cli sandbox ebicssubscriber create \
+       --host-id testhost --partner-id partner01 --user-id user01
+
+Create a bank account for the subscriber and add a sample transaction:
+
+.. code-block:: console
+
+   $ libeufin-cli sandbox ebicsbankaccount create \
+       --currency EUR \
+       --iban DE18500105172929531888 \
+       --bic INGDDEFFXXX \
+       --person-name "Jane Normal" \
+       --account-name "testacct01" \
+       --ebics-host-id testhost \
+       --ebics-user-id user01 \
+       --ebics-partner-id partner01
+
+The account name "testacct01" is the unique identifier of the account within
+the sandbox.  The EBICS parameter identify the subscriber that should have
+access to the bank account via EBICS.
+
+To populate the account with some test transactions, run the following command
+(note that we use the bankaccount subcommand, as this command is not
+EBICS-specific!):
+
+.. code-block:: console
+
+   $ libeufin-cli sandbox bankaccount generate-transactions testacct01
+
+Payments to a sandbox bank account can be listed as follows:
+
+.. code-block:: console
+
+   $ libeufin-cli sandbox bankaccount transactions testacct01
+
+.. note::
+
+   The sandbox is intended as a testing tool and thus not stable.
+
+   For more information on the available commands, use the built-in ``--help`` 
flag.
+
+   The full functionality of the sandbox is available via the API.
+
+
+Connect Nexus with an EBICS account
+===================================
+
+Use the following command to run the nexus service:
 
 .. code-block:: console
 
-  $ libeufin-nexus serve
+  $ libeufin-nexus serve --port 5001
 
-We recommend using the ``--db-conn-string=$DBCONN`` option.  It
-instructs Nexus to reach the database addressed by the connection
-string.  Only *SQLite* and *PostgreSQL (only via TCP)* are supported
-right now.
+By default, the SQLite3 database ``/tmp/libeufin-nexus.sqlite3`` will be used.
+
+We recommend using the ``--db-conn-string=$DBCONN`` option.  It instructs Nexus
+to reach the database addressed by the JDBC connection URI.  Only *SQLite* and
+*PostgreSQL (only via TCP)* are supported right now.
 
 For example:
 
@@ -59,27 +168,32 @@ For example:
 
   $ libeufin-nexus serve 
--db-conn-string=jdbc:postgresql://127.0.0.1:5433/libeufindb?user=foo&password=secret
 
-At this point a *(2) superuser account needs to be activated
-into the system*:
+At this point a superuser account needs to be created:
 
 .. code-block:: console
 
   $ libeufin-nexus superuser 
--db-conn-string=jdbc:postgresql://127.0.0.1:5433/libeufindb?user=foo&password=secret
 foo # Will interactively ask for password
 
-For simplicity, a superuser can as well act as a normal user, but a API
+For simplicity, a superuser can as well act as a normal user, but an API
 to create less privileged users is offered.
 
-Nexus needs now to associate the user to a EBICS subscriber that was
-activated on the bank.  In the Nexus terminology, this is called *(3)
-creating a EBICS connection*.
+.. note::
+
+  Privilege separation is not fully implemented yet.
+
+The command line interface needs the following three values
+to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, 
``LIBEUFIN_NEXUS_USERNAME``,
+and ``LIBEUFIN_NEXUS_PASSWORD``.  In this example, ``LIBEUFIN_NEXUS_USERNAME`` 
should be
+set to ``foo``, and ``LIBEUFIN_NEXUS_PASSWORD`` to the value given for its 
password
+in step (2).
+
+Next, we will create an EBICS *bank connection* that that
+nexus can use to communicate with the bank.
 
 .. note::
 
-  The command line interface needs the following three values
-  to be defined in the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``,
-  and ``NEXUS_PASSWORD``.  In this example, ``NEXUS_USERNAME`` should be
-  set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password
-  in step (2).
+   For the sandbox set up in this guide, the EBICS base URL
+   is ``http://localhost:5000/ebicsweb``.
 
 .. code-block:: console
 
@@ -107,9 +221,24 @@ a backup copy* of such keys.
           $CONNECTION_NAME
 
 At this point, Nexus must communicate all the details to the bank.  Therefore,
-it will *(5) synchronize the connection*.  In this EBICS example, Nexus will 
send
+it will synchronize the connection.  In this EBICS example, Nexus will send
 the *INI* and *HIA* messages to the bank.
 
+Now that the bank has received the public keys of the subscriber 
electronically,
+it also needs to verify them offline.  For this, the nexus can generate a key 
letter:
+
+.. code-block:: console
+
+  $ libeufin-cli connections keyletter $CONNECTION_NAME out.pdf
+
+.. note::
+
+   The resulting PDF should be sent to the bank, which will verify
+   that the keys printed in it match the keys sent electronically.
+
+   When using the LibEuFin sandbox, subscribers are automatically
+   activated after keys are received electronically.
+
 .. code-block:: console
 
   $ libeufin-cli \
@@ -119,7 +248,7 @@ the *INI* and *HIA* messages to the bank.
 
 Once the connection is synchronized, Nexus needs to import locally the data
 corresponding to the bank accounts offered by the bank connection just made.
-The command below *(6) downloads the list of the bank accounts offered by the*
+The command below downloads the list of the bank accounts offered by the
 ``$CONNECTION_NAME``.
 
 .. code-block:: console
@@ -129,7 +258,7 @@ The command below *(6) downloads the list of the bank 
accounts offered by the*
         download-bank-accounts \
           $CONNECTION_NAME
 
-It is now possible to *(7) list the accounts offered by the connection*.
+It is now possible to list the accounts offered by the connection.
 
 .. code-block:: console
 
@@ -138,8 +267,8 @@ It is now possible to *(7) list the accounts offered by the 
connection*.
         list-offered-bank-accounts \
           $CONNECTION_NAME
 
-Nexus now needs an explicit *(8) import of the accounts it needs to manage*.
-This step is needed to let the user pick a custom name for such accounts.
+Nexus now needs an explicit import of the accounts it should to manage.  This
+step is needed to let the user pick a custom name for such accounts.
 
 .. code-block:: console
 
@@ -159,6 +288,7 @@ Request history of transactions
 ===============================
 
 ..
+
   FIXME: explain why requesting the history
   goes through these two-phases.
 
@@ -174,20 +304,27 @@ This command asks Nexus to *download the latest bank 
statements*:
         fetch-transactions \
           $CUSTOM_RENAMING_FOR_ACCOUNT
 
+.. note::
+
+   By default, the latest available transactions are fetched.  It is also
+   possible to specify a custom data range (or even all available transactions)
+   and the type of transactions to fetch ( inter-day statements or intra-day
+   reports).
+
 Once Nexus stored all the information in the database, the
 client can ask to actually **see** the transactions:
 
 .. code-block:: console
 
-  $ libeufin-cli
-      accounts \
-        transactions \
-          $CUSTOM_RENAMING_FOR_ACCOUNT
+  $ libeufin-cli accounts \
+      transactions \
+        $CUSTOM_RENAMING_FOR_ACCOUNT
 
 Make a payment
 ==============
 
 ..
+
   FIXME: explain why payments go through these two-phases.
 
 Payments pass through two phases: preparation and submission.
@@ -199,9 +336,9 @@ The following command prepares a payment:
   $ libeufin-cli \
       accounts \
         prepare-payment \
-          --credit-iban $IBAN_TO_SEND_MONEY_TO \
-          --credit-bic $BIC_TO_SEND_MONEY_TO \
-          --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \
+          --creditor-iban $IBAN_TO_SEND_MONEY_TO \
+          --creditor-bic $BIC_TO_SEND_MONEY_TO \
+          --creditor-name $CREDITOR_NAME \
           --payment-amount $AMOUNT \
           --payment-subject $SUBJECT \
           $CUSTOM_RENAMING_FOR_ACCOUNT
@@ -221,6 +358,49 @@ in the next step, to **send the payment instructions to 
the bank**:
           --payment-uuid $UUID \
           $CUSTOM_RENAMING_FOR_ACCOUNT
 
+Automatic scheduling
+====================
+
+With an EBICS bank connection, the LibEuFin nexus needs to regularly query for
+new transactions and (re-)submit prepared payments.
+
+It is possible to schedule these tasks via an external task scheduler such as
+cron.  However, the nexus also has an internal task scheduling mechanism for
+accounts.
+
+
+The following two create a schedule for submitting payments hourly,
+fetching transactions (intra-day reports) every 5 minutes and once at 11am 
every
+day (inter-day statements):
+
+.. code-block:: console
+
+   $ libeufin-cli accounts task-schedule myacct \
+       --task-type="submit"
+       --task-name='submit-payments-hourly'
+       --task-cronspec='0 0 *'
+
+   $ libeufin-cli accounts task-schedule myacct \
+       --task-type="fetch" \
+       --task-name='fetch-5min' \
+       --task-cronspec='0 */5 *' \
+       --task-param-level=report \
+       --task-param-range-type=latest
+
+   $ libeufin-cli accounts task-schedule myacct \
+       --task-type="fetch" \
+       --task-name='fetch-daily' \
+       --task-cronspec='0 0 23' \
+       --task-param-level=statement \
+       --task-param-range-type=latest
+
+The cronspec has the following format, which is slightly non-standard due to
+the ``SECONDS`` field
+
+.. code-block:: none
+
+  SECONDS MINUTES HOURS DAY-OF-MONTH[optional] MONTH[optional] 
DAY-OF-WEEK[optional]
+
 
 Restore the backup
 ==================

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