┌─────────────────────────────────────────────────────────────────┐
│                    🔄 REVERSO TRANSFER FLOW                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   SEND ──▶ LOCK PERIOD ──▶ CLAIM WINDOW ──▶ COMPLETE           │
│     │          │               │               │                │
│     │    [CANCEL OK]     [RECIPIENT           │                │
│     │                     CLAIMS]              │                │
│     │                          │               │                │
│     └──────────────────────────┴───────────────┘                │
│                                                                 │
│   🛡️ 5 LAYERS OF PROTECTION:                                   │
│   ├── Layer 1: Cancel during lock period                       │
│   ├── Layer 2: Recovery Address 1 (hardware wallet)            │
│   ├── Layer 3: Recovery Address 2 (exchange backup)            │
│   ├── Layer 4: Auto-refund after expiry                        │
│   └── Layer 5: Rescue abandoned funds (90 days)                │
│                                                                 │
│   🏆 PREMIUM INSURANCE (+0.2%):                                 │
│   └── Full refund even if scammer claims your funds!           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Pay 0.2% extra → Insurance coverage (subject to pool balance)

Even if scammer claims your funds:
├── You contact us with proof
├── We verify the scam
└── You get refunded from Insurance Pool 💰

Fully tested: payInsuranceClaim(), withdrawExcessInsurance(),
    reject on non-insured transfer, reject on empty pool.

Example: 10 ETH with insurance
├── Base fee: 0.05 ETH (0.5%)
├── Insurance: 0.02 ETH (0.2%)
├── Total cost: 0.07 ETH (0.7%)
└── Protection: coverage subject to policy/pool ✓

ReversoVault.owner()     → EmergencyGuardian  ✅
EmergencyGuardian.vault  → ReversoVault        ✅
ReversoMonitor.guardian  → EmergencyGuardian  ✅

═══════════════════════════════════════════════════════════════
              🌐 SEPOLIA TESTNET - LIVE TESTS
═══════════════════════════════════════════════════════════════

✅ Test 1: sendETH()        → PASSED (383,452 gas)
   └── 0.001 ETH sent with 1h delay, 0.3% fee collected

✅ Test 2: cancel()         → PASSED (64,138 gas)  
   └── Funds returned to sender, status = Cancelled

✅ Test 3: sendETH()        → PASSED (332,176 gas)
   └── Additional transfer test, cancelled to recover

✅ Test 4: sendETHPremium() → PASSED (358,128 gas)
   └── Insurance flag set, pool increased +0.000002 ETH

✅ Test 5: cancel()         → PASSED (multiple)
   └── All pending transfers successfully cancelled

✅ Test 6: sendToken()      → PASSED (433,095 gas)
   └── ERC20 (TestToken) transfer + cancel working

✅ Test 7: claim()          → PASSED (190,303 gas)
   └── Recipient claimed after 1h unlock period!

═══════════════════════════════════════════════════════════════
                    7/7 TESTS PASSED ✅
═══════════════════════════════════════════════════════════════

═══════════════════════════════════════════════════════════════
                 🧪 REVERSO - TEST RESULTS
═══════════════════════════════════════════════════════════════

TEST 1: CREATE TRANSFER (sendETH)
💸 Sending: 1 ETH
👤 To: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
⏱️  Delay: 1 hour
✅ Transfer created!
📋 Transfer ID: 1
💰 Amount after fee: 0.995 ETH (0.5% fee applied)

═══════════════════════════════════════════════════════════════
TEST 2: CANCEL TRANSFER
💰 Sender balance before: 9998.99 ETH
✅ Transfer CANCELLED!
💰 Sender balance after: 9999.99 ETH
🔙 Refunded: ~0.995 ETH ✓

═══════════════════════════════════════════════════════════════
TEST 3: CLAIM TRANSFER
💰 Recipient balance before: 10000.0 ETH
✅ Transfer CLAIMED!
💰 Recipient balance after: 10000.497 ETH
📊 Status: Claimed ✓

═══════════════════════════════════════════════════════════════
TEST 4: FEE COLLECTION
📊 Total Transfers: 2
🏦 Treasury received fees ✓

TEST 5: ERC20 TRANSFER
🔁 sendToken with fee tier
🏦 Treasury gets token fee
📈 TVL tracks token amount after fee

TEST 6: INSURANCE CLAIM
🛡️ sendETHPremium → claim → payInsuranceClaim
🏦 Insurance pool debits payout
👤 Victim receives compensation

TEST 7: RESCUE (TVL)
🧹 rescueAbandoned reduces TVL after late recovery

═══════════════════════════════════════════════════════════════
                    ✅ ALL TESTS PASSED!
═══════════════════════════════════════════════════════════════

Production: https://reverso-tu3o.onrender.com/api/v1
Development: http://localhost:3000/api/v1

---

## 🔐 Security

### Security Architecture (3-Contract System)

REVERSO uses a **3-layer security architecture**:

### Contract Details

