System Architecture

Overview

Lunarys eDEX is built with FHE technology, enabling a fully encrypted AMM where all reserve balances, trade amounts, and LP positions remain encrypted on-chain. The architecture centers around the EPOOL (Encrypted Pool) contract.

Contract Architecture

graph TD
    Factory[EPoolFactory] -->|creates| Pool1[EPOOL<br/>eBTC/eUSD]
    Factory -->|creates| Pool2[EPOOL<br/>eETH/eUSD]
    Factory -->|creates| PoolN[EPOOL<br/>...]

    Router[UniversalRouter] -->|discovers| Factory
    Router -->|validates paths| Pool1
    Router -->|validates paths| Pool2

    User((User)) -->|calls directly| Pool1
    User -->|calls directly| Pool2

    Pool1 -->|holds| TokenA[CERC20 Token A]
    Pool1 -->|holds| TokenB[CERC20 Token B]
    Pool1 -->|issues| LP[CERC20 LP Token]

    Airdrop[Airdrop] -->|distributes| TokenA
    Airdrop -->|distributes| TokenB

    style Factory fill:#4a5568,color:#fff
    style Router fill:#4a5568,color:#fff
    style Pool1 fill:#2d3748,color:#fff
    style Pool2 fill:#2d3748,color:#fff
    style PoolN fill:#2d3748,color:#fff
    style User fill:#805ad5,color:#fff
    style Airdrop fill:#4a5568,color:#fff

Key relationships:

• EPoolFactory creates EPOOL instances (one per token pair + fee tier)
• UniversalRouter discovers pools and validates multi-hop paths, but does NOT execute swaps
• Users call pools directly for swaps and liquidity operations (encrypted inputs are pool-bound)
• Each EPOOL holds two CERC20 tokens and issues its own CERC20 LP token
• Airdrop distributes test tokens (100 per user per token type)

Technology Stack

Smart Contracts

• Solidity ^0.8.24 with optimization
• FHE Layer: Encrypted types (euint64, euint128, ebool) and FHE operations
• ERC7984: Confidential ERC20 standard for tokens and LP shares
• OpenZeppelin: ReentrancyGuard, Ownable, Ownable2Step

Core Libraries

Library	Purpose
SwapLib	4-term Taylor approximation for constant-product pricing
LiquidityLib	Proportional LP minting and withdrawal math
EPoolObfuscationLib	HCU-optimized random factor generation (3 FHE ops)
EPoolTypes	Shared type definitions
EPoolErrors	Custom error definitions
EPoolFactoryLib	Pool deployment helper

Frontend

• Next.js with React
• FHE SDK (@lunarys/fhe-sdk) for client-side encryption
• ethers.js v6 for contract interaction
• FHE gateway for public decryption of obfuscated reserves

Core Principles

1. Privacy Through Obfuscation

True reserves are encrypted (euint64). The pool exposes obfuscated reserves by multiplying true reserves by a random factor (1M-3M range). This preserves the price ratio while hiding actual magnitudes with ~3x uncertainty.

2. Atomic Execution

All swaps execute in a single transaction. Users provide pre-decrypted obfuscated reserves (with FHE proof) so the pool can validate state without needing oracle callbacks.

3. Proof-Verified State

Swap and liquidity functions require FHE cryptographic proofs that the provided decrypted obfuscated values match the current on-chain ciphertexts. This prevents stale or manipulated inputs.

4. Per-Operation Randomization

Every state-changing operation (swap, add/remove liquidity) rotates the obfuscation factor. This prevents correlation attacks between consecutive operations.

Security Model

Access Control

• Factory: Ownable (pool creation, obfuscation parameter updates)
• EPOOL: Ownable2Step via CERC20 (owner bootstraps; swaps/liquidity permissionless)
• Tokens: Operator approval model (time-limited via setOperator)

Reentrancy Protection

All critical EPOOL functions use OpenZeppelin's ReentrancyGuard.

FHE Security

• All reserve accounting uses encrypted euint64 types
• FHE divisions only use clear denominators (FHE compliance)
• FHE.select for constant-time conditional logic (no encrypted branching)
• Proofs verified via FHE gateway signatures

Economic Security

• Taylor-bounded swaps prevent oversized trades (max ~6.25% of reserve lower bound)
• Slippage protection via encrypted minAmountOut
• 0.05% withdrawal fee prevents JIT liquidity attacks
• Obfuscation prevents MEV/sandwich attacks

Project Structure

contracts/
  EPOOL.sol                    -- Core AMM pool
  EPoolFactory.sol             -- Pool deployment factory
  UniversalRouter.sol          -- Pool discovery and routing
  UniversalRouterHelper.sol    -- Router utility functions
  Airdrop.sol                  -- Token distribution
  TransferHelper.sol           -- Transfer utility
  tokens/
    CERC20.sol                 -- Confidential ERC20 (ERC7984)
    ERC20.sol                  -- Standard ERC20 (testing)
    WrappedERC20.sol           -- ERC20 to ERC7984 wrapper
  libraries/
    SwapLib.sol                -- Swap math (4-term Taylor)
    LiquidityLib.sol           -- LP math
    EPoolObfuscationLib.sol    -- RNG factor generation
    EPoolTypes.sol             -- Type definitions
    EPoolErrors.sol            -- Custom errors
    EPoolFactoryLib.sol        -- Factory helper
  interfaces/
    IPositionNFT.sol           -- Position NFT interface