# Introduction (/docs)



Reforge is an MEV-aware batch auction mechanism for DeFi liquidations. It replaces gas-war Priority Gas Auctions with economic efficiency-based scoring — selecting liquidators by **Net Economic Value** rather than who pays the highest gas bribe.

## Explore the Docs [#explore-the-docs]

<Cards>
  <Card icon="<Compass />" title="Getting Started" description="DeFi fundamentals, the MEV problem, and why Reforge exists" href="/docs/getting-started" />

  <Card icon="<Layers />" title="Architecture" description="System design, tech stack, and component interactions" href="/docs/architecture" />

  <Card icon="<ScrollText />" title="Specifications" description="Living specs for every component — read before coding" href="/docs/specs/contracts" />

  <Card icon="<FlaskConical />" title="Research" description="Hypothesis, methodology, experiment design, and results" href="/docs/research" />

  <Card icon="<FolderArchive />" title="Resources & Decks" description="Research papers, presentations, pitch decks, and downloads" href="/docs/resources" />

  <Card icon="<Wrench />" title="Guides" description="Local development, deployment, simulations, and contributing" href="/docs/guides" />
</Cards>


# Backend Architecture (/docs/architecture/backend)



The Reforge backend is an event-driven microservices architecture built with **Node.js**, **TypeScript**, **Fastify**, **Redis**, and **PostgreSQL**. It continuously ingests on-chain events, computes liquidation opportunities, and orchestrates discrete auction lifecycles.

***

## Service Pipeline & Dataflow [#service-pipeline--dataflow]

<Mermaid
  chart="flowchart TD
    Chain[EVM Blockchain Node / Anvil] -->|WebSocket RPC| Listener[Block Listener]
    
    Listener -->|New Block Header| OppEngine[Opportunity Engine]
    OppEngine -->|Fetch Position State| Chain
    
    OppEngine -->|HF < 1.0 Detected| Queue[(Redis BullMQ Job Queue)]
    
    Queue --> AuctEngine[Auction Engine]
    Queue --> SimEngine[Simulation Engine]
    
    AuctEngine -->|Aggregate Sealed Bids| Scoring[Net Economic Value Scorer]
    Scoring -->|Select Highest NEV| Settle[Settlement Service]
    Settle -->|Submit Settle Tx| Chain
    
    AuctEngine -->|Broadcast State| WS[WebSocket Server]
    WS -->|Live Telemetry| UI[Frontend Marketplace]
    
    Settle -->|Log Historical Events| DB[(PostgreSQL Database)]"
/>

***

## Core Backend Stack [#core-backend-stack]

| Technology                   | Category          | Purpose                                                                                                         |
| :--------------------------- | :---------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Fastify & TypeScript**     | API Framework     | Ultra-low latency HTTP API router with strict JSON schema validation and zero-overhead routing.                 |
| **Redis & BullMQ**           | Task Queue        | High-throughput in-memory job queues managing parallel auction events, delayed jobs, and retries.               |
| **viem & WebSocket RPC**     | Blockchain Client | Lightweight, type-safe EVM interaction library maintaining persistent WebSocket subscriptions to Anvil/Sepolia. |
| **PostgreSQL & Drizzle ORM** | Data Persistence  | Relational persistence for historical auctions, searcher telemetry, gas costs, and experimental metrics.        |

***

## Codebase Directory Structure [#codebase-directory-structure]

The backend source tree is organized into modular domain services:

<Files>
  <Folder name="src">
    <Folder name="modules">
      <Folder name="blockchain">
        <File name="block-listener.ts" />

        <File name="transaction-reader.ts" />

        <File name="contract-client.ts" />
      </Folder>

      <Folder name="lending">
        <File name="position.service.ts" />

        <File name="health-factor.service.ts" />

        <File name="liquidation.service.ts" />
      </Folder>

      <Folder name="liquidation">
        <File name="opportunity.service.ts" />

        <File name="auction.service.ts" />

        <File name="settlement.service.ts" />

        <File name="scoring.service.ts" />
      </Folder>

      <Folder name="simulation">
        <File name="gas-simulator.ts" />

        <File name="liquidation-simulator.ts" />

        <File name="market-simulator.ts" />
      </Folder>

      <Folder name="research">
        <File name="experiment.service.ts" />

        <File name="metrics.service.ts" />

        <File name="scenario.service.ts" />
      </Folder>

      <Folder name="analytics">
        <File name="mev.service.ts" />

        <File name="statistics.service.ts" />
      </Folder>
    </Folder>
  </Folder>
</Files>

***

## Detailed Service Responsibilities [#detailed-service-responsibilities]

### 1. Blockchain Listener (`block-listener.ts`) [#1-blockchain-listener-block-listenerts]

Subscribes to new block headers via WebSocket RPC. Emits internal `block:new` events with gas base fee estimates and block timestamp data.

### 2. Opportunity Engine (`opportunity.service.ts`) [#2-opportunity-engine-opportunityservicets]

Maintains an in-memory registry of open borrower positions. Upon receiving a new block or price oracle update, it recomputes health factors using the mathematical model:

```
HF = (Σ Collateral_i × Price_i × LiquidationThreshold_i) / (Σ Debt_j × Price_j)
```

If `HF < 1.00`, it dispatches a high-priority liquidation job to the BullMQ queue.

### 3. Auction Engine (`auction.service.ts` & `scoring.service.ts`) [#3-auction-engine-auctionservicets--scoringservicets]

Orchestrates the lifecycle of discrete batch auctions:

1. **Auction Open:** Emits auction parameters and opens the bidding window (1–2 blocks).
2. **Bid Collection:** Collects sealed bids with liquidator routing parameters and slippage bounds.
3. **NEV Evaluation:** Scores all submissions according to Net Economic Value:
   ```
   NEV = Gross Liquidation Value - Gas Cost - DEX Slippage Cost
   ```
4. **Settlement:** Automatically submits the winning bid settlement transaction on-chain.


# Frontend Views (/docs/architecture/frontend)



The Reforge frontend is a modular, high-performance web application built with **Next.js 16**, **Tailwind CSS**, and **Fumadocs**. It delivers four dedicated interfaces tailored for observers, MEV liquidator searchers, and protocol researchers.

***

## Views Overview [#views-overview]

<Cards>
  <Card icon="<LayoutDashboard />" title="Protocol Dashboard" description="Global liquidity monitoring, protocol solvency metrics, TVL, and bad debt tracking." href="/docs/specs/frontend/protocol-dashboard" />

  <Card icon="<ShoppingBag />" title="Liquidation Marketplace" description="Real-time orderbook and explorer for at-risk collateral positions and open batch auctions." href="/docs/specs/frontend/liquidation-marketplace" />

  <Card icon="<Bot />" title="Liquidator Console" description="Dedicated searcher cockpit with wallet management, active bid submission, and P&L telemetry." href="/docs/specs/frontend/liquidator-console" />

  <Card icon="<FlaskConical />" title="Research Laboratory" description="Interactive Monte Carlo simulator comparing Conventional PGAs against MEV-Aware Batch Auctions." href="/docs/specs/frontend/research-laboratory" />
</Cards>

***

## 1. Protocol Dashboard (`/dashboard`) [#1-protocol-dashboard-dashboard]

The **Protocol Dashboard** serves as the central command center for monitoring systemic risk, collateralization ratios, and global protocol health across all asset pools.

### Key Metrics Monitored [#key-metrics-monitored]

| Metric                       | Category   | Description                                                                                                                |
| :--------------------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------- |
| **Total Value Locked (TVL)** | Liquidity  | Aggregate value of collateral deposited across all lending pools (ETH, WBTC, wstETH) priced via real-time Chainlink feeds. |
| **Outstanding Debt**         | Solvency   | Total synthetic and stablecoin debt borrowed against active collateral positions (USDC, USDT, DAI).                        |
| **Active Positions**         | Risk       | Total count of live borrower debt positions continuously scanned for solvency.                                             |
| **Liquidatable Positions**   | Alert      | Immediate alert counter showing all positions currently crossing the threshold where `HF < 1.00`.                          |
| **Settled Volume**           | Throughput | Cumulative dollar volume of liquidations settled deterministically through Reforge batch auctions.                         |
| **Bad Debt Prevented**       | Security   | Total protocol insolvency prevented compared to baseline mempool congestion failure rates.                                 |

### Protocol Solvency Telemetry [#protocol-solvency-telemetry]

| Metric                        | Calculation / Source                               | Update Frequency    | Purpose                                              |
| :---------------------------- | :------------------------------------------------- | :------------------ | :--------------------------------------------------- |
| **Global Collateral Ratio**   | `Total Collateral Value / Total Borrowed Debt`     | Per block (12s)     | Measures macro protocol solvency buffer.             |
| **At-Risk Debt (HF \< 1.05)** | Sum of debt for positions with `HF ∈ [1.00, 1.05)` | Real-time WebSocket | Early warning queue for incoming liquidation volume. |
| **Protocol Recovery Rate**    | `(Recovered Collateral / Defaulted Debt) × 100%`   | Per settled auction | Evaluates liquidation execution efficiency.          |
| **Average Auction Duration**  | Block timestamp delta (End - Start)                | Historical indexer  | Monitors batch clearance latency against volatility. |

***

## 2. Liquidation Marketplace (`/marketplace`) [#2-liquidation-marketplace-marketplace]

The **Liquidation Marketplace** is a live feed of underwater loans where liquidators, automated searchers, and users can discover liquidation opportunities.

### Live Opportunities Explorer [#live-opportunities-explorer]

A real-time reactive table displaying open auction events and eligible borrower positions:

| Position ID     | Collateral Asset       | Debt Value   | Health Factor | Est. Gross Profit | Auction Status                                                                                                                                                            | Action        |
| :-------------- | :--------------------- | :----------- | :------------ | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------ |
| `0x7A29...b4F1` | 4.50 ETH ($13,500)     | $9,200 USDC  | **0.97**      | **+$460.00**      | <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-emerald-500/10 text-emerald-500 border border-emerald-500/20">🟢 Bidding Open</span> | Inspect / Bid |
| `0x19E4...88c2` | 1.20 WBTC ($72,000)    | $51,400 USDT | **0.94**      | **+$2,570.00**    | <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-amber-500/10 text-amber-500 border border-amber-500/20">🟡 1 Block Left</span>       | Place Bid     |
| `0x42B0...179A` | 18.00 wstETH ($61,200) | $44,800 USDC | **0.99**      | **+$1,344.00**    | <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-blue-500/10 text-blue-500 border border-blue-500/20">🔵 Calculating</span>           | View Details  |

***

### Position Deep-Dive Inspector [#position-deep-dive-inspector]

Selecting any position opens the comprehensive **Position Inspector Panel**, giving liquidators full transparency before committing capital.

