more-graphs

Author: orangesantra

architecture.md

@@ -1,3 +1,111 @@
+# TLISHook Architecture
+
+## Context: Uniswap V4 and MEV
+
+**Important:** Uniswap V4 pools are **NOT MEV-resistant by default**. V4 provides:
+- ✅ Hooks system (extensibility)
+- ✅ Singleton architecture (gas efficiency)  
+- ✅ Flash accounting (capital efficiency)
+- ❌ NO built-in MEV protection
+
+**Standard V4 pools** (without special hooks) **still suffer from:**
+- Sandwich attacks
+- Front-running
+- JIT liquidity attacks
+- Toxic order flow
+
+**TLISHook is a V4 hook that ADDS MEV protection** on top of V4's infrastructure. Without this hook, V4 pools have the same MEV vulnerabilities as V2/V3.
+
+---
+
+## Pain Points
+
+### 🎯 MEV Exploitation in Standard V4 Pools
+**Problem:** Even on Uniswap V4, sophisticated bots scan the mempool and front-run profitable trades. A user submitting a large swap to a vanilla V4 pool can still lose 2-5% to sandwich attacks.
+
+**How TLISHook Solves It:** Time-locked encryption hides trade details during collection phase. Intents are XOR encrypted with future drand randomness - nobody can decrypt until the unlock time passes.
+
+### 🔍 Privacy Leakage in V4 Swaps
+**Problem:** All V4 swap transaction details (amounts, directions, addresses) are public in the mempool before execution. Large traders reveal their positions, market makers can adjust prices, competitors gain intelligence.
+
+**How TLISHook Solves It:** Encrypted intents hide all parameters for 5 minutes during batch collection. Decryption only happens atomically at execution time.
+
+### 📊 Predictable Execution in V4
+**Problem:** V4 swaps have deterministic execution prices, enabling "just-in-time" MEV attacks. Attackers submit transactions that execute right before victim trades, manipulating prices profitably.
+
+**How TLISHook Solves It:** Surprise pricing adds ±1% randomness (verifiable via drand). Even if encrypted data leaks, execution price remains unpredictable until drand publishes randomness.
+
+### ⚡ Front-Running (Still Possible in V4)
+**Problem:** Even with V4, validators and searchers can reorder transactions to extract value. Priority gas auctions (PGA) waste user funds competing for block space.
+
+**How TLISHook Solves It:** Batch execution with randomized prices makes front-running unprofitable. All trades execute atomically in single transaction at surprise prices.
+
+### 🛡️ Slippage Manipulation in V4 Swaps
+**Problem:** Users set wide slippage bounds (5-10%) to ensure execution on V4 pools, but attackers exploit this by pushing prices to the worst acceptable level via sandwich attacks.
+
+**How TLISHook Solves It:** User-defined price bounds (minSqrtPriceX96, maxSqrtPriceX96) + minAmountOut protection + surprise pricing. Random execution price always clamped to user limits. If random price exceeds bounds, users get their limit price (best case scenario).
+
+---
+
+## Core Innovations
+
+### 🔐 Time-Locked Intent System (TLIS)
+**What:** Intents encrypted with XOR using future drand randomness (per-intent drandRound). Decryption key only available after batch unlock time.
+
+**Why:** Creates temporal privacy - intents visible on-chain but unreadable until execution. No trusted third party needed (drand is decentralized beacon).
+
+**Impact:** 5-minute collection window where trade flow is completely hidden, preventing all mempool-based attacks.
+
+### 🎲 Surprise Pricing: Gamified Trading with Safety Nets
+**What:** Every swap executes at a **surprise price** = market price ± random offset (±1% in sqrtPriceX96 space). You might get lucky and pay less, or unlucky and pay more, but **always within your bounds**. Randomness from drand (verifiable, unpredictable).
+
+**The Game Element:**
+- 🎰 **Risk/Reward:** Set wide bounds for higher chance of surprise upside, or tight bounds for predictability
+- 🎲 **Luck Factor:** Alice sells at $1964 (unlucky -1.8%), Bob buys at $2014 (lucky +0.7%), Carol hits max bound at $2020
+- 🎯 **Strategic Betting:** Trade during volatile batches for bigger surprises, or wait for stable batches for safety
+- 🛡️ **Protected Gambling:** Unlike casino, you can't lose more than your specified worst-case (bounds always enforced)
+
+**The MEV Protection:**
+- Makes arbitrage/front-running unprofitable since execution price unknown until after commitment
+- Even attackers face same price uncertainty as honest users (can't predict if they'll win or lose)
+- Converts zero-sum MEV game into fun user gamble with house protection
+
+**Why It's Powerful:** Combines **excitement** (random outcomes, potential for better prices) + **safety** (bounds guarantee worst-case protection) + **fairness** (same randomness for everyone) + **fun** (trading feels like skill-based lottery, not sterile finance).
+
+**User Perspective:** "I'm willing to get anywhere between $1950-$2050 for my ETH. Let's see if I get lucky!" → Executes at $2014 → "Nice! I beat the market by $14 🎉"
+
+### 📦 Batch Atomicity
+**What:** All intents in a batch execute in single `poolManager.unlock()` → `unlockCallback()` flow. No partial execution, no state changes between swaps.
+
+**Why:** Prevents inter-batch MEV and toxic flow. Settlement happens atomically - either all swaps succeed or all revert.
+
+**Impact:** Eliminates sandwich attacks within batch. Hook acts as escrow, settling all trades simultaneously.
+
+### ⏰ Timestamp-Based Coordination
+**What:** Batch IDs calculated from `block.timestamp / 300` (not sequential counters). Unlock time = `(batchId + 1) * 300 + 60`.
+
+**Why:** Makes batch timing predictable without central coordination. Anyone can calculate when a batch closes and unlocks.
+
+**Impact:** Enables decentralized keeper network - no single entity controls execution timing.
+
+### 🔗 Drand Integration
+**What:** Uses drand quicknet (3-second rounds) for both encryption and randomness. Each intent stores target drandRound calculated at submission.
+
+**Why:** Drand is decentralized, verifiable, and unpredictable. Nobody (including hook operator) can manipulate or predict future randomness.
+
+**Impact:** Trustless randomness source that's already live and battle-tested. No additional oracle assumptions.
+
+### 💰 Escrow-Based Settlement
+**What:** Users deposit tokens into hook's `s_userBalances` mapping. At execution, hook debits inputs and credits outputs atomically.
+
+**Why:** Encrypted intents mean users can't pre-approve exact amounts. Escrow gives hook the ability to settle without user interaction.
+
+**Impact:** Enables fully autonomous execution. After intent submission, users don't need to sign anything - keeper can execute and settle automatically.
+
+---
+
+## High-Level Architecture
+
 ```mermaid
 flowchart TB
     User([👤 User])
@@ -45,4 +153,62 @@ flowchart TB
     class User,Keeper,Done userClass
     class Deposit,Submit,Batch,Lock,Withdraw processClass
     class Execute,Surprise,Swap,Settle execClass
-```
+```
+
+## User Flow Steps
+
+1. **Deposit** - User deposits ETH/USDC into hook's escrow (`s_userBalances`)
+2. **Submit** - User submits encrypted intent with price bounds (pays 0.001 ETH fee)
+3. **Execute** - Keeper executes batch after time-lock expires, decrypts intents with drand
+4. **Withdraw** - User withdraws resulting tokens from escrow
+
+## Why This Works
+
+**Privacy + Surprise = MEV Resistance**
+
+The combination of time-locked encryption (hiding trade details) and random surprise pricing (unpredictable execution prices) creates a two-layer defense:
+
+1. **First Layer (Encryption):** Attackers can't see trade flow during collection phase
+2. **Second Layer (Randomness):** Even if encryption breaks, execution price is random ±1%
+
+**Result:** Front-running and sandwich attacks become unprofitable because attackers can't:
+- See intent details before batch closes (encrypted)
+- Predict execution prices before drand reveals (random)
+- Execute partial batches to extract value (atomic settlement)
+
+**User Protection:** Price bounds ensure users never get worse than their specified limits, while surprise pricing gives them a chance to get better prices than market.
+
+---
+
+## The Innovation: Trading as a Game
+
+**TLISHook transforms boring swaps into exciting gambles** - but with safety rails:
+
+### 🎰 The Bet
+- You're betting on randomness, not against the house
+- Set your risk tolerance via bounds: tight bounds (safe) vs wide bounds (adventurous)
+- Every trade is a mini-lottery where you might beat the market
+
+### 🎲 The Randomness
+- Verifiable via drand - provably fair, can't be manipulated
+- Same randomness for everyone in the batch (no favoritism)
+- ±1% range means real possibility of significantly better/worse prices
+
+### 🛡️ The Safety Net
+- Can't lose more than your worst-case bound (minSqrtPriceX96/maxSqrtPriceX96)
+- minAmountOut provides additional protection
+- If random price exceeds your bound, you get your bound (best case for you)
+
+### 🎯 The Strategy
+- **Conservative:** Set bounds ±0.2% from market → guaranteed near-market execution
+- **Moderate:** Set bounds ±2% from market → good chance of surprise upside
+- **Aggressive:** Set bounds ±5% from market → high risk, high reward potential
+- **Timing:** Trade during high volatility for bigger surprise potential
+
+### 🎉 The Experience
+**Traditional V4 swap:** "I'm selling 1 ETH at market price ~$2000"  
+**TLISHook swap:** "I'm okay with $1950-$2050 for my ETH... let's see what I get! 🎲"  
+→ Executes at $2014 → "YES! I beat the market! 🎉"  
+→ Or $1964 → "Unlucky this time, but still within my limits ✅"
+
+**Result:** Trading becomes engaging, strategic, and fun - while being MORE secure than traditional swaps due to MEV protection. You're not just avoiding MEV extraction; you're actively participating in a fair game where luck might give you BETTER prices than market.