User Guide

This guide explains what the protocol does and walks through every user flow step by step.

Overview

Buttonwood V1 is a decentralized lending and borrowing platform for tokenized equities. It lets you borrow stablecoins against equity-token collateral through mortgage-like instruments, with a unique convertible credit mechanism that lets borrowers retain upside exposure.

The protocol is chain-agnostic: it runs on any EVM chain where supported collateral and a price feed exist. Support for Robinhood Chain and its tokenized equities is forthcoming.

Three Ways to Use Buttonwood

Buy Now Pay Later

Purchase equity tokens by making a down payment in stablecoins and financing the rest. The protocol lends you the difference through origination pools, and you repay monthly over 36 periods.

Get started with BNPL →

Coin Compounding

Use equity tokens you already own as your down payment to purchase more on credit. End up with roughly 2x the equity tokens you started with, all locked as collateral with automatic conversion if prices rise.

Get started with Compounding →

Lending

Deposit stablecoins into origination pools to fund borrowers and earn yield in Consol tokens. Choose from direct pool deposits, automated rollover vaults, or fulfillment vaults.

Get started with Lending →

How It Works

All borrowing produces a Mortgage NFT — a position that represents your loan, tracks your collateral, payment history, interest, and status. Loans are structured in monthly periods (30 days each, up to 36 months). The protocol uses oracle price feeds for real-time collateral pricing; which oracle backs a given deployment depends on the chain.

The protocol's key innovation is the Conversion Queue: if collateral appreciates past a trigger price, the system can automatically convert collateral to pay down debt — letting borrowers capture upside while lenders receive guaranteed returns.

Supported Collateral

Buttonwood extends convertible credit only against equity tokens whose underlying company exceeds $1 trillion of off-chain market capitalization. The proposed set for the Robinhood Chain launch, largest first:

Token	Company	Token	Company
NVDA	NVIDIA	TSM	Taiwan Semiconductor
AAPL	Apple	SPCX	SpaceX
GOOGL	Alphabet	META	Meta Platforms
MSFT	Microsoft	TSLA	Tesla
AMZN	Amazon	LLY	Eli Lilly
AVGO	Broadcom	MU	Micron Technology

The set is a launch proposal, not a commitment — the collateral actually enabled on a given deployment is governed on-chain per chain.

Tokens

Token	Role
Equity tokens	Collateral — tokenized shares in trillion-dollar companies
USDX	Protocol stablecoin — a vault wrapping supported USD stablecoins
Consol	Yield-bearing token earned by lenders
Mortgage NFT	ERC-721 representing each loan position

Quick Links

• Buy Now Pay Later, Coin Compounding, Lending — Step-by-step instructions for each user flow
• Architecture — How the protocol works under the hood
• Smart Contracts — Contract reference documentation
• Glossary — Key terms and definitions

Buy Now Pay Later

BNPL lets you purchase equity tokens by making a down payment in stablecoins and financing the rest. The protocol lends you the difference through its origination pools, and you repay it monthly over 36 periods — similar to a traditional installment purchase.

Step by Step

1. Navigate to /borrow and select the "Buy Now Pay Later" tab.

2. Enter your order. You have two input fields:

   • Buy — The amount of equity tokens you want to purchase. Enter this first and the down payment auto-calculates, or vice versa.
   • Down Payment — The stablecoin amount you pay upfront (in any supported stablecoin, or USDX). This is a fraction of the total purchase price; the protocol borrows the rest from lending pools on your behalf.

3. Review your Payment Plan. The UI shows three key numbers:

   • Total Payments — 36 monthly periods
   • Monthly Payment — Your fixed monthly obligation in USDX (calculated as totalDebt / 36)
   • Borrow APR — The annual interest rate on the borrowed amount (simple interest)

   The total debt is calculated using simple interest:

   totalDebt = borrowed * (1 + APR * years)

4. Optionally enable Conversion. Toggle "Enable Conversion" to allow automatic debt reduction if your equities appreciate past the Conversion Trigger Price. The trigger price is displayed next to the toggle. If the token reaches that price, the protocol can convert some of your collateral to pay down your loan automatically.

5. Set a Mortgage ID. Either type a custom identifier or click the generate button for a random one.