<Tabs items="['Position Financials', 'Auction & Settlement', 'Execution Routing']">
  <Tab value="Position Financials">
    <div className="grid grid-cols-2 gap-4 my-2 text-sm">
      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Total Collateral
        </span>

        <strong className="text-base">
          10.00 ETH ($30,000.00)
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Total Borrowed Debt
        </span>

        <strong className="text-base">
          $21,400.00 USDC
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Current Health Factor
        </span>

        <strong className="text-base text-red-500">
          0.941 (Liquidatable)
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Liquidation Bonus Margin
        </span>

        <strong className="text-base text-emerald-500">
          +5.00% ($1,070.00)
        </strong>
      </div>
    </div>
  </Tab>

  <Tab value="Auction & Settlement">
    <div className="grid grid-cols-2 gap-4 my-2 text-sm">
      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Auction Window
        </span>

        <strong className="text-base">
          Block #19,420,102 → #19,420,104
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Competing Sealed Bids
        </span>

        <strong className="text-base">
          4 Searchers Active
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Scoring Metric
        </span>

        <strong className="text-base">
          Net Economic Value (NEV)
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Settlement Mechanism
        </span>

        <strong className="text-base">
          Single Atomic Tx
        </strong>
      </div>
    </div>
  </Tab>

  <Tab value="Execution Routing">
    <div className="grid grid-cols-2 gap-4 my-2 text-sm">
      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Target AMM Venue
        </span>

        <strong className="text-base">
          Uniswap v3 (0.05% Pool)
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Modeled Slippage Impact
        </span>

        <strong className="text-base">
          0.12% ($25.68)
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Base Gas Estimate
        </span>

        <strong className="text-base">
          142,000 gas ($8.20)
        </strong>
      </div>

      <div className="p-3 rounded-lg border bg-muted/30">
        <span className="text-muted-foreground block text-xs">
          Expected Net Value
        </span>

        <strong className="text-base text-emerald-500">
          $1,036.12
        </strong>
      </div>
    </div>
  </Tab>
</Tabs>

***

## 3. Liquidator Console (`/liquidator`) [#3-liquidator-console-liquidator]

The **Liquidator Console** is an institutional execution workstation allowing searchers and bot operators to monitor their capital efficiency, active commitments, and realized P\&L.

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 my-4">
  <div className="rounded-xl border bg-card/60 p-4 shadow-xs">
    <h4 className="text-sm font-semibold mb-3 flex items-center gap-2">
      <Terminal className="size-4 text-primary" /> Searcher Cockpit Telemetry
    </h4>

    <ul className="text-sm space-y-2 text-muted-foreground">
      <li>
        <strong>Connected Wallet:</strong>

         

        <code className="text-xs">0x94B...28aF</code>

         (Mainnet / Sepolia)
      </li>

      <li>
        <strong>Available Liquidity:</strong>

         $150,000.00 USDC
      </li>

      <li>
        <strong>Active Capital in Transit:</strong>

         $32,400.00 USDC
      </li>
    </ul>
  </div>

  <div className="rounded-xl border bg-card/60 p-4 shadow-xs">
    <h4 className="text-sm font-semibold mb-3 flex items-center gap-2">
      <BarChart3 className="size-4 text-primary" /> Historical Performance Metrics
    </h4>

    <ul className="text-sm space-y-2 text-muted-foreground">
      <li>
        <strong>Auctions Won:</strong>

         142 / 168 (84.5% Win Rate)
      </li>

      <li>
        <strong>Total Net Profit:</strong>

         

        <span className="text-emerald-500 font-semibold">+$18,420.50</span>
      </li>

      <li>
        <strong>Total Gas Expended:</strong>

         $1,240.10 (vs. $9,800+ in baseline PGA)
      </li>

      <li>
        <strong>Effective Net ROI:</strong>

         

        <span className="text-emerald-500 font-semibold">+14.85%</span>
      </li>
    </ul>
  </div>
</div>

<Callout type="info">
  **Zero Gas Bribery Overhead:** Because Reforge awards settlements based on Net Economic Value rather than priority gas placement, searchers keep up to 90% of their gross profit instead of paying it to block proposers.
</Callout>

***

## 4. Research Laboratory (`/research`) [#4-research-laboratory-research]

The **Research Laboratory** is the cornerstone academic interface of Reforge. It enables researchers to configure simulation scenarios, run comparative benchmarks between conventional first-come liquidations and MEV-aware batch auctions, and visualize empirical results.

### Interactive Experiment Configuration [#interactive-experiment-configuration]

<div className="rounded-xl border bg-card p-6 my-6 shadow-xs">
  <h4 className="text-base font-semibold mb-4 flex items-center gap-2">
    <Sliders className="size-4 text-primary" /> Simulation Parameter Matrix
  </h4>

  <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
    <div className="p-4 rounded-lg border bg-muted/20">
      <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
        Liquidation Mechanism
      </span>

      <div className="mt-2 flex gap-2">
        <span className="px-3 py-1.5 rounded-md text-xs font-medium bg-muted text-muted-foreground border">
          Conventional PGA
        </span>

        <span className="px-3 py-1.5 rounded-md text-xs font-medium bg-primary text-primary-foreground">
          MEV-Aware Batch Auction
        </span>
      </div>
    </div>

    <div className="p-4 rounded-lg border bg-muted/20">
      <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
        Competing Liquidators
      </span>

      <p className="text-lg font-bold mt-1">
        10 Active Searcher Bots
      </p>

      <span className="text-xs text-muted-foreground">
        Configurable between 2 to 100 automated agents
      </span>
    </div>

    <div className="p-4 rounded-lg border bg-muted/20">
      <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
        Network Gas Price
      </span>

      <p className="text-lg font-bold mt-1">
        50 Gwei 

        <span className="text-xs font-normal text-muted-foreground">(Base: 35, Priority: 15)</span>
      </p>

      <span className="text-xs text-muted-foreground">
        Simulates normal vs. congested mempool conditions
      </span>
    </div>

    <div className="p-4 rounded-lg border bg-muted/20">
      <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
        Collateral Shock Volatility
      </span>

      <p className="text-lg font-bold mt-1">
        5.0% Flash Drop
      </p>

      <span className="text-xs text-muted-foreground">
        Geometric Brownian motion with jump-diffusion events
      </span>
    </div>
  </div>
</div>

***

### Comparative Benchmark Results [#comparative-benchmark-results]

Simulated execution across 1,000 synthetic liquidation events demonstrates substantial economic advantages:

| Performance Metric         | Conventional PGA | Reforge Batch Auction | Variance                                                        | Economic Impact                                             |
| :------------------------- | :--------------- | :-------------------- | :-------------------------------------------------------------- | :---------------------------------------------------------- |
| **Gas Cost / Liquidation** | **$142.00**      | **$61.00**            | <span className="text-emerald-500 font-bold">-57.0%</span>      | Massive reduction in network congestion and wasted compute. |
| **Liquidator Net Profit**  | **$321.00**      | **$402.00**           | <span className="text-emerald-500 font-bold">+25.2%</span>      | Liquidators retain value instead of paying block proposers. |
| **Borrower Loss**          | **$718.00**      | **$531.00**           | <span className="text-emerald-500 font-bold">-26.0%</span>      | Borrowers preserve substantially more leftover equity.      |
| **Settlement Latency**     | **1.8 blocks**   | **2.1 blocks**        | <span className="text-amber-500 font-medium">+0.3 blocks</span> | Acceptable micro-delay safely offset by protocol buffers.   |
| **Protocol Debt Recovery** | **96.2%**        | **97.1%**             | <span className="text-emerald-500 font-bold">+0.9%</span>       | Higher debt clearance rate with lower bad debt risk.        |

***

## Technical Specifications [#technical-specifications]

For in-depth architectural component designs, interface schemas, and state management models, explore the living specifications:

<Cards>
  <Card icon="<FileCode />" title="Protocol Dashboard Specification" description="Interface state model, WebSocket event subscriptions, and charting libraries." href="/docs/specs/frontend/protocol-dashboard" />

  <Card icon="<FileCode />" title="Liquidation Marketplace Specification" description="Orderbook virtual scrolling, sorting algorithms, and position modal architecture." href="/docs/specs/frontend/liquidation-marketplace" />

  <Card icon="<FileCode />" title="Liquidator Console Specification" description="Web3 provider hooks, EIP-712 bid signing, and local storage state persistence." href="/docs/specs/frontend/liquidator-console" />

  <Card icon="<FileCode />" title="Research Laboratory Specification" description="WebAssembly simulation runtime, Web Worker threading, and Canvas charting." href="/docs/specs/frontend/research-laboratory" />
</Cards>


# System Overview (/docs/architecture)



Reforge is organized into four interconnected layers spanning on-chain protocols, real-time backend coordination services, user/liquidator web applications, and an empirical simulation lab.

***

## High-Level Architecture Flow [#high-level-architecture-flow]

<Mermaid
  chart="flowchart TD
    User([End Users & Liquidators]) -->|Web3 RPC / WS| Frontend[Next.js Web Application]
    Frontend -->|Tx Submissions| Wallet[Web3 Wallet Provider]
    Frontend -->|REST / WebSocket| Backend[Backend API & Coordinator]

    subgraph Backend_Layer [Backend Coordination & Simulation]
        Backend --> Listener[Block Listener]
        Backend --> OppEngine[Opportunity Engine]
        Backend --> AuctEngine[Auction Engine]
        
        Listener & OppEngine --> Queue[(Redis & BullMQ)]
        Queue --> SimEngine[Simulation Engine]
        SimEngine --> Bots[Liquidator Searcher Bots]
    end

    subgraph OnChain_Layer [Smart Contracts - Foundry / EVM]
        Bots & Wallet --> Contracts[Reforge Smart Contracts]
        Contracts --> Pool[LendingPool]
        Contracts --> Auction[LiquidationAuction]
        Contracts --> DEX[MockDEX AMM]
    end

    subgraph Analytics_Layer [Research & Data Pipeline]
        Contracts --> Ledger[(Blockchain Events)]
        Ledger --> DB[(PostgreSQL Timescale)]
        DB --> Analytics[Research Analytics]
        Analytics --> Results[Comparative Benchmarks]
    end"
/>

***

## Architectural Layers [#architectural-layers]

<Cards>
  <Card icon="<FileCode />" title="Smart Contract Layer" description="The foundational EVM financial layer — LendingPool, LiquidationAuction, and PriceOracle written in Solidity." href="/docs/architecture/smart-contracts" />

  <Card icon="<Server />" title="Backend Infrastructure" description="Real-time blockchain listener, BullMQ opportunity queue, scoring engine, and telemetry coordinator." href="/docs/architecture/backend" />

  <Card icon="<LayoutDashboard />" title="Frontend Applications" description="Next.js interfaces featuring the Protocol Dashboard, Liquidation Marketplace, and Research Lab." href="/docs/architecture/frontend" />

  <Card icon="<Layers />" title="Overall Tech Stack" description="Complete tooling breakdown across Foundry, Node.js, Fastify, PostgreSQL, Next.js, and Python." href="/docs/architecture/tech-stack" />
</Cards>

***

## Core System Responsibilities [#core-system-responsibilities]

| System Layer          | Primary Technologies                      | Core Responsibilities                                                                                                              |
| :-------------------- | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| **Smart Contracts**   | Solidity 0.8+, Foundry, OpenZeppelin      | Custodies collateral, manages lending accounting, opens discrete batch auctions, and settles liquidation payouts atomically.       |
| **Backend Services**  | Node.js, TypeScript, Fastify, viem, Redis | Monitors blocks via WebSocket, detects underwater accounts ($HF \< 1.0$), computes Net Economic Value scores, and dispatches jobs. |
| **Frontend Views**    | Next.js 16, Tailwind CSS, Fumadocs        | Provides user dashboard, liquidator bidding console, protocol telemetry, and interactive research simulator.                       |
| **Research Pipeline** | Python, NumPy, Pandas, Matplotlib         | Orchestrates Monte Carlo market shocks, models gas wars vs. batch auctions, and generates empirical comparison figures.            |


