160 lines
3.2 KiB
Markdown
160 lines
3.2 KiB
Markdown
# 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`
|
|
|