Note
This manual contains information for developers working on GNU Taler and related components. It is not intended for a general audience.
Table of Contents
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, donation page and a survey with tipping functionality.
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.
For full make check support, install these programs:
The make check should be able to function without them, but
their presence permits some tests to run that would otherwise be skipped.
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:
$ 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 is done with Mantis (https://www.mantisbt.org/). The bug tracker is available at https://bugs.taler.net. A registration on the Web site is needed in order to use the bug tracker, only read access is granted without a login.
Taler code is versioned with Git. For those users without write access, all the codebases are found at the following URL:
git://git.taler.net/<repository>
A complete list of all the existing repositories is currently found at https://git.taler.net/.
Before you can obtain Git write access, you must sign the copyright agreement. As we collaborate closely with GNUnet, we use their copyright agreement – with the understanding that your contributions to GNU Taler are included in the assignment. You can find the agreement on the GNUnet site. Please sign and mail it to Christian Grothoff as he currently collects all the documents for GNUnet e.V.
To obtain Git access, you need to send us your SSH public key. Most core team members have administrative Git access, so simply contact whoever is your primary point of contact so far. You can find instructions on how to generate an SSH key in the Git book. If you have been granted write access, you first of all must change the URL of the respective repository to:
ssh://git@git.taler.net/<repository>
For an existing checkout, this can be done by editing the .git/config file.
The server is configured to reject all commits that have not been signed with GnuPG. If you do not yet have a GnuPG key, you must create one, as explained in the GNU Privacy Handbook. You do not need to share the respective public key with us to make commits. However, we recommend that you upload it to key servers, put it on your business card and personally meet with other GNU hackers to have it signed such that others can verify your commits later.
To sign all commits, you should run
$ git config --global commit.gpgsign true
You can also sign individual commits only by adding the -S option to the
git commit command. If you accidentally already made commits but forgot
to sign them, you can retroactively add signatures using:
$ git rebase -S
Whether you commit to a personal branch (recommended: dev/$USER/...),
a feature branch or to master should
depend on your level of comfort and the nature of the change. As a general
rule, the code in master must always build and tests should always pass, at
least on your own system. However, we all make mistakes and you should expect
to receive friendly reminders if your change did not live up to this simple
standard. We plan to move to a system where the CI guarantees this invariant
in the future.
In order to keep a linear and clean commits history, we advise to avoid
merge commits and instead always rebase your changes before pushing to
the master branch. If you commit and later find out that new commits were
pushed, the following command will pull the new commits and rebase yours
on top of them.
# -S instructs Git to (re)sign your commits
$ git pull --rebase -S
Every commit to the master branch of any of our public repositories
(and almost all are public) is automatically sent to the
gnunet-svn@gnu.org mailinglist. That list is for Git commits only,
and must not be used for discussions. It also carries commits from
our main dependencies, namely GNUnet and GNU libmicrohttpd. While
it can be high volume, the lists is a good way to follow overall
development.
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).
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.
For example, in the
Taler exchange repository,
the bootstrap script eventually runs the git submodule update command
early on, and later runs script ./contrib/gana.sh, which in turn
runs script ./contrib/gana-update.sh, which performs various tasks,
such as generating the file src/include/taler_signatures.h.
Thus, to update that file, you need to:
gnunet-signatures/registry.rec.
(You can check for uniqueness with the recfix utility.)contrib/gana and run
command git pull there.make install, make check, etc.
(Basically, make sure the change does not break anything.)A similar procedure is required for other databases in GANA.
See file README in the various directories for specific instructions.
We package our software for Debian and Ubuntu.
To try the latest, unstable and untested versions of packages, you can add the nightly package sources.
# For Ubuntu (focal-fossa)
$ echo "deb https://deb.taler.net/apt-nightly focal-taler-nightly main" > /etc/apt/sources.list.d/taler.list
# For Debian (bullseye)
$ echo "deb https://deb.taler.net/apt-nightly bullseye-taler-nightly main" > /etc/apt/sources.list.d/taler.list
# Both: Install signing key for nightly packages
$ wget -O - https://taler.net/taler-systems-nightly.gpg.key | apt-key add -
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.
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.
On gv.taler.net, there are four system users that are set up to
serve Taler on the Internet:
taler-test: serves *.test.taler.net and gets automatically
built by Buildbot.taler-internal: serves *.int.taler.net, and does NOT get
automatically built.demo: serves *.demo.taler.net. Never automatically built.demo user on gv.taler.net.deployment.git code.deployment.git/docker/demo directory.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.
$ 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 demo upgrade checklist to make
sure everything is working.
Nginx is already configured to reach the services as exported by
Docker Compose.
All commands run from deployment.git/docker/demo.
# 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
All Taler components must be tagged with git before they are deployed on the
demo environment, using a tag of the following form:
demo-YYYY-MM-DD-SS
YYYY = year
MM = month
DD = day
SS = serial
GNU Taler uses a buildbot implementation (front end at https://buildbot.taler.net) to manage continuous integration. Buildbot documentation is at https://docs.buildbot.net/.
Here are some highlights:
buildbot-worker command.Best Practices:
master.cfg file, leave a comment specifying the server and user account that this WORKER is called from. (At this time, taler.net is the only server used by this implementation, but it’s still good practice.)buildbot-worker create-worker <workername> localhost <username> <password>Then make sure there is a WORKER defined in master.cfg like: worker.Worker("<username>", "<password>")
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:
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/
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:
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/
All the Taler documentation is built by the user docbuilder that
runs a Buildbot worker. The following commands set the docbuilder up,
starting with an empty home directory.
# Log-in as the 'docbuilder' user.
$ cd $HOME
$ git clone git://git.taler.net/deployment
$ ./deployment/bootstrap-docbuilder
# If the previous step worked, the setup is
# complete and the Buildbot worker can be started.
$ buildbot-worker start worker/
Taler Websites, www.taler.net and stage.taler.net, are built by the
user taler-websites by the means of a Buildbot worker. The following
commands set the taler-websites up, starting with an empty home directory.
# Log-in as the 'taler-websites' user.
$ cd $HOME
$ git clone git://git.taler.net/deployment
$ ./deployment/bootstrap-sitesbuilder
# If the previous step worked, the setup is
# complete and the Buildbot worker can be started.
$ buildbot-worker start worker/
Code coverage tests are run by the lcovworker user, and are also driven
by Buildbot.
# Log-in as the 'lcovworker' user.
$ cd $HOME
$ git clone git://git.taler.net/deployment
$ ./deployment/bootstrap-taler lcov
# If the previous step worked, the setup is
# complete and the Buildbot worker can be started.
$ buildbot-worker start worker/
The results are then published at https://lcov.taler.net/.
Both ‘test’ and ‘demo’ setups get their auditor reports compiled by a Buildbot worker. The following steps get the reports compiler prepared.
# Log-in as <env>-auditor, with <env> being either 'test' or 'demo'
$ git clone git://git.taler.net/deployment
$ ./deployment/buildbot/bootstrap-scripts/prepare-auditorreporter <env>
# If the previous steps worked, then it should suffice to start
# the worker, with:
$ buildbot-worker start worker/
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 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. All tables of a GNU Taler component should live in their own schema.
Please use the release checklist
This document describes the process for releasing a new version of the various Taler components to the official GNU mirrors.
The following components are published on the GNU mirrors
Tag releases with an annotated commit, like
$ git tag -a v0.1.0 -m "Official release v0.1.0"
$ git push origin v0.1.0
For tests in the exchange and merchant to run, make sure that a database talercheck is accessible by $USER. Otherwise tests involving the database logic are skipped.
Note
Taler may store sensitive business and customer data in the database. Any operator SHOULD thus ensure that backup operations are encrypted and secured from unauthorized access.
Set the version in configure.ac. The commit being tagged should be
the change of the version.
Tag the current GANA version that works with the exchange and merchant and checkout that tag of gana.git (instead of master). Otherwise, if there are incompatible changes in GANA (like removed symbols), old builds could break.
Update the Texinfo documentation using the files from docs.git:
# Get the latest documentation repository
$ cd $GIT/docs
$ git pull
$ make texinfo
# The *.texi files are now in _build/texinfo
#
# This checks out the prebuilt branch in the prebuilt directory
$ git worktree add prebuilt prebuilt
$ cd prebuilt
# Copy the pre-built documentation into the prebuilt directory
$ cp -r ../_build/texinfo .
# Push and commit to branch
$ git commit -a -S -m "updating texinfo"
$ git status
# Verify that all files that should be tracked are tracked,
# new files will have to be added to the Makefile.am in
# exchange.git as well!
$ git push
# Remember $REVISION of commit
#
# Go to exchange
$ cd $GIT/exchange/doc/prebuilt
# Update submodule to point to latest commit
$ git checkout $REVISION
Finally, the Automake Makefile.am files may have to be adjusted to
include new *.texi files or images.
For bootstrap, you will need to install GNU Recutils.
For the exchange test cases to pass, make install must be run first.
Without it, test cases will fail because plugins can’t be located.
$ ./bootstrap
$ ./configure # add required options for your system
$ make dist
$ tar -xf taler-$COMPONENT-$VERSION.tar.gz
$ cd taler-$COMPONENT-$VERSION
$ make install check
The version of the wallet is in manifest.json. The version_name
should be adjusted, and version should be increased independently on
every upload to the WebStore.
$ ./configure
$ make dist
See https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
Directive file:
version: 1.2
directory: taler
filename: taler-exchange-0.1.0.tar.gz
Upload the files in binary mode to the ftp servers.
Our general setup is based on https://wiki.debian.org/DebianRepository/SetupWithReprepro
First, update at least the version of the Debian package in debian/changelog, and then run:
$ dpkg-buildpackage -rfakeroot -b -uc -us
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.
Next, the *.deb files should be copied to gv.taler.net, say to
/home/aptbuilder/incoming. Then, run
# cd /home/aptbuilder/apt
# reprepro includedeb bullseye ~/incoming/*.deb
to import all Debian files from ~/incoming/ into the bullseye
distribution. If Debian packages were build against other distributions,
reprepro may need to be first configured for those and the import command
updated accordingly.
Finally, make sure to clean up ~/incoming/ (by deleting the
now imported *.deb files).
CI is done with Buildbot (https://buildbot.net/), and builds are triggered by the means of Git hooks. The results are published at https://buildbot.taler.net/ .
In order to avoid downtimes, CI uses a “blue/green” deployment technique. In detail, there are two users building code on the system, the “green” and the “blue” user; and at any given time, one is running Taler services and the other one is either building the code or waiting for that.
There is also the possibility to trigger builds manually, but this is only reserved to “admin” users.
Internationalization (a.k.a “Translation”) is handled with Weblate (https://weblate.org) via our instance at https://weblate.taler.net/ .
At this time, this system is still very new for Taler.net and this documentation may be incorrect and is certainly incomplete.
At this time, anyone can register an account at https://weblate.taler.net/ to create translations. Registered users default to the Users and Viewers privilege level.
This is the breakdown of privilege levels in Weblate:
To upgrade from Users/Viewers, a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck.
The GNU Taler project is probably the correct project for most Components and Translations falling under this guide. Please contact a superuser if you need another Project created.
Reference: https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#component-configuration
In Weblate, a Component is a subset of a Project and each Component contains N translations. A Component is generally associated with a Git repo.
To create a Component, log into https://weblate.taler.net/ with your Manager or higher credentials and choose + Add from the upper-right corner.
What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your Component to the Taler Git repository:
Under https://weblate.taler.net/create/component/vcs/:
git+ssh://git@git.taler.net/<reponame>`. Check with git remote -v.git+ssh://git@git.taler.net/<reponame>` Check with git remote -v.https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}} where <repositoryname> gets replaced but {{filename}} and other items in braces are actual variables in the string.1 - Log into https://weblate.taler.net
2 - Navigate to Projects > Browse all projects
3 - Choose the Project you wish to contribute to.
4 - Choose the Component you wish to contribute to.
5 - Find the language you want to translate into. Click “Translate” on that line.
6 - Find a phrase and translate it.
You may also wish to refer to https://docs.weblate.org/ .
By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the Component you want to translate for, and click “Start new translation” to begin. If you require a privilege upgrade, please contact a superuser with your request.
When asked, set the license to GPLv3 or later.
Set commit/push to manual only.
weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at https://weblate.taler.net/keys/.
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.
There are currently three Android apps in the official Git repository:
Their git repositories are mirrored at Gitlab
to utilize their CI
and F-Droid’s Gitlab integration
to publish automatic nightly builds
for each change on the master branch.
All three apps publish their builds to the same F-Droid nightly repository (which is stored as a git repository): https://gitlab.com/gnu-taler/fdroid-repo-nightly
You can download the APK files directly from that repository or add it to the F-Droid app for automatic updates by clicking the following link (on the phone that has F-Droid installed).
Note
Nightly apps can be installed alongside official releases and thus are meant only for testing purposes. Use at your own risk!
Note that this guide is different from other guides for building Android apps,
because it does not require you to run non-free software.
It uses the Merchant PoS Terminal as an example, but works as well for the other apps
if you replace merchant-terminal with wallet or cashier.
First, ensure that you have the required dependencies installed:
Then you can get the app’s source code using git:
# Start by cloning the Android git repository
$ git clone https://git.taler.net/taler-android.git
# Change into the directory of the cloned repository
$ cd taler-android
# Find out which Android SDK version you will need
$ grep -i compileSdkVersion merchant-terminal/build.gradle
The last command will return something like compileSdkVersion 29.
So visit the Android Rebuilds project
and look for that version of the Android SDK there.
If the SDK version is not yet available as a free rebuild,
you can try to lower the compileSdkVersion in the app’s merchant-terminal/build.gradle file.
Note that this might break things
or require you to also lower other versions such as targetSdkVersion.
In our example, the version is 29 which is available,
so download the “SDK Platform” package of “Android 10.0.0 (API 29)”
and unpack it:
# Change into the directory that contains your downloaded SDK
$ cd $HOME
# Unpack/extract the Android SDK
$ unzip android-sdk_eng.10.0.0_r14_linux-x86.zip
# Tell the build system where to find the SDK
$ export ANDROID_SDK_ROOT="$HOME/android-sdk_eng.10.0.0_r14_linux-x86"
# Change into the directory of the cloned repository
$ cd taler-android
# Build the merchant-terminal app
$ ./gradlew :merchant-terminal:assembleRelease
If you get an error message complaining about build-tools
- > Failed to install the following Android SDK packages as some licences have not been accepted.
- build-tools;29.0.3 Android SDK Build-Tools 29.0.3
you can try changing the buildToolsVersion in the app’s merchant-terminal/build.gradle file
to the latest “Android SDK build tools” version supported by the Android Rebuilds project.
After the build finished successfully,
you will find your APK in merchant-terminal/build/outputs/apk/release/.
Translations are managed with Taler’s weblate instance: https://weblate.taler.net/projects/gnu-taler/
To update translations, enter the taler-android git repository and ensure that the weblate remote exists:
$ git config -l | grep weblate
If it does not yet exist (empty output), you can add it like this:
$ git remote add weblate https://weblate.taler.net/git/gnu-taler/wallet-android/
Then you can merge in translations commit from the weblate remote:
# ensure you have latest version
$ git fetch weblate
# merge in translation commits
$ git merge weblate/master
Afterwards, build the entire project from source and test the UI to ensure that no erroneous translations (missing placeholders) are breaking things.
After extensive testing, the code making up a new release should get a signed git tag. The current tag format is:
$ git tag -s $APP-$VERSION
Nightly builds get published automatically (see above) after pushing code to the official repo. Actual releases get picked up by F-Droid’s official repository via git tags. So ensure that all releases get tagged properly.
Some information for F-Droid official repository debugging:
Google Play uploads are managed via Fastlane. Before proceeding, ensure that this is properly set up and that you have access to the Google Play API.
To release an app, enter into its respective folder and run fastlane:
$ bundle exec fastlane
Then select the deploy option. Note this requires access to the Google Play upload signing key set via the various environment variables in $app/fastlane/Fastfile.
All uploads are going to the beta track by default. These can be promoted to production later or immediately after upload if you feel daring.
Code coverage is done with the Gcov / Lcov (http://ltp.sourceforge.net/coverage/lcov.php) combo, and it is run nightly (once a day) by a Buildbot worker. The coverage results are then published at https://lcov.taler.net/ .
GNU Taler is developed primarily in C, Kotlin, Python and TypeScript.
These are the general coding style rules for Taler.
taler_” (exception: platform.h),
and MUST live in src/include/taler_” and
MUST NOT live in src/include/ and
SHOULD NOT be included from outside of their own directory-l LOGFILE, its absence means write logs to stderrTALER_, without subsystemnameTALER_ or any other prefixShell scripts should be avoided if at all possible. The only permissible uses of shell scripts in GNU Taler are:
./configure) that must run on
as many systems as possible.When shell scripts are used, they MUST begin with the following set command:
# Make the shell fail on undefined variables and
# commands with non-zero exit status.
$ set -eu
We so far have no specific guidelines, please follow best practices for the language.
Python code should be written and build against version 3.7 of Python.
We use yapf to reformat the
code to conform to our style instructions.
A reusable yapf style file can be found in build-common,
which is intended to be used as a git submodule.
When using Python for writing small utilities, the following libraries are useful:
click for argument parsing (should be preferred over argparse)pathlib for path manipulation (part of the standard library)subprocess for “shelling out” to other programs. Prefer subprocess.run
over the older APIs.This chapter is a VERY ABSTRACT description of how testing is implemented in Taler, and in NO WAY wants to substitute the reading of the actual source code by the user.
In Taler, a test case is an array of struct TALER_TESTING_Command,
informally referred to as CMD, that is iteratively executed by the
testing interpreter. This latter is transparently initiated by the
testing library.
However, the developer does not have to defined CMDs manually, but
rather call the proper constructor provided by the library. For example,
if a CMD is supposed to test feature x, then the library would
provide the TALER_TESTING_cmd_x () constructor for it. Obviously,
each constructor has its own particular arguments that make sense to
test x, and all constructor are thoroughly commented within the
source code.
Internally, each CMD has two methods: run () and cleanup (). The
former contains the main logic to test feature x, whereas the latter
cleans the memory up after execution.
In a test life, each CMD needs some internal state, made by values it keeps in memory. Often, the test has to share those values with other CMDs: for example, CMD1 may create some key material and CMD2 needs this key material to encrypt data.
The offering of internal values from CMD1 to CMD2 is made by traits. A
trait is a struct TALER_TESTING_Trait, and each CMD contains an array
of traits, that it offers via the public trait interface to other
commands. The definition and filling of such array happens transparently
to the test developer.
For example, the following example shows how CMD2 takes an amount object offered by CMD1 via the trait interface.
Note: the main interpreter and the most part of CMDs and traits are hosted inside the exchange codebase, but nothing prevents the developer from implementing new CMDs and traits within other codebases.
/* Without loss of generality, let's consider the
* following logic to exist inside the run() method of CMD1 */
...
struct TALER_Amount *a;
/**
* the second argument (0) points to the first amount object offered,
* in case multiple are available.
*/
if (GNUNET_OK != TALER_TESTING_get_trait_amount_obj (cmd2, 0, &a))
return GNUNET_SYSERR;
...
use(a); /* 'a' points straight into the internal state of CMD2 */
In the Taler realm, there is also the possibility to alter the behaviour of supposedly well-behaved components. This is needed when, for example, we want the exchange to return some corrupted signature in order to check if the merchant backend detects it.
This alteration is accomplished by another service called twister. The twister acts as a proxy between service A and B, and can be programmed to tamper with the data exchanged by A and B.
Please refer to the Twister codebase (under the test directory) in
order to see how to configure it.
This section contains terminology that should be used and that should not be used in the user interface and help materials.
Refreshing is the internal technical terminology for the protocol to give change for partially spent coins
Use instead: “Obtaining change”
Charge has two opposite meanings (charge to a credit card vs. charge a battery). This can confuse users.
Use instead: “Obtain”, “Credit”, “Debit”, “Withdraw”
Coins are an internal construct, the user should never be aware that their balance is represented by coins if different denominations.
Use instead: “(Digital) Cash” or “(Wallet) Balance”
Has bad connotation of consumption.
Use instead: Customer or user.
The term used to describe the process of the merchant facilitating the download of the signed contract terms for an order.
Avoid. Generally events that relate to proposal downloads should not be shown to normal users, only developers. Instead, use “communication with mechant failed” if a proposed order can’t be downloaded.
Should be generally avoided, since Taler is only anonymous for the customer. Also some people are scared of anonymity (which as a term is also way too absolute, as anonymity is hardly ever perfect).
Use instead: “Privacy-preserving”, “Privacy-friendly”
The process of proving to the merchant that the customer is entitled to view a digital product again, as they already paid for it.
Use instead: In the event history, “re-activated digital content purchase” could be used. (FIXME: this is still not nice.)
Too ambiguous in the wallet.
Use instead: Purchase
The entity/service that gives out digital cash in exchange for some other means of payment.
In some contexts, using “Issuer” could also be appropriate. When showing a balance breakdown, we can say “100 Eur (issued by exchange.euro.taler.net)”. Sometimes we may also use the more generic term “Payment Service Provider” when the concept of an “Exchange” is still unclear to the reader.
This glossary is meant for developers. It contains some terms that we usually do not use when talking to end users or even system administrators.
accounting mechanism used by the exchange to track customer funds from incoming wire transfers. 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 wallet to withdraw up to the amount received in fresh coins from the reserve, thereby draining the reserve. If a reserve is not drained, the exchange eventually closes 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.
This section describes various internal programs to make life easier for the developer.
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.