Conversion Mechanism

The conversion mechanism is the core innovation of Buttonwood's convertible credit system. It allows mortgages to automatically resolve when collateral appreciates — borrowers capture upside while lenders receive guaranteed returns.

How Conversion Works

Trigger Price Calculation

Each convertible mortgage has a Conversion Trigger Price — the collateral price at which auto-conversion activates:

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

The conversion premium is a protocol-configured percentage that ensures lenders receive a return above the principal.

Example

Parameter	Value
HYPE deposited	100 HYPE
HYPE price at deposit	$25
Amount borrowed	$1,250 (50 HYPE equivalent)
Total collateral locked	~200 HYPE
Conversion premium	50%
Trigger price	$37.50

If HYPE reaches $37.50:

• The debt portion of collateral (valued at the remaining debt) is transferred to the protocol/lenders
• The borrower keeps the remaining collateral (~64 HYPE after accounting for interest)
• At $37.50 per HYPE, the borrower's ~64 HYPE is worth ~$2,400 — nearly the same as their original $2,500 but with zero remaining debt

ConversionQueue Contract

The ConversionQueue is a double-queue — it inherits from both LenderQueue (FIFO withdrawal queue) and MortgageQueue (price-sorted linked list). It manages two sides:

1. Lender side: Lenders deposit Consol and wait to receive collateral with a premium
2. Borrower side: Borrowers submit mortgage positions and wait to be converted when prices trigger

Enrollment

• Coin Compounding positions are automatically enrolled — a conversionQueue address is required when requesting a compounding mortgage
• BNPL positions can optionally enable conversion via the UI toggle, or the borrower can later call generalManager.enqueueMortgage(tokenId, conversionQueue, hintPrevId)
• The borrower must be the owner of the mortgage
• A valid hintPrevId must be provided to reduce gas costs (the hint should be as close as possible to the proper sorted index)
• Both GeneralManager and ConversionQueue must not be paused

Processing

When the Pyth oracle reports a HYPE price at or above a position's trigger price:

1. A permissionless actor calls conversionQueue.processWithdrawalRequests(numberOfRequests)
2. The ConversionQueue matches lender withdrawal requests (FIFO) against eligible mortgage positions
3. For each matched conversion:
   • Portions of qualified mortgages are liquidated at market prices
   • Lump-sum interest payments are rewarded to the withdrawing lenders
   • SubConsol burns collateral tokens and releases underlying collateral
   • Remaining collateral is returned to the borrower
   • LoanManager updates the mortgage status via the Conversion Role
4. The processor collects gas fees for each processed request

Queue Ordering

The borrower side uses a sorted linked-list (via MortgageQueue) maintaining positions ordered by trigger price, lowest to highest. When HYPE reaches a certain price, all positions with trigger prices at or below that level are eligible for conversion. The processor works through them sequentially, matching against the FIFO lender queue.

Conversion Premium

The conversion premium is a key parameter that balances borrower and lender incentives:

• Higher premium = higher trigger price = less likely to convert, but more profit for lenders if it does
• Lower premium = lower trigger price = more likely to convert, but smaller lender premium

The premium is set at the protocol level and applies to all new mortgages.

Collateral After Conversion

The amount of collateral a borrower keeps after conversion depends on:

1. Total collateral locked (deposit + borrowed amount)
2. Interest accrued over the loan term
3. Remaining debt at the time of conversion

collateralKept = totalCollateral - (remainingDebt / triggerPrice)

Since conversion can happen at any point during the loan term, earlier conversions (before much interest accrues) result in more collateral returned to the borrower.

Integration with Other Components

PythPriceOracle
      │
      │ price update
      ▼
QueueProcessor (off-chain keeper)
      │
      │ identifies eligible positions
      ▼
ConversionQueue
      │
      ├──► SubConsol ──► release collateral
      │
      ├──► UsdxQueue ──► lender payments
      │
      └──► LoanManager ──► update mortgage status

The conversion mechanism relies on:

• PythPriceOracle for accurate, low-latency price feeds
• QueueProcessor (off-chain keeper) for monitoring and triggering conversions
• SubConsol for collateral custody and release
• LoanManager for mortgage state management
• UsdxQueue for routing converted collateral to lenders