MUSD Development Guide

Complete guide for developing with MUSD, the Bitcoin-backed stablecoin on Mezo, covering architecture, core concepts, and contract integration

MUSD is a Bitcoin-backed stablecoin that provides a stable value store while maintaining Bitcoin’s security and decentralization. This guide covers the core architecture of MUSD and how to integrate with its smart contracts.

MUSD is a collateralized debt position (CDP) based on Threshold USD, which is a fork of Liquity.

Architectural Overview

The protocol allows Bitcoin holders to mint MUSD by using their BTC as collateral. This means users can access USD-denominated liquidity while keeping their Bitcoin investment intact. The primary components are how the system handles custody, maintains the price peg, and earns fees.

Custody

A user opens up a position by calling BorrowerOperations.openTrove, providing BTC, and requesting MUSD. The BTC is routed to the ActivePool, where it stays until a user either:

• Withdraws (via BorrowerOperations.withdrawColl)
• Pays off their debt (via BorrowerOperations.closeTrove)
• Is redeemed against (via TroveManager.redeemCollateral)
• Gets liquidated (via TroveManager.liquidate)

Liquidated positions are either paid for by the StabilityPool, in which case the BTC is transferred there, or the debt and collateral are absorbed and redistributed to other users, in which case the BTC is transferred to the DefaultPool.

Maintaining the Peg

Price Floor ($1)

We maintain the price floor of $1 through arbitrage, an external USD ↔ BTC price oracle, and the ability to redeem MUSD for BTC at a 1:1 rate (via TroveManager.redeemCollateral).

Example arbitrage scenario:

Imagine that MUSD was trading for $0.80 on an exchange and that bitcoin is selling for 1 BTC =$100k. An arbitrageur with $800 could:

1. Buy MUSD

   Trade $800 for 1000 MUSD.

2. Redeem for BTC

   Redeem 1000 MUSD for 0.01 BTC ($1000 worth of BTC).

3. Sell BTC

   Sell 0.01 BTC for $1000.

The arbitrageur profits $200 (ignoring fees). This trade **buys** MUSD and **burns** it, causing upward price pressure until the price resets to$1.

Price Ceiling ($1.10)

We maintain a price ceiling of $1.10 via the minimum 110% collateralization ratio.

Example arbitrage scenario:

Imagine that MUSD is trading for $1.20 on an exchange, and that bitcoin is selling for 1 BTC =$100k. An arbitrageur with $100k could:

1. Buy BTC

   Buy 1 BTC (worth $100k).

2. Open Trove

   Open a trove with 1 BTC as collateral and borrow the maximum 90,909 MUSD.

3. Sell MUSD

   Sell 90,909 MUSD for $109,091.

The arbitrageur profits $9,091 (ignoring fees). This trade **sells** and **mints** MUSD, causing downward price pressure until the price reaches$1.10.

Fees

The protocol collects fees in four places:

Borrowing Rate · percentage · default: "0.1%"

Governable fee added as debt to a trove but minted to governance.

Redemption Rate · percentage · default: "0.75%"

Governable fee taken whenever a user redeems MUSD for BTC.

Refinancing Rate · percentage

Operates like the borrowing rate when refinancing a trove.

Interest Rate · percentage

Simple, fixed interest on the principal of the loan.

Core Ideas

Protocol Bootstrap Loan & Stability Pool

Unlike protocols that incentivize stability pool deposits with token rewards, MUSD’s Stability Pool is initially populated with a bootstrapping loan. This MUSD can only be used for liquidations.

When the protocol’s MUSD is used in a liquidation, it is first used to repay any outstanding protocol loan balance, ensuring the bootstrap loan cannot be withdrawn. Repayments on this loan are anticipated to be made weekly.

Protocol Controlled Value (PCV)

Over time, as the protocol accrues interest and fees, the bootstrap loan gets repaid, and the portion of the MUSD in the Stability Pool that is Protocol Controlled Value increases. The PCV contract manages the distribution of accrued MUSD from interest and fees, with the split between loan repayment and a fee recipient being governable.

Immutability and Upgradability

MUSD smart contracts are upgradable to allow for fixes. Substantial changes would require deploying a new set of contracts and having users opt-in to migrate, ensuring user control. Once battle-tested, the contracts will be made immutable.

Repository Structure

The MUSD repository contains:

• Smart Contracts: Core MUSD protocol contracts
• Integration Examples: Sample implementations
• Testing Suite: Comprehensive test coverage
• Documentation: Technical specifications

