Operating the Exchange

Configuration

The following data and facilities have to be set up, in order to run an exchange:

  • Keying
  • Serving
  • Currency
  • Bank account
  • Coins
  • Database

In this document, we assume that $HOME/.config/taler.conf is being customized.

Keying

The exchange works with three types of keys:

  • master key
  • sign keys
  • denomination keys (see section Coins)

master key: in section [exchange], edit the two following values:

  • master_priv_file: Path to the exchange’s master private file.
  • master_public_key: Must specify the exchange’s master public key.

sign keys: the following two options under [exchange_keys] section control sign keys:

  • signkey_duration: How long should one signing key be used?
  • lookahead_sign: How much time we want to cover with our signkeys? Note that if signkey_duration is bigger than lookahead_sign, taler-exchange-keyup will generate a quantity of signkeys which is sufficient to cover all the gap. See Keys duration.

Serving

The exchange can serve HTTP over both TCP and UNIX domain socket. It needs this configuration twice, because it opens one connection for ordinary REST calls, and one for “/admin” and “/test” REST calls, because the operator may want to restrict the access to “/admin”.

The following values are to be configured under the section [exchange] and [exchange-admin]:

  • serve: must be set to tcp to serve HTTP over TCP, or unix to serve HTTP over a UNIX domain socket
  • port: Set to the TCP port to listen on if serve Is tcp.
  • unixpath: set to the UNIX domain socket path to listen on if serve Is unix
  • unixpath_mode: number giving the mode with the access permissiON MASK for the unixpath (i.e. 660 = rw-rw—-).

The exchange can be started with the -D option to disable the administrative functions entirely. It is recommended that the administrative API is only accessible via a properly protected UNIX domain socket.

Currency

The exchange supports only one currency. This data is set under the respective option currency in section [taler].

Bank account

Wireformat

The wireformat is the protocol to be used between the exchange and the banks. The option is wireformat, under section [exchange]. The exchange currently supports the test wireformat. This wireformat is used for testing the system against a fictional bank.

Note

The SEPA wireformat is work in progress.

Incoming

The bank account where the exchange gets money from customers is configured under the section [exchange-wire-incoming-X], where X matches the value given to the option wireformat. This section contains only one option: X_response_file, which takes the path to a text file containing the exchange’s bank account details in JSON format.

The command line tool taler-exchange-wire is used to create such a file. For example, the utility may be invoked as follows:

$ taler-exchange-wire -j '{"name": "The Exchange", "account_number": 10, "bank_uri": "https://bank.demo.taler.net", "type": "test"}' -t test -o exchange.json

Note that the value given to option -t must match the value in the JSON’s field "type".

The generated file will be echoed by the exchange when serving /wire requests.

Outgoing

This exchange’s bank account is used to give money to merchants, after successful deposits operations. If test is the chosen wireformat, the outcoming bank account is configured by the following options under [exchange-wire-outcoming-test]:

  • exchange_account_numer: which bank account number has the exchange
  • bank_uri: base URL of the bank hosting the exchange bank account

Note

The rationale behind having two bank accounts is that the exchange operator, as a security measure, may want to instruct the bank that the incoming bank account is only supposed to receive money.

Database

The option db under section [exchange] gets the DB backend’s name the exchange is going to use. So far, only db = postgres is supported. After choosing the backend, it is mandatory to supply the connection string (namely, the database name). This is possible in two ways:

  • via an environment variable: TALER_EXCHANGEDB_POSTGRES_CONFIG.
  • via configuration option db_conn_str, under section [exchangedb-BACKEND]. For example, the demo exchange is configured as follows:
[exchange]
...
db = postgres
...

[exchangedb-postgres]
db_conn_str = postgres:///talerdemo

Coins (denomination keys)

Sections specifying denomination (coin) information start with “coin_”. By convention, the name continues with “$CURRENCY_[$SUBUNIT]_$VALUE”, i.e. [coin_eur_ct_10] for a 10 cent piece. However, only the “coin_” prefix is mandatory. Each “coin_”-section must then have the following options:

  • value: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is “EUR:0.10”.
  • duration_withdraw: How long can a coin of this type be withdrawn? This limits the losses incurred by the exchange when a denomination key is compromised.
  • duration_overlap: What is the overlap of the withdrawal timespan for this coin type?
  • duration_spend: How long is a coin of the given type valid? Smaller values result in lower storage costs for the exchange.
  • fee_withdraw: What does it cost to withdraw this coin? Specified using the same format as value.
  • fee_deposit: What does it cost to deposit this coin? Specified using the same format as value.
  • fee_refresh: What does it cost to refresh this coin? Specified using the same format as value.
  • rsa_keysize: How many bits should the RSA modulus (product of the two primes) have for this type of coin.

Keys duration

Both signkeys and denom keys have a starting date. The option lookahead_provide, under section [exchange_keys], is such that only keys whose starting date is younger than lookahead_provide will be issued by the exchange.

Installation

Please install the following packages before proceeding with the exchange compilation.

  • autoconf >= 2.69
  • automake >= 1.14
  • libtool >= 2.4
  • autopoint >= 0.19
  • libltdl >= 2.4
  • libunistring >= 0.9.3
  • libcurl >= 7.26 (or libgnurl >= 7.26)
  • GNU libmicrohttpd >= 0.9.39
  • GNU libgcrypt >= 1.6
  • libjansson >= 2.7
  • Postgres >= 9.4, including libpq
  • libgnunetutil (from Git)
  • GNU Taler exchange (from Git)

Except for the last two, these are available in most GNU/Linux distributions and should just be installed using the respective package manager.

The following instructions will show how to install libgnunetutil and the GNU Taler exchange.

Before you install libgnunetutil, you must download and install the dependencies mentioned above, otherwise the build may succeed but fail to export some of the tooling required by Taler.

To download and install libgnunetutil, proceed as follows:

$ git clone https://gnunet.org/git/gnunet/
$ cd gnunet/
$ ./bootstrap
$ ./configure [--prefix=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install

If you did not specify a prefix, GNUnet will install to /usr/local, which requires you to run the last step as root.

To download and install the GNU Taler exchange, proceeds as follows:

$ git clone git://taler.net/exchange
$ cd exchange
$ ./bootstrap
$ ./configure [--prefix=EXCHANGEPFX] \
              [--with-gnunet=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install

If you did not specify a prefix, the exchange will install to /usr/local, which requires you to run the last step as root. Note that you have to specify --with-gnunet=/usr/local if you installed GNUnet to /usr/local in the previous step.

Other

Reserve management

Incoming transactions to the exchange’s provider result in the creation or update of reserves, identified by their reserve key. The command line tool taler-exchange-reservemod allows create and add money to reserves in the exchange’s database.