ChainBridge Overview
This article provides overview of ChainBridge (v1.0), a crossbridge communication protocol. For general overview of crypto bridges refer crypto bridges article here .
Introduction
ChainBridge facilitates transfer of ERC assets and other information(generic data) between EVM compatible chains, i.e. it allows users to transfer assets or generic data from one chain to another. It allows for 3 types of transfers namely ERC20, ERC721 and generic data transfers.
Architecture
Main components of ChainBridge includes bridge contract, handler contracts, target contracts on each source chain and destination chain and relayers.
Components:
1. Bridge Contract:
Bridge contract handles user’s deposit requests, other admin level functionalities like adding/removal of new/existing relayer, changing relayer threshold, setting/resetting of resource ID, etc. End user initiates deposit using bridge contract’s deposit functionality. Bridge contract then delegates the request to particular ERC handler and emits deposit event on success, which will notify registered relayers.
2. Handler Contract:
Handler contract interacts with target contract to execute actual deposit or proposal execution transactions by interacting with target contract of a chain. This contract validates users deposit transaction parameters and maintains deposit records, asset transfer mode settings etc. Handler contract also allows admin to manually withdraw locked tokens i.e. it allows only admin to submit withdraw transaction through bridge contract.
3. Target Contract:
Target contract handles assets which are locked or redeemed between two chains.
4. Relayer:
Relayer is an offchain component that listens to deposit events of configured chains. On receiving deposit event it creates a deposit proposal if not yet created and votes on these deposit proposal, once required number of votes are received(determined by vote threshold set on bridge contracts during deployment) on proposal each of the relayer submits a execute proposal transaction which actually transfers the assets on destination chain.
Asset Transfer modes:
As each asset is specific to a contract and to the underlying blockchain on which this contract is deployed. Crypto bridges attains transfer of these assets by using contract logic where assets are locked/burned on one chain and released/minted on the other chain.
ChainBridge supports below two asset transfer methods:
1. Lock/Release mode
In this mode assets on source chain A is locked and equivalent amount of assets are released on destination chain B. Again when assets needs to be withdrawn then previously released assets are again locked on destination chain A and equivalent amount of previously locked tokens are again released for regular use on source chain.
2. Mint/Burn mode
In this mode assets on source chain A are completely burnt when transfer to destination chain is initiated by user and equivalent amount of assets are then minted on destination chain B. Similarly when user wants to withdraw their assets back to source chain previously minted assets on destination chain are burnt and equivalent amount of asset are minted back on source chain A.
Workflow
This section provides high level overview of process that takes place during asset transfers (like ERC20 and ERC721 assets and generic data) between any two EVM compatible chains.
ERC20/ERC721 Transfers:
Above figure shows a sample ERC workflow which is described in detail in further sections. Workflow steps remains same for both types of ERC20 and ERC721 transfers using ChainBridge bridges.
Setup:
To allow any user to initiate a transfer of assets across the EVM compatible chains pre-requisite setup needs to be completed for each chain. This setup includes following steps:
- Deploy Bridge contract, ERC20 or ERC721 and corresponding handler contracts on source chain A and destination chain B.
- Every asset is linked to a resource ID, this step needs a deployer to create a unique resource ID for an asset on bridge contract. Same resource ID needs to be registered on source chain A and destination chain B so that resource ID allows to map assets on chain A and chain B.
- To setup mint/burn flow deployer needs to set handler contracts as mintable/burnable resource on bridge contract. ChainBridge by default provides lock/release mode as transfer mode so no additional setup is needed except for handler contract needs to have liquidity of tokens on each chain.
- Setup relayers with deployed contracts to listen to events emitted by deployed bridge contracts during deposits.
Once above setup is done user can initiate deposit transactions to transfer assets between the chains.
Workflow:
- User EOA initiates a deposit transaction (after ERC token approval which is used by contract handler during lock/burn mode) on bridge contract, bridge contract delegates it to corresponding ERC handler contract based on modes setup during deployment phase tokens are locked/burned.
- On successful completion of above step deposit event is generated. Relayer listening to these chains create a deposit proposal on destination chain bridge contract.
- Every relayer votes on the existing proposal or creates one if it doesn’t exist.
- Once the relayer threshold is reached proposal event is emitted and every relayer tries to submit execute proposal transaction on destination chain’s bridge contract.
- Bridge contract thus delegates this execute proposal transaction to corresponding asset handler on destination chain, behind the scenes the tokens are either minted or released from handler contract to recipient address(passed in deposit transaction calldata) on destination chain.
- For withdrawing back above process is repeated with deposit transaction being initiated from destination chain.
Generic Data Transfers:
Setup:
To allow any user to initiate a transfer of generic data across the EVM compatible chains pre-requisite setup needs to be completed for each chain. This setup includes following steps:
- Deploy Generic data target contracts, Bridge contract, corresponding handler contracts on source chain A and destination chain B and a relayer component.
- Register generic resource on bridge contract of both chains (which includes resource id, deposit function signature [which is generic data target contract function that will be called successful deposits]).
Workflow:
- Users EOA invokes deposit function with required data that needs to be bridged to other chain.
- On successful completion of deposit execution i.e. after delegating to handler contract on source chain deposit event is emitted.
- On destination chain, every relayer votes on the existing proposal or creates one if it doesn’t exist.
- Once the relayer threshold is reached proposal event is emitted and every relayer tries to submit execute proposal transaction on destination chain’s bridge contract.
- Bridge contract thus delegates this execute proposal transaction to corresponding generic handler on destination chain, behind the scenes on successful completion generic data contract function corresponding to resource id is invoked on generic target contract with user provided generic data thus completing generic data transfers across chains.
Conclusion
- Current implementation of ChainBridge provides trusted federation model bridge implementation.
- Above described workflow includes single relayer which results in making above bridge solution highly centralized, thus a setup should have more than 1 relayer and vote threshold adjusted accordingly.
- Admin keys needs to be stored securely as admin account has full control over funds locked up in contracts as well as admin account can update relayer addresses, proposal votes, voting threshold etc.
- Also fees can be setup during deployment which is given as reward to a relayer from depositor. But current v1.0 implementation does not have automated payout process to transfer these fees to the relayer, it needs to be done manually by admin by withdrawing fees from bridge contract and then transferring it to the relayer.
References
- ChainBridge documentation: https://chainbridge.chainsafe.io/
- ChainBridge Solidity Contracts: https://github.com/ChainSafe/chainbridge-solidity
- ChainBridge Relayer: https://github.com/ChainSafe/ChainBridge
