explorer-monorepo/docs/specs/actions/bridge-engine.md

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

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

{
  "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