# Smart Contract Architecture (/docs/architecture/smart-contracts)



The smart contract layer forms the foundational financial system of Reforge. Written in &#x2A;*Solidity 0.8+** and tested with **Foundry**, these contracts handle collateral custody, loan accounting, price oracle ingestion, discrete batch auctions, and AMM swaps.

***

## Contract Directory Structure [#contract-directory-structure]

<Files>
  <Folder name="contracts">
    <File name="LendingPool.sol" />

    <File name="LiquidationAuction.sol" />

    <File name="LiquidationManager.sol" />

    <File name="PriceOracle.sol" />

    <File name="MockDEX.sol" />

    <File name="MockERC20.sol" />

    <Folder name="interfaces">
      <File name="ILendingPool.sol" />

      <File name="ILiquidationAuction.sol" />

      <File name="IPriceOracle.sol" />
    </Folder>

    <Folder name="libraries">
      <File name="HealthFactor.sol" />
    </Folder>
  </Folder>
</Files>

***

## Core Protocol Contracts [#core-protocol-contracts]

| Contract                     | Role                | Core Responsibility                                                                                                        |
| :--------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------- |
| **`LendingPool.sol`**        | Liquidity Hub       | Manages user deposits, collateral locking, debt borrowing, repayments, and position balances.                              |
| **`LiquidationAuction.sol`** | Auction Coordinator | Central research mechanism: coordinates discrete batch auction windows, collects bids, and executes atomic settlements.    |
| **`LiquidationManager.sol`** | Eligibility & Math  | Evaluates account eligibility, computes maximum liquidatable debt ceilings, and calculates collateral transfer quantities. |
| **`PriceOracle.sol`**        | Pricing Feed        | Dual-mode pricing oracle supporting real-time Chainlink feeds as well as programmatic price shocks for simulations.        |
| **`MockDEX.sol`**            | AMM Simulation      | Simulates constant-product AMM liquidity pools with configurable slippage curves and price impact models.                  |
| **`HealthFactor.sol`**       | Math Library        | Shared mathematical library implementing standardized precision-safe Health Factor calculations.                           |

***

## Contract Interfaces & Function Signatures [#contract-interfaces--function-signatures]

<Tabs items="['LendingPool', 'LiquidationAuction', 'LiquidationManager', 'PriceOracle']">
  <Tab value="LendingPool">
    ```solidity
    interface ILendingPool {
        function deposit(address asset, uint256 amount) external returns (uint256);
        function withdraw(address asset, uint256 amount) external returns (uint256);
        function borrow(address asset, uint256 amount) external returns (uint256);
        function repay(address asset, uint256 amount) external returns (uint256);
        function getAccountData(address user) external view returns (
            uint256 totalCollateralETH,
            uint256 totalDebtETH,
            uint256 availableBorrowsETH,
            uint256 currentLiquidationThreshold,
            uint256 ltv,
            uint256 healthFactor
        );
    }
    ```
  </Tab>

  <Tab value="LiquidationAuction">
    ```solidity
    interface ILiquidationAuction {
        function openAuction(address borrower, uint256 debtToCover) external returns (bytes32 auctionId);
        function submitBid(bytes32 auctionId, uint256 minCollateralOut, bytes calldata routeData) external;
        function closeAuction(bytes32 auctionId) external;
        function settleAuction(bytes32 auctionId) external returns (address winner, uint256 bonusAwarded);
    }
    ```
  </Tab>

  <Tab value="LiquidationManager">
    ```solidity
    interface ILiquidationManager {
        function isLiquidatable(address borrower) external view returns (bool);
        function calculateCollateralToLiquidate(
            address borrower,
            address debtAsset,
            uint256 debtToCover
        ) external view returns (uint256 collateralAmount, uint256 liquidationBonus);
    }
    ```
  </Tab>

  <Tab value="PriceOracle">
    ```solidity
    interface IPriceOracle {
        function getAssetPrice(address asset) external view returns (uint256);
        function setAssetPrice(address asset, uint256 price) external; // Simulation mode
        function setDropPercentage(address asset, uint256 dropBps) external; // Flash crash shock
    }
    ```
  </Tab>
</Tabs>

***

## DEX Liquidation & Price Impact Flow [#dex-liquidation--price-impact-flow]

When liquidators seize collateral during high-volatility events, collateral must be immediately liquidated into debt assets (e.g., ETH $\to$ USDC) on an AMM. Reforge explicitly models this DEX slippage in Net Economic Value scoring:

<Mermaid
  chart="sequenceDiagram
    autonumber
    actor Liquidator as Liquidator Bot
    participant Auction as LiquidationAuction
    participant Pool as LendingPool
    participant DEX as MockDEX (AMM)

    Auction->>Pool: 1. Repay borrower debt ($10,000 USDC)
    Pool->>Liquidator: 2. Transfer seized collateral (3.5 ETH)
    Liquidator->>DEX: 3. Swap 3.5 ETH for USDC
    DEX->>DEX: 4. Compute price impact & slippage
    DEX-->>Liquidator: 5. Return $10,420 USDC (Net $420 profit)"
/>


# Overall Tech Stack (/docs/architecture/tech-stack)



The Reforge platform leverages modern, industry-standard tooling across every layer of the architecture, optimized for developer velocity, type safety, deterministic testing, and high-performance event processing.

***

***

## Detailed Technology Breakdown [#detailed-technology-breakdown]

### 1. Smart Contract & Blockchain Layer [#1-smart-contract--blockchain-layer]

| Technology          | Version / Tool   | Category  | Role & Purpose                                                                            |
| :------------------ | :--------------- | :-------- | :---------------------------------------------------------------------------------------- |
| **Solidity**        | `^0.8.24`        | Language  | Core smart contract development with custom errors and transient storage support.         |
| **Foundry**         | `forge` / `cast` | Toolchain | High-speed compilation, fuzzing, differential testing, and contract deployment.           |
| **Anvil**           | Local Node       | Testing   | Fast local Ethereum node with programmable RPC state manipulation and flash loan mocking. |
| **OpenZeppelin**    | `v5.0`           | Libraries | Standard ERC-20, SafeERC20, ReentrancyGuard, and Ownable implementations.                 |
| **Sepolia Testnet** | Ethereum L1      | Network   | Public testnet deployment venue for end-to-end multi-agent auction trials.                |

***

### 2. Backend Infrastructure & Real-Time Pipeline [#2-backend-infrastructure--real-time-pipeline]

| Technology         | Version / Tool | Category      | Role & Purpose                                                                          |
| :----------------- | :------------- | :------------ | :-------------------------------------------------------------------------------------- |
| **Node.js**        | `v22 LTS`      | Runtime       | High-performance asynchronous execution runtime.                                        |
| **TypeScript**     | `v5.x`         | Language      | Strict end-to-end typing across data schemas, API contracts, and RPC calls.             |
| **Fastify**        | `v4.x`         | Web Framework | Low-overhead HTTP REST API server with built-in JSON schema validation.                 |
| **viem**           | `v2.x`         | Web3 Client   | Modular, lightweight Ethereum client maintaining persistent WebSocket subscriptions.    |
| **Redis & BullMQ** | `v7.x`         | Message Queue | In-memory job queue managing high-priority liquidation discovery and auction timers.    |
| **PostgreSQL**     | `v16`          | Database      | Persistent relational storage for historical auctions, bids, and simulated experiments. |

***

### 3. Frontend & User Interfaces [#3-frontend--user-interfaces]

| Technology       | Version / Tool | Category         | Role & Purpose                                                                          |
| :--------------- | :------------- | :--------------- | :-------------------------------------------------------------------------------------- |
| **Next.js**      | `16.3.0`       | Framework        | React 19 App Router framework with Turbopack compilation and SSR/SSG.                   |
| **Tailwind CSS** | `v4.0`         | Styling          | Modern utility-first CSS engine with dark/light mode CSS variables.                     |
| **Fumadocs**     | `v16.x`        | Documentation    | High-performance MDX documentation engine with search, TOC, and Mermaid diagrams.       |
| **wagmi & viem** | Latest         | Web3 React Hooks | React hooks for Ethereum wallet connection, EIP-712 signing, and contract interactions. |
| **Lucide Icons** | Latest         | Icons            | Clean, consistent SVG icon set utilized throughout the UI.                              |

***

### 4. Research & Scientific Modeling [#4-research--scientific-modeling]

| Technology                 | Category         | Role & Purpose                                                                        |
| :------------------------- | :--------------- | :------------------------------------------------------------------------------------ |
| **Python 3.12**            | Core Language    | Data science, statistical modeling, and simulation execution environment.             |
| **NumPy & SciPy**          | Computation      | Vectorized numerical modeling of borrower health factors and price trajectories.      |
| **Pandas**                 | Data Analysis    | Tabular data manipulation for large-scale multi-run auction benchmark logs.           |
| **Matplotlib & Seaborn**   | Visualization    | Publication-quality chart generation for liquidation latency vs. bad debt trade-offs. |
| **scikit-learn / XGBoost** | Machine Learning | Optional predictive models for estimating optimal auction window lengths.             |


# DeFi Fundamentals (/docs/getting-started/defi-fundamentals)



Decentralized Finance (DeFi) lending protocols allow users to borrow assets against cryptocurrency collateral without intermediaries or credit checks. Understanding these fundamental mechanics is essential to understanding why conventional liquidation systems fail under network congestion.

***

## Core Terminology [#core-terminology]

| Term                      | Definition                                                                       | Role in Reforge                                        |
| :------------------------ | :------------------------------------------------------------------------------- | :----------------------------------------------------- |
| **Collateral (ETH)**      | Volatile crypto asset deposited into a lending pool to back a loan.              | Seized and sold during liquidation to cover debt.      |
| **Debt Asset (USDC)**     | Fiat-pegged stablecoin ($1.00 USD) borrowed by the user.                         | Repaid by the liquidator during liquidation.           |
| **Overcollateralization** | The requirement that collateral value strictly exceeds borrowed value.           | Provides a safety buffer against market price drops.   |
| **Liquidation**           | The programmatic sale of collateral to repay bad debt when loan health degrades. | The core process Reforge redesigns via batch auctions. |
| **Liquidation Bonus**     | A predetermined discount (e.g. 5%) given to liquidators on seized collateral.    | The profit incentive driving liquidator competition.   |
| **Gas Fee**               | Network transaction fee paid to blockchain validators for execution priority.    | Currently wasted in Priority Gas Auctions (PGAs).      |

***

## How DeFi Lending Works [#how-defi-lending-works]

In traditional finance, loans require credit scores and legal recourse. In DeFi, loans are completely trustless and secured through **overcollateralization**.

<Mermaid
  chart="flowchart LR
    A[Borrower] -->|1. Deposits $30,000 ETH Collateral| B[Lending Pool]
    B -->|2. Borrows $20,000 USDC| A
    B -.->|3. Continuously monitors| C[Price Oracle]"
/>

### The Overcollateralization Safety Margin [#the-overcollateralization-safety-margin]

