Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
parent 4d4f8cedad
commit 903c03c65b
815 changed files with 125522 additions and 264 deletions
--- a/docs/BRIDGE_CONTRACT_ARCHITECTURE.md
+++ b/docs/BRIDGE_CONTRACT_ARCHITECTURE.md
@@ -0,0 +1,220 @@
+# 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
+