# 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`