| Contract | Lines | Purpose |
|----------|-------|---------|
| **ReversoVault.sol** | 1,119 | Core vault - reversible transfers, fees, insurance |
| **EmergencyGuardian.sol** | 401 | Multi-sig owner, timelock, emergency controls |
| **ReversoMonitor.sol** | 320 | Real-time monitoring, anomaly detection, auto-pause |

### EmergencyGuardian Features

```solidity
// 🚨 INSTANT - Any guardian can pause immediately
guardian.emergencyPause("Suspicious activity detected");

// ⏱️ TIMELOCK - Critical actions need 24h + dual confirmation
guardian.proposeAction(ActionType.CHANGE_TREASURY, newTreasury);
// ... 24 hours later, DIFFERENT guardian confirms ...
guardian.confirmAction(actionId);
guardian.executeAction(actionId);

// 🔐 MULTI-SIG - Two keys required for sensitive operations
// Primary key: Hot wallet (daily operations)
// Secondary key: Hardware wallet (backup, confirms critical actions)

Layer 1: CANCEL
├── Sender can cancel anytime during lock period
└── 100% refund, zero questions asked

Layer 2: RECOVERY ADDRESS 1
├── If sender loses access, funds go here
└── Recommended: Hardware wallet (Ledger, Trezor)

Layer 3: RECOVERY ADDRESS 2
├── If recovery 1 fails, try recovery 2
└── Recommended: Exchange account (Coinbase, Binance)

Layer 4: AUTO-REFUND
├── If recipient never claims, auto-refund after expiry
└── Anyone can trigger (gas incentive)

Layer 5: RESCUE
├── After 90 days post-expiry, rescue abandoned funds
└── Tries all 3 addresses, then treasury for manual handling

REVERSO/
├── 📁 contracts/                    # Solidity smart contracts
│   ├── ReversoVault.sol             # Core vault (1,119 lines)
│   ├── EmergencyGuardian.sol        # Multi-sig guardian (401 lines)
│   ├── ReversoMonitor.sol           # Anomaly detection (320 lines)
│   └── interfaces/
│       └── IReversoVault.sol        # Contract interface
├── 📁 test/                         # Test suites (131 Hardhat tests)
│   ├── ReversoVault.test.ts         # Vault tests (68 tests)
│   ├── SecurityContracts.test.ts    # Guardian + Monitor tests (48 tests)
│   └── GasBenchmarks.test.ts       # Gas benchmarks (15 tests)
├── 📁 api/                          # Enterprise REST API
│   ├── src/
│   │   ├── index.ts                 # Express server
│   │   ├── routes/                  # Transfer, auth, webhooks, admin, usecases, billing
│   │   ├── middleware/              # HMAC, rate limiting, API keys
│   │   └── utils/                   # Fraud denylist (file + env + runtime)
│   ├── test/                        # API tests (32 Jest tests)
│   ├── sdk/                         # TypeScript SDK with HMAC signing
│   └── config/                      # Multi-chain configuration
├── 📁 website/                      # Production website (Vite)
│   ├── src/
│   │   ├── main.js                  # App logic
│   │   └── styles/                  # CSS
│   └── index.html                   # Entry point
├── 📁 keeper/                       # Keeper bot (WebSocket + Monitor)
│   └── src/index.ts                 # Event listener, reconnection, stats
├── 📁 scripts/                      # Deploy scripts
│   ├── deploy.ts                    # Single chain deploy
│   ├── deploy-stack.ts              # Full 3-contract deploy + wiring
│   └── deploy-multichain.ts         # Multi-chain deploy
├── 📁 security/                     # Security suite
│   ├── foundry-fuzz/                # Foundry fuzz tests (13,000+ runs)
│   ├── slither/                     # Static analysis reports
│   └── gas-benchmarks/              # Gas profiling
├── 📄 .github/workflows/ci.yml     # CI pipeline (contracts + API + website)
├── 📄 hardhat.config.ts             # Multi-chain configuration (15+ chains)
└── 📄 README.md                     # This file

REVERSO/
├── 📁 contracts/           # 3 Solidity smart contracts (1,840 lines total)
│   ├── ReversoVault.sol    # Core vault with 5-layer protection
│   ├── EmergencyGuardian   # Multi-sig + timelock + emergency pause
│   ├── ReversoMonitor      # Anomaly detection + auto-pause
│   └── interfaces/         # Contract interfaces
├── 📁 test/                # Hardhat test suite (131 tests)
├── 📁 security/            # Security suite (Foundry fuzz 13,000+ runs + Slither)
├── 📁 api/                 # Enterprise REST API (32 API tests)
│   ├── src/routes/         # Transfer, auth, webhooks, admin, usecases, billing
│   ├── src/middleware/     # HMAC, rate limiting, API keys
│   ├── src/utils/          # Fraud denylist (file + env + runtime)
│   └── sdk/                # TypeScript SDK with HMAC signing
├── 📁 website/             # Production website (Vite + vanilla JS)
├── 📁 scripts/             # Deploy scripts (single & multi-chain)
├── 📄 README.md            # This file
└── 📄 hardhat.config.ts    # Multi-chain configuration (15+ chains)