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 aafcd913c2
commit 88bc76da91
815 changed files with 125522 additions and 264 deletions
--- a/docs/specs/actions/bridge-engine.md
+++ b/docs/specs/actions/bridge-engine.md
@@ -0,0 +1,159 @@
+# Bridge Engine Specification
+
+## Overview
+
+This document specifies the bridge engine that provides cross-chain asset transfers using CCIP and third-party bridge providers.
+
+## Provider Abstraction
+
+### Bridge Providers
+
+**CCIP**: Chainlink CCIP (primary for supported chains)
+**Third-Party**: 
+- Stargate
+- Hop Protocol
+- Across Protocol
+- Others as needed
+
+### Provider Interface
+
+```typescript
+interface BridgeProvider {
+  getName(): string;
+  getSupportedChains(): number[];
+  getQuote(request: BridgeQuoteRequest): Promise<BridgeQuote>;
+  executeBridge(request: BridgeRequest): Promise<Transaction>;
+  getStatus(txHash: string): Promise<BridgeStatus>;
+}
+```
+
+## Quote Comparison
+
+### Quote Structure
+
+```json
+{
+  "provider": "CCIP",
+  "from_chain": 138,
+  "to_chain": 1,
+  "from_token": "0x...",
+  "to_token": "0x...",
+  "amount_in": "1000000000000000000",
+  "amount_out": "990000000000000000",
+  "fee": "10000000000000000",
+  "estimated_time": 300,  // seconds
+  "trust_score": 0.95,
+  "route": {
+    "steps": [...]
+  }
+}
+```
+
+### Comparison Factors
+
+**1. Fees**: Lower is better
+**2. ETA**: Faster is better
+**3. Trust Score**: Higher is better (security, audits, track record)
+**4. Liquidity**: Sufficient liquidity available
+**5. Supported Amounts**: Amount within limits
+
+### Trust Scores
+
+**Factors**:
+- Security audits
+- Total value locked (TVL)
+- Incident history
+- Team reputation
+- Code maturity
+
+## CCIP Routing Integration
+
+### CCIP as Primary
+
+**When to Use**: Chains supported by CCIP
+**Benefits**: Secure, audited, Chainlink-backed
+
+### CCIP Quote Flow
+
+1. Check CCIP router for quote
+2. Calculate fees (message fee + token fee)
+3. Estimate execution time
+4. Return quote
+
+### CCIP Execution
+
+1. Approve token spending (if needed)
+2. Call CCIP router send function
+3. Monitor source transaction
+4. Track CCIP message
+5. Monitor destination execution
+
+## Failover Routing
+
+### Strategy
+
+**Priority Order**:
+1. CCIP (if available and competitive)
+2. Trusted third-party bridges
+3. Alternative routes
+
+### Failover Triggers
+
+- CCIP unavailable
+- CCIP quote significantly worse
+- User preference
+- Amount limits exceeded
+
+## Proof and Receipt Tracking
+
+### Tracking Flow
+
+1. Store source transaction hash
+2. Monitor CCIP message status
+3. Link to destination transaction
+4. Track execution status
+5. Provide end-to-end visibility
+
+### Status Updates
+
+**States**:
+- `pending`: Source transaction pending
+- `sent`: Message sent to CCIP
+- `delivered`: Message delivered
+- `executing`: Executing on destination
+- `completed`: Bridge completed
+- `failed`: Bridge failed
+
+## API Endpoints
+
+### Get Bridge Quote
+
+`GET /api/v1/bridge/quote`
+
+**Parameters**:
+- `from_chain`: Source chain ID
+- `to_chain`: Destination chain ID
+- `from_token`: Source token address
+- `to_token`: Destination token address
+- `amount`: Amount to bridge
+
+**Response**: Best quote from all providers
+
+### Execute Bridge
+
+`POST /api/v1/bridge/execute`
+
+**Body**: Bridge request parameters
+**Response**: Source transaction hash
+
+### Get Bridge Status
+
+`GET /api/v1/bridge/status/{tx_hash}`
+
+**Response**: Bridge status with source and destination transaction details
+
+## References
+
+- CCIP Tracking: See `../ccip/ccip-tracking.md`
+- Wallet Connectivity: See `wallet-connectivity.md`
+