Relay deployment and configuration
This section describes the process of deploying and configuring an external relay
Last updated
This section describes the process of deploying and configuring an external relay
Last updated
The deployment and configuration of an external relay closely resemble the process of deploying and configuring the client part of the protocol (client contracts and client off-chain module). The process can be divided into 3 steps:
Deployment of external relay contracts to all supported networks
Contacting our support service to obtain an identification key for the relay's off-chain module and adding the addresses of external relay contracts to the trusted list on the protocol initializer contracts
Configuration and launch of the external relay's off-chain module.
First, it is essential to deploy the external relay contracts to all supported networks. The contracts are available in the protocol repositories:
The deployment of the relay contract consists of two steps:
Deployment of the relay contract
Adding the list of supported networks and their types to the contract by invoking the method function addChains(uint64[] calldata _chainIds, uint8[] calldata _chainTypes) on the deployed contract.
Additionally, console commands have been developed to simplify the deployment of these contracts.
The command accepts the following parameters:
testnetFlag - optional parameter, accepted values 0 or 1)
networkName - mandatory parameter: The name of the network into which the contract is being deployed. You can check the list of available networks here
Upon successful execution, the command will return a response similar to the following (the relay address will be displayed under the External relay address):
The command accepts the following parameters:
networkName - mandatory parameter: The name of the network into which the contract is being deployed. You can check the list of available networks here.
Upon successful execution, the command will return a response similar to the following (the relay address will be displayed under the External relay address):
Coming soon
Coming soon
Asterizm Protocol conducts a personal audit of each connected external relay. Additionally, the protocol retains the right to remove a specific external relay from the protocol system if the relay violates the protocol's rules and agreements.
Furthermore, the protocol has a real-time monitoring system for the status of each external relay. In the event of any issues on the external relay's side, its status will be updated on the corresponding page of the protocol scanner.
To execute these protocol logics, the protocol must have the ability to identify each connected external relay. For this purpose, a unique identifier is assigned to each external relay, which needs to be added to the configuration of the off-chain module (see below).
After the relay representative contacts the Asterizm support service, it requests a list of addresses of relay contracts deployed in all supported networks, conducts its own audit, adds the contract addresses to the trusted relay list on the initializer contract, stores the external relay in the internal database, and issues a unique identifier. After this, you can proceed to the final step - configuring the off-chain module of the external relay.
To operate the external relay, in addition to the relay contracts in each network, it is also necessary to configure the off-chain module. The configuration is done on a private server of the external relay and is the responsibility of the external relay's staff. Asterizm Protocol has no access to it.
To proceed further, it's necessary to install Docker together with Docker Compose on the server. You can refer to the official documentation for installation and setup instructions: https://docs.docker.com/engine/install/
For these purposes, Asterizm Protocol has developed a Docker image. You should use this image to create Docker containers on your server. To begin, please download the image:
After downloading the image, you should follow these steps:
Create a docker-compose.yml file to automate the deployment of the server
Configure the configuration parameters for the external relay
Apply migrations, fixtures, and launch the Docker containers
For example, let's assume that the external relay intends to support two networks - Ethereum (EVM) and Everscale (TVM), with the root directory of the off-chain module being /opt/relay. All system configuration files will be based on this example. To add other supported networks, you need to make the necessary changes to the configuration files of the external relay's off-chain module.
This file is intended for automating the deployment of Docker containers. To complete this step, follow these instructions:
In the terminal, create the root directory and, if necessary, assign the required permissions: mkdir /opt/relay && cd /opt/relay (To assign permissions, use the chown {username} /opt/relay command)
Next, create directories for the off-chain module data:
mkdir -p docker-data/db
mkdir -p docker-data/config
Now, create the docker-compose.yml file (touch /opt/relay/docker-compose.yml). Here's the template structure for this file:
In this file, you need to specify the username and password for the PostgreSQL database and Redis caching service of the off-chain module.
After creating this file, you can proceed to the next step.
To set the internal settings of the off-chain module, there is a primary configuration file. You should modify the parameters in this file to suit your needs.
In our example, the configuration file will be located in the directory /opt/relay/docker-data/config/Project.yml(touch /opt/relay/docker-data/config/Project.yml), however, you can change its name/path according to your preference. If you do so, make sure to update the paths in the docker-compose.yml file.
Here is the structure of the configuration file:
Important: Please note that the configuration format for EVM and TVM networks is slightly different: in TVM networks the OwnerPublicKey parameter is added
Supported encryption methods (CipherMethod parameter): AES-{128, 192, 256}-{CBC, OFB, CFB, CTR}. Recommended: AES-256-CBC.
In order for the off-chain module to properly extract the payload received from the contract, it is necessary to specify what types of data are stored in it. For this purpose, the PayloadStruct parameter is used. You need to specify what types of parameters are stored in your contract. System-supported parameters: bool, string, bytes, int (all sizes), uint (all sizes).
You can configure the logging level of the client off-chain module. This parameter affects the completeness of the information in the module's logs. Logs are written to stdout, so you can see them in docker container logs (docker logs -f {container-name}). There are 4 levels:
INFO (logs minimal required information, standard actions),
WARN (includes INFO logging level, adds a detailed log of some exceptions),
ERROR (includes WARN logging level, adds full system error log),
DEBUG (includes ERROR logging level, adds a log of most system actions, used for error detection and debugging, not recommended for product deployment).
Default logging level (if the configuration parameter is not set) is INFO.
Personal unique data, such as the private encryption key, the default encryption salt, the RPC addresses of the nodes, the contract addresses of each network (contracts must already be deployed), and the user names, database, and hash service passwords (specified in the docker-compose.yml file, see the previous step) must be entered into this configuration file.
To start the Docker containers for the off-chain module, you can simply execute one command: docker compose -f /opt/relay/docker-compose.yml up -d. After executing this command, the module will start.
The next and final step is to configure the off-chain module's database. To do this, follow these steps:
docker exec relay-db psql -U database-user -c "CREATE DATABASE relay" - This command will create a database in the relay-db container (note the database user name, it was specified in docker-compose.yml);
docker exec relay-console /app/main migrations/up - this command extracts migrations to the database;
docker exec relay-console /app/main db/seed - this command extracts fixtures onto the database. Important: you can add -test a flag for filling the database with testnet networks.
After successfully executing these commands, the off-chain module's database will be ready for operation. You can then restart the module's containers with the following command: docker compose -f /opt/relay/docker-compose.yml restart.
To enable operation, it is necessary to add data about contract owners to the system. This can be done using the following console command:
This command adds a contract owner of a specific network. It accepts the following parameters:
network-symbol - mandatory parameter, the network symbol (e.g., ETH, POL, etc.)
owner-address - mandatory parameter, the address of the owner
owner-private-key - mandatory parameter, the private key of the owner
owner-public-key - optional parameter, the public key of the owner (used in TVM systems).
To display a list of owners already added to the system, execute the following command:
To display a list of owners already added to the system, you can execute the following command:
network-symbol - optional parameter, the network symbol (e.g., ETH, POL, etc.)
Added owners cannot be deleted; they can only be deactivated. This is done with the following command:
This command deactivates a previously added owner. The command accepts the following parameters:
owner-id - mandatory parameter, the ID of the owner, which can be obtained by executing the console method for listing owners
Deactivated owners can be reactivated. This is achieved by executing the following console command:
This command activates a previously deactivated owner. The command accepts the following parameters:
owner-id - mandatory parameter, the ID of the owner, which can be obtained by executing the console method for listing owners.
After changing the configuration file, it is necessary to restart the system containers (if they were previously running) with the following command: docker compose -f /opt/relay/docker-compose.yml restart
Congratulations! You are now ready to start working with the system.
To check the functionality of the Docker containers, you can use the docker ps command, which will display a list of containers along with their status and other information.
If you want to read the logs of a specific off-chain module container, you can use the docker logs -f relay-eth command. This command will display the logs of the Ethereum network container. You can similarly check the logs of other containers by replacing relay-eth with the name of the specific container you want to check.
The verbosity level of the logs can be configured in the module's configuration file under the Environment.LogLevel parameter.
