- The Trustlines Blockchain Infrastructure
The Trustlines Blockchain Infrastructure
Nodes of the Trustlines Blockchain run various applications:
- The node of the blockchain itself
- The monitor that checks if validators act honestly (optional)
- The bridge between Ethereum and the Trustlines Blockchain (only run by validators)
- The netstats client to report the node state to
There are multiple ways to set each of these up. The most straightforward one by far is via our interactive quickstart script. Finer control can be achieved by starting the components individually as Docker containers. Finally, it is also possible to avoid Docker altogether and run everything directly on the host machine.
Before starting the installation process, please have a look at the following sections on the distinction between Laika and the Trustlines Blockchain, system requirements, and security.
TLBC and Laika
There are two different blockchains related to this project. The first one is a testnet called Laika. The second one is considered to be the main net and called the Trustlines Blockchain or TLBC. The instructions within this document primarily focus on the Trustlines Blockchain.
Based on the experiences we have had on our long-running testnet Laika, we recommend at least 4GB of memory and 20GB of SSD storage.
Validators should make sure their node has a high uptime: Otherwise, they miss out on potential revenue and harm the network by increasing average block intervals and time to finality.
For block validation and creation, it is essential to make sure your host system has the correct time configuration. On
most systems, this should be the case by default. You can check the settings with
timedatectl (look for
"System clock synchronized: yes"). For more information, see for example the corresponding
Ubuntu help page.
For the Docker installation modes, Docker needs to be installed and configured.
For the quickstart mode, docker-compose needs to be installed as well.
You must have at least version
Please refer to the official documentation and make sure your user is added to the
docker user group if you cannot
access root permissions to run containers.
For validators it is crucial to safely back up their private key. If they lose their key, they will not be able to
- create any blocks or earn block rewards or
- withdraw their stake on the main chain once it is unlocked.
Furthermore, it is advisable to keep the amount of funds stored in the validator account small by regularly sending the newly earned income to a different account (e.g., a cold wallet stored on a different machine).
Setup With the Quickstart Script
The quickstart script will set up the blockchain node and the monitor as well as optionally the bridge and netstats clients. It allows importing a private key in order to act as a validator. In addition, it will start a watchtower to automatically update the Docker containers when newer versions become available (e.g. for bug fixes or network forks).
To fetch and run the most recent version of the quickstart script for the Trustlines Blockchain, execute the following command on your machine:
bash <(curl -L quickstart.tlbc.trustlines.foundation)
If you want a quickstart setup for the Laika testnet, use the following command instead:
bash <(curl -L quickstart.laika.trustlines.foundation)
The script is interactive and will ask you which components to set up. Once the
setup is complete, the various components will run in the background in the form
of Docker containers. Configuration and chain data can be found in the
tlbc directory placed in the current working directory (
trustlines in case of a Laika setup). It is possible
to customize the own setup by editing those configuration files. This goes for
the configuration of the different components, as well as the composition of the
Docker containers. If an optional component has not been set up on an earlier
run, it can be added later by executing the quickstart script again.
Executing the script again is safe: No configuration will be overridden without asking, in case the user has changed them itself. If conflicting configuration updates occur, they are shown to the user who can ask to see a diff of the changes.
Setup With Docker
A more explicit way of setting up the various components is starting the Docker containers manually as described here. To keep commands as concise as possible, only the most basic options are provided. You might want to set additional ones, e.g., container names or restart policies.
Alternatively, you could also use the quickstart script and adjust the setup afterwards with commands similar to the following ones.
The blockchain image is a standard Parity client with a custom configuration for the Trustlines Blockchain. It also accepts a few additional command line options as described in the help message:
$ docker run --rm trustlines/tlbc-node:release --help NAME Parity Wrapper SYNOPSIS parity_wrapper.sh [-r] [role] [-a] [address] [-p] [arguments] ...
Before starting the node, create a Docker network to conveniently allow other containers to easily connect to it:
$ docker network create network-tlbc
When running the node, you typically want to forward necessary ports to the host so that Parity can find and connect to peers. Additionally, you might want to mount some volumes to persist configuration and chain data. For instance, to run a non-validator node:
$ mkdir -p tlbc/databases/tlbc tlbc/config tlbc/enode tlbc/shared $ docker run -d --name tlbc-node --network network-tlbc \ -v $(pwd)/tlbc/databases/tlbc:/data \ -v $(pwd)/tlbc/config:/config/custom \ -v $(pwd)/tlbc/enode:/config/network \ -v $(pwd)/tlbc/shared:/shared/ \ -p 30302:3030r -p 30302:30302/udp \ trustlines/tlbc-node:release
If you are a validator, this sequence of commands will supply Parity with your keystore file, password, and address so that it can produce blocks:
$ mkdir -p tlbc/databases/tlbc tlbc/config/keys/tlbc tlbc/enode tlbc/shared $ cp /path/to/your/keystore/file.json tlbc/config/keys/tlbc/account.json $ echo "<passphrase_for_keystore_file>" > tlbc/config/pass.pwd $ docker run -d --name tlbc-node --network network-tlbc \ -v $(pwd)/tlbc/databases/tlbc:/data \ -v $(pwd)/tlbc/config:/config/custom \ -v $(pwd)/tlbc/enode:/config/network \ -v $(pwd)/tlbc/shared:/shared/ \ -p 30302:30302 -p 30302:30302/udp \ trustlines/tlbc-node:release
The netstats client reports the state of your node to the netstats page that gives a rough overview of the current network state. It is an optional component which helps the community by providing information on your running node to a central server.
To participate, you first need to request credentials managed by the Trustlines Foundation. Please email
email@example.com to do so.
Once you have your credentials, create a file
tlbc/netstats-env with the following contents:
WS_USER=username-as-provided-by-the-foundation WS_PASSWORD=password-as-provided-by-the-foundation INSTANCE_NAME=please-choose-a-nice-name-here
If you want to be publicly displayed as a validator, add the following line at the end:
Now, the netstats client can be started with
$ docker run -d --name netstats-client --network network-tlbc \ --env-file tlbc/netstats-env \ -e RPC_HOST=tlbc-node \ -e RPC_PORT=8545 \ trustlines/netstats-client:release
The monitor watches the blockchain and makes sure that validators are online and do not equivocate. Every node in the network should run it and users should regularly check for reports of misbehaving validators.
Assuming the blockchain node was configured as described above, this command will start the monitor:
$ mkdir -p tlbc/monitor/reports tlbc/monitor/state $ docker run -d --name tlbc-monitor --network network-tlbc \ -v $(pwd)/tlbc/shared:/config \ -v $(pwd)/tlbc/monitor/state:/state \ -v $(pwd)/tlbc/monitor/reports:/reports \ trustlines/tlbc-monitor:release \ -c /config/trustlines-spec.json -r /reports -d /state \ -u http://tlbc-node:8545
Validators of the Trustlines Blockchain have to run the bridge that converts TLN tokens on the Ethereum chain to TLC tokens on the Trustlines Blockchain. Non-validators should not run a bridge node.
The bridge requires an Ethereum mainnet node which can be a light client. To start one, execute
$ docker network create network-ethereum $ mkdir -p tlbc/databases/mainnet $ docker run -d --name mainnet-node --network network-ethereum \ -v $(pwd)/tlbc/databases/mainnet:/data/database \ --user root \ ethereum/client-go:stable \ --rpc --rpcaddr 0.0.0.0 --nousb --ipcdisable --syncmode light \ --datadir /data/database --rpccorsdomain * --rpcvhosts=*
Now, write a configuration file for the bridge node and store it in
[foreign_chain] rpc_url = "<http://mainnet-node:8545>" token_contract_address = "0x679131F591B4f369acB8cd8c51E68596806c3916" bridge_contract_address = "0x18BDC736b23Ff7294BED9fa988a1443357C7B0ed" event_fetch_start_block_number = 8932341 [home_chain] rpc_url = "<http://tlbc-node:8545>" bridge_contract_address = "0x0000000000000000000000000000000000000401" event_fetch_start_block_number = 0 [validator_private_key] keystore_path = "/config/keys/tlbc/account.json keystore_password_path = "/config/pass.pwd"
Note that the keystore path is not an actual path on the host machine, but rather in the bridge container. The container will have to connect to both of the Docker networks and access the config directory. Therefore, the command looks like this:
$ docker run -d --name bridge-client --network network-tlbc --network network-ethereum \ -v $(pwd)/tlbc/config:/config \ -v $(pwd)/tlbc/bridge-config.toml:/config/bridge-config.toml \ trustlines/bridge:release \ -c /config/bridge-config.toml
Setup Without Docker
We refer to the documentation of the individual components:
For the Trustlines Blockchain node, make sure it uses the correct chain
specification file (
./chain/tlbc/tlbc-spec.json), that the right TCP and UDP
ports are used (30302), and that the JSON RPC APIs
Build Own Image
To build the Docker image, checkout this repository and run
docker build with your preferred tag name. As the context of
the build must be the project root, the path to the
Dockerfile has to be specified manually.
$ git clone https://github.com/trustlines-protocol/blockchain $ docker build -f ./chain/laika/Dockerfile -t MY_TAGNAME ./chain $ docker run ... MY_TAGNAME ...
Running Tests on Contracts
First, install the solidity compiler
solc for compiling the contracts. You
can follow the official installation
documentation. Make sure that you install the version
From the root directory of the repository you can run the tests by calling
make test contracts. This will create a virtual Python environment, install the
dependencies, compile the contracts and run the tests.
The Trustlines Foundation hosts a publically accessible node for the Laika Testnet.
You can access it via the following URL: https://access.laika.trustlines.foundation