Because cryptocurrencies like ETH are volatile, protocols require borrowers to deposit more collateral than the value of debt they borrow.

<Tabs items="['Healthy Position', 'Market Drop (At Risk)', 'Insolvent (Liquidatable)']">
  <Tab value="Healthy Position">
    ```
    Collateral: 10 ETH @ $3,000/ETH = $30,000
    Borrowed:   $20,000 USDC
    LTV Ratio:  $20,000 / $30,000 = 66.7%
    Threshold:  75.0%
    Status:     ✅ Safe (Healthy buffer)
    ```
  </Tab>

  <Tab value="Market Drop (At Risk)">
    ```
    ETH Price drops to $2,800:
    Collateral: 10 ETH @ $2,800/ETH = $28,000
    Borrowed:   $20,000 USDC
    LTV Ratio:  $20,000 / $28,000 = 71.4%
    Threshold:  75.0%
    Status:     ⚠️ Warning (Approaching liquidation threshold)
    ```
  </Tab>

  <Tab value="Insolvent (Liquidatable)">
    ```
    ETH Price drops to $2,600:
    Collateral: 10 ETH @ $2,600/ETH = $26,000
    Borrowed:   $20,000 USDC
    LTV Ratio:  $20,000 / $26,000 = 76.9%
    Threshold:  75.0%
    Status:     🚨 Liquidatable (Immediate liquidation trigger)
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  **Why liquidation is critical:** If the price of ETH falls below the debt value ($20,000) and the borrower walks away, the protocol incurs **bad debt** and lenders lose their funds. Liquidation must occur before this point.
</Callout>

***

## The Anatomy of a Liquidation [#the-anatomy-of-a-liquidation]

When a loan crosses the liquidation threshold, the protocol allows third-party actors (**Liquidators**, typically automated bots) to step in.

<Mermaid
  chart="sequenceDiagram
    autonumber
    actor L as Liquidator Bot
    participant P as Lending Pool Contract
    participant O as Price Oracle
    actor B as Borrower Position

    L->>P: 1. Repay partial debt ($10,000 USDC)
    P->>O: 2. Fetch current collateral price
    P->>B: 3. Seize collateral + 5% bonus ($10,500 ETH)
    P->>L: 4. Transfer $10,500 ETH to Liquidator
    Note over L: Liquidator nets $500 gross profit"
/>

### Numerical Walkthrough [#numerical-walkthrough]

<Steps>
  <Step>
    #### 1. Position Breaches Threshold [#1-position-breaches-threshold]

    * **Collateral:** $26,000 ETH (10 ETH)
    * **Debt:** $20,000 USDC
    * **LTV Ratio:** 76.9% (exceeds 75% max threshold)
  </Step>

  <Step>
    #### 2. Liquidator Repays Partial Debt [#2-liquidator-repays-partial-debt]

    * The liquidator calls the smart contract and pays off **$10,000 USDC** of the borrower's debt.
    * Remaining Debt: `$20,000 - $10,000 = $10,000 USDC`.
  </Step>

  <Step>
    #### 3. Protocol Awards Discounted Collateral [#3-protocol-awards-discounted-collateral]

    * The protocol calculates collateral repayment equal to the debt paid plus a **5% liquidation bonus**:
      `$10,000 + $500 = $10,500 worth of ETH`.
    * Liquidator receives **$10,500 in ETH*&#x2A; for spending $10,000 in USDC (Gross Profit = **$500**).
  </Step>

  <Step>
    #### 4. Restored Health State [#4-restored-health-state]

    * **New Collateral:** `$26,000 - $10,500 = $15,500 ETH`.
    * **New Debt:** `$10,000 USDC`.
    * **New LTV Ratio:** `$10,000 / $15,500 = 64.5%` (well below 75% threshold, restoring safety).
  </Step>
</Steps>

***

## Next Up: The Structural Flaw [#next-up-the-structural-flaw]

While this mechanism protects the protocol from bad debt in theory, in practice it sparks aggressive bot competition.

<Cards>
  <Card icon="<AlertTriangle />" title="The Problem: MEV & Priority Gas Auctions" description="How the race to liquidate first creates massive gas waste and extracts excessive value from borrowers." href="/docs/getting-started/problem-statement" />
</Cards>


# Overview (/docs/getting-started)



Welcome to the **Getting Started** section of Reforge. This section establishes the economic and technical foundations behind decentralized lending, demonstrates why conventional first-come liquidations fail under MEV competition, and outlines Reforge's batch auction solution.

***

## The Learning Journey [#the-learning-journey]

<Mermaid
  chart="flowchart LR
    A[&#x22;1. DeFi Fundamentals&#x22;] --> B[&#x22;2. The Problem (MEV & PGAs)&#x22;]
    B --> C[&#x22;3. Literature Review (12+ Papers)&#x22;]
    C --> D[&#x22;4. Our Solution (Batch Auctions)&#x22;]"
/>

***

## Core Topics in this Section [#core-topics-in-this-section]

<Cards>
  <Card icon="<Coins />" title="DeFi Fundamentals" description="Understand collateral deposits, borrowing, overcollateralization safety buffers, and liquidation bonuses." href="/docs/getting-started/defi-fundamentals" />

  <Card icon="<AlertTriangle />" title="The Problem: MEV & PGAs" description="How the race to liquidate first causes Priority Gas Auctions, extreme gas waste, and excessive borrower losses." href="/docs/getting-started/problem-statement" />

  <Card icon="<Library />" title="Literature Review" description="Deep-dive into 12+ seminal academic papers across DeFi liquidations, MEV, PBS, and consensus order-fairness." href="/docs/getting-started/literature-review" />

  <Card icon="<Lightbulb />" title="Our Solution" description="Explore how Reforge replaces PGAs with a discrete Batch Auction scored by Net Economic Value." href="/docs/getting-started/our-solution" />
</Cards>


# Our Solution (/docs/getting-started/our-solution)



Reforge addresses the structural failure of Priority Gas Auctions by replacing latency-driven mempool races with a **discrete, time-windowed Batch Auction**.

Instead of rewarding whichever bot pays the largest gas bribe to a validator, Reforge evaluates competing bids on **Net Economic Value** and executes exactly one optimal liquidation per unhealthy position.

***

## Core Contribution [#core-contribution]

<Callout type="info">
  ### Working Title [#working-title]

  **"A MEV-Aware Batch Auction Mechanism for DeFi Liquidations: Reducing Gas Competition and Collateral Loss"**

  **Primary Contribution:**\
  Design, implementation, and empirical evaluation of an end-to-end MEV-aware liquidation mechanism that explicitly accounts for liquidation profitability, transaction costs, competition, auction latency, and borrower/protocol outcomes.
</Callout>

***

## Mechanism Overview: From Race to Batch Auction [#mechanism-overview-from-race-to-batch-auction]

<Mermaid
  chart="flowchart TD
    A[Unhealthy Position Detected HF < 1.0] --> B[1. Protocol Opens Auction Window]
    B --> C[2. Competing Liquidators Submit Bids]

    subgraph Liquidator Bids [Discrete Auction Window (1-2 Blocks)]
        B1[Liquidator A: $1000 Gross | $200 Gas | $80 Slip]
        B2[Liquidator B: $1000 Gross | $60 Gas | $40 Slip]
        B3[Liquidator C: $1000 Gross | $120 Gas | $20 Slip]
    end

    C --> B1
    C --> B2
    C --> B3

    B1 --> D[3. Scoring Function: Net Economic Value]
    B2 --> D
    B3 --> D

    D --> E[Winner Selected: Liquidator B ($900 Net)]
    E --> F[4. Settle Exactly ONE Liquidation Transaction]"
/>

***

## The Scoring Function: Net Economic Value [#the-scoring-function-net-economic-value]

Conventional protocols accept the first valid transaction. Reforge scores all bids submitted during the auction window using an objective economic metric:

```
Net Economic Value = Gross Liquidation Value − Gas Cost − DEX/Slippage Cost
```

<Tabs items="['Bid Comparison Matrix', 'Why Winner B Wins']">
  <Tab value="Bid Comparison Matrix">
    | Bidder           | Gross Value | Gas Expenditure             | DEX Slippage Impact     | Net Economic Value | Rank / Decision |
    | :--------------- | :---------- | :-------------------------- | :---------------------- | :----------------- | :-------------- |
    | **Liquidator A** | $1,000      | $200 (High gas war)         | $80 (High impact)       | **$720**           | ❌ 3rd Place     |
    | **Liquidator B** | $1,000      | **$60 (Efficient routing)** | **$40 (Optimized AMM)** | **$900**           | 🏆 **Winner**   |
    | **Liquidator C** | $1,000      | $120 (Moderate gas)         | $20 (Low impact)        | **$860**           | ❌ 2nd Place     |
  </Tab>

  <Tab value="Why Winner B Wins">
    Even if Liquidator A attempts to frontrun by offering $200 in gas fees, **the protocol ignores transaction priority**.

    Because Liquidator B routes trades with lower slippage and minimal gas overhead, it generates **$900 in true economic value** vs. Liquidator A's $720. Liquidator B is awarded the liquidation.
  </Tab>
</Tabs>

***

## Tripartite Alignment: Balancing All Three Stakeholders [#tripartite-alignment-balancing-all-three-stakeholders]

A sustainable liquidation mechanism must align incentives across the three primary participants:

<Mermaid
  chart="graph LR
    L[Reforge Batch Auction] --> B[Borrower]
    L --> P[Protocol]
    L --> Q[Liquidator]

    B -->|Minimizes Collateral Loss| B1[Retains more leftover equity]
    P -->|Reduces Bad Debt Risk| P1[Reliable debt clearance during congestion]
    Q -->|Fair Execution Margins| Q1[No longer surrenders profit to gas bribes]"
/>

| Stakeholder    | Conventional System (PGA)                                           | Reforge MEV-Aware Batch Auction                                        |
| :------------- | :------------------------------------------------------------------ | :--------------------------------------------------------------------- |
| **Borrower**   | Suffers fixed, aggressive collateral penalties (5-10%).             | Maximizes preserved equity by reducing unnecessary discounts.          |
| **Protocol**   | Transactions fail during mempool congestion; bad debt piles up.     | Guaranteed single-transaction settlement with deterministic inclusion. |
| **Liquidator** | Surrenders 70-90% of gross margin to block proposers in gas bribes. | Retains profits based on execution and routing efficiency.             |

***

## The Critical Research Trade-Off [#the-critical-research-trade-off]

Every architectural decision carries trade-offs. Introducing a batch auction window requires careful scientific evaluation.

<Callout type="warn">
  ### The Auction Latency Problem [#the-auction-latency-problem]

  In a conventional system, liquidation is immediate (next block). In Reforge, the auction window introduces a **1–2 block delay**.

  <Mermaid
    chart="timeline
    title The Latency vs. Efficiency Trade-off
    Block 0 : Position drops to HF 0.95
    Block 1 : Auction opens & bids collected : (ETH price drops further?)
    Block 2 : Auction closes & winner settles : (Potential bad debt if ETH crash is severe)"
  />

  During this 1–2 block window, if the collateral price experiences an extreme flash crash, the position could become underwater before settlement.
</Callout>

### The Central Research Question [#the-central-research-question]

> **Does the significant reduction in MEV gas waste and collateral loss outweigh the marginal risk introduced by auction latency?**

Our empirical research platform and simulation engine (`/docs/research`) are designed specifically to answer this question across historical and synthetic stress-test market conditions.

***

## Explore Next [#explore-next]

<Cards>
  <Card icon="<Layers />" title="System Architecture" description="Explore the end-to-end architecture across contracts, backend, frontend, and simulation." href="/docs/architecture" />

  <Card icon="<ScrollText />" title="Specifications" description="Review the technical specifications for each contract and backend service." href="/docs/specs/contracts" />
</Cards>


# The Problem (/docs/getting-started/problem-statement)



In conventional DeFi lending protocols (such as Aave, Compound, and MakerDAO), liquidation is designed around a **first-come, first-served** model. When a position becomes unhealthy, whoever submits the first valid liquidation transaction captures the profit.

This design inadvertently triggers intense &#x2A;*Maximal Extractable Value (MEV)** competition that damages borrowers, protocols, and the wider blockchain network.

***

## The Health Factor Metric [#the-health-factor-metric]

Lending protocols standardize position health using a single composite formula:

```
Health Factor (HF) = (Collateral Value × Liquidation Threshold) / Debt Value
```

<Callout type="info">
  * **$HF > 1.0$**: The position is healthy and adequately collateralized.
  * **$HF \< 1.0$**: The position has breached the risk threshold and is immediately liquidatable by any network participant.
</Callout>

### Example Scenario [#example-scenario]

```
Collateral: 10 ETH @ $3,000/ETH = $30,000
Liquidation Threshold: 80% (0.8)
Borrowed Debt: $20,000 USDC

