Default implementation (manual)

The client off-chain module is deployed via Docker image, implemented by the Asterizm team.

To deploy the client off-chain module, you must first install the Docker, which installs together with Docker Compose.

The official installation guide: https://docs.docker.com/engine/install/

The image is a node scanner written on GO. It is publicly available at https://hub.docker.com/.

Download command (in the server console):

docker pull asterizm/client-server:latest

After installing the Docker, please follow these steps:

  1. Create a docker-compose.yml to automate the deployment of the server;

  2. Set up the server environment;

  3. Start containers, and place migrations into the database;

  4. Add the private keys of contract owners via asterizm-console or Fireblocks integration.

1. Docker-compose.yml

This file is used to automate the deployment of the client's server using Docker Compose.

For example, let's configure the service so that we can send transfers between Ethereum (EVM) and Everscale (TVM) networks.

  1. Create a base directory on the server and navigate to it. Let's call it /opt/asterizm - in the terminal run mkdir /opt/asterizm && cd /opt/asterizm (assign current user permissions to the directory with chown {username} /opt/asterizm command)

  2. Next, you need to create directories for the system containers to work, run the following commands: mkdir -p docker-data/db mkdir -p docker-data/config With these commands, the structure for the Docker containers to work will be created.

  3. Now let's create docker-compose.yml - touch /opt/asterizm/docker-compose.yml :

/opt/asterizm/docker-compose.yml
version: '3.9'
services:

  asterizm-db:
    container_name: asterizm-db
    image: postgres:15-alpine
    restart: always
    volumes:
      - ./docker-data/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=database-user # set it to config file
      - POSTGRES_PASSWORD=database-password # set it to config file
    networks:
      - asterizm

  asterizm-console: &console-template
    container_name: asterizm-console
    privileged: true
    image: asterizm/client-server:latest
    working_dir: /app
    restart: always
    depends_on:
      - asterizm-db
    volumes:
      - ./docker-data/config/Project.yml:/app/config.yml:rw
    networks:
      - asterizm

  asterizm-cron:
    <<: *console-template
    container_name: asterizm-cron
    command: ["cron/process"]

  asterizm-eth:
    <<: *console-template
    container_name: asterizm-eth
    command: ["node/scan", "ETH"]

  asterizm-ever:
    <<: *console-template
    container_name: asterizm-ever
    command: ["node/scan", "EVER"]

  asterizm-ton:
    <<: *console-template
    container_name: asterizm-ton
    command: ["node/scan", "TON"]

  asterizm-sol:
    <<: *console-template
    container_name: asterizm-sol
    command: ["node/scan", "SOL"]

networks:
  asterizm:
    driver: bridge

In this file, you have to specify the database user name, as well as the database passwords.

After creating this file, you can proceed to the next step of configuring the client off-chain module.

2. Setting up the server environment

For the most part, installing Docker is the main step in setting up the environment, but you should do a few more things to work comfortably with the client's off-chain module.

Create a basic server configuration file: touch docker-data/config/Project.yml:

docker-data/config/Project.yml
Environment:
  LogLevel: INFO
Utils:
  Encryption:
    EncryptPayload: true # encryption activation flag (false - transfer data will not be encrypted)
    Key: "encryption-key" #transfer data encryption key
    Salt: "encryption-default-salt" # default data encryption salt
    CipherMethod: "AES-256-CBC" # encryption method
  Db:
    Host: asterizm-db # database host (name of database container docker)
    Port: 5432 # database port
    Name: client_server # database name
    User: "database-user" # database user name
    Password: "database-password" # database user password
  AsterizmTranslator:
    Host: https://tr.asterizm.io # Asterizm host translator
    ApiKey: "13b7AYfdKsYqQiQa7Bv9twgeQzLhZAayTXK8MbqQ1d9Kcw49" # Asterizm translator api key (just copipast it in your config)
