README.md

Bridge Deployments

Requirements

Make sure to install docker and docker-compose to be able to run and test bridge deployments. If for whatever reason you can't or don't want to use Docker, you can find some scripts for running the bridge here.

Networks

One of the building blocks we use for our deployments are networks. A network is a collection of homogenous blockchain nodes. We have Docker Compose files for each network that we want to bridge. Each of the compose files found in the ./networks folder is able to independently spin up a network like so:

docker-compose -f ./networks/rialto.yml up

After running this command we would have a network of several nodes producing blocks.

Bridges

A bridge is a way for several networks to connect to one another. Bridge deployments have their own Docker Compose files which can be found in the ./bridges folder. These Compose files typically contain bridge relayers, which are services external to blockchain nodes, and other components such as testing infrastructure, or user interfaces.

Unlike the network Compose files, these cannot be deployed on their own. They must be combined with different networks.

In general, we can deploy the bridge using docker-compose up in the following way:

docker-compose -f <bridge>.yml \
               -f <network_1>.yml \
               -f <network_2>.yml \
               -f <monitoring>.yml up

If you want to see how the Compose commands are actually run, check out the source code of the ./run.sh.

One thing worth noting is that we have a monitoring Compose file. This adds support for Prometheus and Grafana. We cover these in more details in the Monitoring section. At the moment the monitoring Compose file is not optional, and must be included for bridge deployments.

Running and Updating Deployments

We currently support two bridge deployments

1. Ethereum PoA to Rialto Substrate
2. Rialto Substrate to Millau Substrate

These bridges can be deployed using our ./run.sh script.

The first argument it takes is the name of the bridge you want to run. Right now we only support two bridges: poa-rialto and rialto-millau.

./run.sh poa-rialto

If you add a second update argument to the script it will pull the latest images from Docker Hub and restart the deployment.

./run.sh rialto-millau update

You can also bring down a deployment using the script with the stop argument.

./run.sh poa-rialto stop

Adding Deployments

We need two main things when adding a new deployment. First, the new network which we want to bridge. A compose file for the network should be added in the /networks/ folder. Secondly we'll need a new bridge Compose file in ./bridges/. This should configure the bridge relayer nodes correctly for the two networks, and add any additional components needed for the deployment. If you want you can also add support in the ./run script for the new deployment. While recommended it's not strictly required.

General Notes

Rialto authorities are named: Alice, Bob, Charlie, Dave, Eve. Rialto-PoA authorities are named: Arthur, Bertha, Carlos. Millau authorities are named: Alice, Bob, Charlie, Dave, Eve.

Both authorities and following accounts have enough funds (for test purposes) on corresponding Substrate chains:

• on Rialto: Ferdie, George, Harry.
• on Millau: Ferdie, George, Harry.

Names of accounts on Substrate (Rialto and Millau) chains may be prefixed with // and used as seeds for the sr25519 keys. This seed may also be used in the signer argument in Substrate and PoA relays. Example:

./substrate-relay relay-headers RialtoToMillau \
	--source-host rialto-node-alice \
	--source-port 9944 \
	--target-host millau-node-alice \
	--target-port 9944 \
	--source-signer //Harry \
	--prometheus-host=0.0.0.0

Some accounts are used by bridge components. Using these accounts to sign other transactions is not recommended, because this may lead to nonces conflict.

Following accounts are used when poa-rialto bridge is running:

• Rialto's Alice signs relay transactions with new Rialto-PoA headers;
• Rialto's Bob signs relay transactions with Rialto-PoA -> Rialto currency exchange proofs.
• Rialto-PoA's Arthur: signs relay transactions with new Rialto headers;
• Rialto-PoA's Bertha: signs currency exchange transactions.

Following accounts are used when rialto-millau bridge is running:

• Millau's Charlie signs complex headers+messages relay transactions on Millau chain;
• Rialto's Charlie signs complex headers+messages relay transactions on Rialto chain;
• Millau's Dave signs Millau transactions which contain messages for Rialto;
• Rialto's Dave signs Rialto transactions which contain messages for Millau;
• Millau's Eve signs relay transactions with message delivery confirmations (lane 00000001) from Rialto to Millau;
• Rialto's Eve signs relay transactions with messages (lane 00000001) from Millau to Rialto;
• Millau's Ferdie signs relay transactions with messages (lane 00000001) from Rialto to Millau;
• Rialto's Ferdie signs relay transactions with message delivery confirmations (lane 00000001) from Millau to Rialto.

Following accounts are used when westend-millau bridge is running:

• Millau's George signs relay transactions with new Westend headers.

Docker Usage