Development Setup

Prerequisites

• Node.js 18+ (check .nvmrc for exact version)
• pnpm package manager
• Foundry for smart contract development
• Git

Installation

1. Clone Repository

   git clone https://github.com/mezo-org/musd.git
   cd musd
   
2. Install Dependencies

   pnpm install
   
3. Configure Environment

   cp .env.example .env
   # Edit .env with your configuration
   

System Overview

The MUSD system consists of four main contract groups:

• Core Protocol: Handles main operations like opening/closing positions and managing collateral
• Asset Pools: Manages the system’s various collateral and liquidity pools
• Supporting Contracts: Provides services like price feeds, remote trove management, and PCV

Integration Guide

Opening a Trove

For optimal gas efficiency, provide hints for the trove’s insertion position in the sorted list.

TypeScript

async function openTroveWithHints(
  contracts: {
    borrowerOperations: Contract,
    troveManager: Contract,
    sortedTroves: Contract,
    hintHelpers: Contract
  },
  wallet: Wallet,
  debtAmount: bigint,
  assetAmount: bigint
) {
  // Compute expected total debt by adding gas compensation and fee
  const gasCompensation = await contracts.troveManager.MUSD_GAS_COMPENSATION();
  const expectedFee = 
    await contracts.borrowerOperations.getBorrowingFee(debtAmount);
  const expectedTotalDebt = debtAmount + expectedFee + gasCompensation;

  const nicr = (assetAmount * BigInt(1e20)) / expectedTotalDebt;

  const { '0': approxHint } = await contracts.hintHelpers.getApproxHint(nicr, 15, 42);

  const { '0': upperHint, '1': lowerHint } =
    await contracts.sortedTroves.findInsertPosition(nicr, approxHint, approxHint);

  await contracts.borrowerOperations
    .connect(wallet)
    .openTrove(debtAmount, upperHint, lowerHint, { value: assetAmount });
}

Adjusting and Closing Troves

You can similarly adjust (adjustTrove) or close (closeTrove) troves. Convenience functions are also available for withdrawing/repaying MUSD and adding/withdrawing collateral.

For complete examples, see the demo test file.

Liquidations

When a trove’s collateralization ratio falls below 110%, it can be liquidated by anyone. The liquidator is rewarded with a gas compensation and a percentage of the trove’s collateral.

Liquidation Flows

1. With Stability Pool: The Stability Pool’s MUSD is burned to cover the debt, and it seizes the collateral.
2. Partial Stability Pool: If the pool is insufficient, it covers what it can, and the remaining debt/collateral is redistributed to other active troves.
3. Empty Stability Pool: All debt and collateral are redistributed to other active troves.

Executing a Liquidation

Single Liquidation

async function liquidateTrove(
  troveManager: Contract,
  wallet: Wallet,
  borrowerAddress: string
) {
  await troveManager.connect(wallet).liquidate(borrowerAddress);
}

Redemptions

Any MUSD holder can redeem their tokens for an equivalent value of BTC, which helps maintain the $1 peg. The system redeems against the trove with the lowest collateral ratio.

For step-by-step instructions and code, see the dedicated guide:

• MUSD Redemptions

Borrower Risks

Be aware of these risks when using MUSD:

• Liquidation Risk: Your collateral can be liquidated if its value falls below 110% of your debt.
• Redemption Risk: Your collateral can be redeemed to maintain the peg, causing a taxable event and loss of upside exposure.
• Bad Debt: In extreme cases, bad debt could be socialized across other borrowers.

Testing

# Run all tests
pnpm test

# Run with gas reporting
pnpm test:gas

# Run with coverage
pnpm coverage

Key Changes from THUSD

• Fixed-Interest Borrowing: Interest rates are fixed when a trove is opened and can be refinanced.
• Protocol Controlled Value (PCV): Manages fees for loan repayment and other system needs.
• EIP-712 Signature Verification: Allows for gasless transaction authorizations.
• No Special Recovery Mode Liquidations: Liquidations follow a single process.

Definitions

Trove · concept

A collateralized debt position (CDP).

ICR · metric

Individual Collateralization Ratio of a single trove.

TCR · metric

Total Collateralization Ratio of the entire system.

Recovery Mode · state

Activated if TCR falls below 150%, enforcing stricter borrowing rules.

Additional Resources

• MUSD Main README - Comprehensive architectural overview
• Demo Test Suite - Working code examples
• MUSD User Guide - End-user documentation