ArchitectureOverview

Architecture Overview

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

  1. Market Isolation — Every borrower operates within their own cloned market contract, isolating risk and collateral.
  2. Order-Book Matching — Lender offers are filled lowest-APR-first from an on-chain order book, not a shared liquidity pool.
  3. Independent Interest Accrual — Each lender position accrues interest at its own quoted rate, never a blended average.
  4. Collateralized Security — A dedicated escrow contract per market with Chainlink-priced health monitoring and Dutch-auction liquidation.
  5. Reputation-Linked Risk — A protocol-wide reputation registry scores every borrower by actual repayment history.
  6. Position Tokenization — Lender positions are ERC-721 NFTs, transferable on secondary markets.
  7. Managed Withdrawals — An epoch-based liquidity queue governs lender exits to prevent bank runs.

Core Components

RevvFiArchController
├── Registers/removes approved borrowers
├── Approves/blacklists borrow & collateral assets and oracles
└── Tracks all deployed markets

RevvFiFactory
├── Clones a Market + CollateralEscrow + OfferBook + LiquidityQueue per deployMarket() call
├── Collects a one-time deployment fee
└── Wires each new market's contracts together

RevvFiMarket (one per borrower)
├── Holds each position's principal, APR, seniority, and last-accrual timestamp
├── Handles borrow / repay / repayFull / claimFunds
└── Coordinates with the OfferBook and CollateralEscrow

RevvFiOfferBook (one per market)
├── Stores lender offers bucketed by APR
├── Fills borrow requests lowest-APR-first
└── Supports partial fills, modification, and cancellation

RevvFiCollateralEscrow (one per market)
├── Holds the borrower's collateral
├── Reads price from a real Chainlink AggregatorV3Interface feed
└── Enforces min collateral ratio + liquidation threshold

RevvFiLiquidityQueue (one per market)
└── Epoch-based withdrawal processing for lenders exiting a position

RevvFiPositionNFT
└── ERC-721 representing a lender's claim (principal, APR, seniority, market)

RevvFiLiquidator
└── Runs the declining-price liquidation auction, shared across all markets

ReputationRegistry
└── Protocol-wide borrower reputation score (0–1000), derived from success rate

Key Architectural Decisions

1. Order-Book Matching, Not a Shared Pool

Unlike pool-based protocols (Aave, Compound), RevvFi does not blend every lender into one pool rate. Lenders submit offers with their own amount, APR, and seniority; borrowing fills the request starting from the lowest-APR active offers. Each lender then earns exactly the rate they quoted for the life of their position.

2. Isolated Markets Per Borrower

Each borrower gets their own cloned RevvFiMarket/RevvFiCollateralEscrow/RevvFiOfferBook/RevvFiLiquidityQueue set (EIP-1167 minimal proxies, deployed by the Factory). A default in one borrower’s market has zero effect on any other market’s lenders or collateral.

3. Per-Position Independent Interest Accrual

Every position stores its own principal, its own apr, and its own lastAccrualTime. Interest is computed per-position on demand (principal * apr * elapsedTime), rolled into principal on any repayment or loss event. There is no shared market-wide index — this was a deliberate correction after an earlier design (a single blended borrow index) was found to pay every lender in a market the same average rate regardless of what they individually quoted.

4. Chainlink Oracle Integration

Collateral value is priced via a real AggregatorV3Interface feed (latestRoundData()), with an owner/factory-configurable stalePriceThreshold per market (24 hours by default) rather than one hardcoded global value — real feeds have different heartbeats, and testnet feeds in particular can go far longer between updates than a mainnet ETH/USD feed.

5. Pull-Based Claims

When a borrower repays, the market credits each affected lender’s claimable balance — it does not push tokens to lenders automatically. Lenders call claimFunds(positionId) themselves. This keeps repayment a single, bounded-gas transaction regardless of how many lenders are in a market.

6. Dutch/English Hybrid Liquidation

Liquidation auctions start at 100% of debt and decay in steps toward an 80%-of-debt reserve floor, but — unlike a pure Dutch auction — bidders can still outbid each other before the auction ends, with a 15-minute anti-sniping extension on late bids.

7. Position Tokenization

Every position is minted as a RevvFiPositionNFT. Loan parameters are readable from the NFT/market state directly; ownership transfer moves the underlying claim.

Next Steps

HomeSmart Contracts