smom-dbis-138/docs/bridge/trustless/ARCHITECTURE.md

# Trustless Bridge Architecture

## Overview

The Trustless Bridge system enables permissionless value transfer from ChainID 138 (Besu) to Ethereum Mainnet, with automated swaps to stablecoins (USDT/USDC/DAI) via Uniswap V3 and Curve. The system uses **economic security** (bonds + slashing) and **cryptographic verification** instead of trusted third parties or governance.

## Design Principles

1. **No Human Governance**: All operations are automated and permissionless
2. **Economic Security**: Security comes from economic costs (bonds) and incentives (slashing rewards)
3. **Cryptographic Verification**: Fraud proofs and Merkle proofs verify claims (future: light clients)
4. **Permissionless**: Anyone can become a relayer, challenger, or liquidity provider

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     ChainID 138 (Besu)                          │
│                                                                  │
│  ┌──────────────┐                                               │
│  │  Lockbox138  │  ← Users deposit ETH/WETH here               │
│  └──────┬───────┘                                               │
│         │                                                        │
│         │ Emits: Deposit(depositId, asset, amount, recipient)   │
│         │                                                        │
└─────────┼────────────────────────────────────────────────────────┘
          │
          │ Off-chain: Relayer monitors events
          │
┌─────────┼────────────────────────────────────────────────────────┐
│         │              Ethereum Mainnet                          │
│         │                                                        │
│  ┌──────▼──────────┐                                            │
│  │   InboxETH      │  ← Relayers submit claims here            │
│  └──────┬──────────┘                                            │
│         │                                                        │
│    ┌────┴────┐                                                  │
│    │         │                                                  │
│ ┌──▼────┐ ┌──▼──────────┐                                      │
│ │ Bond  │ │  Challenge  │                                      │
│ │Manager│ │  Manager    │                                      │
│ └───┬───┘ └──────┬──────┘                                      │
│     │            │                                              │
│     │            │ If challenged → slash bond                   │
│     │            │ If not challenged → finalize                 │
│     │            │                                              │
│     └────────────┼──────────────┐                               │
│                  │              │                               │
│         ┌────────▼──────┐  ┌───▼──────────┐                    │
│         │ Liquidity     │  │  SwapRouter  │                    │
│         │ Pool ETH      │  │  (Uniswap    │                    │
│         │               │  │   V3/Curve)  │                    │
│         └────────┬──────┘  └──────┬───────┘                    │
│                  │                │                             │
│         ┌────────▼────────────────▼───────┐                    │
│         │  BridgeSwapCoordinator          │                    │
│         │  (Release + Swap)               │                    │
│         └──────────────┬──────────────────┘                    │
│                        │                                        │
│                   USDT/USDC/DAI                                 │
│                        │                                        │
│                   Recipient                                     │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

## Components

### 1. Lockbox138 (ChainID 138)

**Purpose**: Lock assets on source chain before bridging

**Key Functions**:
- `depositNative(amount, recipient, nonce)`: Lock native ETH
- `depositERC20(token, amount, recipient, nonce)`: Lock ERC-20 tokens (WETH)

**Security**:
- Replay protection via nonces and deposit ID tracking
- Immutable after deployment (no admin functions)

### 2. InboxETH (Ethereum)

**Purpose**: Receive and process claims from relayers

**Key Functions**:
- `submitClaim(depositId, asset, amount, recipient, proof)`: Submit claim with bond

**Flow**:
1. Relayer monitors `Deposit` events on ChainID 138
2. Relayer submits claim to `InboxETH` with required bond
3. Claim registered in `ChallengeManager`
4. Pending claim added to `LiquidityPoolETH`

### 3. BondManager (Ethereum)

**Purpose**: Manage bonds for economic security

**Key Functions**:
- `postBond(depositId, depositAmount)`: Post bond for claim
- `slashBond(depositId, challenger)`: Slash bond on fraud proof
- `releaseBond(depositId)`: Release bond after finalization

**Bond Sizing**:
- `bondAmount = max(depositAmount * 1.1, 1 ETH)`
- Ensures bond exceeds potential profit from fraud

### 4. ChallengeManager (Ethereum)

**Purpose**: Manage fraud proof challenges

