Architecture Overview

RevvFi’s V2 architecture is built on a resilient, multi-market peer-to-peer lending framework with the following core principles:

1. Market Isolation - Every borrower operates within an independent market, isolating risk and reputation.
2. Competitive Matching - A sophisticated matching engine that pairs borrow requests with the lowest APR offers.
3. Collateralized Security - Dedicated escrow contracts with real-time health monitoring and automated liquidations.
4. Reputation-Linked Risk - On-chain reputation scores that evolve based on repayment history.
5. Secondary Liquidity - Lender positions are tokenized as NFTs, enabling secondary market trading.
6. Managed Withdrawals - Epoch-based liquidity management to prevent bank runs.

Core Components

RevvFiLendingEngine
├── Market Factory (Deploys new borrower markets)
├── Reputation Registry (Global score tracking)
└── Oracle Hub (Chainlink price feed management)

LendingMarket (One per Borrower)
├── Manages borrow requests
├── Houses the Offer Book
├── Executes matching logic
└── Tracks active positions

CollateralEscrow
├── Securely holds collateral assets
├── Monitors Health Factor (HF)
└── Orchestrates Dutch Auction liquidations

LenderPosition (ERC721)
├── Tokenized debt position
├── Encodes: Principal, APR, Seniority, Maturity
└── Facilitates ownership transfer

Key Architectural Decisions

1. The P2P Matching Engine

Unlike pool-based protocols like Aave or Compound where users borrow from a communal reservoir, RevvFi utilizes a Peer-to-Peer Matching Engine.

• Offer Side: Lenders submit “Offers” specifying amount, minimum/maximum APR, and preferred seniority.
• Request Side: Borrowers submit “Requests” for specific capital amounts.
• Matching: The protocol sorts compatible offers by APR (lowest first) and Seniority to satisfy the request.

This ensures borrowers always get the most competitive market rate while lenders compete for yield.

2. Isolated Market Risks

In RevvFi, each borrower (or project) has their own LendingMarket.

• Risk Containment: A default in Market A does not impact LPs in Market B.
• Custom Parameters: Borrowers can configure their own liquidation thresholds, loan-to-value (LTV) ratios, and accepted collateral types.

3. Dynamic Reputation System

The architecture includes a global ReputationRegistry that tracks every borrower’s performance across the entire protocol.

• Score Range: 0 to 1000 (starting at 500).
• Invariants: Scores are updated settlement-by-settlement, providing a real-time risk signal to prospective lenders.
• Benefit: Higher scores attract lower APR offers and higher LTV limits.

4. Dutch Auction Liquidations

To ensure efficient collateral recovery during market volatility, RevvFi uses a Dutch Auction mechanism rather than single-price liquidations.

• Efficiency: Prices drop gradually until a buyer is found, preventing “death spirals.”
• Recovery Guarantee: A reserve price (80% of debt) ensures that at least a significant portion of lender principal is prioritized.

5. Position Tokenization

Every active loan is represented by a LenderPosition NFT.

• Transferability: Lenders can sell their debt positions on secondary markets if they need immediate liquidity.
• Metadata: All loan parameters (accrual status, principal, interest) are readable directly from the NFT’s state or associated market.

Architecture Diagram

User Flow:
┌─────────────┐
│   Creator   │ ──┐
└─────────────┘   │
                  ├──> RevvFiFactory ──> Deploys per-launch contracts
┌─────────────┐   │         │
│ Liquidity   │ ──┤         ├──> TokenTemplateFactory ──> ERC20 Token
│  Providers  │   │         │
└─────────────┘   │         ├──> CreatorVestingVault
                  ├──> RevvFiBootstrapper ──┬──> TreasuryVault
                  │         │               ├──> StrategicReserveVault
                  └──────────┤               ├──> RewardsDistributor
                              └──> Uniswap V2 Pair (REVV/WETH)

Contract Lifecycle

Phase 1: Creation

• Creator calls RevvFiFactory.createLaunch()
• 0.1 ETH launch fee required
• New bootstrapper + vaults deployed
• Token minted to bootstrapper

Phase 2: Deposit Window

• LPs deposit ETH into RevvFiBootstrapper
• Shares minted 1:1 with ETH
• Deposits tracked until raiseEndTime
• Hard cap enforced if set

Phase 3: Launch

• Anyone calls launch() when target reached
• Liquidity added to Uniswap V2
• Creator/Treasury/Reserve/Rewards tokens transferred
• Lock period begins: maturityTime = raiseEndTime + lockDuration

Phase 4: Withdrawal

• After maturityTime, LPs can:
  • withdrawAsAssets: Receive ETH + tokens
  • withdrawAsETH: Swap tokens for ETH first

Phase 5: Governance

• LPs vote on treasury/strategic releases
• Proposals use share balance = voting power
• Thresholds: Treasury (60%), Strategic (66%), Emergency (80%)

Deployment Targets

Next Steps

• Read Architectural Decisions for deep dives
• Explore Smart Contracts for full specifications
• Review Data Structures for storage patterns
• Check Deployment for network config