⚡

HoloFi Protocol Architecture

V1 Smart Contracts

B2B Real-World Asset (RWA) TCG Physical Collateral Lending & Dutch Auction Protocol

Highlight Layer:
💡 Click any contract block to inspect functions, storage & invariants
🌐 Off-Chain Logistics & Oracle Pipeline External Inputs
🏢 Blink Vault Partner

Physical card custody, authentication, grading & cert hash attestation.

📈 FMV Valuation Engine

TCG market sales IQR filter + 90d VW-TWAP pricing submitted on-chain.

🏪 KYB Whitelisted Stores

Verified merchant wallets eligible for isolated credit vault operations.

RBAC

AccessControlManager

contracts/AccessControlManager.sol

Protocol-wide centralized Role-Based Access Control registry and merchant KYB whitelist status manager.

ADMIN_ROLE ORACLE_ROLE KYB_MANAGER_ROLE PAUSER_ROLE MINTER_ROLE LOCKER_ROLE
ERC-721 URIStorage

HoloFiVaultCard

Single global collection representing vaulted TCG cards. Supports collateral transfer locking (`isLocked`).

• mintCard() [MINTER]
• setCardLock() [LOCKER]
• burnCard() [Owner]
ORACLE EnumerableSet

HoloFiCardPriceFeed

Gas-optimized FMV price registry packed into 1 storage slot (128-bit USD + 128-bit timestamp).

• setPrice() [ORACLE]
• setBatchPrices()
• getPrice(cardTypeId)
POLICY ICardEligibility

GradeEligibilityPolicy

Modular pool collateral filter enforcing grading companies (PSA/BGS) & grade ranges (≥10, ≥9).

• registerCardType()
• isCardTypeEligible()
• parseGrade(gradeStr)
Core Credit Engine
ESCROW & CREDIT

HoloFiVaultLoanCore

IERC721Receiver • ReentrancyGuard

Manages isolated CollateralVault instances for stores. Handles NFT custody escrow, continuous per-second interest accrual, LTV validation, draw requests, and liquidation triggers.

Escrow
depositCollateral()
withdrawCollateral()
Credit
borrow()
repayAndWithdraw()
Accounting
accrueInterest()
getHealthFactor()
Liquidation
startLiquidation()
finalizeLiquidation()
FACTORY Multi-Asset

HoloFiLendingPoolFactory

Deploys and registers isolated ERC-4626 pools with customized risk parameters per asset.

• createPool(asset, name, symbol, ...)
• isValidPool(address) => bool
ERC-4626 pToken Shares

HoloFiLendingPool

Permissioned liquidity vault. Enforces non-transferable shares, 3-decimal inflation offset, and pool-level risk caps.

• drawLiquidity() [LoanCore]
• returnLiquidity() [Core/Auc]
• maxLtvBps / ltBps
• borrowRateBpsPerYear
AUCTION

HoloFiDutchAuction

48h Linear Decay • Surplus Waterfall

Automated liquidation engine triggered when $HF < 1.0$. Price decays linearly from 120% FMV to Reserve Price (Debt + Penalty). Supports liquidator settlement and Treasury backstop buyback.

1. startAuction()

Locks vault, fixes 120% start & reserve price.

2. settleAuction()

Liquidator pays clearing price; surplus goes to store.

3. treasuryBuyback()

Protocol backstop if expired after 48 hours.

Contract Inspector

Core

HoloFiVaultLoanCore

contracts/HoloFiVaultLoanCore.sol

Central collateral escrow and risk engine. Manages isolated merchant vaults, verifies KYB approvals, computes Health Factors, accrues continuous per-second interest, and coordinates asset draws from registered Lending Pools.

Key Storage & Mappings

mapping(uint256 => CollateralVault) public vaults;
mapping(uint256 => uint256) public nftVaultId;
uint256 public nextVaultId = 1;

Key Invariants & Security

  • Collateral card is locked in HoloFiVaultCard upon deposit.
  • Total Debt never exceeds getMaxBorrowCapacity().
  • Continuous Interest is accrued before any debt or collateral state mutation.
  • Reentrancy guarded via OpenZeppelin ReentrancyGuard.
OpenZeppelin Base: IERC721Receiver, ReentrancyGuard, Pausable
💡 Architecture Insight

HoloFi implements an isolated multi-vault architecture where each merchant creates their own vault bound to a specific lending pool asset, ensuring pool-level risk separation and transparent NFT collateral backing.