diff options
Diffstat (limited to 'taler-developer-manual.rst')
| -rw-r--r-- | taler-developer-manual.rst | 771 |
1 files changed, 445 insertions, 326 deletions
diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst index 91bec2b1..3035e55d 100644 --- a/taler-developer-manual.rst +++ b/taler-developer-manual.rst @@ -1,7 +1,7 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2021 Taler Systems SA + Copyright (C) 2014-2023 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 @@ -20,11 +20,6 @@ Developer's Manual ################## .. toctree:: - :hidden: - - checklist-release - checklist-demo-upgrade - .. note:: @@ -32,11 +27,171 @@ Developer's Manual and related components. It is not intended for a general audience. .. contents:: Table of Contents + :depth: 2 + :local: + + +Project Overview +================ + +GNU Taler consists of a large (and growing) number of components +in various Git repositories. The following list gives a first +overview: + + * exchange: core payment processing logic with a REST API, plus various + helper processes for interaction with banks and cryptographic + computations. Also includes the logic for the auditor and an + in-memory "bank" API implementation for testing. + + * libeufin: implementation of the "bank" API using the EBICS protocol + used by banks in the EU. Allows an exchange to interact with + European banks. + + * deploymerization: implementation of the "bank" API on top of + blockchains, specifically Bitcoin and Ethereum. Allows an exchange + to interact with crypto-currencies. + + * merchant: payment processing backend to be run by merchants, + offering a REST API. + + * wallet-core: platform-independent implementation of a wallet to be run by + normal users. Includes also the WebExtension for various browsers. + Furthermore, includes various single-page apps used by other + components (especially as libeufin and merchant). Also includes + command-line wallet and tools for testing. + + * taler-android: Android Apps including the Android wallet, the + Android point-of-sale App and the Android casher app. + + * taler-ios: iOS wallet App. + + * sync: backup service, provides a simple REST API to allow users to + make encrypted backups of their wallet state. + + * anastasis: key escrow service, provides a simple REST API to allow + users to distribute encryption keys across multiple providers and + define authorization policies for key recovery. + + * taler-mdb: integration of Taler with the multi-drop-bus (MDB) API + used by vending machines. Allows Taler payments to be integrated + with vending machines. + + * gnu-taler-payment-for-woocommerce: payment plugin for the + woocommerce (wordpress) E-commerce solution. + + * twister: man-in-the-middle proxy for tests that require fuzzing a + REST/JSON protocol. Used for some of our testing. + + * challenger: implementation of an OAuth 2.0 provider that can be used + to verify that a user can receive SMS or E-mail at particular addresses. + Used as part of KYC processes of the exchange. + + * taler-mailbox: messaging service used to store and forward payment + messages to Taler wallets. + + * taldir: directory service used to lookup Taler wallet addresses for + sending invoices or payments to other wallets. + + * taler-merchant-demos: various demonstration services operated at + 'demo.taler.net', including a simple shop and a donation page. + +There are other important repositories without code, including: + + * gana: Hosted on git.gnunet.org, this repository defines various + constants used in the GNU Taler project. + + * docs: documentation, including this very document. + + * marketing: various presentations, papers and other resources for + outreach. + + * large-media: very large data objects, such as videos. + * www: the taler.net website. Fundamentals ============ +Versioning +---------- + +A central rule is to never break anything for any dependency. To accomplish +this, we use versioning, of the APIs, database schema and the protocol. The +database versioning approach is described in the :ref:`Database schema +versioning <DatabaseVersioning>` section. Here, we will focus on API and +protocol versioning. + +The key issue we need to solve with protocols and APIs (and that does not +apply to database versioning) is being able to introduce and remove features +without requiring a flag day where all components must update at the same +time. For this, we use GNU libtool style versioning with MAJOR:REVISION:AGE +and *not* semantic versioning (SEMVER). With GNU libtool style versioning, +first the REVISION should be increased on every change to the respective code. +Then, each time a feature is introduced or deprecated, the MAJOR and AGE +numbers are increased. Whenever an API is actually removed the AGE number is +reduced to match the distance since the removed API was deprecated. Thus, if +some client implements version X of the protocol (including not using any APIs +that have been deprecated), it is compatible for any implementation where +MAJOR is larger or equal to X, and MAJOR minus AGE is smaller or equal to X. +REVISION is not used for expected compatibility issues and merely serves to +uniquely identify each version (in combination with MAJOR). + +To evolve any implementation, it is thus critical to first of all never +just break an existing API or endpoint. The only acceptable modifications +are to return additional information (being aware of binary compatibility!) +or to accept additional optional arguments (again, in a way that does not +break existing users). Thus, the most common way to introduce changes will +be the addition of new endpoints. Breaking existing endpoints is only ever +at best acceptable while in the process of introducing it and if you are +absolutely sure that there are zero users in other components. + +When removing endpoints (or fields being returned), you must first deprecate +the existing API (incrementing MAJOR and AGE) and then wait for all clients, +including all clients in operation (e.g. Android and iOS Apps, e-commerce +integrations, etc.) to upgrade to a protocol implementation above the +deprecated MAJOR revision. Only then you should remove the endpoint and reduce +AGE. + +To document these changes, please try to use ``@since`` annotations in the API +specifications to explain the MAJOR revision when a feature became available, +but most importantly use ``@deprecated X`` annotations to indicate that an API +was deprecated and will be removed once MAJOR minus AGE is above X. When using +an API, use the ``/config`` endpoints to check for compatibility and show a +warning if the version(s) you support and the version(s) offered by the server +are incompatible. + + +Testing Tools +------------- + +For full ``make check`` support, install these programs: + +- `jq <https://github.com/stedolan/jq>`__ +- `curl <http://curl.haxx.se>`__ +- `faketime <https://github.com/wolfcw/libfaketime>`__ + +The ``make check`` should be able to function without them, but +their presence permits some tests to run that would otherwise be skipped. + +Manual Testing Database Reset +----------------------------- + +Sometimes ``make check`` will fail with some kind of database (SQL) +error, perhaps with a message like ``OBJECT does not exist`` in the +``test-suite.log`` file, where ``OBJECT`` is the name of a table or function. +In that case, it may be necessary to reset the ``talercheck`` database +with the commands: + +.. code-block:: console + + $ dropdb talercheck + $ createdb talercheck + +This is because, at the moment, there is no support for +doing these steps automatically in the ``make check`` flow. + +(If ``make check`` still fails after the reset, file a bug report as usual.) + Bug Tracking ------------ @@ -143,11 +298,51 @@ development. Communication ------------- -We use the #taler channel on the Freenode IRC network and the taler@gnu.org -public mailinglist for discussions. Not all developers are active on IRC, but -all developers should probably subscribe to the low-volume Taler mailinglist. -There are separate low-volume mailinglists for gnunet-developers (@gnu.org) -and for libmicrohttpd (@gnu.org). +For public discussions we use the taler@gnu.org mailinglist. All developers +should subscribe to the low-volume Taler mailinglist. There are separate +low-volume mailinglists for gnunet-developers (@gnu.org) and for libmicrohttpd +(@gnu.org). For internal discussions we use https://mattermost.taler.net/ +(invitation only, but also achieved). + + +What to put in bootstrap +------------------------ + +Each repository has a ``bootstrap`` script, which contains commands for the +developer to run after a repository checkout (i.e., after ``git clone`` or +``git pull``). +Typically, this updates and initializes submodules, prepares the tool chain, +and runs ``autoreconf``. +The last step generates the ``configure`` script, whether for immediate use or +for inclusion in the distribution tarball. + +One common submodule is ``contrib/gana``, which pulls from the +`GNUnet GANA repository <https://git.gnunet.org/gana.git/>`__. +For example, in the +`Taler exchange repository <https://git.taler.net/exchange.git>`__, +the bootstrap script eventually runs the ``git submodule update --init`` command +early on, and later runs script ``./contrib/gana-generate.sh``, which +generates files such as ``src/include/taler_signatures.h``. + +Thus, to update that file, you need to: + +- (in GANA repo) Find a suitable (unused) name and number for the Signature + Purposes database. + +- Add it to GANA, in ``gnunet-signatures/registry.rec``. + (You can check for uniqueness with the ``recfix`` utility.) + +- Commit the change, and push it to the GANA Git repo. + +- (in Taler Repo) Run the ``contrib/gana-latest.sh`` script. + +- Bootstrap, configure, do ``make install``, ``make check``, etc. + (Basically, make sure the change does not break anything.) + +- Commit the submodule change, and push it to the Taler exchange Git repo. + +A similar procedure is required for other databases in GANA. +See file ``README`` in the various directories for specific instructions. Debian and Ubuntu Repositories @@ -182,22 +377,19 @@ Language-Specific Guidelines Taler Deployment on gv.taler.net ================================ -This section describes the GNU Taler deployment on ``gv.taler.net``. -``gv`` is our server at BFH. It hosts the Git repositories, Web sites, -CI and other services. Developers can receive an SSH account and -e-mail alias for the system. As with Git, ask your primary team -contact for shell access if you think you need it. +This section describes the GNU Taler deployment on ``gv.taler.net``. ``gv`` +is our server at BFH. It hosts the Git repositories, Web sites, CI and other +services. Developers can receive an SSH account and e-mail alias for the +system, you should contact Javier, Christian or Florian. As with Git, ask +your primary team contact for shell access if you think you need it. -Our old server, ``tripwire``, is currently offline and will likely -go back online to host ``production`` systems for operating real -Taler payments at BFH in the future. DNS --- -DNS records for taler.net are controlled by the GNU Taler -maintainers, specifically Christian and Florian. If you -need a sub-domain to be added, please contact one of them. +DNS records for taler.net are controlled by the GNU Taler maintainers, +specifically Christian and Florian, and our system administrator, Javier. If +you need a sub-domain to be added, please contact one of them. User Acccounts @@ -212,29 +404,63 @@ serve Taler on the Internet: - ``taler-internal``: serves ``*.int.taler.net``, and does *NOT* get automatically built. -The following two users are *never* automatically built, and they both -serve ``*.demo.taler.net``. At any given time, only one is active and -serves the HTTP requests from the outside; the other one can so be -compiled without any downtime. If the compilation succeeds, the inactive -user can be switched to become active (see next section), and vice versa. - -- ``demo-blue`` -- ``demo-green`` +- ``demo``: serves ``*.demo.taler.net``. Never automatically built. Demo Upgrade Procedure ====================== +#. Login as the ``demo`` user on ``gv.taler.net``. +#. Pull the latest ``deployment.git`` code. +#. Navigate to the ``deployment.git/docker/demo`` directory. +#. Refer to the README, or the smaller cheat sheet below. + +The deployment is based on rootless Docker, managed by the +SystemD unit in userspace: ``docker.service``. The running daemon +is reached by every Docker command at the address held into the +``DOCKER_HOST`` environment variable. Normally, it points to +``unix:///run/user/$(id -u)/docker.sock``. Such variable is automatically +exported by ``~/.bashrc``. + +.. note:: + + Should the rootless Docker be installed, run the following command + or consult the `official documentation <https://docs.docker.com/engine/security/rootless/>`_. + + .. code-block:: console + + $ curl -fsSL https://get.docker.com/rootless | sh + Upgrading the ``demo`` environment should be done with care, and ideally be coordinated on the mailing list before. It is our goal for ``demo`` to always run a "working version" that is compatible with various published wallets. +Please use the :doc:`demo upgrade checklist <checklists/checklist-demo-upgrade>` to make +sure everything is working. +Nginx is already configured to reach the services as exported by +Docker Compose. -Before deploying on ``demo``, the same version of all components **must** -be deployed *and* tested on ``int``. -Please use the :doc:`demo upgrade checklist <checklist-demo-upgrade>` to make -sure everything is working. +Cheat sheet +----------- + +All commands run from deployment.git/docker/demo. + +.. code-block:: console + + # Start services. + $ docker-compose start --remove-orphans -d + # Stop services. + $ docker-compose stop + + # Build base image (without tags-file builds master) + $ ./build_base.sh images/base/Dockerfile [tags-file] + + # Build all the services based on the latest base image + $ docker-compose build + + # View live logs of the daemonized services. + $ docker-compose logs Tagging components ------------------ @@ -250,99 +476,7 @@ All Taler components must be tagged with git before they are deployed on the DD = day SS = serial - -Environment Layout ------------------- - -Environments have the following layout: - -.. code-block:: none - - $HOME/ - deployment (deployment.git checkout) - envcfg.py (configuration of the Taler environment) - activate (bash file, sourced to set environment variables) - logs/ (log files) - local/ (locally installed software) - sources/ (sources repos of locally build components) - sockets/ (unix domain sockets of running components) - taler-data (on-disk state, public and private keys) - .config/taler.conf (main Taler configuration file) - -On ``demo-blue`` and ``demo-green``, ``taler-data`` is a symlink pointing to ``$HOME/demo/shared-data`` -instead of a directory. - - -Using envcfg.py ---------------- - -The ``$HOME/envcfg.py`` file contains (1) the name of the environment and (2) the version -of all components we build (in the form of a git rev). - -The ``envcfg.py`` for demo looks like this: - -.. code-block:: python - - env = "demo" - tag = "demo-2019-10-05-01: - tag_gnunet = tag - tag_libmicrohttpd = tag - tag_exchange = tag - tag_merchant = tag - tag_bank = tag - tag_twister = tag - tag_landing = tag - tag_donations = tag - tag_blog = tag - tag_survey = tag - tag_backoffice = tag - tag_sync = tag - -Currently only the variables ``env`` and ``tag_${component}`` are used. - -When deploying to ``demo``, the ``envcfg.py`` should be committed to ``deployment.git/envcfg/envcfg-demo-YYYY-MM-DD-SS.py``. - - -Bootstrapping an Environment ----------------------------- - -.. code-block:: console - - $ git clone https://git.taler.net/deployment.git ~/deployment - $ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py - $ ./deployment/bin/taler-deployment bootstrap - $ source ~/activate - $ taler-deployment build - $ taler-deployment-prepare - $ taler-deployment-start - $ taler-deployment-arm -I # check everything works - # The following command sets up the 'blog' and 'donations' instances. - $ taler-config-instances - - -Upgrading an Existing Environment ---------------------------------- - -.. code-block:: console - - $ rm -rf ~/sources ~/local - $ git -C ~/deployment pull - $ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py - $ taler-deployment bootstrap - $ taler-deployment build - $ taler-deployment-prepare - $ taler-deployment-restart - $ taler-deployment-arm -I # check everything works - -Switching Demo Colors ---------------------- - -As the ``demo`` user, to switch to color ``${COLOR}``, -run the following script from ``deployment/bin``: - -.. code-block:: console - - $ taler-deployment switch-demo +.. include:: checklists/checklist-demo-upgrade.rst Environments and Builders on taler.net @@ -376,6 +510,40 @@ Best Practices: Then make sure there is a WORKER defined in master.cfg like: ``worker.Worker("<username>", "<password>")`` +Test builder +------------ + +This builder (``test-builder``) compiles and starts every Taler component. +The associated worker is run by the ``taler-test`` Gv user, via the SystemD +unit ``buildbot-worker-taler``. The following commands start/stop/restart +the worker: + +.. code-block:: + + systemctl --user start buildbot-worker-taler + systemctl --user stop buildbot-worker-taler + systemctl --user restart buildbot-worker-taler + +.. note:: + the mentioned unit file can be found at ``deployment.git/systemd-services/`` + +Wallet builder +-------------- + +This builder (``wallet-builder``) compiles every Taler component +and runs the wallet integration tests. The associated worker is +run by the ``walletbuilder`` Gv user, via the SystemD unit ``buildbot-worker-wallet``. +The following commands start/stop/restart the worker: + +.. code-block:: + + systemctl --user start buildbot-worker-wallet + systemctl --user stop buildbot-worker-wallet + systemctl --user restart buildbot-worker-wallet + +.. note:: + the mentioned unit file can be found at ``deployment.git/systemd-services/`` + Documentation Builder --------------------- @@ -440,47 +608,6 @@ by Buildbot. The results are then published at ``https://lcov.taler.net/``. -Service Checker ---------------- - -The user ``demo-checker`` runs periodic checks to see if all the -``*.demo.taler.net`` services are up and running. It is driven by -Buildbot, and can be bootstrapped as follows. - -.. code-block:: console - - # Log-in as the 'demo-checker' user - - $ cd $HOME - $ git clone git://git.taler.net/deployment - $ ./deployment/bootstrap-demochecker - - # If the previous step worked, the setup is - # complete and the Buildbot worker can be started. - - $ buildbot-worker start worker/ - - -Tipping reserve top-up ----------------------- - -Both 'test' and 'demo' setups get their tip reserve topped up -by a Buildbot worker. The following steps get the reserve topper -prepared. - -.. code-block:: console - - # Log-in as <env>-topper, with <env> being either 'test' or 'demo' - - $ git clone git://git.taler.net/deployment - $ ./deployment/prepare-reservetopper <env> - - # If the previous steps worked, then it should suffice to start - # the worker, with: - - $ buildbot-worker start worker/ - - Producing auditor reports ------------------------- @@ -493,7 +620,7 @@ prepared. # Log-in as <env>-auditor, with <env> being either 'test' or 'demo' $ git clone git://git.taler.net/deployment - $ ./deployment/prepare-auditorreporter <env> + $ ./deployment/buildbot/bootstrap-scripts/prepare-auditorreporter <env> # If the previous steps worked, then it should suffice to start # the worker, with: @@ -501,11 +628,13 @@ prepared. $ buildbot-worker start worker/ +.. _DatabaseVersioning: + Database schema versioning -------------------------- -The Postgres databases of the exchange and the auditor are versioned. -See the 0000.sql file in the respective directory for documentation. +The PostgreSQL databases of the exchange and the auditor are versioned. +See the ``versioning.sql`` file in the respective directory for documentation. Every set of changes to the database schema must be stored in a new versioned SQL script. The scripts must have contiguous numbers. After @@ -513,17 +642,22 @@ any release (or version being deployed to a production or staging environment), existing scripts MUST be immutable. Developers and operators MUST NOT make changes to database schema -outside of this versioning. +outside of this versioning. All tables of a GNU Taler component should live in their own schema. +QA Plans +======== + +.. include:: checklists/qa-0.9.4.rst + Releases ======== -Release Process and Checklists ------------------------------- +.. include:: checklists/checklist-release.rst -Please use the :doc:`release checklist <checklist-release>` +Release Process +--------------- This document describes the process for releasing a new version of the various Taler components to the official GNU mirrors. @@ -532,10 +666,11 @@ The following components are published on the GNU mirrors - taler-exchange (exchange.git) - taler-merchant (merchant.git) -- talerdonations (donations.git) -- talerblog (blog.git) -- taler-bank (bank.git) -- taler-wallet-webex (wallet-webex.git) +- sync (sync.git) +- taler-mdb (taler-mdb.git) +- libeufin (libeufin.git) +- challenger (challenger.git) +- wallet-core (wallet-core.git) Tagging ------- @@ -638,6 +773,7 @@ Directive file: version: 1.2 directory: taler filename: taler-exchange-0.1.0.tar.gz + symlink: taler-exchange-0.1.0.tar.gz taler-exchange-latest.tar.gz Upload the files in **binary mode** to the ftp servers. @@ -658,6 +794,8 @@ debian/changelog, and then run: in the respective source directory (GNUnet, exchange, merchant) to create the ``.deb`` files. Note that they will be created in the parent directory. This can be done on gv.taler.net, or on another (secure) machine. +Actual release builds should be done via the Docker images +that can be found in ``deployment.git`` under packaging. On ``gv``, we use the ``aptbuilder`` user to manage the reprepro repository. @@ -792,6 +930,56 @@ weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F26 This means that contributions made through weblate will not be signed with the individual contributor's key when they are checked into the Git repository, but with the weblate key. + +iOS Apps +======== + +.. _Build-iOS-from-source: + +Building Taler Wallet for iOS from source +----------------------------------------- + +The GNU Taler Wallet iOS app is in +`the official Git repository <https://git.taler.net/taler-ios.git>`__. + +Compatibility +^^^^^^^^^^^^^ + +The minimum version of iOS supported is 15.0. +This app runs on all iPhone models at least as new as the iPhone 6S. + + +Building +^^^^^^^^ + +Before building the iOS wallet, you must first checkout the +`quickjs-tart repo <https://git.taler.net/quickjs-tart.git>`__ +and the +`wallet-core repo <https://git.taler.net/wallet-core.git>`__. + +Have all 3 local repos (wallet-core, quickjs-tart, and this one) adjacent at +the same level (e.g. in a "GNU_Taler" folder) +Taler.xcworkspace expects the QuickJS framework sub-project to be at +``../quickjs-tart/QuickJS-rt.xcodeproj``. + +Build wallet-core first: + +.. code-block:: shell-session + + $ cd wallet-core + $ make embedded + $ open packages/taler-wallet-embedded/dist + +then drag or move its product "taler-wallet-core-qjs.mjs" +into your quickjs-tart folder right at the top level. + +Open Taler.xcworkspace, and set scheme / target to Taler_Wallet. Build&run... + +Don't open QuickJS-rt.xcodeproj or TalerWallet.xcodeproj and build anything +there - all needed libraries and frameworks will be built automatically from +Taler.xcworkspace. + + Android Apps ============ @@ -989,7 +1177,7 @@ then published at https://lcov.taler.net/ . Coding Conventions ================== -GNU Taler is developed primarily in C, Kotlin, Python and TypeScript. +GNU Taler is developed primarily in C, Kotlin, Python, Swift and TypeScript. Components written in C ----------------------- @@ -1122,6 +1310,19 @@ are useful: * ``subprocess`` for "shelling out" to other programs. Prefer ``subprocess.run`` over the older APIs. + +Swift +----- + +Please follow best practices for the language. + + +TypeScript +---------- + +Please follow best practices for the language. + + Testing library =============== @@ -1209,9 +1410,15 @@ Refreshing **Use instead**: "Obtaining change" +Charge + Charge has two opposite meanings (charge to a credit card vs. charge a battery). + This can confuse users. + + **Use instead**: "Obtain", "Credit", "Debit", "Withdraw", "Top up" + Coin Coins are an internal construct, the user should never be aware that their balance - is represented by coins if different denominations. + is represented by coins of different denominations. **Use instead**: "(Digital) Cash" or "(Wallet) Balance" @@ -1317,18 +1524,16 @@ use when talking to end users or even system administrators. trusted third party that verifies that the :term:`exchange` is operating correctly bank - traditional financial service provider who offers wire :term:`transfers <transfer>` between accounts + traditional financial service provider who offers + :term:`wire transfers <wire transfer>` between accounts buyer individual in control of a Taler :term:`wallet`, usually using it to - :term:`spend` the :term:`coins` on :term:`contracts` (see also :term:`customer`). + :term:`spend` the :term:`coins <coin>` on :term:`contracts <contract>` (see also :term:`customer`). close - closes - closed - closing operation an :term:`exchange` performs on a :term:`reserve` that has not been - :term:`drained` by :term:`withdraw` operations. When closing a reserve, the + :term:`emptied <empty>` by :term:`withdraw` operations. When closing a reserve, the exchange wires the remaining funds back to the customer, minus a :term:`fee` for closing @@ -1336,10 +1541,8 @@ use when talking to end users or even system administrators. individual that directs the buyer (perhaps the same individual) to make a purchase coin - coins coins are individual token representing a certain amount of value, also known as the :term:`denomination` of the coin - commitment refresh commitment data that the wallet commits to during the :term:`melt` stage of the :term:`refresh` protocol where it @@ -1348,9 +1551,8 @@ use when talking to end users or even system administrators. probabilistically (see: :term:`kappa`) during the :term:`reveal` stage. contract - contracts formal agreement between :term:`merchant` and :term:`customer` specifying the - :term:`contract terms` and signed by the merchant and the :term:`coins` of the + :term:`contract terms` and signed by the merchant and the :term:`coins <coin>` of the customer contract terms @@ -1366,32 +1568,32 @@ use when talking to end users or even system administrators. particular :term:`denomination` deposit - deposits - depositing operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using an :term:`aggregate` :term:`wire transfer` drain - drained - a :term:`reserve` is being drained when a :term:`wallet` is using the - reserve's private key to :term:`withdraw` coins from it. This reduces - the balance of the reserve. Once the balance reaches zero, we say that - the reserve has been (fully) drained. Reserves that are not drained - (which is the normal process) are :term:`closed` by the exchange. + process by which an exchange operator takes the profits + (from :term:`fees <fee>`) out of the escrow account and moves them into + their regular business account dirty - dirty coin - a coin is dirty if its public key may be known to an entity other than + a :term:`coin` is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to link multiple transactions of coin's owner if the coin is not refreshed + empty + a :term:`reserve` is being emptied when a :term:`wallet` is using the + reserve's private key to :term:`withdraw` coins from it. This reduces + the balance of the reserve. Once the balance reaches zero, we say that + the reserve has been (fully) emptied. Reserves that are not emptied + (which is the normal process) are :term:`closed <close>` by the exchange. + exchange Taler's payment service operator. Issues electronic coins during withdrawal and redeems them when they are deposited by merchants expired - expiration Various operations come with time limits. In particular, denomination keys come with strict time limits for the various operations involving the coin issued under the denomination. The most important limit is the @@ -1413,18 +1615,17 @@ use when talking to end users or even system administrators. fee an :term:`exchange` charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for - :term:`withdrawing`, :term:`depositing`, :term:`melting`, and - :term:`refunding`. Furthermore, there are fees per wire transfer - for :term:`closing` a :term:`reserve`: and for - :term:`aggregate` :term:`wire transfers` to the :term:`merchant`. + :term:`withdrawing <withdraw>`, :term:`depositing <deposit>`, :term:`melting <melt>`, and + :term:`refunding <refund>`. Furthermore, there are fees per wire transfer + when a :term:`reserve` is :term:`closed <close>` + and for :term:`aggregate` :term:`wire transfers <wire transfer>` + to the :term:`merchant`. fresh - fresh coin - a coin is fresh if its public key is only known to the customer + a :term:`coin` is fresh if its public key is only known to the customer - json JSON - JavaScript Object Notation + JavaScript Object Notation (JSON) is a serialization format derived from the JavaScript language which is commonly used in the Taler protocol as the payload of HTTP requests and responses. @@ -1434,11 +1635,11 @@ use when talking to end users or even system administrators. The probability of successfully evading the income transparency with the refresh protocol is 1:kappa. - LibEuFin - FIXME: explain + libeufin + Kotlin component that implements a regional currency bank and an + adapter to communicate via EBICS with European core banking systems. link - linking specific step in the :term:`refresh` protocol that an exchange must offer to prevent abuse of the :term:`refresh` mechanism. The link step is not needed in normal operation, it just must be offered. @@ -1448,9 +1649,7 @@ use when talking to end users or even system administrators. message signing keys melt - melted - melting - step of the :term:`refresh` protocol where a :term:`dirty coin` + step of the :term:`refresh` protocol where a :term:`dirty` :term:`coin` is invalidated to be reborn :term:`fresh` in a subsequent :term:`reveal` step. @@ -1461,7 +1660,9 @@ use when talking to end users or even system administrators. key used by the exchange to sign online messages, other than coins order - FIXME: to be written! + offer made by the merchant to a wallet; pre-cursor to + a contract where the wallet is not yet fixed. Turns + into a :term:`contract` when a wallet claims the order. owner a coin is owned by the entity that knows the private key of the coin @@ -1474,19 +1675,19 @@ use when talking to end users or even system administrators. recoup Operation by which an exchange returns the value of coins affected - by a :term:`revocation` to their :term:`owner`, either by allowing the owner to + by a :term:`revocation <revoke>` to their :term:`owner`, either by allowing the owner to withdraw new coins or wiring funds back to the bank account of the :term:`owner`. planchet precursor data for a :term:`coin`. A planchet includes the coin's internal secrets (coin private key, blinding factor), but lacks the RSA signature - of the :term:`exchange`. When :term:`withdrawing`, a :term:`wallet` + of the :term:`exchange`. When :term:`withdrawing <withdraw>`, a :term:`wallet` creates and persists a planchet before asking the exchange to sign it to get the coin. purchase Refers to the overall process of negotiating a :term:`contract` and then - making a payment with :term:`coins` to a :term:`merchant`. + making a payment with :term:`coins <coin>` to a :term:`merchant`. privacy policy Statement of an operator how they will protect the privacy of users. @@ -1499,13 +1700,11 @@ use when talking to end users or even system administrators. merchant backend. refresh - refreshing - operation by which a :term:`dirty coin` is converted into one or more - :term:`fresh` coins. Involves :term:`melting` the :term:`dirty coin` and - then :term:`revealing` so-called :term:`transfer keys`. + operation by which a :term:`dirty` :term:`coin` is converted into one or more + :term:`fresh` coins. Involves :term:`melting <melt>` the :term:`dirty` coins and + then :term:`revealing <reveal>` so-called :term:`transfer keys <transfer key>`. refund - refunding operation by which a merchant steps back from the right to funds that he obtained from a :term:`deposit` operation, giving the right to the funds back to the customer @@ -1517,25 +1716,23 @@ use when talking to end users or even system administrators. reserve accounting mechanism used by the exchange to track customer funds - from incoming :term:`wire transfers`. A reserve is created whenever + from incoming :term:`wire transfers <wire transfer>`. A reserve is created whenever a customer wires money to the exchange using a well-formed public key in the subject. The exchange then allows the customer's :term:`wallet` to :term:`withdraw` up to the amount received in :term:`fresh` - :term:`coins` from the reserve, thereby draining the reserve. If a - reserve is not drained, the exchange eventually :term:`closes` it. + :term:`coins <coin>` from the reserve, thereby emptying the reserve. If a + reserve is not emptied, the exchange will eventually :term:`close` it. Other definition: Funds set aside for future use; either the balance of a customer at the exchange ready for withdrawal, or the funds kept in the exchange;s bank account to cover obligations from coins in circulation. reveal - revealing step in the :term:`refresh` protocol where some of the transfer private keys are revealed to prove honest behavior on the part of the wallet. In the reveal step, the exchange returns the signed :term:`fresh` coins. revoke - revocation exceptional operation by which an exchange withdraws a denomination from circulation, either because the signing key was compromised or because the exchange is going out of operation; unspent coins of a revoked @@ -1547,22 +1744,14 @@ use when talking to end users or even system administrators. time. spend - spending operation by which a customer gives a merchant the right to deposit coins in return for merchandise - transfer - transfers - wire transfer - wire transfers - method of sending funds between :term:`bank` accounts - transfer key - transfer keys special cryptographic key used in the :term:`refresh` protocol, some of which are revealed during the :term:`reveal` step. Note that transfer keys have, - despite the name, no relationship to :term:`wire transfers`. They merely - help to transfer the value from a :term:`dirty coin` to a :term:`fresh coin` + despite the name, no relationship to :term:`wire transfers <wire transfer>`. They merely + help to transfer the value from a :term:`dirty` coin to a :term:`fresh` coin terms the general terms of service of an operator, possibly including @@ -1595,25 +1784,27 @@ use when talking to end users or even system administrators. Cross-browser API used to implement the GNU Taler wallet browser extension. wire gateway - FIXME: explain + API used by the exchange to talk with some real-time gross settlement system + (core banking system, blockchain) to notice inbound credits wire transfers + (during withdraw) and to trigger outbound debit wire transfers (primarily + for deposits). + + wire transfer + a wire transfer is a method of sending funds between :term:`bank` accounts wire transfer identifier - wtid Subject of a wire transfer from the exchange to a merchant; set by the aggregator to a random nonce which uniquely identifies the transfer. withdraw - withdrawing - withdrawal operation by which a :term:`wallet` can convert funds from a :term:`reserve` to fresh coins zombie - zombie coin - coin where the respective :term:`denomination key` is past its - :term:`deposit` :term:`expiration` time, but which is still (again) valid - for an operation because it was :term:`melted` while it was still + :term:`coin` where the respective :term:`denomination key` is past its + :term:`deposit` :term:`expiration <expired>` time, but which is still (again) valid + for an operation because it was :term:`melted <melt>` while it was still valid, and then later again credited during a :term:`recoup` process @@ -1625,84 +1816,12 @@ This section describes various internal programs to make life easier for the developer. -taler-config-generate ---------------------- - -**taler-config-generate** - tool to simplify Taler configuration generation - - -**taler-config-generate** -[**-C** *CURRENCY* | **--currency=**\ \ *CURRENCY*] -[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] -[**-e** | **--exchange**] -[**-f** *AMOUNT* | *--wirefee=*\ \ *AMOUNT*] -[**-h** | **--help**] -[**-J** *JSON* | **--wire-json-exchange=**\ \ *JSON*] -[**-j** *JSON* | **--wire-json-merchant=**\ \ *JSON*] -[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] -[**-m** | **--merchant**] -[**-t** | **--trusted**] -[**-v** | **--version**] -[**-w** *WIREFORMAT* | **--wire** *WIREFORMAT*] -[**--bank-uri**] -[**--exchange-bank-account**] -[**--merchant-bank-account**] - - -**taler-config-generate** can be used to generate configuration files -for the Taler exchange or Taler merchants. - -**-C** *CURRENCY* \| **--currency=**\ \ *CURRENCY* - Which currency should we use in the configuration. - -**-c** *FILENAME* \| **--config=**\ \ *FILENAME* - Location where to write the generated configuration. Existing file - will be updated, not overwritten. - -**-e** \| **--exchange** - Generate configuration for a Taler exchange. - -**-f** *AMOUNT* \| *-wirefee=*\ \ *AMOUNT* - Setup wire transfer fees for the next 5 years for the exchange (for - all wire methods). - -**-h** \| **--help** - Shows this man page. - -**-J** *JSON* \| **--wire-json-exchange=**\ \ *JSON* - Wire configuration to use for the exchange. - -**-j** *JSON* \| **--wire-json-merchant=**\ \ *JSON* - Wire configuration to use for the merchant. - -**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* - Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and - ERROR. - -**-m** \| **--merchant** - Generate configuration for a Taler merchant. - -**-t** \| **--trusted** - Setup current exchange as trusted with current merchant. Generally - only useful when configuring for testcases. - -**-v** \| **--version** - Print version information. - -**-w** *WIREFORMAT* \| **--wire** *WIREFORMAT* - Specifies which wire format to use (i.e. “test” or “sepa”) +taler-harness +------------- -**--bank-uri** - Alternative to specify wire configuration to use for the exchange and - merchant for the “test” wire method. Only useful if WIREFORMAT was - set to “test”. Specifies the URI of the bank. +**taler-harness deployment gen-coin-config** is a tool to simplify Taler configuration generation. -**--exchange-bank-account** - Alternative to specify wire configuration to use for the exchange for - the “test” wire method. Only useful if WIREFORMAT was set to “test”. - Specifies the bank account number of the exchange. -**--merchant-bank-account** - Alternative to specify wire configuration to use for the merchant for - the “test” wire method. Only useful if WIREFORMAT was set to “test”. - Specifies the bank account number of the merchant. +**taler-harness deployment gen-coin-config** +[**-min-amount**=**\ \ *VALUE*] +[**-max-amount**=**\ \ *VALUE*] |