mte/README.md

# MirageOS Taler Exchange

OCaml-based unikernel implementation of a GNU Taler exchange.

# Implementation status

MTE is still experimental and under development.

Currently supported Exchange API endpoint (protocol version v31):
- /terms
- /privacy
- /seed
- /config
- /management/*
- /keys

# Developement setup

Because MTE compile to an unikernel, it requires to be given a TAP interface for network connectivity, and a file (formated to FAT) to use for cryptographic keys storage.
It also require a connection to a PostgreSQL database.

## Network

We need to make a bridge device and asign it the `10.0.0.1` address, then attach a TAP device to it.
To create the appropriate virtual network run `network.sh`.

Be sure that your firewall (e.g. iptables) allows to reach the server and for the server and database to comunicate.

## Database

To setup PostgreSQL, first you will need to initialize a database cluster, create a user and a database.
For that we recommand to follow the archlinuxwiki documentation `https://wiki.archlinux.org/title/PostgreSQL` .
It is important to set the database username to 'mte' and the database name to 'taler-exchange', as those value 
are hardcoded in setup scripts/config.

PostgreSQL need to be configured to listen and accept connection at address `10.0.0.1` on port `5432` (same address as our virtual network bridge, this is for simplicity, as network configuration can be quite cubersome).
Edit PostgreSQL's configuration file to allow that (PostgreSQL's configuration file location may vary depending on your system).

```
/var/lib/postgres/data/postgresql.conf

listen_addresses = '10.0.0.1'
```

```
/var/lib/postgres/data/pg_hba.conf

# TYPE  DATABASE        USER            ADDRESS                 METHOD
# IPv4 local connections:
host    all             all             10.0.0.1/24           trust
```

You may need to restart PostgreSQL after configuration change, or if the bridge at `10.0.0.1` was not yet UP.

Futhermore the database must be initialized (with sql tables, etc) before starting the server.
We aim for database compatibility with GNU Taler exchange.
To initialize the database use the `tools/dbinit.sh` script, it aggregates together the GNU Taler exchange's SQL files required to initialize the database and send commands to the PostgreSQL server with `psql`.
(Or directly use a compatible version of GNU Taler Exchange's `taler-exchange-dbinit` tool)

Prepare SQL queries and create the various elements (e.g. sql tables) required to be in the database.

```
./tools/dbinit fetch
./tools/dbinit build
./tools/dbinit init
```

## Dependencies

MTE use the opam package manager and the dune build system.

Create a dedicated opam switch, pin libraries to the required version and install them.

```
make setup-switch
```

For compilation to a solo5 unikernel, we also need to "vendor" some libraries.

```
make vendors
```

## Assets, configuration file and keys

Create a `keys/` folder, generate a fresh master key for the server (and also a file with the required postgres_password to connect to the database).

```
make keys
```

Create `keys/secmod.fat` file that will be the FAT block storage given to MTE.
MTE will use it to store it's signatures and denominations keys.

```
make secmod.fat
```

Create a `assets/` folder containing default terms of use files and a default configuration file.

```
make assets
```

Complete the configuration file by writing master public key of the server we previously generated into it.

```
make config
```

## Build and run

Now everything should be in place to build and run MTE:

```
make build
make run
```

Access the server on `http://10.0.0.2:3434/`

# Tests

Run tests with

```
dune runtest
```

This will run tests for various utility functions, binary formats and cryptographic functions.
It also test that MTE's binary formats and cryptographic signature on the various fields of `/keys` API are consistent with the reference implementation.

It is also possible to run a test scenario of the `/management` API with the `/test/management.sh` script.
It uses `mte-offline-tool` executable to produce various keys, signatures and JSON objects used in the `/management` API.
Note that this script assumes a server is already running at `http://10.0.0.2:3434`, and that it will write changes to the database.