Skip to content

README.md

Latest commit

 

History

History
151 lines (98 loc) · 6.12 KB

README.md

File metadata and controls

151 lines (98 loc) · 6.12 KB

RLC Layer Zero Bridge

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.

Architecture

The system consists of two main components:

  1. RLCAdapter (on Ethereum Sepolia): Wraps the existing RLC ERC-20 token to make it compatible with LayerZero's cross-chain messaging.
  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.

Architecture Diagram

Prerequisites

  • Foundry for contract compilation and deployment
  • Ethereum wallet with Sepolia ETH and Arbitrum Sepolia ETH for gas
  • RLC tokens on Sepolia testnet for bridge testing

Installation

  1. Clone the repository

    git clone https://github.com/iExecBlockchainComputing/rlc-multichain.git
cd rlc-multichain

  2. Install dependencies

    forge install

  3. Create a .env file

    cp .env.template .env # and edit .env content

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:

cast wallet import --private-key <RAW_PRIVATE_KEY> <ACCOUNT_NAME>

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.

Contract Overview

Instead of duplicating code that may become outdated, here are links to the key contracts in the repository:

  • RLCAdapter.sol - Ethereum-side adapter that wraps the existing RLC token
  • RLCOFT.sol - Arbitrum-side token that implements the OFT standard

Deployment

The deployment process involves four steps:

  1. Deploy the RLCAdapter on Ethereum Sepolia:

    make deploy-adapter

  2. Deploy the RLCOFT on Arbitrum Sepolia:

    make deploy-oft

  3. Configure the RLCAdapter to trust the RLCOFT contract:

    make configure-adapter

  4. Configure the RLCOFT to trust the RLCAdapter contract:

    make configure-oft

After deployment, update your .env file with the deployed contract addresses.

Usage

Bridge RLC

A. To send RLC tokens from Ethereum Sepolia to Arbitrum Sepolia:

make send-tokens-to-arbitrum-sepolia

This will:

  1. Approve the RLCAdapter to spend your RLC tokens
  2. Initiate the cross-chain transfer through LayerZero
  3. Lock tokens in the adapter and mint equivalent tokens on Arbitrum

B. To send RLC tokens from Arbitrum Sepolia back to Ethereum Sepolia:

make send-tokens-to-sepolia

This will:

  1. Burn RLCOFT tokens on Arbitrum
  2. Send a cross-chain message to the adapter
  3. Release the original RLC tokens on Ethereum

How It Works

  1. Ethereum → Arbitrum:

    • User approves RLCAdapter to spend RLC tokens
    • RLCAdapter locks the RLC tokens
    • LayerZero delivers a message to RLCOFT
    • RLCOFT mints equivalent tokens to the recipient on Arbitrum

  2. Arbitrum → Ethereum:

    • User initiates transfer from RLCOFT
    • RLCOFT burns the tokens
    • LayerZero delivers a message to RLCAdapter
    • RLCAdapter unlocks the original RLC tokens to the recipient on Ethereum

Security Considerations

  • The bridge security relies on LayerZero's security model
  • Administrative functions are protected by the Ownable pattern
  • Use caution when setting trusted remotes to prevent unauthorized cross-chain interactions
  • Always test thoroughly on testnets before deploying to mainnet

Gas Costs and Fees

LayerZero transactions require fees to cover:

  1. Gas on the source chain
  2. Gas on the destination chain (prepaid)
  3. LayerZero relayer fees

The scripts automatically calculate these fees and include them in the transaction.

Troubleshooting

References