Skip to content

Commit

Permalink
add README for Celer IM based ERC20 bridge
Browse files Browse the repository at this point in the history
  • Loading branch information
i9 committed Feb 25, 2024
1 parent 6af81b5 commit 7379133
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 0 deletions.
1 change: 1 addition & 0 deletions contracts/message/apps/erc20-bridge/MsgTokenBridge.sol
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
// SPDX-License-Identifier: GPL-3.0-only
39 changes: 39 additions & 0 deletions contracts/message/apps/erc20-bridge/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# ERC20 Bridge using Celer IM
## Scope
- For one token like USDC, some chains are officially supported so bridge will use deposit/withdraw (we call these vaults as tokens are locked in contract), others are mint/burn (called peg)
- If peg chain is later promoted to official (ie. becomes a vault chain), corresponding locked amount on vault chains must be burned to avoid duplicated supply (required by Circle)
- This bridge is only intended to work between vault and peg, or between peg and peg. For transfers between vault chains, use cBridge
- **ERC20 contract decimal MUST be the same amont all chains** (we could add decimal into crosschain message with added cost and complexity)

## Fee
To ensure mint amount equals locked, fee is set and collected on dest chain. For example, user locks 100 on source chain, bridge will mint 100 on dest chain, and send 100-fee amount to receiver.

Fee has 2 parts:
- base fee: to cover gas cost for message executor. not related to source chain
- percentage fee: collected in bridge contract, may vary for different source chain due to business reason

## Contract
```solidity
/// MsgTokenBridge address on other chains, key is chain id
mapping(uint64 => address) public bridgeAddr;
/// for each erc20 token, config of cap, fee, etc. key is token address on this chain
mapping(address => tokenCfg) public tokenConfig;
struct tokenCfg {
bool isVault; // default false, mint/burn. if set to true, use erc20 transfer for deposit/withdraw
// send cap. set minSend to max will effectively stop new user requests
uint256 minSend;
uint256 maxSend;
uint256 baseFee; // when emit token to receiver, cut baseFee to msg executor
// fee percentage based on different source chain ids, key is source chain id, value is percentage * 1M, ie. 0.1% becomes 1000
// 0 <= valid value <= 1M
mapping(uint64 => uint32) feePerc;
// token address on other chains, key is chain id
mapping(uint64 => address) tokenAddr;
}
```
- Note: delay transfer and volume control parameters are set in their own contracts

## Refund
TBD

0 comments on commit 7379133

Please sign in to comment.