# 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**:
```bash
./scripts/check-bridge-config.sh
```

### Comprehensive Verification

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

**Usage**:
```bash
./scripts/verify-complete-ccip-setup.sh
```

---

## Related Documentation

- [CCIP Configuration Status](./CCIP_CONFIGURATION_STATUS.md)
- [Complete Task Catalog](./CCIP_COMPLETE_TASK_CATALOG.md)
- [Token Mechanism Documentation](./TOKEN_MECHANISM_DOCUMENTATION.md)

---

**Last Updated**: 2025-01-12