6. Submit. The button progresses through stages:

   • Connect — Connect your wallet via RainbowKit
   • Approve — Approve the Router contract to spend your stablecoin (includes a slippage buffer)
   • Request Mortgage — Submits the mortgage request on-chain

7. Wait for fulfillment. Orders take approximately 60 seconds to fill. If the order doesn't fill before the expiration window (default: 5 minutes), all funds are refunded. You cannot cancel during the fill window.

8. Your position is created. Once filled:

   • A Mortgage NFT is minted to your wallet
   • Equity-token collateral is locked in the SubConsol escrow contract
   • Your loan is now active — make monthly payments on the /manage page

How It Works Under the Hood

The protocol distributes your borrow across one or more Origination Pools (lender-funded pools). Each pool has a capacity limit and a multiplier that determines how much down payment is required relative to the borrowed amount. If one pool can't cover the full borrow, the system draws from the next pool until the order is filled.

Key Differences from Compounding

• You are buying an asset you don't yet own (with credit)
• You pay a down payment in stablecoins, not a deposit of the collateral itself
• Conversion is optional (off by default)
• A payment plan is always required (you must make monthly payments)

Coin Compounding

Coin Compounding lets you use equity tokens you already own as your down payment (instead of stablecoins) to purchase more on credit. It is functionally equivalent to BNPL with a flash loan — the protocol finances the rest, and you end up with roughly 2x the equity tokens you started with, all locked as collateral in a Mortgage NFT. Your collateral is automatically enrolled in the Conversion Queue. If the equity appreciates past a trigger price, the mortgage auto-converts — your debt is forgiven in exchange for a portion of the collateral, and you keep the rest.

Step by Step

1. Navigate to /borrow and select the "Coin Compounding" tab (this is the default tab).

2. Enter your deposit. Two input fields:

   • Deposit — The amount of equity tokens you want to deposit as collateral. Enter this first and the borrow amount auto-calculates, or vice versa.
   • Borrow — The token-equivalent amount the protocol will lend you (denominated in the collateral token for display, but borrowed as USDX internally).

3. Review Conversion Details. Two boxes are displayed:

   • Conversion Trigger Price — The token price at which auto-conversion activates:

     triggerPrice = (1 + conversionPremium%) * amountBorrowed * 2 / collateralAmount

     For example, if you deposit 100 equity tokens at $25 each and borrow $1,250 with a 50% conversion premium, the trigger price is $37.50.

   • Collateral After Conversion — How many tokens you keep if conversion triggers:

     remaining = deposit * (1 - APR * years)

     For example, 100 tokens at 12% APR over 3 years = ~64 tokens remaining.

   This is the core value proposition: you started with 100 tokens ($2,500) and ended up with ~200 tokens locked as collateral. After conversion you keep ~64 tokens (now worth $37.50+ each = $2,400+). You effectively doubled your exposure and captured the upside.

4. Optionally create a Payment Plan. Toggle on/off:

   • On (default): You make 36 equal monthly payments in USDX. The UI shows total payments, monthly payment amount, and APR.
   • Off: You owe a single bullet payment at the end of the full term. No monthly obligations, but the full debt (principal + interest) is due at maturity.

5. Set a Mortgage ID and submit (same Connect → Approve → Request Mortgage flow as BNPL).

6. Your position is created. All purchased equity tokens (your deposit + the financed amount) are locked as collateral in SubConsol, and the mortgage is automatically enrolled in the Conversion Queue.

What Happens Over Time

Scenario A — the token doesn't reach the trigger price

You make your monthly USDX payments (or the bullet payment at maturity). Once fully paid off, you redeem your Mortgage NFT on the /manage page and get all your equity tokens back.

Scenario B — the token reaches the trigger price

The Conversion Queue automatically processes your position. A portion of your collateral covers the remaining debt (goes to the protocol/lenders), and you keep the rest. Any remaining monthly payment obligations adjust accordingly. You end up with fewer equity tokens than the ~2x you had locked, but each is worth significantly more.

Key Differences from BNPL

• Your down payment is in equity tokens rather than stablecoins — equivalent to BNPL with a flash loan
• Both input fields are denominated in the collateral token, not stablecoins
• You end up with ~2x the equity tokens you started with, all locked as collateral
• Conversion is always enabled (automatic enrollment in the Conversion Queue)
• Payment plan is optional (you can choose a bullet payment instead)