Nodes:
  PayloadStruct: ["uint256", "uint256", "uint256", "uint256", "uint8"] # client contract payload types
  List:
    ETH: # Ethereum network (EVM)
      RPC: https://ethereum-rpc.com # RPC nodes
      ContractAddress: "client-contract-address-in-eth-network" # client contract address on Ethereum network
      MaxResendTries: 3 # The maximum number of transaction retry attempts (in case the transaction is stuck due to a sudden gas price spike, for example)
      FeeMultiplierPercent: 20 # The recommended fee multiplier to cover the transfer in the destination network. Recommended value is 20 (20%) 
    POL: # Polygon network (EVM)
      RPC: https://polygon-rpc.com # RPC nodes
      ContractAddress: "client-contract-address-in-pol-network" # client contract address on Polygon network
      MaxResendTries: 3 # The maximum number of transaction retry attempts (in case the transaction is stuck due to a sudden gas price spike, for example)
      FeeMultiplierPercent: 20 # The recommended fee multiplier to cover the transfer in the destination network. Recommended value is 20 (20%) 
    EVER: # Everscale network (TVM)
      RPC: https://everscale-rpc.com # node RPC
      ContractAddress: "client-contract-address-in-everscale-network" # client contract address on Everscale network
      MaxResendTries: 3 # The maximum number of transaction retry attempts (in case the transaction is stuck due to a sudden gas price spike, for example)
      FeeMultiplierPercent: 20 # The recommended fee multiplier to cover the transfer in the destination network. Recommended value is 20 (20%)
    VNM: # Venom network (TVM)
      RPC: https://venom-rpc.com # node RPC
      ContractAddress: "client-contract-address-in-venom-network" # client contract address on Venom network
      MaxResendTries: 3 # The maximum number of transaction retry attempts (in case the transaction is stuck due to a sudden gas price spike, for example)
      FeeMultiplierPercent: 20 # The recommended fee multiplier to cover the transfer in the destination network. Recommended value is 20 (20%)
    TON: # Ton network (TON)
      RPC: https://ton-rpc.com # node RPC
      ContractAddress: "client-contract-address-in-venom-network" # client contract address on Ton network
      MaxResendTries: 3 # The maximum number of transaction retry attempts (in case the transaction is stuck due to a sudden gas price spike, for example)
      FeeMultiplierPercent: 10 # The recommended fee multiplier to cover the transfer in the destination network. Recommended value is 20 (20%)
    SOL: # Solana network (SOL) IMPORTANT! this configuration is for cross-chain tokens only
      RPC: https://solana-rpc.com # node RPC
      TokenProgramId: "token-program-id" # base program address of the cross-chain token
      TokenName: "token-name" # cress-chain token name
      ClientProgramId: "client-program-id" # base client program address
      ClientUserAddress: "client-sender-address" # PDA address of the client sender
      InitializerProgramId: "initinalizer-program-id" # initializer program address
      RelayerProgramId: "relay-program-id" # relay program address
      SystemRelayOwnerAddress: "base-relay-owner-address" # base relay owner address
      RelayOwnerAddress: "external-owner-address" # external relay owner address (if available)
      MaxResendTries: 3 # The maximum number of transaction retry attempts (in case the transaction is stuck due to a sudden gas price spike, for example)
      FeeMultiplierPercent: 10 # The recommended fee multiplier to cover the transfer in the destination network. Recommended value is 20 (20%)

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.

3. Running Docker containers

To start the client's server containers, you need to execute a single command (note the path to the docker-compose.yml file): docker compose -f /opt/asterizm/docker-compose.yml up -d After running this command, the Docker containers of the client off-chain module will be up and running.

The next step is to create a database and run migrations and fixtures.

To do this, run the following commands:

  1. docker exec asterizm-db psql -U database-user -c "CREATE DATABASE client_server" - This command will create a database in the asterizm-db container (note the database user name, it was specified in docker-compose.yml);

  2. docker exec asterizm-console /app/main migrations/up - this command extracts migrations to the database;

  3. docker exec asterizm-console /app/main db/seed - this command extracts fixtures onto the database. Important: you can add -test flag for filling database with testnet networks.

After executing these commands, the client off-chain module's database is ready to work.

It is necessary to restart the client's server containers. To do that, please use this command: docker compose -f /opt/asterizm/docker-compose.yml restart

4.a. Managing system owners

To enable operation, it is necessary to add data about contract owners to the system. This can be done using the following console command:

docker exec asterizm-console /app/main owners/add {netwotk-symbol} {owner-private-key} {?owner-public-key/?address-type}

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-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 only)

    • address-type - owner address type (used in TON systems only), available values: v3r1, v3r2, highloadv3, v4r1, v4r2, v5r1

To display a list of owners already added to the system, execute the following command:

docker exec asterizm-console /app/main owners/list {?network-symbol}

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:

docker exec asterizm-console /app/main owners/disable {owner-id}

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:

docker exec asterizm-console /app/main owners/enable {owner-id}

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.

4.b. Fireblocks integration

For the successful operation of the Asterizm Protocol system, it is essential to manage the private keys of contract owners. In certain cases, this may pose a security risk due to potential access by unauthorized parties, such as system developers.

To address this issue we integrated Fireblocks. Through this system, the owner of the client server can store private keys within it, configuring specific permissions for each key. This eliminates the need to store private keys of owners on the client server.

To integrate Fireblocks, registration in the system by obtaining an ApiKey and RSA file is required. These details must be added to the configuration file of the client server (Project.yml), specifically in the network section:

POL:
  RPC: https://polygon-mumbai.blockpi.network/v1/rpc/public
  ContractAddress: "contract-address"
  Fireblocks: # Fireblocks system configuration block
    ApiKey: "fireblocks-apikey" # Fireblocks system ApiKey
    SecretPath: "./fireblocks_secret.rsa" # Path to the Fireblocks system RSA file
    VaultAccountIds: ["1"] # List of Fireblocks vault account IDs in use

This configuration block needs to be added to the configuration of each network that will utilize owners stored in the Fireblocks system.

Important! If the Asterizm Protocol detects the Fireblocks configuration file, along with owners added through the console command, the system will specifically use the Fireblocks owners.

After setting up the configuration file, it is necessary to restart the system containers (if they were previously running) with the following command: docker compose -f /opt/asterizm/docker-compose.yml restart

PreviousSimple implementation (shell script)Next3. Important! One final pre-flight check

Last updated