commit da0086d56537f186914b4a47ec15952b1a3cf000
parent 0f79848a49a9199ae4954f2a311205a1f4e22efb
Author: Christian Grothoff <christian@grothoff.org>
Date: Mon, 23 Feb 2026 15:31:44 +0100
give more motivation on libeufin-ebisync and taler-cyclos
Diffstat:
8 files changed, 97 insertions(+), 26 deletions(-)
diff --git a/depolymerization/index.rst b/depolymerization/index.rst
@@ -15,6 +15,7 @@
@author Antoine d'Aligny
+.. _depolymerization:
Depolymerization Manuals
########################
diff --git a/images/Makefile b/images/Makefile
@@ -1,7 +1,11 @@
-diagrams: regional-arch.png arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png
+diagrams: regional-arch.png arch-api.png coin.png deposit.png reserve.png transaction-common-states.png transaction-withdrawal-states.png transaction-payment-states.png transaction-refund-states.png transaction-refresh-states.png transaction-deposit-states.png transaction-push-debit-states.png transaction-push-credit-states.png transaction-pull-credit-states.png transaction-pull-debit-states.png challenger.png taler-cyclos.png libeufin-ebisync.png
arch-api.png: arch-api.dot
dot -Tpng arch-api.dot > arch-api.png
+libeufin-ebisync.png: libeufin-ebisync.dot
+ dot -Tpng libeufin-ebisync.dot > libeufin-ebisync.png
+taler-cyclos.png: taler-cyclos.dot
+ dot -Tpng taler-cyclos.dot > taler-cyclos.png
regional-arch.png: regional-arch.dot
dot -Tpng regional-arch.dot > regional-arch.png
challenger.png: challenger.dot
diff --git a/images/libeufin-ebisync.dot b/images/libeufin-ebisync.dot
@@ -0,0 +1,11 @@
+digraph G {
+
+ rest[label="REST client"];
+ cloud[label="Cloud storage"];
+ ebisync[label="LibEuFin EbiSync"];
+ bank[label="Core bank system"];
+ rest->ebisync[label="PAIN submission"];
+ ebisync->cloud[label="CAMT upload"];
+ ebisync->bank[label="EBICS"];
+ bank->ebisync;
+}
diff --git a/images/libeufin-ebisync.png b/images/libeufin-ebisync.png
Binary files differ.
diff --git a/images/taler-cyclos.dot b/images/taler-cyclos.dot
@@ -0,0 +1,15 @@
+digraph G {
+
+ subgraph taler_core {
+ wallet[label="Wallet"];
+ merchant [label="Merchant"];
+ exchange [label="Exchange"];
+ } [label="Taler-core"];
+ adapter[label="taler-cyclos"];
+ cyclos[label="Cyclos"];
+ exchange->wallet[label="withdraw"];
+ wallet->merchant[label="pay"];
+ merchant->exchange[label="deposit"];
+ exchange->adapter[label="wire gateway"];
+ adapter->cyclos[label="wire transfer"];
+}
diff --git a/images/taler-cyclos.png b/images/taler-cyclos.png
Binary files differ.
diff --git a/libeufin/ebisync-manual.rst b/libeufin/ebisync-manual.rst
@@ -24,8 +24,21 @@ EbiSync Manual
LibEuFin EbiSync is an EBICS synchronization tool. It offers a command line interface to setup EBICS access and download & submit ISO20022 files.
-Today, the LibEuFin implementation supports EBICS 3.0 and has been
-tested with Postfinance (CHF), GLS (EUR), Maerki Baumann (CHF) and Valiant (CHF). Contact us if you need support for another bank.
+It addresses the problem that interacting with banks over EBICS requires
+implementing a complex cryptographic handshake to download transaction data
+(CAMT files) or to upload instructions for payment initiation (PAIN files).
+With LibEuFin EbiSync, existing systems can use LibEuFin to talk with
+core banking systems over EBICS without having to implement EBICS or the
+:ref:`Taler Wire Gateway API <taler-wire-gateway-http-api>` themselves.
+Instead, existing systems can simply use a HTTP POST request to submit
+PAIN files. Incoming CAMT files can be automatically placed into
+Cloud BLOB storage and processed from there.
+
+.. image:: ../images/libeufin-ebisync.png
+
+Today, the LibEuFin implementation supports EBICS 3.0 and has been tested with
+Postfinance (CHF), GLS (EUR), Maerki Baumann (CHF) and Valiant (CHF). Contact
+us if you need support for another bank.
In this manual, we explain how to setup an EBICS subscriber. We assume that
the bank has already granted EBICS access to the subscriber.
@@ -84,7 +97,7 @@ To install EbiSync as a Debian/Ubuntu package with an automated secure setup and
.. code-block:: console
- $ sudo apt install debhelper
+ $ sudo apt install debhelper
$ make deb
$ sudo dpkg -i ../libeufin-ebisync*.deb
@@ -269,22 +282,22 @@ The following command will finish the fetcher setup process:
Fetching files
==============
-The responsible subcommand for fetching and uploading files is
-``fetch``, and its configuration is a **superset** of ebisync-core-config_. On
-top of that, it expects the database connection string, the destination config and *optionally* a
+The responsible subcommand for fetching and uploading files is
+``fetch``, and its configuration is a **superset** of ebisync-core-config_. On
+top of that, it expects the database connection string, the destination config and *optionally* a
frequency and a checkpoint time of day.
-``fetch`` will run a periodical fetch of pending documents (documents
-that have never been fetched before). If the bank server supports it, it will
-also listen to real-time document availability notifications and fetch
-documents as soon as they are announced. This enables instant registration of
-instant transactions. If your bank server does not support real-time
-notifications, it is recommended that you fetch more often; otherwise, you can
+``fetch`` will run a periodical fetch of pending documents (documents
+that have never been fetched before). If the bank server supports it, it will
+also listen to real-time document availability notifications and fetch
+documents as soon as they are announced. This enables instant registration of
+instant transactions. If your bank server does not support real-time
+notifications, it is recommended that you fetch more often; otherwise, you can
reduce the fetch frequency.
-Only fetching pending documents is not always reliable, if other EBICS clients
-use the same connection settings as ``libeufin-ebisync``, they can consume documents before they are ingested. In case of bank downtime, the status of
-documents can be lost. This is why ``fetch`` will run a checkpoint every
+Only fetching pending documents is not always reliable, if other EBICS clients
+use the same connection settings as ``libeufin-ebisync``, they can consume documents before they are ingested. In case of bank downtime, the status of
+documents can be lost. This is why ``fetch`` will run a checkpoint every
day to download all documents generated since the last checkpoint.
If the bank supports real-time notifications, you can expect transactions to be registered as soon as they are booked: ~10s for instant transactions and 24 to 72h for other transactions. Otherwise, expect a latency corresponding to the fetch frequency for instant transactions. Thanks to checkpointing, latency should not exceed one day.
@@ -315,7 +328,7 @@ The following command would download any unseen EBICS files:
The ``fetch`` subcommand will always cause libeufin-ebisync to download EBICS files and upload them to the configured destination.
-The ``--transient`` flag makes the command sync only
+The ``--transient`` flag makes the command sync only
once and return immediately afterwards. Without the flag, EbiSync
will download at the frequency specified in the configuration or when it receive real time notifications.
diff --git a/taler-cyclos-manual.rst b/taler-cyclos-manual.rst
@@ -1,6 +1,6 @@
..
This file is part of GNU TALER.
- Copyright (C) 2025 Taler Systems SA
+ Copyright (C) 2025, 2026 Taler Systems SA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU Affero General Public License as published by the Free Software
@@ -14,15 +14,43 @@
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
@author Antoine d'Aligny
+ @author Christian Grothoff
Cyclos Adapter Setup Manual
###########################
-taler-cyclos is a Cyclos Taler adapter.
+taler-cyclos is a Cyclos Taler adapter. It allows running a GNU Taler exchange
+on top of a core banking system provided by Cyclos, which is commonly
+used for regional currencies. taler-cylos implements the
+taler-wire-gateway API, which is alternatively provided by the
+:ref:`libeufin-bank <libeufin-bank>` (stand-alone),
+:ref:`libeufin-nexus <libeufin-nexus>` (EBICS integration) or the
+:ref:`Deploymerizer <depolymerization>` (for Bitcoin and Ethereum).
+
+.. image:: images/taler-cyclos.png
+
+
+To use the adapter, you must setup an account for the GNU Taler exchange
+in your Cyclos system and configure the adapter with the respective
+credentials. Furthermore, you must point the GNU Taler exchange to the
+taler-cyclos adapter as its taler-wire-gateway (and again provide the
+necessary credentials).
+
+Afterwards, taler-cyclos will inform your GNU Taler exchange about
+wire transfers made within Cyclos to the GNU Taler exchange account,
+allowing users to withdraw digital cash by sending money in Cyclos
+to the GNU Taler exchange account. Similarly, when a merchant receives
+payments via the GNU Taler exchange, the GNU Taler exchange will use
+the taler-cyclos adapter to send funds from its Cyclos account to
+the merchant's Cyclos account.
+
+As a result, you can use GNU Taler as a digital cash payment system
+on top of any regional currency using Cyclos.
This manual targets system administrators who want to install and
-operate a Cyclos GNU Taler adapter
+operate a Cyclos GNU Taler adapter.
+
.. contents:: Table of Contents
:depth: 1
@@ -80,7 +108,7 @@ To install the adapter as a Debian/Ubuntu package with an automated secure setup
.. code-block:: console
- $ sudo apt install debhelper
+ $ sudo apt install debhelper
$ make deb
$ sudo dpkg -i ../taler-cyclos*.deb
@@ -163,7 +191,7 @@ If the database is run on a different host, please follow the instructions
from the PostgreSQL manual for configuring remote access.
Assuming the configuration is correct, the following
-command initializes (or upgrades) the database schema using:
+command initializes (or upgrades) the database schema using:
You can then use a script to automate a secure database setup:
.. code-block:: console
@@ -190,7 +218,7 @@ Update the configuration files:
USERNAME = admin
PASSWORD = password
-And then run the setup process:
+And then run the setup process:
.. code-block:: console
@@ -214,7 +242,7 @@ The setup process should fail and provide you with the information needed to fil
ACCOUNT_TYPE_ID = 7762070814178012479
PAYMENT_TYPE_ID = 7762070814178012479
-And finaly run the setup process again:
+And finaly run the setup process again:
.. code-block:: console
@@ -295,4 +323,4 @@ Launching the adapter
.. code-block:: console
- # systemctl enable --now taler-cyclos.target
-\ No newline at end of file
+ # systemctl enable --now taler-cyclos.target
