smom-dbis-138/docs/architecture/PREDEPLOYED_WETH_ARCHITECTURE.md

Predeployed WETH Architecture

Overview

WETH9 and WETH10 are predeployed at their canonical Ethereum Mainnet addresses via the alloc section in genesis.json. This provides the "same address across chains" property, enabling seamless cross-chain compatibility.

Canonical Addresses

Contract	Mainnet Address	ChainID 138 Address
WETH9	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 ✅ Same
WETH10	0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f	0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f ✅ Same

Benefits

1. Same Address Across Chains: Users can use the same WETH addresses on both Mainnet and ChainID 138
2. No Deployment Needed: Contracts exist from genesis block
3. Cross-Chain Compatibility: DApps can reference the same addresses
4. WETH10 Advanced Features: Flash-mint and complex structures work out of the box

Genesis Configuration

The contracts are added to genesis.json in the alloc section:

{
  "alloc": {
    "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
      "code": "0x608060405234801561001057600080fd5b50...",
      "balance": "0x0"
    },
    "0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f": {
      "code": "0x608060405234801561001057600080fd5b50...",
      "balance": "0x0"
    }
  }
}

Bridge Architecture

Cross-Chain Bridge Pattern

The bridge contracts (CCIPWETH9Bridge and CCIPWETH10Bridge) work with the predeployed WETH contracts:

┌─────────────────────────────────────────────────────────────┐
│                    Ethereum Mainnet                         │
│                                                              │
│  User WETH (0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)     │
│           │                                                  │
│           │ Lock/Burn                                        │
│           ▼                                                  │
│  CCIPWETH9Bridge                                            │
│           │                                                  │
│           │ CCIP Message                                     │
│           ▼                                                  │
└───────────┼──────────────────────────────────────────────────┘
            │
            │ CCIP Cross-Chain
            │
┌───────────┼──────────────────────────────────────────────────┐
│           ▼                    ChainID 138                   │
│  CCIPWETH9Bridge                                             │
│           │                                                  │
│           │ Mint/Unlock                                      │
│           ▼                                                  │
│  WETH9 (0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)         │
│           │                                                  │
│           │ User receives WETH                               │
│           ▼                                                  │
│  User                                                         │
└─────────────────────────────────────────────────────────────┘

Bridge Functions

Lock/Unlock Pattern (WETH9)

On Mainnet:

1. User deposits WETH to bridge
2. Bridge locks WETH (transfers from user)
3. Bridge sends CCIP message to ChainID 138

On ChainID 138:

1. Bridge receives CCIP message
2. Bridge mints WETH to user (same address as Mainnet)

Mint/Burn Pattern (WETH10)

On Mainnet:

1. User deposits WETH to bridge
2. Bridge burns WETH
3. Bridge sends CCIP message to ChainID 138

On ChainID 138:

1. Bridge receives CCIP message
2. Bridge mints WETH to user (same address as Mainnet)

Bridge Contract Implementation

The bridge contracts reference the predeployed WETH addresses:

// CCIPWETH9Bridge.sol
address public immutable weth9 = 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2;

// CCIPWETH10Bridge.sol
address public immutable weth10 = 0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f;

WETH10 Advanced Features

WETH10 is treated as an advanced instrument with:

• Flash-Mint: ERC-3156 flash loan support
• Complex Structures: More sophisticated internal logic
• Same Address: Works seamlessly across chains

Deployment Process

1. Compile Contracts

forge build

2. Add to Genesis

./scripts/genesis/add-predeployed-weth.sh

This script:

• Compiles WETH9 and WETH10
• Extracts bytecode
• Adds to genesis.json alloc section
• Backs up original genesis file

3. Deploy Bridge Contracts

# Deploy CCIPWETH9Bridge
forge script script/DeployCCIPWETH9Bridge.s.sol --rpc-url $RPC_URL --broadcast

# Deploy CCIPWETH10Bridge
forge script script/DeployCCIPWETH10Bridge.s.sol --rpc-url $RPC_URL --broadcast

4. Verify

# Check WETH9 exists at canonical address
cast code 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 --rpc-url $RPC_URL

# Check WETH10 exists at canonical address
cast code 0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f --rpc-url $RPC_URL

Cross-Chain Usage

Example: User Wants to Bridge WETH

1. User on Mainnet:

   // Approve bridge
   IERC20(WETH9).approve(bridgeAddress, amount);
   
   // Bridge WETH
   CCIPWETH9Bridge(bridgeAddress).sendCrossChain(
       destinationChainSelector,
       recipient,
       amount
   );
   

2. Bridge on Mainnet:

   • Locks WETH from user
   • Sends CCIP message

3. Bridge on ChainID 138:

   • Receives CCIP message
   • Mints WETH to user at same address

4. User on ChainID 138:

   • Receives WETH at 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
   • Can use immediately (same address as Mainnet)

Security Considerations

1. Bytecode Verification: Ensure bytecode matches Mainnet exactly
2. Initial State: Contracts start with zero balance (no pre-minted tokens)
3. Bridge Security: Bridge contracts must be secure (audit recommended)
4. Access Control: Only bridge contracts should mint/burn on ChainID 138

Advantages Over Deployment

Aspect	Predeployment	Deployment
Address	✅ Same as Mainnet	❌ Different
Cross-Chain	✅ Seamless	⚠️ Requires mapping
User Experience	✅ Same addresses	❌ Different addresses
DApp Compatibility	✅ Works immediately	⚠️ Needs updates

Conclusion

Predeploying WETH9 and WETH10 at their canonical Mainnet addresses provides:

• ✅ Same addresses across chains
• ✅ Seamless cross-chain compatibility
• ✅ Better user experience
• ✅ DApp compatibility out of the box

The bridge contracts handle the lock/unlock and mint/burn operations, enabling true cross-chain WETH transfers while maintaining address consistency.