Simple implementation (shell script)

To simplify the integration of the client off-chain module, we developed a shell script.

The integration process consists of two steps:

Setup of the configuration file of the client off-chain module
Loading and running the integration shell script

IMPORTANT: The script allows to deploy the module only on Linux-based servers with apt package manager installed (e.g. Ubuntu, Debian). If you want to deploy the module on other systems (e.g. Windows), you need to manually configure it (see Default implementation).

Configuration file setup

Here is an example of a configuration file:

config.yml

# Environment Settings Block
Environment:
  # Log level setting; if not provided, the builder will generate it automatically
  # ERROR - Critical error; if found - contact the developers. Script terminates on such errors 
  # WARN - Critical error, but not bad enough to terminate the script; developers should be notified
  # INFO - Informational logs with main details, such as transmission hashes, scanned block numbers, program execution results
  # DEBUG - Debug logs with additional execution details; useful when ERROR or WARN occurs to provide extra information to developers
  # The user sets the LogLevel, below which logs won't be displayed. For instance, if LogLevel is set to WARN, logs of level ERROR and WARN will be displayed.
  # Log level hierarchy: ERROR <- WARN <- INFO <- DEBUG. Recommended setting is INFO, displaying ERROR, WARN, and INFO logs.
  # Optional parameter, default is INFO
  LogLevel: INFO
# Utilities Configuration Block
Utils:
  # Encryption block is mandatory, but the builder will generate it if absent
  Encryption:
    # Whether to encrypt the transmitted information from InitiateTransferEvent on the server side.
    # Recommended to encrypt
    # Optional parameter, default is false
    EncryptPayload: true
    # Encryption key; can be generated on your side or the builder will generate it
    # Mandatory parameter
    Key: key
    # Encryption salt; can be generated on the Client's side or the builder will generate it
    # Mandatory parameter
    Salt: salt
    # Encryption method; available methods: AES-{128/192/256}-{CBC/OFB/CFB/CTR}
    # Recommended method: AES-256-CBC
    # Mandatory parameter
    CipherMethod: "AES-256-CBC"
  # Database configuration block is mandatory, but the builder will generate it if absent
  # PostgreSQL supported
  Db:
    # Database host; mandatory field
    # Note: If 'asterizm-db' is specified, the builder will run it within Docker
    Host: asterizm-db
    # Database port; mandatory field
    Port: 5432
    # Database name; mandatory field
    Name: db
    # Database user; mandatory field
    User: user
    # Database password; mandatory field, the builder will generate it if absent
    Password: password
  # Relay configuration block, mandatory; builder will fail if absent
  AsterizmTranslator:
    # Relay host
    Host: https://tr.asterizm.io
    # Relay API key
    ApiKey: "13b7AYfdKsYqQiQa7Bv9twgeQzLhZAayTXK8MbqQ1d9Kcw49"
