> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.lat/llms.txt
> Use this file to discover all available pages before exploring further.

# Bridge Architecture Tradeoffs

> Design space exploration for Cowboy's Ethereum bridge - options, tradeoffs, and open questions

# Bridge Architecture Tradeoffs

This document explores the design space for Cowboy's Ethereum bridge without making final decisions. The goal is to enumerate options, tradeoffs, and open questions.

## Core Problem

Cowboy is a sovereign L1 that needs to transfer assets (ETH, ERC-20s) and messages to/from Ethereum. Unlike L2 rollups, there is no escape hatch to Ethereum consensus—bridge security depends on its own trust assumptions.

## Bridge Security Models

### 1. Validator Committee (Multisig)

**How it works:** A subset of Cowboy validators run Ethereum light clients. They sign attestations when deposits/withdrawals occur. N-of-M signatures required to release funds.

| Pros                                   | Cons                                      |
| -------------------------------------- | ----------------------------------------- |
| Simple to implement                    | Trust assumption on committee honesty     |
| Fast finality (minutes)                | Collusion risk if M validators coordinate |
| Leverages existing validator set       | Committee key management is complex       |
| Battle-tested (Wormhole, Axelar, etc.) | Single exploit can drain bridge           |

**Open questions:**

* What is the right M and N? (e.g., 5-of-9, 7-of-13?)
* Should bridge validators be the same as consensus validators or a separate set?
* How to handle validator set changes mid-flight?
* What slashing conditions apply to bridge misbehavior?

### 2. Optimistic Bridge

**How it works:** Withdrawals are assumed valid. A challenge period (e.g., 7 days) allows anyone to submit a fraud proof if the withdrawal is invalid.

| Pros                              | Cons                                |
| --------------------------------- | ----------------------------------- |
| Minimal trust assumptions         | 7-day withdrawal delay              |
| Only need one honest watcher      | Poor UX for users needing liquidity |
| No committee key management       | Fraud proof complexity              |
| Proven model (Optimism, Arbitrum) | Liveness assumption on challengers  |

**Open questions:**

* Is 7 days acceptable for Cowboy's agent use cases?
* Can we offer a "fast path" with lower security for small amounts?
* Who runs the watchers? Incentives?
* What happens if fraud proof gas costs exceed the disputed amount?

### 3. ZK Light Client

**How it works:** A ZK circuit verifies Ethereum consensus (sync committee signatures). Proofs are verified on-chain on Cowboy, and vice versa.

| Pros                             | Cons                                      |
| -------------------------------- | ----------------------------------------- |
| Trustless (only trust math)      | Extremely complex to build                |
| No committee or challenge period | Proving costs are high                    |
| Future-proof security model      | Ethereum consensus changes break circuits |
| Fast finality once proven        | Few production implementations exist      |

**Open questions:**

* Is this feasible given current ZK infrastructure maturity?
* What are proving costs per bridge transaction?
* How do we handle Ethereum hard forks that change consensus?
* Should this be a v2/v3 goal rather than launch?

### 4. Hybrid Approaches

**Option A: Fast path + slow path**

* Small withdrawals (below threshold X): Validator committee, instant
* Large withdrawals (above threshold X): Optimistic, 7-day delay

**Option B: Committee with optimistic fallback**

* Normal path: Validator committee
* If committee is unresponsive or disputed: Fall back to fraud proofs

**Option C: Committee now, ZK later**

* Launch with validator committee
* Migrate to ZK light client as infrastructure matures

**Open questions:**

* What threshold separates "small" from "large"?
* How do users choose which path?
* Does the hybrid add too much complexity?

## Attack Vectors

### Bridge-Specific Attacks

| Attack                  | Description                              | Mitigations                                      |
| ----------------------- | ---------------------------------------- | ------------------------------------------------ |
| **Committee collusion** | M validators collude to steal funds      | Higher M, diverse validator set, slashing        |
| **Key compromise**      | Bridge keys stolen via hack              | HSMs, threshold signatures, key rotation         |
| **Reorg exploitation**  | Deposit on Ethereum, reorg, double-spend | Wait for Ethereum finality (\~13 min)            |
| **Censorship**          | Committee refuses to process withdrawals | Fallback mechanism, governance override          |
| **Oracle manipulation** | False attestations about Ethereum state  | Multiple data sources, light client verification |

