# DirvenBank V2: CCTP-Centric Settlement Architecture

## Why This Architecture

The Omnibridge failure taught us one critical lesson: **third-party bridge infrastructure is a single point of catastrophic failure.** When a bridge breaks at 2.1B scale, recovery becomes a multi-protocol, multi-jurisdictional nightmare.

V2 eliminates this by:
1. **EURC only moves via Circle CCTP** — Circle's own burn/mint protocol. No AMBs, no validators, no 3rd-party bridges.
2. **DEUR is the settlement layer** — users never touch EURC. DEUR moves cheaply between chains via our lightweight SettlementBridge.
3. **Hard caps per chain** — no single chain holds more than 100M EURC. If something breaks, it breaks at 100M, not 2.1B.
4. **Automated circuit breakers** — reserve ratio is watched 24/7. Any drop below 100% auto-pauses all vaults.

## Architecture Overview

```
USER LAYER
  ┌─────────────────────────────────────────────┐
  │  DEUR (Dirven Euro) — Settlement Token       │
  │  • 1 DEUR = 1 EURC at all times             │
  │  • Users deposit EURC → get DEUR            │
  │  • Users burn DEUR → get EURC               │
  │  • DEUR moves between chains in seconds     │
  └─────────────────────────────────────────────┘

RESERVE LAYER
  ┌─────────────────────────────────────────────┐
  │  EURCVault_v2 (per chain)                    │
  │  • Holds canonical EURC                      │
  │  • Mints/burns DEUR at 1:1                  │
  │  • Max 100M EURC cap per chain              │
  │  • Daily deposit/withdraw limits            │
  │  • Auto-pauses if reserve < 100%            │
  └─────────────────────────────────────────────┘

BRIDGE LAYER
  ┌─────────────────┐    ┌──────────────────────┐
  │  CCTPModule      │    │  SettlementBridge    │
  │  • Circle CCTP   │    │  • DEUR settlement   │
  │  • EURC movement │    │  • Multi-relayer     │
  │  • 3-5 min final │    │  • ~30 sec final     │
  └─────────────────┘    └──────────────────────┘

MONITORING LAYER
  ┌─────────────────────────────────────────────┐
  │  ProofOfReserve (+ Circuit Breaker)          │
  │  • Cross-chain reserve tracking             │
  │  • Public watchdog (anyone can trigger)     │
  │  • Auto-pauses all vaults if ratio < 100%  │
  └─────────────────────────────────────────────┘
```

## Component Details

### 1. EURCVault_v2 (`contracts/EURCVault_v2.sol`)
- **Per-chain deployment**: One vault per chain holding that chain's EURC
- **Core function**: `deposit(EURC) → mint(DEUR)` and `burn(DEUR) → withdraw(EURC)`
- **Cap**: Hard max cap (configurable, default 100M EURC)
- **Limits**: Daily deposit/withdraw limits, per-user cooldown
- **Circuit breaker**: `paused` flag stops all deposits/withdrawals
- **CCTP integration**: `bridgeToChain()` → CCTPModule for cross-chain EURC movement
- **Reserve check**: Anyone can call `checkReserve()` which compares EURC balance against DEUR supply

### 2. CCTPModule (`contracts/CCTPModule.sol`)
- **Integrates Circle CCTP**: Calls `depositForBurn()` on TokenMessenger
- **Outbound**: Vault calls `initiateBridge(amount, destDomain, recipient)` → EURC is burned
- **Inbound**: Relayer calls `receiveWithAttestation()` → EURC minted to vault, DEUR minted to user
- **Daily limits**: Prevents large unauthorized outflows
- **Domain whitelist**: Only supported destination chains can be bridged to

### 3. SettlementBridge (`contracts/SettlementBridge.sol`)
- **DEUR-only bridge**: Users lock DEUR on chain A, mint DEUR on chain B
- **Multi-relayer security**: 2-of-3 signature scheme (configurable)
- **Daily mint limits**: Prevents unauthorized large mints
- **Fast settlement**: ~30 seconds (block time + relayer processing)
- **Non-repudiation**: Each lock has unique nonce, no replay possible