HF = ($30,000 × 0.8) / $20,000 = 1.20 (Healthy)
```

If ETH price plunges from **$3,000 to $2,300**:

```
New Collateral Value = $23,000
New HF = ($23,000 × 0.8) / $20,000 = 0.92 (Liquidatable!)
```

***

## The Core Failure: Priority Gas Auctions (PGAs) [#the-core-failure-priority-gas-auctions-pgas]

When $HF \< 1.0$, multiple automated searcher bots detect the exact same opportunity simultaneously. Because only the **first** transaction gets included, bots enter a &#x2A;*Priority Gas Auction (PGA)**.

<Mermaid
  chart="sequenceDiagram
    autonumber
    participant M as Mempool
    actor BotA as Liquidator A
    actor BotB as Liquidator B
    actor BotC as Liquidator C
    participant V as Block Validator (Proposer)

    Note over BotA,BotC: All bots see $500 gross liquidation profit
    BotA->>M: Bid 20 Gwei gas fee
    BotB->>M: Outbid: 45 Gwei gas fee
    BotC->>M: Outbid: 90 Gwei gas fee
    BotB->>M: Final Push: 140 Gwei gas fee
    M->>V: Validator selects Bot B (Highest bribe)
    V-->>BotB: Executes Liquidation
    Note over BotB: Gross: $500 | Gas: $220 | Net: $280
    Note over V: Validator extracts $220 pure MEV"
/>

### The Misalignment of Incentives [#the-misalignment-of-incentives]

In a PGA, the winner is determined by **who can pay the highest bribe to the block validator**, not who executes the liquidation most economically for the borrower or protocol.

<Tabs items="['Gross vs Net Profit', 'Economic Breakdown']">
  <Tab value="Gross vs Net Profit">
    | Participant        | Gross Incentive | Gas Bid Paid        | DEX Slippage | Net Liquidator Profit    | Value Transferred to Validator |
    | :----------------- | :-------------- | :------------------ | :----------- | :----------------------- | :----------------------------- |
    | **Bot A**          | $500            | $40 (20 gwei)       | $20          | $440 (Failed / Replaced) | $0                             |
    | **Bot B (Winner)** | $500            | **$220 (140 gwei)** | $30          | **$250**                 | **$220**                       |
    | **Bot C**          | $500            | $150 (90 gwei)      | $25          | $325 (Failed / Replaced) | $0                             |
  </Tab>

  <Tab value="Economic Breakdown">
    ```
    Gross Liquidation Bonus:   $500.00  (Extracted from Borrower)
    ----------------------------------------------------------
    - Paid in Gas Bribes:      $220.00  (Transferred to Block Validator)
    - DEX Slippage & Fees:      $30.00  (Slippage on Collateral Dump)
    ==========================================================
    = Net Liquidator Profit:   $250.00  (Only 50% of incentive retained!)
    ```
  </Tab>
</Tabs>

***

## Systemic Negative Externalities [#systemic-negative-externalities]

| Problem / Externality                     | Mechanism & Impact                                                                                                                         |
| :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Massive Economic Gas Waste**         | Liquidators surrender up to 70–90% of their gross margin in gas wars, directing capital away from DeFi utility and into validator pockets. |
| **2. Excessive Borrower Collateral Loss** | Borrowers suffer fixed 5–10% penalties regardless of whether market conditions require such heavy discounts to achieve liquidity.          |
| **3. Cascading DEX Price Crashes**        | Liquidators dump seized collateral rapidly on AMMs to lock in profits, causing localized slippage and triggering secondary liquidations.   |
| **4. Consensus Instability**              | High MEV rewards create incentives for time-bandit attacks, transaction reordering, block reorganizations, and validator timing games.     |

***

## The Central Research Questions [#the-central-research-questions]

<Callout type="warn">
  ### Research Question 1 [#research-question-1]

  **Does competitive MEV extraction make DeFi liquidation unnecessarily expensive and amplify the economic damage suffered by borrowers?**
</Callout>

<Callout type="warn">
  ### Research Question 2 [#research-question-2]

  **Can the liquidation mechanism be redesigned so that competition is based on economic efficiency rather than a race to submit the highest-priority gas bribe?**
</Callout>

***

## Next Up: Academic Literature & Our Solution [#next-up-academic-literature--our-solution]

<Cards>
  <Card icon="<Library />" title="Literature Review" description="Examine 12 foundational academic papers analyzing DeFi liquidations, MEV, and order-fairness." href="/docs/getting-started/literature-review" />

  <Card icon="<Lightbulb />" title="Our Solution" description="How Reforge's MEV-Aware Batch Auction replaces PGAs with Net Economic Value scoring." href="/docs/getting-started/our-solution" />
</Cards>


# Contributing (/docs/guides/contributing)



## Spec-First Rule [#spec-first-rule]

TODO

## Branch Naming [#branch-naming]

TODO

## PR Process [#pr-process]

TODO

## Code Review [#code-review]

TODO

## Status [#status]

Draft


# Deploying Contracts (/docs/guides/deploying-contracts)



## Prerequisites [#prerequisites]

TODO

## Local Deployment (Anvil) [#local-deployment-anvil]

TODO

## Testnet Deployment (Sepolia) [#testnet-deployment-sepolia]

TODO

## Verify on Etherscan [#verify-on-etherscan]

TODO

## Status [#status]

Draft


# Local Development (/docs/guides/local-development)



## Prerequisites [#prerequisites]

TODO

## Clone & Install [#clone--install]

TODO

## Start Anvil (Local Chain) [#start-anvil-local-chain]

TODO

## Deploy Contracts [#deploy-contracts]

TODO

## Start Backend [#start-backend]

TODO

## Start Frontend [#start-frontend]

TODO

## Verify [#verify]

TODO

## Status [#status]

Draft


# Running Simulations (/docs/guides/running-simulations)



## Prerequisites [#prerequisites]

TODO

## Configuration [#configuration]

TODO

## Running a Simulation [#running-a-simulation]

TODO

## Interpreting Results [#interpreting-results]

TODO

## Status [#status]

Draft


# Overview (/docs/resources)



This section serves as the repository for all non-markdown project artifacts—including academic paper drafts, technical presentations (PPT/Keynote), architecture slide decks, and external references.

***

## Quick Navigation [#quick-navigation]

<Cards>
  <Card icon="<FileText />" title="Whitepapers & Research Papers" description="Working papers, formal mechanism proofs, empirical evaluation drafts, and BibTeX citations." href="/docs/resources/whitepapers-and-papers" />

  <Card icon="<Presentation />" title="Slide Decks & Presentations" description="Team presentation decks, technical architecture walkthroughs, and conference slides." href="/docs/resources/slide-decks" />
</Cards>

***

## How to Manage Documents in this Project [#how-to-manage-documents-in-this-project]

We recommend a hybrid management workflow depending on the file type and update frequency:

<Mermaid
  chart="flowchart TD
    A[New Document / Artifact] --> B{What type of document?}
    
    B -->|Final / Versioned PDF| C[&#x22;1. Local Assets (public/documents/)&#x22;]
    B -->|Live / Collaborative Deck| D[&#x22;2. Cloud Link (Google Slides, Canva)&#x22;]
    B -->|Large Dataset >50MB| E[&#x22;3. External Release / IPFS / S3&#x22;]
    
    C --> F[Commit to Git & Embed directly in MDX]
    D --> G[Embed via IFrame & Add View Link]
    E --> H[Add External Download Link]"
/>

### 1. Local Files (`public/documents/`) [#1-local-files-publicdocuments]

For finalized PDFs, whitepapers, and exported slide decks:

* Place files in `public/documents/<filename>.pdf`
* Reference them directly in MDX using `/documents/<filename>.pdf`
* **Benefits:** Offline access, version-controlled with the repository, fast loading.

### 2. Live Cloud Decks (Google Slides / Pitch.com) [#2-live-cloud-decks-google-slides--pitchcom]

For working presentations that your team updates regularly:

* Keep the master deck in Google Slides or Pitch
* Embed the view-only iframe into `content/docs/resources/slide-decks.mdx`
* **Benefits:** No need to re-export or recommit files after every minor edit.

***

## Document Inventory [#document-inventory]

| Title                                 | Type         | Format              | Location                                           | Status        |
| :------------------------------------ | :----------- | :------------------ | :------------------------------------------------- | :------------ |
| **MEV-Aware DeFi Liquidation System** | Review Paper | PDF (220 KB)        | `/documents/MEV_Aware_DeFi_Liquidation_System.pdf` | ✅ `Available` |
| **System Architecture Walkthrough**   | Presentation | Slides / PDF        | `/documents/architecture-deck.pdf`                 | `Planned`     |
| **MEV Batch Auction Pitch Deck**      | Slide Deck   | Google Slides / PPT | Cloud Link                                         | `In Progress` |
| **Empirical Simulation Benchmarks**   | Data Report  | PDF                 | `/documents/simulation-report.pdf`                 | `Pending`     |


# Research & Review Papers (/docs/resources/papers)



This page hosts official academic papers, technical whitepapers, and review preprints produced by the Reforge research team.

***

## 1. MEV-Aware DeFi Liquidation System (Review & Research Draft) [#1-mev-aware-defi-liquidation-system-review--research-draft]

<Callout type="info">
  ### Document Information [#document-information]

  * **Title:** *MEV-Aware DeFi Liquidation System*
  * **File:** `MEV_Aware_DeFi_Liquidation_System.pdf` (220 KB)
  * **Status:** Review Paper Draft (2026)
</Callout>

### Abstract [#abstract]

Decentralized lending protocols rely on liquidation mechanisms to maintain protocol solvency. However, conventional first-come, first-served liquidations trigger intense Priority Gas Auctions (PGAs) among automated searchers, transferring significant economic value to block proposers and forcing borrowers to surrender excessive collateral discounts. Reforge proposes an end-to-end MEV-aware batch auction liquidation mechanism that aggregates competing bids within discrete block windows and selects winning liquidators based on **Net Economic Value** (Gross Liquidation Value minus Gas and Slippage Costs).

### Downloads & Repositories [#downloads--repositories]

<Cards>
  <Card icon="<Download />" title="Download Review Paper (PDF)" description="220 KB • Direct download of MEV_Aware_DeFi_Liquidation_System.pdf" href="/documents/MEV_Aware_DeFi_Liquidation_System.pdf" />

  <Card icon="<Code2 />" title="Paper Repository (GitHub)" description="LaTeX source code, figures, and experimental scripts in the research paper repository." href="https://github.com/reforge-lab/paper" />
</Cards>

***

## In-Browser Document Preview [#in-browser-document-preview]

You can read and interact with the uploaded review paper directly below:

<iframe src="/documents/MEV_Aware_DeFi_Liquidation_System.pdf" className="w-full h-[800px] rounded-xl border shadow-md my-6" title="MEV-Aware DeFi Liquidation System PDF Preview" />

<Callout type="tip">
  **Full Screen / Native Controls:** Use the top bar in the viewer above to zoom, search text, print, or download the PDF file directly.
</Callout>

***

## BibTeX Citation [#bibtex-citation]

To cite this paper in academic publications, research articles, or theses:

```bibtex
@misc{reforge2026mev,
  title={A MEV-Aware Batch Auction Mechanism for DeFi Liquidations: Reducing Gas Competition and Collateral Loss},
  author={Reforge Research Team},
  year={2026},
  howpublished={\url{https://github.com/reforge-lab}},
  note={Working Paper}
}
```


# Slide Decks & Presentations (/docs/resources/slide-decks)



This page contains presentation slide decks used for technical walkthroughs, research conferences, and stakeholder pitches.

***

## 1. Technical Architecture Walkthrough Deck [#1-technical-architecture-walkthrough-deck]

A slide-by-slide visual walkthrough of the Reforge liquidation pipeline, smart contracts, BullMQ backend orchestration, and frontend dashboards.

<Cards>
  <Card icon="<FileText />" title="Download Presentation (PDF)" description="Offline-compatible vector slides with high-resolution system diagrams." href="/documents/architecture-deck.pdf" />

  <Card icon="<Presentation />" title="Download PowerPoint (.pptx)" description="Editable PowerPoint presentation file for team presentations." href="/documents/architecture-deck.pptx" />
</Cards>

### Embedded Slide Viewer [#embedded-slide-viewer]

<Tabs items="['PDF Slide Viewer', 'Google Slides Embed Example']">
  <Tab value="PDF Slide Viewer">
    ```html
    <iframe
      src="/documents/architecture-deck.pdf"
      className="w-full h-[550px] rounded-lg border shadow-sm my-4"
      title="Architecture Presentation Slides"
    />
    ```
  </Tab>

  <Tab value="Google Slides Embed Example">
    If your presentation is hosted on Google Slides:

    ```html
    <iframe
      src="https://docs.google.com/presentation/d/e/YOUR_SLIDES_ID/embed?start=false&loop=false&delayms=3000"
      frameBorder="0"
      width="100%"
      height="500"
      allowFullScreen={true}
      className="rounded-lg border shadow-sm my-4"
    />
    ```
  </Tab>
</Tabs>

***

## Key Presentation Highlights [#key-presentation-highlights]

<Steps>
  <Step>
    #### Slide 1–3: The Liquidation Dilemma [#slide-13-the-liquidation-dilemma]

    Overview of DeFi lending growth, health factor thresholds, and why conventional liquidations leak 70%+ of gross profit to gas bidding wars.
  </Step>

  <Step>
    #### Slide 4–7: The MEV-Aware Batch Auction Solution [#slide-47-the-mev-aware-batch-auction-solution]

    Discrete block windows, Net Economic Value scoring function, and deterministic single-transaction settlement.
  </Step>

  <Step>
    #### Slide 8–11: Empirical Results & Latency Analysis [#slide-811-empirical-results--latency-analysis]

    Simulation benchmarks comparing Conventional PGAs against MEV-Aware auctions across market crash scenarios.
  </Step>
</Steps>


# DeFi Liquidations & Market Impact (/docs/getting-started/literature-review/defi-liquidations)



This section reviews the empirical literature examining how lending protocols execute liquidations and how protocol design choices affect borrower collateral loss, liquidator profits, and AMM price stability.

***

## 1. An Empirical Study of DeFi Liquidations [#1-an-empirical-study-of-defi-liquidations]

<Callout type="info">
  **Citation:** Kaihua Qin, Liyi Zhou, Pablo Gamito, Peter Jovanovic, Arthur Gervais. &#x2A;ACM Internet Measurement Conference (IMC)*, 2021.\
  [Read Paper (PDF)](https://discovery.ucl.ac.uk/id/eprint/10150722/1/an-empirical-study-of-defi-liquidations.pdf)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr]

Existing fixed-discount liquidation mechanisms (like Aave and Compound) successfully incentivize liquidators to clear debt, but **force borrowers to surrender significantly more collateral than economically necessary**.

### Key Findings & Analysis [#key-findings--analysis]

* **Multi-Protocol Evaluation**: Empirically analyzed on-chain data across **Aave, Compound, MakerDAO, and dYdX** over multiple market cycles.
* **Excessive Collateral Loss**: Fixed discounts (e.g. 5–10%) transfer oversized economic surplus from distressed borrowers to liquidators. Even when market liquidity is deep and execution costs are low, the borrower pays the full fixed penalty.
* **Optimal Liquidator Strategies**: Formulated an optimal liquidation game showing that liquidators maximize returns by strategically selecting positions, structuring partial repayments, and timing transactions.
* **Economic Game Formulation**: Demonstrated that a liquidation mechanism cannot be judged solely by whether bad debt is repaid; it must be evaluated on **how much unnecessary value is extracted from borrowers**.

<Callout type="warn">
  ### Relevance to Reforge [#relevance-to-reforge]

  Directly motivates Reforge's core mission: replace fixed collateral discounts with a **competitive batch auction** that minimizes borrower collateral loss while guaranteeing debt repayment.
</Callout>

***

## 2. Liquidation Mechanisms and Price Impacts in DeFi [#2-liquidation-mechanisms-and-price-impacts-in-defi]

<Callout type="info">
  **Citation:** Phoebe Tian, Yu Zhu. *Bank of Canada Staff Working Paper*, 2025.\
  [Read Paper (PDF)](https://www.bankofcanada.ca/wp-content/uploads/2025/03/swp2025-12.pdf)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr-1]

Comparing fixed-spread (Aave) vs. auction-based (MakerDAO) liquidations reveals that &#x2A;*competitive auctions reduce liquidation discounts and market price impact by over 70%**.

### Empirical Comparison: Aave vs. MakerDAO [#empirical-comparison-aave-vs-makerdao]

| Metric                            | Aave (Fixed Spread) | MakerDAO (Dutch Auction) | Reduction with Auctions             |
| :-------------------------------- | :------------------ | :----------------------- | :---------------------------------- |
| **Average Liquidation Discount**  | 5.0%                | **1.8%**                 | 🔻 **64% lower collateral penalty** |
| **Secondary Market Price Impact** | 0.054%              | **0.010%**               | 🔻 **81% lower market distortion**  |
| **Liquidator Participation**      | Lower diversity     | Higher competition       | 🟢 More robust liquidity            |

### Two Competing Economic Effects [#two-competing-economic-effects]

1. **Participation Effect**: Auctions attract more competing liquidators because profit opportunities are flexible, ensuring unhealthy loans are cleared even during market distress.
2. **Competition Effect**: Bidding competition pushes the clearance price closer to fair market value, meaning **less borrower collateral must be sold** to cover the same debt.

<Callout type="warn">
  ### Relevance to Reforge [#relevance-to-reforge-1]

  Serves as direct empirical validation for Reforge's thesis: auctions preserve borrower capital and reduce secondary AMM price slippage compared to static discount models.
</Callout>

***

## 3. Recent Advances: OEV and Gas-Sensitive Liquidations (2025–2026) [#3-recent-advances-oev-and-gas-sensitive-liquidations-20252026]

Recent studies in 2025 and 2026 explore the intersection of Oracle Extractable Value (OEV), transaction fees, and liquidation profitability:

* **Participation Costs**: Research indicates that when liquidator participation costs (gas, infrastructure) are high, auction efficiency can degrade unless the protocol explicitly optimizes for execution cost.
* **Fee-Sensitive Manipulation**: Models show that gas fees materially determine whether manipulation-based liquidations (oracle manipulation + frontrunning) are economically viable for attackers.

<Callout type="tip">
  ### Design Takeaway for Reforge [#design-takeaway-for-reforge]

  Reforge's scoring formula explicitly incorporates `Gas Cost` and `DEX Slippage Cost` into **Net Economic Value**, ensuring the auction remains resilient even under volatile gas regimes.
</Callout>

***

## Next Literature Deep-Dive [#next-literature-deep-dive]

<Cards>
  <Card title="2. MEV & Priority Gas Auctions" description="How mempool visibility and transaction-ordering races create systemic MEV waste." href="/docs/getting-started/literature-review/02-mev-foundations" />
</Cards>


# Fair Ordering & Protocol Security (/docs/getting-started/literature-review/fair-ordering-and-security)



This section synthesizes theoretical literature on Byzantine consensus ordering guarantees, formal taxonomies of front-running attacks, and frameworks differentiating smart contract technical security from economic game-theoretic security.

***

## 1. Order-Fairness for Byzantine Consensus [#1-order-fairness-for-byzantine-consensus]

<Callout type="info">
  **Citation:** Mahimna Kelkar, Fan Zhang, Steven Goldfeder, Ari Juels. *CRYPTO*, 2020.\
  [Read Paper (PDF)](https://eprint.iacr.org/2020/269.pdf)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr]

Standard Byzantine consensus protocols only guarantee **consistency** (agreement on history) and **liveness** (transactions eventually get included). They fail to guarantee **order-fairness**, allowing block leaders to manipulate transaction sequence at will.

### Key Contributions & The Aequitas Protocol [#key-contributions--the-aequitas-protocol]

* **Definition of Order-Fairness**: A consensus protocol is order-fair if, whenever a majority of honest nodes observe transaction $T\_1$ before $T\_2$, $T\_1$ is guaranteed to be scheduled before $T\_2$ in the final block sequence.
* **The Aequitas Family**: Introduces formal consensus constructions that prevent privileged latency actors and malicious leaders from extracting ordering rents.

<Callout type="warn">
  ### Relevance to Reforge [#relevance-to-reforge]

  Proves that simply making liquidations open to all network nodes is insufficient if the underlying execution layer allows arbitrary ordering manipulation. Reforge enforces fair economic clearing at the application layer.
</Callout>

***

## 2. SoK: Transparent Dishonesty — Front-Running Attacks on Blockchain [#2-sok-transparent-dishonesty--front-running-attacks-on-blockchain]

<Callout type="info">
  **Citation:** Shayan Eskandari, Seyedehmahsa Moosavi, Jeremy Clark. &#x2A;Financial Cryptography and Data Security (FC)*, 2019.\
  [Read Paper (PDF)](https://arxiv.org/pdf/1902.05164)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr-1]

Formalizes a taxonomy classifying blockchain front-running attacks into **Displacement, Insertion, and Suppression**, surveying foundational defenses.

<Mermaid
  chart="graph TD
    FR[Front-Running Attack Taxonomy] --> D[1. Displacement Attack]
    FR --> I[2. Insertion Attack]
    FR --> S[3. Suppression Attack]
    
    D --> D1[Attacker runs same action first to invalidate victim]
    I --> I1[Sandwich attacks before/after victim]
    S --> S1[Spamming network or delaying victim transaction]"
/>

* **Displacement in Liquidations**: The classic liquidation race is a pure displacement attack: the searcher copies the victim's liquidation parameters and pays a higher gas fee to execute first, causing all competitor transactions to revert and waste gas.

***

## 3. Systematization of Knowledge (SoK) on DeFi Security & Risks [#3-systematization-of-knowledge-sok-on-defi-security--risks]

### A. SoK: Decentralized Finance (Werner et al., 2021) [#a-sok-decentralized-finance-werner-et-al-2021]

[Read Paper (PDF)](https://arxiv.org/pdf/2101.08778)

* **Technical vs. Economic Security**: Smart contracts can have zero coding bugs (100% technical security) and yet suffer catastrophic failure due to **economic incentive vulnerabilities** and MEV extraction.
* **Cross-Layer Interactivity**: Analyzes how lending protocols, price oracles, and AMM DEXs interact, showing that liquidation events generate cross-protocol MEV cascades.

### B. SoK: DeFi Fundamentals, Taxonomy and Risks (Gogol et al., 2024) [#b-sok-defi-fundamentals-taxonomy-and-risks-gogol-et-al-2024]

[Read Paper (PDF)](https://arxiv.org/pdf/2404.11281)

* **Taxonomy of Lending Risk**: Maps protocol insolvency not just to smart contract exploits, but to market price volatility, external searcher bot incentives, and oracle update latency.
* **Liquidation Fragility**: Highlights that relying on uncoordinated third-party bots to liquidate debt creates severe fragility during high-volatility market crashes.

***

## Summary: How Literature Shaped Reforge [#summary-how-literature-shaped-reforge]

The collective body of academic literature points to three undeniable conclusions:

1. **Fixed liquidation discounts extract excessive value from borrowers** (Qin 2021, Tian 2025).
2. **First-come races in transparent mempools inevitably collapse into destructive MEV bidding wars** (Daian 2019, Qin 2022).
3. **PBS and MEV-Boost concentrate liquidation power among dominant block builders** (Pai 2023, Wang 2024).

<Callout type="tip">
  **Reforge's Response:** A protocol-native **MEV-Aware Batch Auction** that evaluates liquidations on **Net Economic Value**, restoring economic efficiency, borrower equity, and fair market competition.
</Callout>

***

## Continue to Reforge Solution [#continue-to-reforge-solution]

<Cards>
  <Card title="Our Solution: The MEV-Aware Batch Auction" description="Explore the full mechanism design and Net Economic Value scoring formula." href="/docs/getting-started/our-solution" />
</Cards>


# Literature Review (/docs/getting-started/literature-review)



The design of Reforge builds upon extensive academic research across DeFi liquidation mechanics, Maximal Extractable Value (MEV), Proposer-Builder Separation (PBS), and consensus order-fairness.

Rather than treating liquidation as an isolated smart contract call, the literature demonstrates that liquidation is a multi-layered economic game played across mempools, block builders, and AMM secondary markets.

***

## Recommended Reading Pathway [#recommended-reading-pathway]

For researchers and engineers onboarding to the Reforge protocol, prioritize papers in this sequence:

<Mermaid
  chart="flowchart LR
    A[&#x22;1. DeFi Liquidations (Qin 2021)&#x22;] --> B[&#x22;2. Auction Impacts (Tian 2025)&#x22;]
    B --> C[&#x22;3. Flash Boys 2.0 (Daian 2019)&#x22;]
    C --> D[&#x22;4. Quantifying BEV (Qin 2022)&#x22;]
    D --> E[&#x22;5. Order-Fairness (Kelkar 2020)&#x22;]
    E --> F[&#x22;6. PBS & Private Flow (Wang 2024)&#x22;]"
/>

***

## Literature Categorization [#literature-categorization]

<Cards>
  <Card icon="<Scale />" title="DeFi Liquidations & Market Impact" description="Empirical analyses of Aave, MakerDAO, and Compound; fixed discounts vs. competitive auctions." href="/docs/getting-started/literature-review/01-defi-liquidations" />

  <Card icon="<Zap />" title="MEV & Priority Gas Auctions" description="Foundational works on transaction reordering, PGA bidding dynamics, and value quantification." href="/docs/getting-started/literature-review/02-mev-foundations" />

  <Card icon="<Boxes />" title="PBS, Private Order Flow & Latency" description="Builder monopolies, MEV-Boost integration advantages, and strategic timing delays." href="/docs/getting-started/literature-review/03-pbs-and-builder-markets" />

  <Card icon="<ShieldCheck />" title="Fair Ordering & Protocol Security" description="Byzantine consensus order-fairness (Aequitas), front-running taxonomy, and DeFi security SoKs." href="/docs/getting-started/literature-review/04-fair-ordering-and-security" />
</Cards>

***

## Research Synthesis Matrix [#research-synthesis-matrix]

| #      | Paper / Study                                                                                                   | Year | Key Finding                                                                         | Relevance to Reforge                                                          |
| :----- | :-------------------------------------------------------------------------------------------------------------- | :--- | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| **1**  | [Flash Boys 2.0](https://arxiv.org/abs/1904.05234)                                                              | 2019 | Priority Gas Auctions (PGAs) cause consensus instability and time-bandit risks.     | Proves that block positioning itself is a source of extractable profit.       |
| **2**  | [Empirical Study of DeFi Liquidations](https://discovery.ucl.ac.uk/id/eprint/10150722/)                         | 2021 | Fixed liquidation discounts cause borrowers to lose excess collateral.              | Establishes the necessity of value-based liquidation scoring.                 |
| **3**  | [Quantifying Blockchain Extractable Value](https://discovery.ucl.ac.uk/id/eprint/10182325/)                     | 2022 | $540M+ extracted via arbitrage, sandwiching, and liquidations.                      | Quantifies liquidations as major systemic MEV attack surfaces.                |
| **4**  | [Order-Fairness for Byzantine Consensus](https://eprint.iacr.org/2020/269.pdf)                                  | 2020 | Consistency and liveness do not prevent latency exploitation; introduces Aequitas.  | Theoretical backing for batch windows over latency races.                     |
| **5**  | [SoK: Decentralized Finance](https://arxiv.org/abs/2101.08778)                                                  | 2021 | Differentiates technical smart contract security from economic mechanism security.  | Framework for analyzing liquidation incentive mechanisms.                     |
| **6**  | [SoK: DeFi Fundamentals & Risks](https://arxiv.org/abs/2404.11281)                                              | 2024 | Taxonomizes lending risks across market volatility, oracles, and liquidators.       | Maps liquidation failure modes to external market structure.                  |
| **7**  | [Liquidation Mechanisms & Price Impacts](https://www.bankofcanada.ca/wp-content/uploads/2025/03/swp2025-12.pdf) | 2025 | Maker auctions reduced price impact (0.01% vs. 0.054%) and discounts (1.8% vs. 5%). | **Direct validation**: Competitive auctions dramatically cut collateral loss. |
| **8**  | [Integrated Builders in MEV-Boost](https://arxiv.org/abs/2311.09083)                                            | 2023 | Vertically integrated searcher-builders gain unfair 2nd-price auction advantages.   | Highlights why public mempool liquidations become centralized.                |
| **9**  | [Private Order Flows & Monopolies](https://arxiv.org/abs/2410.12352)                                            | 2024 | Top 3 block builders capture >95% of blocks through private order flow.             | Shows that exclusive builder deals distort open liquidation competition.      |
| **10** | [Artificial Latency in PBS](https://arxiv.org/abs/2312.09654)                                                   | 2023 | Validators strategically delay block proposals to capture 1.28% additional MEV.     | Demonstrates that timing manipulation affects liquidation capture.            |
| **11** | [SoK: Front-Running Attacks](https://arxiv.org/abs/1902.05164)                                                  | 2019 | Classifies attacks into displacement, insertion, and suppression.                   | Formal vocabulary for classifying liquidation frontrunning.                   |
| **12** | [Ethereum MEV Docs](https://ethereum.org/developers/docs/mev/)                                                  | —    | Official architectural specification of the MEV supply chain.                       | Standard terminology for searchers, builders, and gas golfing.                |
| **13** | Recent 2026 Studies                                                                                             | 2026 | Transaction fees and gas prices materially determine OEV manipulation viability.    | Informs Reforge's dynamic gas-aware scoring algorithm.                        |

***

## Deep-Dives by Topic [#deep-dives-by-topic]

Explore the full analysis for each thematic area:

<Cards>
  <Card icon="<Scale />" title="Read Section 1: DeFi Liquidations" href="/docs/getting-started/literature-review/01-defi-liquidations" />

  <Card icon="<Zap />" title="Read Section 2: MEV Foundations" href="/docs/getting-started/literature-review/02-mev-foundations" />
</Cards>


# MEV & Priority Gas Auctions (/docs/getting-started/literature-review/mev-foundations)



This section reviews the seminal literature establishing &#x2A;*Maximal Extractable Value (MEV)** as a fundamental property of transparent blockchain mempools and examining how Priority Gas Auctions (PGAs) distort transaction execution.

***

## 1. Flash Boys 2.0: Frontrunning, Transaction Reordering, and Consensus Instability [#1-flash-boys-20-frontrunning-transaction-reordering-and-consensus-instability]

<Callout type="info">
  **Citation:** Philip Daian, Steven Goldfeder, Tyler Kell, Tingwei Li, Yikai Zhao, Iddo Bentov, Lorenz Breidenbach, Ari Juels. &#x2A;IEEE Symposium on Security and Privacy (S\&P)*, 2019.\
  [Read Paper (PDF)](https://arxiv.org/pdf/1904.05234)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr]

Pending transactions in public mempools create arbitrage opportunities that automated bots exploit through &#x2A;*Priority Gas Auctions (PGAs)**. When extractable value is large enough, it threatens the **consensus security** of the blockchain itself.

### Key Insights & Findings [#key-insights--findings]

* **Priority Gas Auctions (PGAs)**: When multiple bots spot the same opportunity, they engage in continuous, high-frequency bidding wars—escalating gas prices in fractions of a second to win top block inclusion.
* **Block Positioning as Profit**: Proves that transaction ordering within a single block is not neutral; position itself carries substantial monetary value.
* **Time-Bandit Attacks**: Demonstrates that if MEV rewards exceed standard block subsidies, rational miners/validators are incentivized to **reorganize recent blocks** (forking history) to steal historical MEV opportunities.

<Callout type="warn">
  ### Relevance to Reforge [#relevance-to-reforge]

  Establishes that a liquidation transaction cannot be treated as a simple atomic action: **who gets included first and where it is ordered relative to competitors is an extractable rent**. Reforge removes this rent by settling liquidations in discrete batch rounds.
</Callout>

***

## 2. Quantifying Blockchain Extractable Value: How Dark is the Forest? [#2-quantifying-blockchain-extractable-value-how-dark-is-the-forest]

<Callout type="info">
  **Citation:** Kaihua Qin, Liyi Zhou, Arthur Gervais. *IEEE S\&P*, 2022.\
  [Read Paper (PDF)](https://discovery.ucl.ac.uk/id/eprint/10182325/1/2101.05511.pdf)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr-1]

Measures over **$540.54 million in extracted value** across 32 months of Ethereum mainnet data, proving that liquidations represent one of the three primary systemic MEV pillars alongside DEX arbitrage and sandwich attacks.

<Mermaid
  chart="pie title $540.5M Historical MEV Breakdown (Qin et al. 2022)
    &#x22;DEX Arbitrage&#x22; : 62
    &#x22;Liquidations&#x22; : 26
    &#x22;Sandwich Attacks&#x22; : 12"
/>

### Key Empirical Metrics [#key-empirical-metrics]

* **Total Extracted Profit**: $540.54M captured across 11,000+ unique searcher addresses.
* **Largest Single Extraction*&#x2A;: A single liquidation opportunity yielded **$4.1 million** in profit.
* **Generalized Frontrunning & Transaction Replay**: Shows that sophisticated searchers monitor mempools to replay, duplicate, and outbid victim transactions without understanding their internal business logic.

<Callout type="warn">
  ### Relevance to Reforge [#relevance-to-reforge-1]

  Provides empirical proof that liquidations are high-value systemic MEV targets. Bidding wars around liquidations are not edge cases—they represent hundreds of millions of dollars in extracted economic rent.
</Callout>

***

## 3. Ethereum Official MEV Documentation & Architecture [#3-ethereum-official-mev-documentation--architecture]

<Callout type="info">
  **Source:** Ethereum Foundation Developer Documentation.\
  [Read Official Docs](https://ethereum.org/developers/docs/mev/)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr-2]

The official architectural specification of the modern MEV supply chain, formalizing the roles of &#x2A;*Searchers, Block Builders, Relays, and Proposers (Validators)**.

### The Modern MEV Supply Chain [#the-modern-mev-supply-chain]

<Mermaid
  chart="graph LR
    S[Searchers / Liquidators] -->|Submit Bundles| B[Block Builders]
    B -->|Relay Best Blocks| R[MEV-Boost Relays]
    R -->|Propose Winning Block| V[Validators / Proposers]
    V -->|Commit to Chain| E[Ethereum Blockchain]"
/>

* **Searchers**: Run complex algorithms to spot arbitrage, liquidations, and transaction-ordering opportunities.
* **Gas Golfing**: Searchers optimize contract bytecode and storage layout down to single gas units to minimize overhead and outbid rivals.
* **Value Leakage**: Confirms that competitive searchers surrender the vast majority of their margins to block proposers via direct builder payments (coinbase transfers).

***

## Next Literature Deep-Dive [#next-literature-deep-dive]

<Cards>
  <Card title="3. PBS, Private Order Flow & Latency" description="How MEV-Boost, integrated builder monopolies, and timing games distort open competition." href="/docs/getting-started/literature-review/03-pbs-and-builder-markets" />
</Cards>


# PBS, Private Order Flow & Latency (/docs/getting-started/literature-review/pbs-and-builder-markets)



Following the introduction of Proposer-Builder Separation (PBS) via MEV-Boost, MEV competition shifted from the public mempool into specialized block-builder auctions. This section reviews literature examining how builder monopolies, private order flow, and latency games shape execution fairness.

***

## 1. Structural Advantages for Integrated Builders in MEV-Boost [#1-structural-advantages-for-integrated-builders-in-mev-boost]

<Callout type="info">
  **Citation:** Mallesh Pai, Max Resnick. *arXiv preprint*, 2023.\
  [Read Paper (PDF)](https://arxiv.org/pdf/2311.09083)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr]

Block builders vertically integrated with their own proprietary searcher operations enjoy **unfair latency and informational advantages**, turning what should be a fair open auction into an asymmetric game where independent liquidators face the "winner's curse".

### Key Insights [#key-insights]

* **Asymmetric Auction Dynamics**: Integrated searcher-builders can bid closer to block deadline because they face zero inter-entity network communication latency.
* **First-Price vs. Second-Price Asymmetry**: Independent searchers must submit fixed first-price bids to external builders, whereas integrated builders observe competitors' bundles in real time and bid just enough to win (effectively enjoying 2nd-price auction economics).
* **Winner's Curse**: Independent liquidators who bid too early risk market price movements making their liquidation unprofitable before block commitment.

<Callout type="warn">
  ### Relevance to Reforge [#relevance-to-reforge]

  Proves that simply relying on MEV-Boost / private builder relays does not solve unfair liquidation competition; it merely shifts the advantage to vertically integrated block builders. Reforge provides protocol-level batch clearing that neutralizes builder latency advantages.
</Callout>

***

## 2. Private Order Flows and Builder Bidding Dynamics [#2-private-order-flows-and-builder-bidding-dynamics]

<Callout type="info">
  **Citation:** Shuzheng Wang, Tarun Chitra, Ciamac Moallemi et al. *arXiv preprint*, 2024/2025.\
  [Read Paper (PDF)](https://arxiv.org/pdf/2410.12352)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr-1]

Private order flow (transactions bypassing the public mempool) accounts for **54.59% of total block value**. The resulting feedback loop enables the **top 3 block builders to capture over 95% of Ethereum blocks**, threatening open market competition.

<Mermaid
  chart="flowchart TD
    A[Exclusive Private Order Flow] --> B[Builder Constructs More Valuable Blocks]
    B --> C[Builder Wins >95% of MEV-Boost Auctions]
    C --> D[More Apps / Searchers Send Private Flow to Top Builder]
    D --> A"
/>

### Empirical Findings (Jan 2023 – May 2024) [#empirical-findings-jan-2023--may-2024]

* **Market Concentration**: The top 3 builders regularly construct >95% of all Ethereum mainnet blocks.
* **Mempool Exclusion**: When liquidations are sent via private order flow to dominant builders, independent liquidators monitoring the public mempool are completely shut out from competing.

***

## 3. The Cost of Artificial Latency in the PBS Context [#3-the-cost-of-artificial-latency-in-the-pbs-context]

<Callout type="info">
  **Citation:** Umberto Natale, Michael Moser. *arXiv preprint*, 2023.\
  [Read Paper (PDF)](https://arxiv.org/pdf/2312.09654)
</Callout>

### Core Takeaway (TL;DR) [#core-takeaway-tldr-2]

Validators can systematically increase their MEV revenue by **intentionally delaying block proposal deadlines**, waiting until the last possible millisecond for higher bids to arrive.

### Key Analysis [#key-analysis]

* **Strategic Slowness**: Winning bids become increasingly valuable closer to the slot cutoff. Validators delaying proposals by 500–1000ms capture an estimated median **1.28% increase in MEV rewards**.
* **Systemic Risk**: Strategic latency games increase the rate of missed slots, chain forks, and network-level instability.
* **Liquidation Impact**: Liquidators who can optimize millisecond-level network transit to late-proposing validators capture more liquidation volume.

***

## Next Literature Deep-Dive [#next-literature-deep-dive]

<Cards>
  <Card title="4. Fair Ordering & Protocol Security" description="Consensus-level order-fairness (Aequitas), front-running taxonomy, and DeFi security frameworks." href="/docs/getting-started/literature-review/04-fair-ordering-and-security" />
</Cards>


# Experiment Design (/docs/research/experiment-design)



## Scenarios [#scenarios]

TODO

## Parameters [#parameters]

TODO

## Baseline (Conventional PGA) [#baseline-conventional-pga]

TODO

## Treatment (MEV-Aware Batch Auction) [#treatment-mev-aware-batch-auction]

TODO

## Status [#status]

Draft


# Overview (/docs/research)



Does the reduction in MEV/gas competition outweigh the additional liquidation latency and associated risk?

Brief overview of the hypothesis and expected contribution.


# Methodology (/docs/research/methodology)



## Approach [#approach]

TODO

## Variables [#variables]

TODO

## Controls [#controls]

TODO

## Measurement [#measurement]

TODO

## Status [#status]

Draft


# Results (/docs/research/results)



> This page will be populated with experimental results as simulations are executed.

## Status [#status]

Pending


# Auction Engine (/docs/specs/backend/auction-engine)



Auction lifecycle coordination — opening, bid aggregation, winner selection, and settlement orchestration.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Block Listener (/docs/specs/backend/block-listener)



WebSocket-based blockchain event subscription, new block monitoring, and reconnection handling.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Opportunity Engine (/docs/specs/backend/opportunity-engine)



Continuous position scanning, health factor evaluation, and liquidation opportunity queueing via BullMQ.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Scoring Function (/docs/specs/backend/scoring-function)



Net Economic Value calculation - Gross Liquidation Value - Gas Cost - DEX/Slippage Cost.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Simulation Engine (/docs/specs/backend/simulation-engine)



Multi-bot orchestration, gas simulation, market volatility modeling, and comparative benchmarking.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# HealthFactor Library (/docs/specs/contracts/health-factor-lib)



Shared mathematical library for health factor calculations: HF = (Collateral × Threshold) / Debt.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# LendingPool (/docs/specs/contracts/lending-pool)



Core lending protocol — deposit, withdraw, borrow, repay, and position accounting.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# LiquidationAuction (/docs/specs/contracts/liquidation-auction)



MEV-aware batch auction mechanism — openAuction, submitBid, closeAuction, selectWinner, settleLiquidation.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# LiquidationManager (/docs/specs/contracts/liquidation-manager)



Position eligibility evaluation, debt ceilings, collateral transfer calculations, and incentive bonuses.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# MockDEX (/docs/specs/contracts/mock-dex)



AMM liquidity pool simulation with configurable slippage and price impact modeling.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# PriceOracle (/docs/specs/contracts/price-oracle)



Dual-mode price oracle supporting realistic feeds and programmatic price drops for simulations.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Liquidation Marketplace (/docs/specs/frontend/liquidation-marketplace)



Real-time liquidation opportunity explorer with position details, health factors, and estimated profits.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Liquidator Console (/docs/specs/frontend/liquidator-console)



Dedicated liquidator interface — wallet integration, bid submission, active auctions, P\&L tracking, and ROI.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Protocol Dashboard (/docs/specs/frontend/protocol-dashboard)



Global protocol metrics view — TVL, outstanding debt, active positions, liquidation stats, and recovery rates.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft


# Research Laboratory (/docs/specs/frontend/research-laboratory)



Experiment configuration, comparative benchmarking (Conventional vs. MEV-Aware), and result visualization.

## Purpose [#purpose]

TODO

## Interface [#interface]

> Define public API / function signatures / event schemas here
> TODO

## State & Data Model [#state--data-model]

TODO

## Behavior [#behavior]

> Step-by-step logic, state transitions, sequence diagrams
> TODO

## Invariants [#invariants]

> Things that must always be true
> TODO

## Edge Cases [#edge-cases]

TODO

## Acceptance Criteria [#acceptance-criteria]

TODO

## Status [#status]

Draft