### Economic Attacks

| Attack             | Description                      | Mitigations                       |
| ------------------ | -------------------------------- | --------------------------------- |
| **Bridge run**     | Mass withdrawals drain liquidity | Rate limits, withdrawal caps      |
| **Griefing**       | Spam invalid fraud proofs        | Bonds for challengers             |
| **MEV extraction** | Front-run bridge transactions    | Encrypted mempool for bridge txs? |

## Rate Limits and Caps

Most bridges implement rate limits to bound maximum loss from exploits:

**Options:**

* Per-transaction cap (e.g., max \$1M per withdrawal)
* Per-epoch cap (e.g., max \$10M per hour)
* Per-user cap (e.g., max \$100K per address per day)
* Dynamic caps based on bridge TVL (e.g., max 5% of TVL per hour)

**Open questions:**

* What caps are appropriate for launch?
* Should caps be governance-tunable?
* How do caps interact with large institutional users?

## Finality Considerations

### Ethereum → Cowboy

Ethereum has \~13 minute finality (2 epochs). Options:

1. **Wait for finality:** Deposits confirmed after 13 min. Safe but slow.
2. **Accept at N confirmations:** Faster but reorg risk. How many confirmations?
3. **Probabilistic acceptance:** Accept immediately with fraud recourse.

### Cowboy → Ethereum

Cowboy has \~2 second finality. This is fast, but:

1. Bridge validators must wait for Cowboy finality before signing
2. Ethereum transaction inclusion adds latency
3. Total time: \~2s (Cowboy) + variable (Ethereum mempool) + 13 min (Ethereum finality for confirmation)

## Comparison to Existing Bridges

| Bridge          | Model                        | TVL       | Notable Exploits                    |
| --------------- | ---------------------------- | --------- | ----------------------------------- |
| **Wormhole**    | Guardian multisig (19-of-19) | \$2.5B    | \$320M (2022, signature bypass)     |
| **Axelar**      | Validator committee          | \$200M    | None major                          |
| **LayerZero**   | Oracle + Relayer             | \$5B+     | None major (design concerns raised) |
| **Optimism**    | Optimistic (7-day)           | Native L2 | N/A (native, not bridge)            |
| **Polygon PoS** | Validator committee          | \$1B      | None major                          |
| **Ronin**       | Multisig (5-of-9)            | —         | \$600M (2022, key compromise)       |

**Lessons:**

* Multisig bridges are high-value targets
* Key management is critical
* Higher M thresholds reduce collusion but increase coordination overhead
* Bridges without rate limits lose everything in one exploit

## Open Design Questions

1. **Should bridge validators be consensus validators?**
   * Pro: Leverages existing stake and slashing
   * Con: Increases validator complexity, single point of failure

2. **How much should be slashable for bridge misbehavior?**
   * If bridge TVL exceeds total validator stake, slashing is insufficient deterrent

3. **Should we support arbitrary message passing or just assets?**
   * Assets only: Simpler, lower attack surface
   * Messages: Enables cross-chain contract calls, more complex

4. **What's the upgrade path?**
   * Can we migrate from committee to ZK without disruption?
   * How do we handle bridge contract upgrades on Ethereum?

5. **Insurance and recovery:**
   * Should there be a bridge insurance fund?
   * What happens if the bridge is exploited? Governance bailout? Accept losses?

6. **Ethereum L2 support:**
   * Should we bridge to Ethereum L1 only, or also Arbitrum/Optimism/Base?
   * Each L2 is a separate integration effort

## Recommendations (For Discussion)

**Launch (v1):**

* Validator committee (subset of consensus validators)
* Conservative rate limits
* Wait for Ethereum finality (13 min deposits)
* Assets only (ETH, major ERC-20s)

**Near-term (v2):**

* Add optimistic fallback for large withdrawals
* Expand supported assets
* Consider fast path for small amounts

**Long-term (v3+):**

* ZK light client if infrastructure matures
* Arbitrary message passing
* L2 integrations