|
1 | | -## Foundry |
| 1 | +# RLC Layer Zero Bridge |
2 | 2 |
|
3 | | -**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.** |
| 3 | +This project implements a cross-chain token bridge for the RLC token between Ethereum and Arbitrum using LayerZero's OFT (Omnichain Fungible Token) protocol. It enables seamless token transfers between Ethereum Sepolia and Arbitrum Sepolia testnets. |
4 | 4 |
|
5 | | -Foundry consists of: |
| 5 | +## Architecture |
6 | 6 |
|
7 | | -- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools). |
8 | | -- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data. |
9 | | -- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network. |
10 | | -- **Chisel**: Fast, utilitarian, and verbose solidity REPL. |
| 7 | +The system consists of two main components: |
11 | 8 |
|
12 | | -## Documentation |
| 9 | +1. **RLCAdapter (on Ethereum Sepolia)**: Wraps the existing RLC ERC-20 token to make it compatible with LayerZero's cross-chain messaging. |
| 10 | +2. **RLCOFT (on Arbitrum Sepolia)**: A new token that's minted when RLC tokens are locked in the adapter on Ethereum, and burned when tokens are sent back. |
13 | 11 |
|
14 | | -https://book.getfoundry.sh/ |
| 12 | +[](https://mermaid.live/edit#pako:eNqNVNtO4zAQ_RXLvAY2F3JpQEhpLrsPRUhQXqBoZRKXRjh2ZCdouf372nHSEhrYddV2MjnHZ-ZM4leYswLDED5wVG_AMllRIJdo73ViBdNmgzluK3CFa0ZKtIIaotblIr6VX7Bkj5ju0qflWXoZ2-bpj_LsbpeOClQ3mCtGH44oF9myT3_iLW5-p8tftwv0jPkN5gyktKhZSZseg2mhg73aI35fNny6dimnKpF_E-XL7H4R0eX8v4u4Fph3VasAMAoGG-_A4eHZmwWiuubsCQvQKHHxBkaWDPQObIMYESKAkBqfcP1FB3PAguWPuw1lc_ugY2kFLQSosBDoAb_15mqgjjucC2LOhDjMN6ikI7R0YYuWcYf2QIJJ-YT5h42lhRqnHFYgH5xLu3b1dT0qTweLhmnd7Rk56EQjJ_YU5mDecrpT2APEE91P9ZN82f2UV-lE919OKQPXlPx7Tj_BkiMq1mrTkWHbAvRvTpAQCV4DPLym65KQ8CD24iyyDdFwSQ4PnMQ1576RM8J4eE9Q_njyiY-GV0Xz51bqZNmWb0eBnQXf8Vs1RM3NssSOzC03y4LANL_jkpeembjqs6u6WxPMD3xlnzE4N5jwUaAb_tDd6Mbgp7F9xlQTI4iestE_GuTlBBqwwrxCZSHPzFcFXUEpWuEVDGVY4DVqSaPOmXcJRW3Drp5pDkMpjg3Y1gVqcFIieUBVMFwjImS2RvSGsWoAyUsYvsI_MAysI8_yfNuZeY7tuUFgwGcYWjP3yLdN1_Jl5PiBab8b8KXbwDyaufbMOnYs27OsIPA8A3LWPmy2WrgoG8bP9ZnfHf2GPPpVN1qcy_cD85i1tJFKlj3UnHY8jXr_C5RA8AI) |
15 | 13 |
|
16 | | -## Usage |
| 14 | +## Prerequisites |
17 | 15 |
|
18 | | -### Build |
| 16 | +- [Foundry](https://book.getfoundry.sh/getting-started/installation.html) for contract compilation and deployment |
| 17 | +- Ethereum wallet with Sepolia ETH and Arbitrum Sepolia ETH for gas |
| 18 | +- RLC tokens on Sepolia testnet for bridge testing |
19 | 19 |
|
20 | | -```shell |
21 | | -$ forge build |
22 | | -``` |
| 20 | +## Installation |
23 | 21 |
|
24 | | -### Test |
| 22 | +1. Clone the repository |
25 | 23 |
|
26 | | -```shell |
27 | | -$ forge test |
28 | | -``` |
| 24 | + ```bash |
| 25 | + git clone https://github.com/iExecBlockchainComputing/rlc-multichain.git |
| 26 | + cd rlc-multichain |
| 27 | + ``` |
29 | 28 |
|
30 | | -### Format |
| 29 | +2. Install dependencies |
31 | 30 |
|
32 | | -```shell |
33 | | -$ forge fmt |
34 | | -``` |
| 31 | + ```bash |
| 32 | + forge install |
| 33 | + ``` |
35 | 34 |
|
36 | | -### Gas Snapshots |
| 35 | +3. Create a `.env` file |
37 | 36 |
|
38 | | -```shell |
39 | | -$ forge snapshot |
40 | | -``` |
| 37 | + ```sh |
| 38 | + cp .env.template .env # and edit .env content |
| 39 | + ``` |
41 | 40 |
|
42 | | -### Anvil |
| 41 | +**Note:** To run scripts, you must save a wallet in the Foundry keystore. Use the following command to import a wallet with a raw private key: |
43 | 42 |
|
44 | | -```shell |
45 | | -$ anvil |
| 43 | +```bash |
| 44 | +cast wallet import --private-key <RAW_PRIVATE_KEY> <ACCOUNT_NAME> |
46 | 45 | ``` |
47 | 46 |
|
48 | | -### Deploy |
| 47 | +Alternatively, you can use a mnemonic by specifying the `--mnemonic-path` option. Remember the `<ACCOUNT_NAME>` you choose, and set it in your `.env` file under the `ACCOUNT` field. |
49 | 48 |
|
50 | | -```shell |
51 | | -$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key> |
52 | | -``` |
| 49 | +## Contract Overview |
| 50 | + |
| 51 | +Instead of duplicating code that may become outdated, here are links to the key contracts in the repository: |
| 52 | + |
| 53 | +- [RLCAdapter.sol](https://github.com/iExecBlockchainComputing/rlc-multichain/blob/main/src/RLCAdapter.sol) - Ethereum-side adapter that wraps the existing RLC token |
| 54 | +- [RLCOFT.sol](https://github.com/iExecBlockchainComputing/rlc-multichain/blob/main/src/RLCOFT.sol) - Arbitrum-side token that implements the OFT standard |
| 55 | + |
| 56 | +## Deployment |
| 57 | + |
| 58 | +The deployment process involves four steps: |
| 59 | + |
| 60 | +1. Deploy the RLCAdapter on Ethereum Sepolia: |
| 61 | + |
| 62 | + ```bash |
| 63 | + make deploy-adapter |
| 64 | + ``` |
| 65 | + |
| 66 | +2. Deploy the RLCOFT on Arbitrum Sepolia: |
| 67 | + |
| 68 | + ```bash |
| 69 | + make deploy-oft |
| 70 | + ``` |
| 71 | + |
| 72 | +3. Configure the RLCAdapter to trust the RLCOFT contract: |
| 73 | + |
| 74 | + ```bash |
| 75 | + make configure-adapter |
| 76 | + ``` |
| 77 | + |
| 78 | +4. Configure the RLCOFT to trust the RLCAdapter contract: |
| 79 | + |
| 80 | + ```bash |
| 81 | + make configure-oft |
| 82 | + ``` |
| 83 | + |
| 84 | +After deployment, update your `.env` file with the deployed contract addresses. |
53 | 85 |
|
54 | | -### Cast |
| 86 | +## Usage |
| 87 | + |
| 88 | +### Bridge RLC |
| 89 | + |
| 90 | +A. To send RLC tokens from Ethereum Sepolia to Arbitrum Sepolia: |
55 | 91 |
|
56 | | -```shell |
57 | | -$ cast <subcommand> |
| 92 | +```bash |
| 93 | +make send-tokens-to-arbitrum-sepolia |
58 | 94 | ``` |
59 | 95 |
|
60 | | -### Help |
| 96 | +This will: |
| 97 | + |
| 98 | +1. Approve the RLCAdapter to spend your RLC tokens |
| 99 | +2. Initiate the cross-chain transfer through LayerZero |
| 100 | +3. Lock tokens in the adapter and mint equivalent tokens on Arbitrum |
| 101 | + |
| 102 | +B. To send RLC tokens from Arbitrum Sepolia back to Ethereum Sepolia: |
61 | 103 |
|
62 | | -```shell |
63 | | -$ forge --help |
64 | | -$ anvil --help |
65 | | -$ cast --help |
| 104 | +```bash |
| 105 | +make send-tokens-to-sepolia |
66 | 106 | ``` |
| 107 | + |
| 108 | +This will: |
| 109 | + |
| 110 | +1. Burn RLCOFT tokens on Arbitrum |
| 111 | +2. Send a cross-chain message to the adapter |
| 112 | +3. Release the original RLC tokens on Ethereum |
| 113 | + |
| 114 | +## How It Works |
| 115 | + |
| 116 | +1. **Ethereum → Arbitrum:** |
| 117 | + - User approves RLCAdapter to spend RLC tokens |
| 118 | + - RLCAdapter locks the RLC tokens |
| 119 | + - LayerZero delivers a message to RLCOFT |
| 120 | + - RLCOFT mints equivalent tokens to the recipient on Arbitrum |
| 121 | + |
| 122 | +2. **Arbitrum → Ethereum:** |
| 123 | + - User initiates transfer from RLCOFT |
| 124 | + - RLCOFT burns the tokens |
| 125 | + - LayerZero delivers a message to RLCAdapter |
| 126 | + - RLCAdapter unlocks the original RLC tokens to the recipient on Ethereum |
| 127 | + |
| 128 | +## Security Considerations |
| 129 | + |
| 130 | +- The bridge security relies on LayerZero's security model |
| 131 | +- Administrative functions are protected by the Ownable pattern |
| 132 | +- Use caution when setting trusted remotes to prevent unauthorized cross-chain interactions |
| 133 | +- Always test thoroughly on testnets before deploying to mainnet |
| 134 | +
|
| 135 | +## Gas Costs and Fees |
| 136 | +
|
| 137 | +LayerZero transactions require fees to cover: |
| 138 | +
|
| 139 | +1. Gas on the source chain |
| 140 | +2. Gas on the destination chain (prepaid) |
| 141 | +3. LayerZero relayer fees |
| 142 | +
|
| 143 | +The scripts automatically calculate these fees and include them in the transaction. |
| 144 | +
|
| 145 | +## Troubleshooting |
| 146 | +
|
| 147 | +## References |
| 148 | +
|
| 149 | +- [LayerZero Documentation](https://layerzero.gitbook.io/docs/) |
| 150 | +- [OFT Contracts](https://github.com/LayerZero-Labs/solidity-examples/tree/main/contracts/token/oft) |
| 151 | +- [iExec Platform Documentation](https://docs.iex.ec/) |
0 commit comments