Bridge deposit troubleshooting guide

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.

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:

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:

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.

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:

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:

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

note

To see additional filter fields for the deposit query, refer to deposits.rell.

Check for bounced deposit:

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

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:

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

chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_registered_erc20_assets -- network_id=56

The bridge contract is not registered on the Bridge Chain, or the ERC-20 token is not linked to the bridge contract:
```
chr query --api-url $NODE -brid $BRIDGE eif.hbridge.get_bridge_contracts -- network_id=56
```
For native mode, if the deposit amount exceeds the bridge account balance.

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

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

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

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.

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

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:

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

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

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:

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

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:

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

Retrieve FT4 account balance:

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

1. Verify EVM transaction​

2. Verify Event Receiver Chain configuration​

3. Verify transaction block processing on the Event Receiver Chain​

4. Verify Bridge Chain configuration​

5. Verify deposit event status on the Bridge Chain​

Retrieve deposit event by EVM transaction hash:​

Retrieve deposit event by FT4 account ID:​

Check for bounced deposit:​

6. Verify account balance​

Find FT4 account ID by EVM address:​

Retrieve FT4 asset ID by symbol:​

Retrieve FT4 account balance:​