Lending

Lending lets you deposit stablecoins into Origination Pools to fund borrowers and earn yield in the form of Consol tokens. There are three ways to participate, with increasing levels of automation.

Lending Pool (Direct Pool Deposit)

The simplest way to lend. You deposit into a specific origination pool for a fixed epoch.

Step by Step

1. Navigate to /lend. The "Lending Pool" tab is selected by default.

2. Browse available pools. The "Join Lending Pool" section shows pool cards, each displaying:

   • Pool name (e.g., "LP - 1")
   • Commission — The upfront fee percentage you earn when your capital is deployed to borrowers
   • Pool capacity — Current fill vs. limit (e.g., "500k / 1M")
   • Countdown — Time remaining before the pool moves to the Deploy phase

3. Click "Deposit" on a pool. A modal opens where you:

   • Enter the amount to deposit
   • Select your stablecoin (USDT0, USDC, or USDX)

4. Submit. The transaction flow:

   • Connect your wallet (if needed)
   • Approve the Router to spend your stablecoin
   • Deploy Origination Pool (first-time only — if the pool hasn't been initialized yet, this step deploys it on-chain)
   • Deposit — Your stablecoins are converted to USDX, then to Consol, and deposited into the pool. You receive Pool Tokens representing your share.

Pool Lifecycle

Each pool progresses through three phases:

Phase	What happens	Can deposit?	Can withdraw?
Deposit	Pool accumulates lender capital	Yes	No
Deploy	Capital is lent out to borrowers	No	No
Redemption	Loans mature, capital returns	No	Yes

5. Withdraw when the pool reaches Redemption. In the "Exit Lending Pool" section, your positions are listed. Once a pool enters Redemption phase, the "Withdraw" button becomes active. Clicking it burns your pool tokens and returns your proportional share of:
   • USDX — Your original capital plus returns
   • Consol — Yield earned from borrower interest and commissions

Rollover Vault (Automated Re-investment)

Instead of manually depositing into each new pool epoch, the Rollover Vault automates this for you. You stake once, and the vault continuously rolls your capital into the next available origination pool when the current one matures.

Step by Step

1. Select the "Rollover" tab on the /lend page. (This tab only appears if you have Rollover Vault access.)

2. Stake. Enter the amount and select your stablecoin. The transaction:

   • Approve the Router
   • Stake — Calls router.rolloverVaultDeposit(). Your stablecoins are deposited and you receive RLV tokens (Rollover Vault shares).

3. Monitor. The UI shows:

   • Your share of the Rollover Vault (as a percentage)
   • The vault's current holdings: USDX balance, Consol balance, and all origination pool tokens it holds

4. Unstake anytime. Enter the amount of RLV to redeem. The vault burns your RLV and returns your proportional share of all assets the vault holds (USDX, Consol, and any pool tokens).

The vault is managed by an automated Roller keeper service that handles the actual pool-to-pool transitions each epoch.

Fulfillment Vault (Order Fulfillment Liquidity)

The Fulfillment Vault provides liquidity specifically for the protocol to fill borrower purchase orders. It earns yield from order fulfillment fees.

Step by Step

1. Select the "Fulfillment" tab on the /lend page. (This tab only appears if you have Fulfillment Vault access.)

2. Stake. Same flow as Rollover — enter amount, select stablecoin, approve, and stake. You receive FLV tokens (Fulfillment Vault shares).

3. Monitor. The UI shows your vault share percentage and the vault's USDX and Consol balances.

4. Unstake anytime. Redeem FLV for your proportional share of USDX and Consol.

The Fulfillment Vault is simpler than the Rollover Vault — it holds only USDX and Consol (no pool tokens), and its capital is used by the automated trading bots to fill purchase orders on the chain's trading venue.

Position Management

After borrowing, visit the /manage page to manage your Mortgage NFT positions.

Available Actions

• View positions — See all your Mortgage NFTs with collateral amounts, payment status, interest rates, and maturity dates
• Make payments — Pay your monthly USDX obligation (or penalties if late)
• Refinance — Adjust your interest rate and term (requires no missed payments or outstanding penalties)
• Transfer — Send your Mortgage NFT to another wallet
• Redeem — Once fully paid, burn the NFT and reclaim your collateral
• Convert — Manually trigger conversion if eligible
• Wrap/Unwrap — Convert between USDX and underlying stablecoins

Penalties and Foreclosure

• Payments are due every 30 days. A 3-day late window is allowed.
• Missing a payment accrues a penalty (percentage of the monthly amount).
• Missing more than 2 payments makes your position eligible for foreclosure — your collateral is seized and sent to the ForfeitedAssetsPool, and your Mortgage NFT is marked as foreclosed.

Position Lifecycle

Mortgage Created
    │
    ▼
Active (making payments)
    │
    ├──► Fully Paid ──► Redeemable ──► Redeemed (collateral returned)
    │
    ├──► Conversion Triggered ──► Converted (partial collateral returned)
    │
    └──► Missed 2+ Payments ──► Foreclosed (collateral seized)

Payment Schedule

Each mortgage has 36 monthly periods. Your monthly payment is:

monthlyPayment = totalDebt / 36

Where totalDebt = borrowed * (1 + APR * years).

Payments can be made in any supported stablecoin (USDT0, USDC) or directly in USDX. The Router handles conversion automatically.

Glossary

Tokens

Term	Meaning
Equity token	Collateral — an on-chain token tracking shares in a listed company. Buttonwood accepts only equity tokens whose underlying company exceeds $1 trillion of off-chain market capitalization. See Supported Collateral.
USDX	Protocol stablecoin — a multi-token vault that wraps any USD-pegged token into a common 18-decimal rebasing token. Backed by the stablecoins supported on the host chain.
Consol	The protocol's main rebasing treasury token. Backed by a portfolio of USDX, ForfeitedAssetsPool tokens, and SubConsol for each supported collateral. Appreciates from mortgage interest payments.
SubConsol	Collateral-specific vault that accepts a single collateral type and mints tokens based on principal borrowed. Manages collateral deposits/withdrawals and can deploy to yield strategies. Not rebasing.
Mortgage NFT	ERC-721 token representing ownership of a mortgage position in LoanManager. Carries a user-chosen MortgageId label.
Pool Tokens	Receipt tokens (1:1 ratio) received when depositing into an Origination Pool, burned on redemption for proportional USDX + Consol.
RLV	Rollover Vault share token — represents your stake in the automated lending vault
FLV	Fulfillment Vault share token — represents your stake in the order fulfillment vault

Core Contracts

Term	Meaning
GeneralManager	Upgradeable central orchestrator owned by governance. Controls penalty rates, refinance rates, insurance fund, oracles, pool scheduler, and loan manager. Routes mortgage creation requests through OriginationPools.
LoanManager	Creates new loans and manages the full mortgage lifecycle — payments, penalties, redemption, refinancing, foreclosure, and conversions.
OriginationPool	Non-upgradeable, disposable pools for originating loans. Issues receipt tokens. Progresses through Deposit → Deploy → Redemption phases. Withdrawals are never impacted by pause state.
OriginationPoolScheduler	Upgradeable contract owned by governance that creates new OriginationPools on a schedule (weekly epochs starting Friday 2am GMT).
OrderPool	Order book contract that holds PurchaseOrders for buying collateral and finalizes mortgage origination. Authorized fulfillers process orders by providing collateral in exchange for USDX.
Forfeited Assets Pool	Holds collateral seized from foreclosed mortgages and issues liability tokens. Users burn Consol to redeem proportional foreclosed collateral at a discount.
Router	Periphery contract that handles multi-step user transactions (approvals, wrapping, deposits)

Queues

Term	Meaning
Conversion Queue	Double-queue: lenders deposit Consol and wait to get collateral out with a premium; borrowers submit mortgages and wait to get converted. Processes conversions when collateral prices hit trigger thresholds.
USDX Queue	Withdrawal queue where users deposit Consol and wait to receive USDX out. Processed FIFO by permissionless actors who collect gas fees.
Forfeited Assets Queue	Withdrawal queue where users deposit Consol and wait to burn ForfeitedAssetsPool tokens for underlying foreclosed collateral. Value received may exceed Consol deposited.
Mortgage Queue	Sorted linked-list maintaining mortgage positions ordered by trigger price (lowest to highest) for efficient conversion processing.

Oracles

Term	Meaning
Pyth Price Oracle	Pull-oracle reading Pyth price feeds for real-time collateral/USD prices. Validates freshness (max 60s) and confidence thresholds.
Pyth Interest Rate Oracle	Pull-oracle reading 3-year and 5-year US Treasury rates from Pyth. Multiplies by 2, adds 100 bps. Additional 100 bps if no payment plan. Reverts if age > 60s or confidence > 100 bps.
Static Interest Rate Oracle	Fallback fixed interest rate oracle

Mortgage Terms

Term	Meaning
BNPL	Buy Now Pay Later — purchasing equity tokens with a stablecoin down payment and financing the rest. Borrower provides USDX for half the collateral; the other half is borrowed from an OriginationPool.
Coin Compounding	Using equity tokens you already hold as a down payment to purchase more on credit (~2x leverage). Borrower provides half the collateral directly; the other half is purchased with borrowed USDX.
Conversion Trigger Price	The collateral price at which auto-conversion activates for a position in the ConversionQueue
Conversion Premium	Percentage above the purchase price that collateral must appreciate before conversion occurs
Bullet Payment	Single lump-sum payment at maturity instead of monthly installments (mortgage with hasPaymentPlan = false)
Foreclosure	Seizure of all collateral after exceeding the maximum missed payments (3). Collateral transferred to ForfeitedAssetsPool.
Refinance	Recalculating interest on outstanding principal for a new duration. Charges a refinance fee. Requires no unpaid penalties.
Balance Sheet Expansion	Adding additional principal and collateral to an existing mortgage position

Protocol Constants

Constant	Value	Description
BPS	1000	Basis points in a whole, used for percentage/rate calculations
PERIOD_DURATION	30 days	Duration of one mortgage period
PERIODS_PER_YEAR	12	Number of periods per year
LATE_PAYMENT_WINDOW	3 days	Grace period after due date
MAXIMUM_MISSED_PAYMENTS	3	Missed payments before foreclosure eligibility
MINIMUM_AMOUNT_BORROWED	1 USDX	Minimum borrow amount (1e18 wei)
EPOCH_DURATION	1 week	Duration of origination pool deployment epoch
EPOCH_OFFSET	1 day + 2 hours	Guarantees epochs start Friday 2am GMT

Roles

Role	Intended Holders	Purpose
Default Admin	Governance	Manage supported tokens, set caps, assign roles, upgrade contracts
Withdraw Role	ConversionQueues, LoanManager, SubConsols, UsdxQueue, ForfeitedAssetsQueue	Withdraw/flash-swap from Consol
Pause Role	Governance + automated safety checks	Emergency pause of deposits, deployments, and mortgage operations
Depositor Role	LoanManager	Deposit foreclosed assets and update liabilities
Conversion Role	ConversionQueue(s)	Convert mortgage positions by reducing principal and collateral
NFT Role	LoanManager, OrderPool	Burn mortgage NFTs by tokenId
Fulfillment Role	Authorized market maker	Sell collateral to OrderPool and receive USDX
Deploy Role	GeneralManager	Flash-loan USDX from OriginationPools for repayment in Consol
Accounting Role	LoanManager, ConversionQueue	Mint/burn SubConsol tokens
Portfolio Role	Governance + automated safety	Deposit/withdraw collateral from SubConsol into YieldStrategies
Ignore Cap Role	Governance + Routers	Bypass relative cap restrictions on USDX and Consol
Supported Token Role	Governance	Add/remove input tokens backing Consol and USDX

Other

Term	Meaning
Epoch	A lending cycle (1 week) — pools progress through Deposit, Deploy, and Redemption phases
Yield Strategy	Escrow contract associated with a SubConsol that earns yield on collateral via staking. Supports async deposit/withdrawal.
Purchase Order	On-chain intent to purchase collateral for a mortgage at a specified price, with a 5-minute expiration window
Flash Swap	Temporary borrow of tokens from Consol, repaid in different supported tokens within the same transaction. Used during foreclosure to swap SubConsol for ForfeitedAssetsPool tokens.
NFT Metadata Generator	Upgradeable contract that generates art and metadata for Mortgage NFTs