commit 6177e079abc5f73466bc2ac7d4151640d9c981ea
parent 1f63718499ff7ca1acc860e01d4652f36b2eead5
Author: Antoine A <>
Date: Wed, 29 Jul 2026 17:05:00 +0200
add taler-wise manual
Diffstat:
2 files changed, 313 insertions(+), 1 deletion(-)
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -176,7 +176,9 @@ components:
implements a wire adapter towards the Magnet Bank API.
(4) **taler-cyclos** component
implements a wire adapter towards the Cyclos API.
- (5) To use GNU Taler with blockchains, the **Depolymerization**
+ (5) **taler-wise** component
+ implements a wire adapter towards the Wise API.
+ (6) To use GNU Taler with blockchains, the **Depolymerization**
component provides a wire gateway API that runs on top of
blockchains like Bitcoin and Ethereum.
diff --git a/taler-wise-manual.rst b/taler-wise-manual.rst
@@ -0,0 +1,309 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 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
+ Foundation; either version 3.0, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Antoine d'Aligny
+ @author Christian Grothoff
+
+
+Wise Adapter Setup Manual
+###########################
+
+taler-wise is a Wise Taler adapter. It allows running a GNU Taler exchange
+on top of a core banking system provided by Wise, which is commonly
+used for regional currencies. taler-wise 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-wise.png
+
+To use the adapter, you must setup an account for the GNU Taler exchange
+in Wise and configure the adapter with the respective
+credentials. Furthermore, you must point the GNU Taler exchange to the
+taler-wise adapter as its taler-wire-gateway (and again provide the
+necessary credentials).
+
+Afterwards, taler-wise will inform your GNU Taler exchange about
+transfers to the GNU Taler exchange account,
+allowing users to withdraw digital cash by sending money.
+
+This manual targets system administrators who want to install and
+operate a Wise GNU Taler adapter.
+
+.. warning::
+
+ This adapter is read-only. It cannot perform transfer or bounce malformed transactions.
+
+
+.. contents:: Table of Contents
+ :depth: 1
+ :local:
+
+Installation
+============
+
+Installing on Debian
+--------------------
+
+.. include:: frags/installing-debian.rst
+
+To install the adapter, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-wise
+
+Installing on Ubuntu
+--------------------
+
+.. include:: frags/installing-ubuntu.rst
+
+To install the adapter, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-wise
+
+Building from source
+--------------------
+
+Cyclos Adapter belongs to the Taler Rust project, and can be downloaded via Git:
+
+.. code-block:: console
+
+ $ git clone git://git.taler.net/taler-rust
+ $ cd taler-rust
+
+You will need the latest version of the rust stable toolchain and a C toolchain:
+
+.. code-block:: console
+
+ $ sudo apt install rustup build-essential
+ $ rustup toolchain install stable
+
+Then from top-level run:
+
+.. code-block:: console
+
+ $ ./bootstrap
+
+To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
+
+.. code-block:: console
+
+ $ sudo apt install debhelper
+ $ make deb
+ $ sudo dpkg -i ../taler-wise*.deb
+
+If the previous steps succeeded, the ``taler-wise`` command should be found in the $PATH.
+
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *taler-wise* package will create several system users
+to compartmentalize different parts of the system:
+
+* ``taler-wise-httpd``: runs the HTTP daemon with the API logic.
+* ``taler-wise-worker``: runs the worker daemon interacting with the Wise API.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+
+The adapter setup uses the following system groups:
+
+* ``taler-wise-db``: group for all adapter users with direct database access, specifically taler-wise-httpd and taler-wise-worker.
+
+The package will deploy systemd service files in
+``/usr/lib/systemd/system/`` for the various components:
+
+* ``taler-wise-httpd.service``: adapter REST API.
+* ``taler-wise-httpd.socket``: systemd socket activation for the HTTP daemon.
+* ``taler-wise-worker.service``: worker daemon interacting with the Wise API.
+* ``taler-wise.target``: main target for the adapter to be operational.
+
+The deployment creates the following key locations in the system:
+
+* ``/etc/taler-wise/``: configuration files.
+* ``/run/taler-wise/``: contains the UNIX domain sockets for inter-process communication (IPC).
+
+Configuration Fundamentals
+==========================
+
+This chapter provides fundamental details about the adapter configuration.
+
+The configuration for all adapter components uses a single configuration file
+as entry point: ``/etc/taler-cyclos/taler-wise.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/taler-wise/config.d``.
+These default files should never be modified.
+
+The default configuration ``taler-wise.conf`` configuration file
+also includes all configuration files in ``/etc/taler-wise/conf.d``.
+The settings from files in
+``conf.d`` are only relevant to particular components of an adapter, while
+``taler-wise.conf`` contains settings that affect all adapter components.
+
+
+The directory ``/etc/taler-wise/secrets`` contains configuration file snippets with
+values that should only be readable to certain users. They are included with the ``@inline-secret@``
+directive and should end with ``.secret.conf``.
+
+To view the entire configuration annotated with the source of each configuration option, you
+can use the ``taler-wise config`` helper:
+
+
+.. code-block:: shell-session
+
+ # taler-wise config dump --diagnostics
+
+Basic Setup
+===========
+
+Database setup
+--------------
+
+The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
+is:
+
+.. code-block:: ini
+ :caption: /etc/taler-wise/secrets/wise-db.secret.conf
+
+ [wisedb-postgres]
+ config = postgres:///taler-wise
+
+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:
+You can then use a script to automate a secure database setup:
+
+.. code-block:: console
+
+ # taler-wise-dbconfig
+
+Worker setup
+------------
+
+You will need a Wise account to sync.
+Update the configuration files:
+
+.. code-block:: ini
+ :caption: /etc/taler-wise/secrets/wise-worker.secret.conf
+
+ [wise-worker]
+ TOKEN = 4e6a7a34-8f20-4376-912f-8c679b6b4fda
+
+And then run the setup process:
+
+.. code-block:: console
+
+ $ sudo -u taler-wise-worker taler-wise -c /etc/taler-wise/taler-wise.conf setup
+
+The setup process should fail and provide you with the information needed to fill in the required Wise profile information:
+
+.. code-block:: ini
+ :caption: /etc/taler-wise/taler-wise.conf
+
+ [wise]
+ NAME = John Smith S.A.
+
+.. code-block:: ini
+ :caption: /etc/taler-wise/conf.d/wise-worker.conf
+
+ [wise-worker]
+ PROFILE_ID = 77620708
+
+The setup process should fail and provide you with the information needed to fill the Wise balances information:
+
+.. code-block:: ini
+ :caption: /etc/taler-wise/conf.d/wise-worker.conf
+ [wise-balance-eur]
+ ID = 139524631
+ CURRENCY = EUR
+ PAYTO_TYPE = iban
+ IBAN = GB82WEST12345698765432
+ BIC = TRWIBEB1XXX
+
+And finally run the setup process again:
+
+.. code-block:: console
+
+ $ sudo -u taler-wise-worker taler-wise -c /etc/taler-wise/taler-wise.conf setup
+
+This time, you should not see any errors; if you do, you should modify the configuration until it works.
+
+Wire Gateway setup
+------------------
+
+Update the configuration files:
+
+.. code-block:: ini
+ :caption: /etc/taler-wise/conf.d/wise-httpd.conf
+
+ [wise-httpd-wire-gateway-api]
+ ENABLED = YES
+
+.. code-block:: ini
+ :caption: /etc/taler-wise/secrets/wise-httpd.secret.conf
+
+ [wise-httpd-wire-gateway-api]
+ AUTH_METHOD = bearer
+ TOKEN = $SECRET_TOKEN
+
+Check the server is correctly configured:
+
+.. code-block:: console
+
+ $ sudo -u taler-wise-httpd taler-wise -c /etc/taler-wise/taler-wise.conf serve --check
+
+Deployment
+==========
+
+This chapter describes how to deploy the adapter once the basic installation
+and configuration are completed.
+
+Reverse Proxy Setup
+-------------------
+
+By default, the ``taler-wise-httpd`` service listens for HTTP connections
+on a UNIX domain socket. To make the service publicly available, a reverse
+proxy such as nginx should be used. We strongly recommend to configure nginx
+to use TLS.
+
+The ``taler-wise`` package ships with a sample configuration that can be
+enabled in nginx:
+
+.. code-block:: shell-session
+
+ # vim /etc/nginx/sites-available/taler-wise
+ < ... customize configuration ... >
+ # ln -s /etc/nginx/sites-available/taler-wise /etc/nginx/sites-enabled/taler-wise
+ # systemctl reload nginx
+
+With this last step, we are finally ready to launch the
+main adapter process.
+
+Launching the adapter
+---------------------
+
+.. code-block:: console
+
+ # systemctl enable --now taler-wise.target
+
+Use adapter APIS
+----------------
+
+The adapter expose the :ref:`Adapter API <adapter-api>` for each configured balance prefixes by ``/balances/{BALANCE_ID}/``.
+\ No newline at end of file
