Skip to main content

Protocol Overview

Buttonwood V1 is a decentralized convertible credit protocol deployed on HyperEVM (the EVM-compatible layer of Hyperliquid). It enables collateralized lending with a unique conversion mechanism that aligns incentives between borrowers and lenders.

Core Concept​

Traditional DeFi lending forces borrowers to choose: either hold an appreciating asset or access liquidity. Buttonwood eliminates this trade-off with convertible credit — mortgages that can automatically convert if the collateral appreciates, letting borrowers capture upside while guaranteeing lender returns.

Three User Flows​

1. Buy Now Pay Later (BNPL)​

Users purchase HYPE with a stablecoin down payment and finance the remainder through origination pools. A Mortgage NFT is minted representing the position, with the purchased HYPE locked as collateral.

2. Coin Compounding​

Users deposit existing HYPE to borrow more HYPE on credit (~2x leverage). The position is automatically enrolled in the Conversion Queue, so if HYPE appreciates the debt is forgiven in exchange for a portion of the collateral.

3. Lending​

Lenders deposit stablecoins into pools that fund borrower mortgages. They earn yield through Consol tokens and can participate via direct pool deposits, automated rollover vaults, or fulfillment vaults.

Architecture Diagram​

┌─────────────┐     ┌──────────┐     ┌──────────────────┐
│   Borrower  │────►│  Router  │────►│ Origination Pools│
│  (BNPL /    │     │          │     │  (Lender Capital)│
│  Compound)  │     └────┬─────┘     └────────┬─────────┘
└─────────────┘          │                    │
                         ▼                    ▼
                  ┌─────────────┐    ┌────────────────┐
                  │ LoanManager │    │  Consol Token   │
                  │ (Mortgage   │    │  (Yield-bearing │
                  │  NFTs)      │    │   rebasing)     │
                  └──────┬──────┘    └────────┬────────┘
                         │                    │
                         ▼                    ▼
                  ┌─────────────┐    ┌────────────────┐
                  │  SubConsol  │    │     USDX       │
                  │  (Escrow)   │    │ (Multi-token   │
                  │             │    │  stablecoin)   │
                  └──────┬──────┘    └────────────────┘
                         │
                         ▼
                  ┌──────────────┐
                  │  Conversion  │
                  │    Queue     │
                  └──────────────┘

Price Oracles​

The protocol uses Pyth Network pull-oracles for:

  • Collateral pricing — PythPriceOracle reads real-time collateral/USD prices, validates freshness (max 60 seconds old) and confidence thresholds
  • Interest rates — PythInterestRateOracle reads 3-year and 5-year US Treasury rates, multiplies by 2, and adds 100 bps. An additional 100 bps is added for mortgages without a payment plan. Reverts if the price age exceeds 60 seconds or confidence exceeds 100 bps. A StaticInterestRateOracle serves as a fallback.

Order Fulfillment​

When a borrower submits a BNPL or Compounding order:

  1. Borrower calls generalManager.requestMortgageCreation(creationRequest) (via the Router)
  2. A Mortgage NFT is minted with the requested MortgageId
  3. A PurchaseOrder is enqueued in the OrderPool with the collateral amount and purchase price
  4. An authorized fulfiller monitors the OrderPool and calls orderPool.processOrders(indices, hintPrevIds)
  5. For each order, the fulfiller swaps collateral for the USDX purchase amount
  6. The OriginationPool flash-deploys USDX and receives Consol as repayment (via IOriginationPoolDeployCallback)
  7. Collateral is deposited into SubConsol, and the mortgage is created in LoanManager
  8. If a ConversionQueue was specified, the mortgage is automatically enqueued

BNPL specifics: The borrower provides USDX for half the collateral purchase; the other half is borrowed from the OriginationPool. Pool fees are added on top.

Compounding specifics: The borrower provides half the collateral directly (not USDX). The other half is purchased with USDX borrowed from the OriginationPool. Pool fees are factored into the borrowed amount.

Orders have a 5-minute expiration window. Expired orders are deleted and NFTs burned, freeing the MortgageId for reuse. The fulfiller collects a gas fee for each processed order.

Key Design Decisions​

  • Simple interest — Loans use simple (not compound) interest: totalDebt = principal * (1 + APR * years)
  • Fixed 36-period terms — All mortgages have a maximum of 36 monthly periods (30 days each)
  • Multi-stablecoin support — Users can pay in USDT0, USDC, or USDH; the Router auto-wraps to USDX
  • NFT-based positions — Each mortgage is an ERC-721 token, making positions transferable
  • Rebasing yield — Consol is a rebasing ERC20 that automatically accrues yield for lenders
  • Non-upgradeable core — OriginationPool, LoanManager, and token contracts are immutable to minimize smart contract risk. Only GeneralManager and OriginationPoolScheduler are UUPS-upgradeable.
  • Permissionless queue processing — Anyone can call processWithdrawalRequests() on the queues and collect gas fees as incentive
  • Flash-deploy origination — OriginationPools flash-lend USDX and receive Consol repayment in a single transaction via callbacks