Docs
chromia.com

Deploy Chromia bridge chains

On this page

This section describes deploying the Event Receiver Chain and the Bridge Chain on Chromia, enabling ERC20 token transfers between Chromia and EVM-compatible networks.

Prerequisites

Before proceeding, ensure you have the following:

If you haven't cloned the repository yet, run:

Terminal
git clone https://bitbucket.org/chromawallet/chromia-bridge-demo.git

1. Navigate to the rell folder

The following steps require you to be inside the chromia-bridge-demo/rell folder. Ensure you are in the correct directory:

Terminal
cd chromia-bridge-demo/rell

2. Install the FT4 Rell library

Before proceeding, install the necessary dependencies using chr library install:

Terminal
chr library install

3. Ensure GTX modules are included

The GTX modules are essential for the bridge to function correctly, enabling transactions between Chromia and external blockchains. The bridge demo app already includes the correct GTX configuration in chromia.yml, so no changes are needed when following this guide. However, if you are setting up your chains, ensure that both the Event Receiver Chain and Bridge Chain include the required GTX modules and synchronization extensions.

Check your chromia.yml

Open chromia.yml and verify the following for each chain:

Event Receiver Chain

YAML
blockchains:
  <event_receiver_chain>:
    module: <module_name>
    config:
      gtx:
        modules:
          - "net.postchain.eif.EifGTXModule"
          - "net.postchain.d1.icmf.IcmfSenderGTXModule"
      sync_ext:
        - "net.postchain.eif.EifSynchronizationInfrastructureExtension"

Bridge Chain

YAML
blockchains:
  <bridge_chain>:
    module: <module_name>
    config:
      gtx:
        modules:
          - "net.postchain.eif.EifGTXModule"
          - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
      sync_ext:
        - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"

For further information about GTX and its role in Chromia's architecture, refer to the Generic Transaction Protocol (GTX) documentation.

4. Deploy the Event Receiver Chain to Testnet

Set the token bridge contract address and block height

In your chromia.yml, update the configuration as follows:

YAML
blockchains:
  <event_receiver_name>:
    module: event_receiver
    config:
      ...
      eif:
        chains:
          bsc:
            network_id: 97
            contracts:
              - "<your_bridge_contract_address>"
            skip_to_height: <latest_block_height>
  • <event_receiver_name> — give this deployment a unique name.
  • <your_bridge_contract_address> — your deployed bridge contract address (must be quoted).
  • <latest_block_height> — a recent block height from the appropriate EVM chain which can be found on the evm explorer respectively.

Set your container ID

Before deploying, ensure the testnet deployment block in your chromia.yml includes the correct container:

YAML
deployments:
  testnet:
    brid: x"6F1B061C633A992BF195850BF5AA1B6F887AEE01BB3F51251C230930FB792A92"
    url: https://node0.testnet.chromia.com
    container: <container_id>

You can obtain the testnet container by following this link:
👉 Get a testnet container

Deploy the Event Receiver Chain to Testnet

Run the following command to deploy the Event Receiver Chain to Testnet:

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <event_receiver_name>

or

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <event_receiver_name> - - key-id=”<key file name>”

By default, this command reads the keyId from the configuration file located at .chromia/config.

  • Windows: C:\Users\<YourUsername>\.chromia\config
  • macOS and Linux: /Users/<YourUsername>/.chromia/config or /home/<YourUsername>/.chromia/config

If you prefer to use a different configuration file, you can specify the path using the --config option:

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <event_receiver_name> --config <config file path>

You can also specify the Key ID by using the --key-id=<your_key_id> flag when invoking the command. This overrides all configuration files:

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <event_receiver_name> --key-id=<your_key_id>

You can also specify the Key ID by using the --key-id=<your_key_id> flag when invoking the command. This overrides all configuration files:

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <event_receiver_name> --key-id=<your_key_id>

You can also specify the Key ID by using the --key-id=<your_key_id> flag when invoking the command. This overrides all configuration files:

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <event_receiver_name> --key-id=<your_key_id>

Expected sample output after event receiver deployment:

Output
deployments:
  testnet:
    chains:
      <event_receiver_name>: x"..."

Make sure to save the event receiver BRID in your chromia.yml file under deployments, inside chains, using the unique name you gave your event receiver in the previous steps.

5. Configure the Bridge Chain in chromia.yml

Before deploying, update the configuration for the <bridge_name> chain in your chromia.yml:

YAML
blockchains:
  <bridge_name>:
    ...
    config:
      ...
      icmf:
        receiver:
          local:
            - bc-rid: x"<event_receiver_brid>"
              topic: "L_evm_block_events"
    moduleArgs:
      bridge:
        bsc_asset_network_id: 97
        bsc_asset_address: x"<evm_token_address>"
        asset_name: "Alice Test"
        asset_symbol: "tALICE"
        asset_decimals: 18
        asset_icon: "https://s2.coinmarketcap.com/static/img/coins/64x64/8766.png"
        bridge_address: x"<evm_bridge_contract_address>"

Replace the following:

  • <bridge_name>: A unique name for your Bridge Chain.
  • <event_receiver_brid>: The RID output from deploying the Event Receiver Chain.
  • <evm_token_address>: The deployed ERC20 token address (hex-prefixed with x"").
  • <evm_bridge_contract_address>: The EVM bridge contract address (also prefixed with x"").

6. Deploy the Bridge Chain to Testnet

Run the following command to deploy the Bridge Chain to Testnet:

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <bridge_name>

or

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <bridge_name>  - - key-id=”<key file name>”

By default, this command reads the keyId from the configuration file located at .chromia/config.

  • Windows: C:\Users\<YourUsername>\.chromia\config
  • macOS and Linux: /Users/<YourUsername>/.chromia/config or /home/<YourUsername>/.chromia/config

If you prefer to use a different configuration file, you can specify the path using the --config option:

Terminal
chr deployment create --settings chromia.yml --network testnet --blockchain <bridge_name> --config <config file path>

Expected sample output after event receiver deployment:

Output
deployments:
  testnet:
    chains:
      <bridge_name>: x"..."

Make sure to save the bridge BRID in your chromia.yml file under deployments, inside chains, using the unique name you gave your bridge in the previous steps.

7. Initialize the Bridge Chain

Run the following command:

Terminal
chr tx --api-url "https://node0.testnet.chromia.com" -brid <BRIDGE_BRID> init

While this command is running, it performs the following steps:

  1. Initializes the Chromia bridge component.
  2. Registers the FT4 asset.
  3. Registers the ERC-20 token.
  4. Links the FT4 asset and ERC-20 token.
  5. Registers the bridge contract and configures it to work with the registered FT4 assets and ERC-20 tokens.