Docs
chromia.com

Bridge deposit troubleshooting guide

On this page

If your deposit from the EVM to Chromia does not appear on the Chromia side, follow these steps to identify and resolve the issue.

1. Verify EVM transaction

First, check whether your transaction was successful on the EVM chain:

  • Look up your transaction hash on the appropriate blockchain explorer to verify that the transaction status is "Success."
  • Ensure that the transaction has enough block confirmations, as defined by the eif.chains.<EVM_CHAIN>.evm_read_offset parameter in the Event Receiver Chain configuration. The following values are recommended defaults:
    • Mainnet: 50 for Ethereum and 100 for BSC
    • Testnet: 10 for both Ethereum and BSC.

2. Verify Event Receiver Chain configuration

Ensure the Event Receiver chain is configured correctly to receive EIF events and send ICMF messages to the Bridge 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"

3. Verify transaction block processing on the Event Receiver Chain

Check whether the Event Receiver chain has processed your transaction block using the following CLI commands:

To retrieve the last processed block data:

Terminal
chr query --api-url $NODE -brid $ER get_last_evm_block_data -- network_id=56
# or
chr query --api-url $NODE -brid $ER get_last_evm_block_data_with_events -- network_id=56

To retrieve specific block data:

Terminal
chr query --api-url $NODE -brid $ER get_evm_block_data -- network_id=56 height=12345678
# or
chr query --api-url $NODE -brid $ER get_evm_block_data_with_events -- network_id=56 height=12345678

4. Verify Bridge Chain configuration

Ensure the Bridge chain is configured correctly to receive ICMF messages from the Event Receiver chain and process EIF events.

YAML
blockchains:
  <bridge_chain>:
    module: <module_name>
    config:
      gtx:
        modules:
          - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
          - "net.postchain.eif.EifGTXModule"
      sync_ext:
        - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"
      icmf:
        local:
          - topic: L_evm_block_events
            bc-rid: x"{EVENT_RECEIVER_BLOCKCHAIN_RID}"

5. Verify deposit event status on the Bridge Chain

Use the following CLI commands to check whether the Bridge Chain has detected and processed your deposit.

Retrieve deposit event by EVM transaction hash:

Terminal
chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_erc20_deposits -- 'filter=[null,null,null,null,x"{EVM_TX_HASH}"]' page_size=null page_cursor=null

Retrieve deposit event by FT4 account ID:

Terminal
chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_erc20_deposits -- 'filter=[null,null,x"{FT4_ACCOUNT_ID}",null,null]' page_size=null page_cursor=null

Check for bounced deposit:

If the deposit event is not found, check whether your deposit has bounced using the command below:

Terminal
chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_erc20_withdrawals -- filter='[null,null,x"{EVM_BENEFICIARY_ADDRESS}",null,null,null,null]' page_size=null page_cursor=null

The deposit event may be bounced for the following reasons:

  1. The ERC-20 token is not registered on the Bridge Chain:

    Terminal
    chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_registered_erc20_assets -- network_id=56
  2. The bridge contract is not registered on the Bridge Chain, or the ERC-20 token is not linked to the bridge contract:

    Terminal
    chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_bridge_contracts -- network_id=56
  3. For native mode, if the deposit amount exceeds the bridge account balance.

  4. For deposits from a smart contract address, if the smart contract address is not linked to the FT4 account:

    Terminal
    chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_account_for_sc_address -- evm_address='x"{SMART_CONTRACT_ADDRESS}"' network_id=56

    or

    Terminal
    chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_sc_addresses_for_account -- account_id='x"{FT4_ACCOUNT_ID}"'
  5. If the FT4 account is not created and the FT4 transfer strategy rules are not met, check the lib.ft4.core.accounts.strategies.transfer module arguments in the Bridge Chain configuration.

  6. If the FT4 account is not created and there is a pending deposit for the EOA address:

    Terminal
    chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_erc20_deposits -- 'filter=[null,null,x"{FT4_ACCOUNT_ID}",null,null]' page_size=null page_cursor=null

    Where {FT4_ACCOUNT_ID} can be calculated from the EOA address:

    Terminal
    chr repl -c 'x"{EOA_ADDRESS}".hash()'

    If the FT4 account exists but is not on the access list:

    Terminal
    chr query --api-url $NODE -brid $BRIDGE eif.hbridge.is_account_on_access_list -- account_id='x"{FT4_ACCOUNT_ID}"'

6. Verify account balance

Allow some time for the deposit to be fully processed. Then, check your account balance on the Bridge chain and compare it with the expected amount.

Find FT4 account ID by EVM address:

Terminal
chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_account_for_eoa_address -- evm_address='x"{EOA_ADDRESS}"'

or

Terminal
chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_account_for_sc_address -- evm_address='x"{SMART_CONTRACT_ADDRESS}"' network_id=56

Retrieve FT4 asset ID by symbol:

Terminal
chr query --api-url $NODE -brid $BRIDGE ft4.get_assets_by_symbol -- symbol=CHR page_size=null page_cursor=null

Retrieve FT4 account balance:

Terminal
chr query --api-url $NODE -brid $BRIDGE ft4.get_asset_balance -- account_id='x"{FT4_ACCOUNT_ID}"' asset_id='x"{FT4_ASSET_ID}"'