Running the Trustlines system
This document explains how to run your own trustlines network relay server infrastructure. We will walk you through setting up a relay server and all dependent components. The current documentation is written for a Debian-based Linux system.
If you are low on time, you may jump to the description of the docker-compose based setup.
#
DependenciesSince the trustlines infrastructure components are implemented in python 3, you need to install relevant dependencies. You will need at least python 3.6.
The installation instructions assume you create a dedicated user account and put files directly into the user's home directory. Else, adapt the paths to your needs!
#
Trustlines BlockchainYou need to run our modified OpenEthereum node, which provides the JSONRPC API to the relay server and the indexer. The documentation on how to run it can be found here.
#
ContractsThe trustlines-contracts
repository contains the
solidity contracts to be deployed on the blockchain and a commandline tool to deploy the contracts. The
deploy tools section in the contracts docs contains more information on how to deploy the contracts.
The tool will return the addresses of the deployed contracts. You need to provide that information to the relay server with as json file addresses.json
with the following format:
The directory called config/
contains already prepared files for the different
networks of the foundation. Those include a list of addresses for the registered
currency networks. You can copy one of those files and adopt it to your needs,
in case you want to add custom deployed networks.
We assume from now on that the contracts have already been deployed
and that the addresses.json
file has been copied to the user's home directory.
#
PostgreSQLThe trustlines system uses a PostgreSQL database to store some user data and to keep a synchronized view on the relevant state from the blockchain.
Install PostgreSQL with:
After this, a database user must be created. Please use a real password:
Next, the postgres environment should be configured for the account running the relay server:
After logging in again, in order to have the environment variables set, the user should be able to create the database:
The rest of this tutorial assumes that the user running the relay and
py-eth-index related commands has a working postgresql environment
configured. All programs consider the PG*
environment variables
(like PGHOST
, PGUSER
, ...) and will read ~/.pgpass
for
information about passwords. The py-eth-index section
describes how to create the trustlines specific tables.
#
Creating a VirtualenvRun the following command to create a virtualenv:
And activate the virtualenv with
This will add ~/opt/trustlines-system/bin to PATH
. The following
steps assumes an acticated virtualenv.
#
Py-eth-indexThe py-eth-index repository contains a helper program that synchronizes the relevant information from the blockchain into a postgresql database.
#
Installation of py-eth-indexClone the git repository:
And install py-eth-index
#
Initializing the DatabaseAfter the database has been created, it must be initialized. This can be done with the following command:
#
Importing the ABIsWe need to import the ABIs from the trustline-contracts. Trustlines-contracts is installed as a dependency of the relay server. Please run the following only after you have installed the relay server.
If you did not follow this document to install the relay but prefer an
alternative approach (like via
docker-compose), checkout this
section about the different options to retrieve the
contracts.json
file.
#
Importing EventsThe following command will start importing all relevant events into the postgres database:
This program will run forever.
#
Relay Server#
Installation of the Relay ServerClone the git repository and install it:
#
Running the Relay ServerThe relay server needs the addresses of the deployed contracts. In case you've
deployed your own contracts, please copy addresses.json to ~
.
We will also need a config file. You can use the one from the git checkout:
The relay server reads both files from the current directory per default, so we need to start it where those files have been copied to:
However, this behaviour can be changed, you can check the options with:
The relay server needs access to the OpenEthereum node and the PostgreSQL database.
ethindex runsync
also has to be running for a fully functioning system.
#
Signing TransactionsThe relay server needs to sign transactions. The default behaviour is to rely on a OpenEthereum node with an unlocked account, that signs transactions.
Alternatively the relay can sign transactions locally itself with a configured key. For this approach add the following section to the configuration file and adjust the values. The key is expected to be encrypted in a keystore file. To unlock the key, a password file in clear text must be provided as well.
#
Get Contract ABIsThe file with the compiled contracts (contracts.json
) is bundled within
multiple packages on different platforms. Please checkout that approach that
fits the best for your setup from list below.
#
PyPITo download a specific version, add the version directly behind the package name
separated with a ==
(e.g. trustlines-contracts-bin==1.1.2
).
#
NPMTo download a specific version, add the version directly behind the package name
separated with a @
(e.g. trustlines-contracts-abi@1.1.2
).
#
DockerHubTo download a specific version in relation of the relay, add the wished image
tag behind the image name (e.g. trustlines/relay:0.12.1
).