explorer-monorepo/docs/BRIDGE_CONTRACT_ARCHITECTURE.md

Bridge Contract Architecture Documentation

Date: 2025-01-12
Network: ChainID 138

---

Overview

This document describes the architecture and design of the CCIP bridge contracts for WETH9 and WETH10 tokens.

---

Bridge Contracts

CCIPWETH9Bridge

Address: 0x89dd12025bfCD38A168455A44B400e913ED33BE2
Network: ChainID 138
Purpose: Bridge WETH9 tokens across chains using CCIP

CCIPWETH10Bridge

Address: 0xe0E93247376aa097dB308B92e6Ba36bA015535D0
Network: ChainID 138
Purpose: Bridge WETH10 tokens across chains using CCIP

---

Contract Relationships

Architecture Diagram

User
  │
  ├─► WETH9/WETH10 Token
  │     │
  │     ├─► Wrap ETH → WETH
  │     └─► Unwrap WETH → ETH
  │
  ├─► Bridge Contract (CCIPWETH9Bridge/CCIPWETH10Bridge)
  │     │
  │     ├─► Approve tokens
  │     ├─► sendCrossChain()
  │     │
  │     └─► CCIP Router
  │           │
  │           ├─► Calculate fees
  │           ├─► Send message
  │           └─► Oracle Network
  │                 │
  │                 └─► Destination Chain
  │                       │
  │                       └─► Destination Bridge
  │                             │
  │                             └─► Receiver

---

Key Functions

sendCrossChain()

Sends tokens across chains using CCIP.

Parameters:

• destinationChainSelector: uint64 - Destination chain selector
• receiver: address - Receiver address on destination chain
• amount: uint256 - Amount of tokens to bridge

Process:

1. Validate destination is configured
2. Transfer tokens from user to bridge
3. Calculate CCIP fees
4. Call CCIP Router to send message
5. Pay fees (LINK tokens)
6. Emit event

addDestination()

Adds a destination chain to the bridge routing table.

Parameters:

• chainSelector: uint64 - Destination chain selector
• bridgeAddress: address - Bridge contract address on destination chain

Access Control: Owner/Admin only

destinations()

Gets the bridge address for a destination chain.

Parameters:

• chainSelector: uint64 - Destination chain selector

Returns: address - Bridge contract address on destination chain

---

Data Flow

Outbound Flow (Source Chain → Destination Chain)

1. User Initiates:

   • User wraps ETH → WETH
   • User approves bridge to spend WETH
   • User calls sendCrossChain()

2. Bridge Processes:

   • Bridge validates destination
   • Bridge transfers WETH from user
   • Bridge calculates fees
   • Bridge calls CCIP Router

3. CCIP Router:

   • Router validates message
   • Router calculates fees
   • Router sends message to oracle network

4. Oracle Network:

   • Oracles commit message
   • Oracles execute on destination

5. Destination Bridge:

   • Destination bridge receives message
   • Destination bridge mints/releases WETH
   • Destination bridge transfers to receiver

Inbound Flow (Destination Chain → Source Chain)

1. User Initiates (on destination chain)
2. Destination Bridge Processes
3. CCIP Router (on destination chain)
4. Oracle Network
5. Source Bridge (releases tokens)

---

Security Model

Access Control

• Owner/Admin: Can add/remove destinations
• Public: Can send cross-chain transfers (with approval)

Validation

• Destination Check: Verifies destination is configured
• Balance Check: Verifies user has sufficient balance
• Approval Check: Verifies bridge has approval
• Fee Check: Verifies sufficient LINK for fees

Error Handling

• Revert on Invalid Destination: Prevents sending to unconfigured chains
• Revert on Insufficient Balance: Prevents failed transfers
• Revert on Insufficient Fees: Prevents failed CCIP messages

---

Configuration

Destination Chains

Bridge contracts maintain a routing table mapping:

• Chain Selector → Destination Bridge Address

Current Status: ⚠️ Partially configured

• Some destinations configured
• Ethereum Mainnet not configured (blocked by stuck transaction)

Router Integration

Bridge contracts integrate with CCIP Router:

• Router Address: 0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e
• Fee Token: LINK (0x514910771AF9Ca656af840dff83E8264EcF986CA)

---

Verification

Contract Deployment

Status: ✅ Complete

• Both bridge contracts deployed
• Bytecode verified
• Functions accessible

Configuration Verification

Script: scripts/check-bridge-config.sh

Usage:

./scripts/check-bridge-config.sh

Comprehensive Verification

Script: scripts/verify-complete-ccip-setup.sh

Usage:

./scripts/verify-complete-ccip-setup.sh

---

Related Documentation

• CCIP Configuration Status
• Complete Task Catalog
• Token Mechanism Documentation

---

Last Updated: 2025-01-12