exchange/README

                       Welcome to GNU Taler


What is Taler?
==============

Taler is an electronic payment system providing the ability to pay
anonymously using digital cash.  Taler consists of a network protocol
definition (using a RESTful API over HTTP), a Exchange (which creates
digital coins), a Wallet (which allows customers to manage, store and
spend digital coins), and a Merchant website which allows customers to
spend their digital coins.  Naturally, each Merchant is different, but
Taler includes code examples to help Merchants integrate Taler as a
payment system.

Taler is currently developed by a worldwide group of independent free
software developers and the DECENTRALISE team at Inria Rennes.  Taler
is free software and a GNU package (https://www.gnu.org/).

This is an alpha release with a few known bugs, lacking a few
important features, documentation, testing, performance tuning and an
external security audit.  However, you can run the code and it largely
works fine.  that does not work yet.  This package also only includes
the Taler exchange, not the other components of the system.

Documentation about Taler can be found at https://taler.net/.
Our bug tracker is at https://gnunet.org/bugs/.


Dependencies:
=============

These are the direct dependencies for running a Taler exchange:

- GNUnet            >= 0.10.2
- GNU libmicrohttpd >= 0.9.55
- Postgres          >= 9.5



Project structure is currently as follows:

src/include/
  -- installed headers for public APIs

src/util/
  -- common utility functions (currency representation,
     Taler-specific cryptography, Taler-specific json
     support)

src/pq/
  -- Postgres-specific utility functions

src/exchangedb/
  -- Exchange database backend (with DB-specific plugins)

src/exchange/
  -- taler exchange server

src/exchange-tools/
  -- taler exchange helper programs

src/exchange-lib/
  -- libtalerexchange: C API to issue HTTP requests to exchange

src/auditor/
  -- tools to generate reports about financial performance and
     to validate that the exchange has been operating correctly

src/benchmark/
  -- tool to run performance measurements



Getting Started
===============

The following steps illustrate how to set up a exchange HTTP server.
They take as a stub for configuring the exchange the content of 'contrib/exchange-template/config/'.

1) Create a 'test/' directory and copy the stubs in it:

mkdir -p test/config/
cp exchange/contrib/exchange-template/config/* test/config/
cd test/

2) Create the exchange's master with the tool 'gnunet-ecc':

gnunet-ecc -g1 master.priv

3) Edit config/exchange-common.conf by replacing the right value on the line with the
MASTER_PUBLIC_KEY entry with the fresh generated (ASCII version of) master.priv.
This ASCII version is obtained by issuing:

gnunet-ecc -p master.priv

4) Generate other exchange related keys ('denomination' and 'signing' keys), by issuing:

taler-exchange-keyup -d `pwd` -m master.priv

5) Check with:

taler-exchange-keycheck -d `pwd`

6) A exchange needs a database to operate, so the following instructions relate to
how to set up PostgreSQL. On debian, the two packages needed are:

* postgresql
* postgresql-client

For other operating systems, please refer to the relevant documentation.

In this settlement, the exchange wll use a database called 'talercheck' and will
run under the username through which 'taler-exchange-httpd' is launched. Thus assuming
that this user is 'demo', we need to create a 'demo' role for postgresql and make
him the owner of 'talercheck' database.

To perform these administrative tasks we have to impersonate the 'postgres' (by default,
postgres installation assigns privileges to such a user) user, then connect to the running DBMS.
Issue the following:

su # give your root password
su - postgres
psql # this is the command-line client to the DMBS
# the following lines are SQL
CREATE USER demo;
CREATE DATABASE talercheck OWNER demo;
# quit with CTRL-D

7) If any previous step has been successful, it is now possbile to start up the
exchange web server (by default it will listen on port 4241); issue:


taler-exchange-httpd -d `pwd` # assuming we did not move outside of the 'test' directory