Smart Contracts Overview

Buttonwood V1 consists of two contract packages: Core (the protocol's fundamental logic) and Periphery (user-facing helpers and vaults).

Contract Properties

Contract	Upgradeable	Pausable	Permissions	Notes
OriginationPoolScheduler	Yes (UUPS)	Yes	Yes
OriginationPool	No	Yes	Yes	ERC20 receipt tokens
GeneralManager	Yes (UUPS)	Yes	Yes
LoanManager	No	No	No	Flash-swaps via Consol
MortgageNFT	No	No	No	ERC721
OrderPool	No	No	Yes
SubConsol	No	No	Yes	ERC20 (not rebasing)
USDX	No	No	Yes	Rebasing
Consol	No	No	Yes	Rebasing
ForfeitedAssetsPool	No	Yes	Yes	ERC20 (not rebasing)
ConversionQueue	No	No	Yes	LenderQueue + MortgageQueue
UsdxQueue	No	Yes	Yes	LenderQueue
ForfeitedAssetsQueue	No	Yes	Yes	LenderQueue
PythPriceOracle	No	No	No	Pyth pull-oracle
PythInterestRateOracle	No	No	No	Pyth pull-oracle

Core Contracts

Token Contracts

Contract	Description
USDX	Unified USD-pegged vault wrapping multiple stablecoins with configurable scaling factors into a standard 18-decimal rebasing token
Consol	The protocol's main rebasing treasury token — backed by USDX, ForfeitedAssetsPool, and SubConsol tokens. Provides flash swap functionality for efficient asset swapping. Withdrawal restricted to authorized queues.
SubConsol	Collateral-specific vault that accepts a single collateral type, mints tokens based on principal borrowed, and can deploy collateral to yield strategies for additional returns. Not rebasing.
RebasingERC20	Abstract shares-based ERC20 where balances adjust based on underlying asset value — enables passive yield accrual
MultiTokenVault	Abstract vault accepting multiple ERC20 deposits, minting a single rebasing token. Provides relative token caps and registry.

Lending & Borrowing

Contract	Description
GeneralManager	Central upgradeable orchestrator. Validates and routes mortgage requests through OriginationPools, coordinates oracles, manages collateral types and terms, handles balance sheet expansions.
LoanManager	Manages full mortgage lifecycle — creation (depositing collateral into SubConsols), payment processing with automatic late fees, redemption, refinancing, foreclosure, and conversions
MortgageNFT	ERC-721 representing ownership of a mortgage position. Manages user-chosen MortgageId labels.
OriginationPool	Non-upgradeable lending pool. Accepts USDX deposits (Deposit phase), flash-deploys for origination receiving Consol repayment (Deploy phase), allows proportional USDX+Consol redemption (Redemption phase). Withdrawals never affected by pause.
OriginationPoolScheduler	Creates new OriginationPools on a weekly schedule. Manages pool configurations including limits, growth rates, and multipliers.
OrderPool	Order book holding PurchaseOrders for collateral. Authorized fulfillers process orders by providing collateral in exchange for USDX, while expired orders are deleted and NFTs burned.

Queues & Processing

Contract	Description
ConversionQueue	Double-queue: lenders deposit Consol to get collateral with a premium; borrowers submit mortgages to be converted when prices trigger. Processes by liquidating portions of qualified mortgages at market prices with lump-sum interest rewarded to withdrawers.
UsdxQueue	FIFO withdrawal queue — users deposit Consol and receive USDX. Permissionless processing with gas fee collection.
ForfeitedAssetsQueue	FIFO withdrawal queue — users deposit Consol to burn ForfeitedAssetsPool tokens for underlying foreclosed collateral. Value received may exceed Consol deposited.
MortgageQueue	Sorted linked-list of mortgage positions ordered by trigger price (lowest to highest) for efficient conversion processing
LenderQueue	Abstract base for FIFO withdrawal queues with gas fees, minimum amounts, and cancellation logic
QueueProcessor	Processes items across the various queues

Oracles

Contract	Description
PythPriceOracle	Pull-oracle for real-time collateral/USD prices. Validates freshness (max 60s) and confidence thresholds.
PythInterestRateOracle	Reads 3yr and 5yr US Treasury rates from Pyth, multiplies by 2, adds 100 bps (+100 bps more if no payment plan). Reverts if age > 60s or confidence > 100 bps.
StaticInterestRateOracle	Fallback fixed interest rate oracle

Other

Contract	Description
ForfeitedAssetsPool	Holds collateral from foreclosed mortgages, issues liability tokens. Users burn Consol to redeem proportional foreclosed collateral at a discount, removing bad debt from the protocol.

Periphery Contracts

Contract	Description
Router	Entry point for all user transactions — handles multi-step flows (wrap, approve, deposit)
RolloverVault	Automated vault that re-invests lender capital across pool epochs
FulfillmentVault	Vault providing liquidity for order fulfillment on Hyperliquid
LiquidityVault	Abstract base for vault share token mechanics

Contract Interactions

                    ┌────────────────┐
                    │     Router     │  ◄── User entry point
                    └───────┬────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
    ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
    │GeneralManager│ │    USDX     │ │  Origination │
    │              │ │             │ │    Pool      │
    └──────┬───────┘ └──────┬──────┘ └──────┬───────┘
           │                │               │
           ▼                ▼               ▼
    ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
    │ LoanManager  │ │   Consol    │◄│  OrderPool   │
    └──────┬───────┘ └──────┬──────┘ └──────────────┘
           │                │
           ▼                ▼
    ┌──────────────┐ ┌──────────────┐  ┌─────────────┐
    │ MortgageNFT  │ │  SubConsol   │  │ UsdxQueue   │
    └──────────────┘ │  (escrow)    │  ├─────────────┤
                     └──────┬───────┘  │ForfeitedAsQ │
                            │          ├─────────────┤
                            ▼          │Conversion Q │
                     ┌──────────────┐  └─────────────┘
                     │  Conversion  │
                     │    Queue     │
                     └──────────────┘

Access Control

The protocol uses role-based access control across multiple contracts. See the Glossary — Roles section for a complete reference of all roles, their intended holders, and applicable contracts.

Key roles:

Default Admin (Governance) — Manage supported tokens, set caps, assign roles, upgrade contracts
Withdraw Role — Authorized contracts that can withdraw/flash-swap from Consol
Pause Role (Governance + automated safety) — Emergency pause of deposits, deployments, and operations
Fulfillment Role (Market maker) — Sell collateral to OrderPool and receive USDX
Deploy Role (GeneralManager) — Flash-loan USDX from OriginationPools

Key Interfaces

Interface	Purpose
IInterestRateOracle	Dynamic interest rates based on term length and payment structure
IPriceOracle	Real-time collateral pricing in USDX terms
IConsolFlashSwap	Flash swap callback for temporarily borrowing from Consol
IOriginationPoolDeployCallback	Callback for origination pool fund deployment (flash-lending)
IYieldStrategy	Yield-generating strategies for SubConsol collateral
INFTMetadataGenerator	Dynamic metadata generation for Mortgage NFTs

Deployment

All contracts are deployed on HyperEVM (Hyperliquid's EVM). The protocol uses deterministic deployment via Foundry scripts for reproducible addresses.

Contract Properties​

Core Contracts​

Token Contracts​

Lending & Borrowing​

Queues & Processing​

Oracles​

Other​

Periphery Contracts​

Contract Interactions​

Access Control​

Key Interfaces​

Deployment​