### 4. ProofOfReserve (`contracts/ProofOfReserve.sol`)
- **Cross-chain aggregator**: Relayers push reserve snapshots from each chain
- **Global ratio**: `totalEURC * 1e12 / totalDEUR` across all chains
- **Circuit breaker**: Auto-pauses all vaults if ratio < 100%
- **Public watchdog**: Anyone can call `triggerCircuitBreaker()` if they detect a shortfall
- **Transparency**: All snapshots are public and verifiable on-chain

## Flow Diagrams

### User Deposit (User has EURC, wants DEUR)
```
User                   EURCVault                 DEUR
  │                      │                        │
  │──approve(EURC, vault)                         │
  │──deposit(amount)─────│                        │
  │                      │──transferFrom(user)    │
  │                      │──mint(user, DEUR)──────│
  │<──── DEUR received───│                        │
```

### User Cross-Chain Move (User on Chain A wants DEUR on Chain B)
```
Chain A                             Chain B
  │                                   │
  │──bridgeToChain(amount, B, addr)   │
  │    │                              │
  │    ├──burn DEUR from user         │
  │    ├──send EURC to CCTPModule     │
  │    └──initiateBridge()──CCTP──────│
  │                                   │──EURC minted to vault
  │                                   │──DEUR minted to user
  │<──────── confirmation ───────────│
```

### User Withdrawal (User has DEUR, wants EURC)
```
User                   EURCVault                 EURC
  │                      │                        │
  │──withdraw(DEUR)──────│                        │
  │                      │──burn DEUR from user   │
  │                      │──transfer EURC─────────│
  │<──── EURC received───│                        │
```

## What Breaks & What Doesn't

| Scenario | Impact | Recovery |
|----------|--------|----------|
| Omnibridge-style AMB failure | ❌ Cannot bridge DEUR via CCTP | Use SettlementBridge (different mechanism) |
| CCTP downtime (Circle issue) | ⏸️ Pause cross-chain EURC moves | SettlementBridge still works for DEUR |
| SettlementBridge relayer failure | ⏸️ Pause DEUR bridging | Deploy new relayers (owner action) |
| Single vault hacked | 🔒 Max 100M EURC lost (cap) | Circuit breaker stops other vaults |
| EURC depeg | 📉 DEUR follows EURC 1:1 | No action needed (backed 1:1) |
| 15-of-15 multisig lost | ✅ Not used in V2 | Single owner + circuit breaker |
| Relayer key leak | 🔑 Rotate relayer (30 min) | SettlementBridge.setRelayer() |

## Migration from V1 to V2

1. **Deploy V2 contracts** per chain (deployment script: `scripts/deploy_v2_architecture.py`)
2. **Set V2 vault as DEUR owner** on each chain
3. **Gradually migrate EURC**: withdraw from Omnibridge/V1 vault → deposit into V2 vault
4. **Cap V1 vaults** to prevent new deposits
5. **Verify reserve ratio** after migration (should remain 100%+)
6. **Enable SettlementBridge relayers**
7. **Open V2 for user activity**

## Security Considerations

- **CCTP is the only EURC bridge**: No AMBs, no custom bridge validators, no Wormhole/Axelar for EURC
- **DEUR is lightweight**: DEUR can use any cheap bridge (SettlementBridge, LayerZero, HyperLane) — if DEUR bridge breaks, EURC is still safe in vaults
- **Caps prevent black-swan**: 100M max per chain means worst-case loss is bounded
- **Public circuit breaker**: Anyone can halt the system if reserve looks unhealthy
- **Multiple relayers**: No single point of failure for settlement

## Deployment Addresses (V2)

| Chain | EURCVault_v2 | CCTPModule | SettlementBridge |
|-------|-------------|------------|------------------|
| Gnosis | TBD | N/A (no CCTP) | TBD |
| Arbitrum | TBD | TBD | TBD |
| Base | TBD | TBD | TBD |
| Polygon | TBD | TBD | TBD |

*See `deployment_v2.json` after running deployment script.*

## Compilation Instructions

```bash
# Install solc
npm install -g solc

# Compile contracts
for f in contracts/*_v2.sol contracts/CCTPModule.sol contracts/SettlementBridge.sol contracts/ProofOfReserve.sol; do
  name=$(basename $f .sol)
  solc --abi --bin --overwrite -o build/ $f
  mv build/${name}.abi build/${name}.abi 2>/dev/null || true
  mv build/${name}.bin build/${name}.bin 2>/dev/null || true
done

# Run deployment
python scripts/deploy_v2_architecture.py
```