🌉 Mini Cross-Chain Bridge Demo

A demonstration of a cross-chain bridge that transfers tokens between two test networks using Rust, Solidity, and Ethers.js.

Architecture

• Solidity Contracts: Bridge and Token contracts deployed on both chains
• Rust Backend: Relayer service that monitors events and processes cross-chain transfers
• Frontend Dashboard: Web interface built with Ethers.js for monitoring and initiating transfers

Project Structure

solid/
├── contracts/          # Solidity smart contracts
│   ├── Bridge.sol     # Bridge contract for locking/unlocking tokens
│   └── Token.sol      # ERC20 token contract with faucet
├── rust-bridge/        # Rust relayer service
│   └── src/
│       └── main.rs    # Event monitoring and relaying logic
├── frontend/           # Dashboard UI
│   ├── index.html
│   └── main.js        # Ethers.js integration
├── scripts/            # Deployment scripts
│   ├── deploy-chain1.js
│   ├── deploy-chain2.js
│   ├── link-bridges.js
│   └── start-nodes.js # Start both Hardhat nodes
└── README.md

Prerequisites

• Node.js (v18+)
• Rust (latest stable)
• Hardhat
• MetaMask (for testing)

Quick Start

1. Install Dependencies

# Install Node.js dependencies
npm install

# Install frontend dependencies
cd frontend && npm install && cd ..

2. Start Hardhat Nodes

In Terminal 1, start both Hardhat nodes:

npm run nodes

This will start:

• Chain 1 on http://localhost:8545
• Chain 2 on http://localhost:8546

Keep this terminal running!

3. Deploy Contracts

In Terminal 2, deploy contracts to both chains:

# Compile contracts
npm run compile

# Deploy to Chain 1
npm run deploy:chain1

# Deploy to Chain 2
npm run deploy:chain2

After deployment, copy the bridge addresses from the output.

4. Configure Environment

Create a .env file in the root directory:

# Chain 1 Configuration
CHAIN1_RPC_URL=http://localhost:8545
CHAIN1_BRIDGE_ADDRESS=<from deployment output>
CHAIN1_TOKEN_ADDRESS=<from deployment output>

# Chain 2 Configuration
CHAIN2_RPC_URL=http://localhost:8546
CHAIN2_BRIDGE_ADDRESS=<from deployment output>
CHAIN2_TOKEN_ADDRESS=<from deployment output>

# Wallet (for Rust relayer) - Use Hardhat's first default account
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Create a .env file in the frontend directory:

VITE_CHAIN1_RPC=http://localhost:8545
VITE_CHAIN2_RPC=http://localhost:8546
VITE_CHAIN1_BRIDGE=<from deployment output>
VITE_CHAIN2_BRIDGE=<from deployment output>
VITE_API_URL=http://localhost:8080

5. Link Bridges

In Terminal 2, link the bridges:

npm run link

6. Start Rust Relayer

In Terminal 3, start the Rust relayer:

cd rust-bridge
cargo run

The relayer will:

• Monitor Lock events on both chains
• Process transfers and call unlock on the target chain
• Serve an API at http://localhost:8080

Keep this terminal running!

7. Start Frontend

In Terminal 4, start the frontend:

npm run frontend

The dashboard will be available at http://localhost:3000 (or the port shown in the terminal).

Usage

1. Open the Dashboard: Navigate to http://localhost:3000 in your browser

2. Connect MetaMask:

   • Click "Connect Wallet" in the header
   • Approve the connection in MetaMask
   • Add the local Hardhat networks to MetaMask if prompted
   • Note: The same wallet address will appear for both chains - this is correct! Your wallet works on both networks.

3. Get Test Tokens:

   • Click "Get Tokens (Chain 1)" to receive 1000 BTC1 tokens
   • Click "Get Tokens (Chain 2)" to receive 1000 BTC2 tokens
   • Note: MetaMask may show a security warning. Click "I understand" - this is safe for local test networks.

4. Initiate Transfer:

   • Select source chain (Chain 1 or Chain 2)
   • Enter recipient address
   • Enter amount
   • Click "Initiate Transfer"
   • Approve the transaction in MetaMask

5. Monitor Transfers: View all recent transfers in the transfer history section

How It Works

1. Lock: User calls lock() on the source chain bridge, burning tokens
2. Event: Bridge emits a Lock event with transfer details
3. Relay: Rust relayer detects the event and calls unlock() on target chain
4. Unlock: Target chain bridge mints tokens to the recipient

Development

Compile Contracts

npm run compile

Run Tests

npm test

Build Rust Service

cd rust-bridge
cargo build --release

All-in-One Setup Script

npm run setup

This will compile, deploy to both chains, and link the bridges.

Troubleshooting

"Bridge contract not configured"

• Make sure you've deployed contracts and updated .env files
• Restart the frontend after updating .env files

"RPC unavailable" or "Network error"

• Make sure both Hardhat nodes are running (npm run nodes)
• Check that Chain 1 is on port 8545 and Chain 2 is on port 8546

"Insufficient balance"

• Use the faucet buttons to get test tokens
• Make sure you're on the correct chain in MetaMask

MetaMask Security Warning

• This is normal for unverified contracts on local networks
• Click "I understand" to proceed - it's safe for local testing

Security Notes

⚠️ This is a demo project for educational purposes only.

For production use, you would need:

• Proper cryptographic proofs (e.g., Merkle proofs)
• Multi-signature oracles
• Economic security mechanisms
• Comprehensive testing and audits
• Rate limiting and access controls

License

MIT