# Node Configuration Block
Nodes:
  # Optional field. If true, events will be sent sorted by the Nonce field; default is false
  # If absent, the builder will set a default value
  ForceOrder: false
  # Structure of transmitted ABI information; the structure must match the transmitted information in exact order
  # Field is mandatory only if you're transmitting information between networks with different virtual machines
  # For example, if transmitting from ETH to BSC, the field is optional. But if from ETH to EVER, the field is mandatory.
  # If, for instance, you're transmitting timestamp and name info with abi.encode(1682079822, "John"), specify ["uint16", "string"] in PayloadStruct
  # Supported data types: bool, string, bytes, int{size} (int8, int16, etc), uint{size} (uint8, uint16, etc)
  # Size of int and uint must be 8 to 256 and divisible by 8 without remainder
  # If absent, the builder will leave the array empty
  PayloadStruct: ["uint256", "uint256", "uint256", "uint256", "uint8"]
  List:
    # List of networks where the scanner will run
    # Builder will fail if the list is empty
    # Supported EVM networks: ETH, POL, OPT, AUR, FTM, CEL, AVA, ARB, BOB, BSC, XVM, PZK, BTG
    # Supported TVM networks: EVER, VNM
    ETH:
      # RPC URL, mandatory; builder will fail if absent
      RPC: https://rpc-url
      # Chain Id, mandatory; builder will fail if absent
      ChainId: chainId
      # Deployed client contract address, mandatory; builder will fail if absent
      ContractAddress: contractAddress
      # Address for transmitting information to the blockchain, mandatory; builder will fail if absent
      # Note: The address must be encrypted using the 'utils/encrypt' command (encryption keys and method from Utils.Encryption)
      # Builder will automatically encrypt the address if it's not encrypted
      OwnerAddress: ownerAddress
      # Private key for transmitting information to the blockchain, mandatory; builder will fail if absent
      # Note: The private key must be encrypted using the 'utils/encrypt' command (encryption keys and method from Utils.Encryption)
      # Builder will automatically encrypt the private key if it's not encrypted
      OwnerPrivateKey: ownerPrivateKey
      # Applicable only to TVM networks
      # Public key for transmitting information to the blockchain, mandatory; builder will fail if absent
      # Note: The public key must be encrypted using the 'utils/encrypt' command (encryption keys and method from Utils.Encryption)
      # Builder will automatically encrypt the public key if it's not encrypted
      OwnerPublicKey: ownerPublicKey
      # This field specifies how many times to attempt resending the event transaction to the translator
      # For instance, if the program receives an event with information and sends it to the translator, but gas prices unexpectedly surge at the time of sending, causing the transaction to be stuck in the mempool.
      # If the transaction remains in the mempool for longer than the average transaction confirmation time (e.g., 5 minutes for Ethereum), the program will attempt to resend the transaction.
      # If the field is set to 5, the program will make 5 attempts; if it fails on the 5th attempt, no further retries will be made
      # Optional field, default is 3 attempts
      MaxResendTries: 3
      # This field indicates the percentage increase in the transaction fee.
      # For example, the program calculates a transaction fee for sending to the blockchain, but gas prices surge at the time of sending.
      # You can specify a percentage increase in the fee to account for the potential spike in gas prices
      # The final fee will be calculated using the formula: fee + (fee / 100 * FeeMultiplierPercent)
      # If FeeMultiplierPercent is set to 100, the fee will double; if set to 0, no fee increase will occur
      # Optional field, default is 0; recommended value is 20
      FeeMultiplierPercent: 100

Supported networks:

Mainnet Testnet

Running a shell script

First, you need to determine your system's architecture (32 or 64 bits). To determine whether your Linux installation is 32-bit or 64-bit, you can use the uname command:

uname -m

If the output is x86_64 or amd64, your system is 64-bit. If the output is i686 or i386, your system is 32-bit. Based on that, download and execute the appropriate script:

wget https://github.com/Asterizm-Protocol/client-module-deploy/blob/master/bin/lunix_x64

After downloading, you need to run it with sudo privileges (required for installing Docker), passing the full path to the configuration file as a parameter:

sudo ./lunix_x64 -f /path/to/config.yml

In case of deploying a test environment (testnet), you need to add an additional flag: -test

sudo ./lunix_x64 -f /path/to/config.yml -test

wget https://github.com/Asterizm-Protocol/client-module-deploy/blob/master/bin/lunix_x32

After downloading, you need to run it with sudo privileges (required for installing Docker), passing the full path to the configuration file as a parameter:

sudo ./lunix_x32 -f /path/to/config.yml

In case of deploying a test environment (testnet), you need to add an additional flag: -test

sudo ./lunix_x32 -f /path/to/config.yml -test

After the script executes successfully, your environment will be configured, and the client's off-chain module will be up and running.

If you're interested in the shell script implementation details, you can check it here:

Previous2. Implement off-chain module NextDefault implementation (manual)

Last updated 1 month ago