221 lines
5.0 KiB
Markdown
221 lines
5.0 KiB
Markdown
# 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
|
|
|