Skip to main content

Deploy Chromia bridge chains

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:

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:

cd chromia-bridge-demo/rell

2. Install the FT4 Rell library​

Before proceeding, install the necessary dependencies using chr install:

chr 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​

gtx:
  modules:
    - "net.postchain.eif.EifGTXModule"
    - "net.postchain.d1.icmf.IcmfSenderGTXModule"
sync_ext:
  - "net.postchain.eif.EifSynchronizationInfrastructureExtension"

Bridge Chain​

gtx:
  modules:
    - "net.postchain.eif.EifGTXModule"
    - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
sync_ext:
  - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"
warning

If these modules are missing, deposits and withdrawals will not be processed correctly.

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​

warning

The Event Receiver Chain name must be unique. Replace <EVENT_RECEIVER_NAME> with a custom identifier (e.g., pirate_dapp_event_receiver).

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

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 explorer.
note

ℹ️ The values bsc and 97 are defaults for BSC Testnet. You can adjust them if you are bridging to a different EVM network.

Set your container ID​

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

deployments:
testnet:
  brid: x"BA320798BA35DD6E38F3DF24D241B7D94E5613899F64520DFB53D59793CDC5A3"
  url: https://node0.testnet.chromia.com:7740
  container: <CONTAINER_ID>

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

Deploy the Event Receiver Chain to Testnet​

note

Make sure you have already created a Testnet container. It is required for deployment.

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

chr deployment create --settings chromia.yml --network testnet --blockchain <EVENT_RECEIVER_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:

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

5. Configure the Bridge Chain in chromia.yml​

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

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:

chr deployment create --settings chromia.yml --network testnet --blockchain <BRIDGE_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:

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

7. Initialize the Bridge Chain​

Run the following command:

chr tx --api-url "https://node0.testnet.chromia.com:7740" -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.