# Docs


- **Welcome**
- [Introduction](/docs): Documentation hub for the MEV-Aware Batch Auction Liquidation Protocol

- **Foundation & Design**
- Getting Started
  - [Overview](/docs/getting-started): Foundational knowledge — DeFi lending, liquidation mechanics, MEV gas wars, and academic literature
  - [DeFi Fundamentals](/docs/getting-started/defi-fundamentals): Core concepts of decentralized lending, overcollateralization, and liquidation mechanics
  - [The Problem](/docs/getting-started/problem-statement): How Priority Gas Auctions and MEV extraction make conventional DeFi liquidations economically inefficient
  - Literature Review
    - [Literature Review](/docs/getting-started/literature-review): Academic foundations, empirical benchmarks, and theoretical models informing Reforge
    - [DeFi Liquidations & Market Impact](/docs/getting-started/literature-review/defi-liquidations): Empirical findings on collateral loss, fixed-discount vs auction mechanisms, and secondary market slippage
    - [MEV & Priority Gas Auctions](/docs/getting-started/literature-review/mev-foundations): Foundational studies on transaction reordering, PGA bidding dynamics, and the quantification of extractable value
    - [PBS, Private Order Flow & Latency](/docs/getting-started/literature-review/pbs-and-builder-markets): How Proposer-Builder Separation, vertical builder integration, and timing games centralize liquidation access
    - [Fair Ordering & Protocol Security](/docs/getting-started/literature-review/fair-ordering-and-security): Consensus-level order fairness, front-running taxonomy, and holistic DeFi security systematization
  - [Our Solution](/docs/getting-started/our-solution): The MEV-Aware Batch Auction mechanism and Net Economic Value scoring function
- Architecture
  - [System Overview](/docs/architecture): High-level system architecture, cross-tier dataflow, and component interactions
  - [Overall Tech Stack](/docs/architecture/tech-stack): Complete technology stack across smart contracts, backend services, web applications, and research tooling
  - [Smart Contract Architecture](/docs/architecture/smart-contracts): Core EVM protocols, Foundry contracts, batch auction mechanisms, and lending accounting
  - [Backend Architecture](/docs/architecture/backend): Event listening, real-time liquidation opportunity detection, and auction coordination services
  - [Frontend Views](/docs/architecture/frontend): Next.js frontend interfaces, real-time dashboards, liquidator console, and empirical research laboratory

- **Technical Specs**
- Smart Contracts
  - [LendingPool](/docs/specs/contracts/lending-pool): Core lending protocol — deposit, withdraw, borrow, repay, and position accounting
  - [LiquidationAuction](/docs/specs/contracts/liquidation-auction): MEV-aware batch auction mechanism — openAuction, submitBid, closeAuction, selectWinner, settleLiquidation
  - [LiquidationManager](/docs/specs/contracts/liquidation-manager): Position eligibility evaluation, debt ceilings, collateral transfer calculations, and incentive bonuses
  - [PriceOracle](/docs/specs/contracts/price-oracle): Dual-mode price oracle supporting realistic feeds and programmatic price drops for simulations
  - [MockDEX](/docs/specs/contracts/mock-dex): AMM liquidity pool simulation with configurable slippage and price impact modeling
  - [HealthFactor Library](/docs/specs/contracts/health-factor-lib): Shared mathematical library for health factor calculations — HF = (Collateral × Threshold) / Debt
- Backend Services
  - [Block Listener](/docs/specs/backend/block-listener): WebSocket-based blockchain event subscription, new block monitoring, and reconnection handling
  - [Opportunity Engine](/docs/specs/backend/opportunity-engine): Continuous position scanning, health factor evaluation, and liquidation opportunity queueing via BullMQ
  - [Auction Engine](/docs/specs/backend/auction-engine): Auction lifecycle coordination — opening, bid aggregation, winner selection, and settlement orchestration
  - [Scoring Function](/docs/specs/backend/scoring-function): Net Economic Value calculation - Gross Liquidation Value - Gas Cost - DEX/Slippage Cost
  - [Simulation Engine](/docs/specs/backend/simulation-engine): Multi-bot orchestration, gas simulation, market volatility modeling, and comparative benchmarking
- Frontend Views
  - [Protocol Dashboard](/docs/specs/frontend/protocol-dashboard): Global protocol metrics view — TVL, outstanding debt, active positions, liquidation stats, and recovery rates
  - [Liquidation Marketplace](/docs/specs/frontend/liquidation-marketplace): Real-time liquidation opportunity explorer with position details, health factors, and estimated profits
  - [Liquidator Console](/docs/specs/frontend/liquidator-console): Dedicated liquidator interface — wallet integration, bid submission, active auctions, P&L tracking, and ROI
  - [Research Laboratory](/docs/specs/frontend/research-laboratory): Experiment configuration, comparative benchmarking (Conventional vs. MEV-Aware), and result visualization

- **Research & Resources**
- Research
  - [Overview](/docs/research): Research hypothesis, central question, and academic contribution of the Reforge project
  - [Methodology](/docs/research/methodology): Experimental methodology for evaluating the MEV-aware batch auction mechanism
  - [Experiment Design](/docs/research/experiment-design): Scenario configurations, parameter ranges, and benchmark setup for comparative evaluation
  - [Results](/docs/research/results): Empirical findings from comparative simulations — populated as experiments are run
- Resources & Decks
  - [Overview](/docs/resources): Centralized hub for research papers, presentation decks, whitepapers, and downloadable resources
  - [Research & Review Papers](/docs/resources/papers): Formal working papers, mechanism design drafts, and academic citations for Reforge
  - [Slide Decks & Presentations](/docs/resources/slide-decks): Technical architecture slide decks, presentation materials, and conference slides
- Guides
  - [Local Development](/docs/guides/local-development): Complete setup guide for running the full Reforge stack locally
  - [Deploying Contracts](/docs/guides/deploying-contracts): Step-by-step guide for deploying Reforge smart contracts to Anvil and Sepolia testnet using Foundry
  - [Running Simulations](/docs/guides/running-simulations): How to configure and execute comparative liquidation simulations using the Python research layer
  - [Contributing](/docs/guides/contributing): Team workflow, PR conventions, and the spec-first development rule