**Key Functions**:
- `registerClaim(...)`: Register claim (called by InboxETH)
- `challengeClaim(depositId, proofType, proof)`: Challenge claim with fraud proof
- `finalizeClaim(depositId)`: Finalize claim after challenge window

**Challenge Window**: 30 minutes (default, configurable)

**Fraud Proof Types**:
- `NonExistentDeposit`: Deposit doesn't exist on source chain
- `IncorrectAmount`: Amount mismatch
- `IncorrectRecipient`: Recipient mismatch
- `DoubleSpend`: Deposit already claimed elsewhere

### 5. LiquidityPoolETH (Ethereum)

**Purpose**: Provide near-instant liquidity for bridge releases

**Key Functions**:
- `provideLiquidity(assetType)`: LP deposits ETH/WETH
- `withdrawLiquidity(amount, assetType)`: LP withdraws (subject to liquidity ratio)
- `releaseToRecipient(...)`: Release funds to recipient (authorized contracts only)

**Features**:
- Separate pools for ETH and WETH
- LP fee: 5 bps (0.05%) on bridge amount
- Minimum liquidity ratio: 110% (withdrawals blocked if below)

### 6. SwapRouter (Ethereum)

**Purpose**: Swap ETH/WETH to stablecoins via DEXs

**Supported Providers**:
- **Primary**: Uniswap V3 (WETH → USDT/USDC/DAI)
- **Secondary**: Curve (for stable/stable pairs)
- **Optional**: 1inch (aggregation routing)

**Key Functions**:
- `swapToStablecoin(inputAsset, stablecoinToken, amountIn, amountOutMin, routeData)`: Execute swap

### 7. BridgeSwapCoordinator (Ethereum)

**Purpose**: Coordinate bridge release + swap in single transaction

**Key Functions**:
- `bridgeAndSwap(depositId, recipient, outputAsset, stablecoinToken, amountOutMin, routeData)`: Release + swap

**Flow**:
1. Verify claim finalized
2. Release from `LiquidityPoolETH` to `SwapRouter`
3. Execute swap via `SwapRouter`
4. Transfer stablecoin to recipient

## Economic Model

### Bond Economics

- **Bond Size**: 110% of deposit amount (minimum 1 ETH)
- **Slashed Bonds**: 50% to challenger, 50% burned
- **Released Bonds**: Returned to relayer after successful finalization

### LP Economics

- **Fee**: 5 bps (0.05%) on bridge amount
- **Liquidity Ratio**: Minimum 110% of pending claims must remain in pool
- **Withdrawals**: Blocked if withdrawal would violate minimum ratio

### Relayer Economics

- **Costs**: Gas fees for submitting claims + bond posting
- **Revenue**: Relayer fees (future: can be added to bridge)
- **Risk**: Bond slashed if fraudulent claim is challenged

### Challenger Economics

- **Costs**: Gas fees for submitting challenges
- **Revenue**: 50% of slashed bond
- **Incentive**: Economic incentive to monitor and challenge fraudulent claims

## Security Model

### Economic Security

- Bonds must exceed potential profit from fraud (110% of deposit)
- Slashing mechanism makes fraud economically unprofitable
- Challengers earn rewards for detecting fraud

### Cryptographic Security

- Deposit IDs are unique (hash of parameters + timestamp + block)
- Replay protection via nonces and processed deposit tracking
- Fraud proofs verify claims against source chain state (future: Merkle proofs)

### Operational Security

- Permissionless relayers and challengers (no single point of failure)
- Challenge window allows time for fraud detection
- Liquidity pool provides instant availability while finality completes

## Known Limitations & Future Improvements

1. **Fraud Proof Implementation**: Currently placeholder - needs actual Merkle proof verification
2. **Light Client Integration**: Future integration for trustless state verification
3. **Multi-Hop Swaps**: Curve integration needs WETH→stablecoin intermediate swap
4. **Relayer Fees**: Currently no fees for relayers (can be added)
5. **Rate Limiting**: Basic epoch-based rate limiting (can be improved)

## Risk Assessment

| Risk | Mitigation |
|------|------------|
| Fraudulent claims | Bonds + slashing + challenges |
| Liquidity risk | Minimum liquidity ratio enforcement |
| Smart contract bugs | Comprehensive testing + audit (recommended) |
| Economic attacks | Bond sizing exceeds profit potential |
| Centralization | Permissionless relayers/challengers |