Skip to main content

Configs Explanation

The kickstart file 'docker.env'

docker.env is the basefile which kickstarts all configs generation

Required Parameters

Below is an example of the mimimum file required for configs generation.

#deployment config

#subnet config

#parentchain config
  1. CONFIG_PATH - This is the path to the directory where you want to put the generated configs. Most likely it is your current directory.

  2. NETWORK_NAME - Your subnet Name

  3. NUM_SUBNET - The total number of subnet nodes you want to deploy.

  4. NUM_MACHINE - The number of machines that you want to deploy the subnet across. The generated configs will evenly spread the nodes across the machines.

  5. MAIN_IP - The IP address of the main machine(machine1) which will host subnet services and the bootnode. This IP should be known to all other machines, could be private or public (preferrably private).

  6. PARENTCHAIN - The Parentchain where the Checkpoint Smart Contract (CSC) will be deployed and where relayer will push block headers. Available: 'devnet', 'testnet', 'mainnet'. (Currently only 'devnet' is supported)

  7. PARENTCHAIN_WALLET_PK - The private key of Parentchain wallet

    Optional Parameters

    Versions Config

    By default, generated configs will use the current stable version which is hard coded in the generator (not latest). To customize version the specific component version parameter can be included. Set the value to the docker image version tag you want (eg. VERSION_SUBNET=v0.1.3, VERSION_RELAYER=latest). Brose XDC dockerhub to check the available docker images. Below are the available parameters for versioning.


    Other Configs

  • RELAYER_MODE - 'full' or 'lite', this effects the type of Checkpoint Smart Contract(CSC) that is deployed. Defaults to 'full'. Please check here for relayer mode documentation.
  • GRANDMASTER_PK - The Grandmaster privatekey, only one is allowed. Random if not provided.
  • SUBNETS_PK - Subnet nodes' privatekeys, multiple keys separated by comma(,). Number of keys must equal NUM_SUBNET. Randomized by default.
  • OS - 'linux' or 'mac', default 'linux'. 'mac' is an optional value for single machine testing environment on MacOS. The docker compose setup is differrent due to docker network limitation.
  • NETWORK_ID - If you want a specific number, must be between 1-65536. Default is random.
  • SERVICES_SECRET - A shared secret for authentication between the stats service and the subnet nodes. Default to a random string.
  • SLEEP - Debug parameter, set a timer(in seconds) to prevent the generator docker image from shutting down after generation finished.

Files under 'generated' directory

After the generator has succesfully run, all generated files will be under 'generated' directory. These files can be edited if you would like to further customize your subnet. Below is a description of each generated file and how it is used.

  • commands.txt - The generated instructions to launch the subnet.
  • docker-compose.yml - The main deployment file. Includes docker images versions, startup commands, network configurations.
  • docker-compose.env - The config injection path that docker uses to point to other *.env files.
  • genesis.json - The 'block 0' of the Subnet. Initializes the blockchain for subnet nodes.
  • genesis_input.yml - An intermediate file used in config generation.
  • deployment.config.json - The config file used for CSC deployment.
  • keys.json - Generated keypairs or custom keypairs by user input. Please be mindful to remove this file and keep the credentials securely.
  • common.env - The config parameters for Subnet services.
  • subnet*.env - The config parameters for each Subnet node.

Subnet Ports

  1. Subnet Nodes - 3 ports are used per each subnet, RPC port, WS port, and Peering port. The port number is incremented by 1 for the next subnet node. For example subnet1's RPC is 8545, subnet2's RPC will be 8546 and so on.
  • RPC PORT - 8545, 8546, 8547, ... This is the API port, for outside chain communication to issue transaction or query chaindata.
  • WS PORT - 9555, 9556, 9557, ... This is not used currently.
  • Peering port - 20303, 20304, 20305, ... This is used for subnet nodes and bootnode peering and communication.
  • Subnet ports config can be changed in subnetX.env for each individual subnet.
  1. Bootnode - port 20301
  • Bootnode port can be changed at BOOTNODE_PORT under common.env. Also in each subnetX.env, BOOTNODES port has to be changed.
  1. Stats Server (UI backend) - port 3000.
  • To change this change left value inside docker-compose.yml stats port config. For example 3001:3000 will deploy on port 3001. In each subnetX.env file, STATS_SERVICE_ADDRESS port needs to be changed. In common.env, VITE_SUBNET_URL port also needs to change.
  1. UI Frontend - port 5000.
  • To change this change left value inside docker-compose.yml frontend port config. For example 5001:5000 will deploy on port 5001. Then restart the docker image.