MUSD Redemptions

Step-by-step guide for redeeming MUSD tokens for BTC through smart contract integration

Redeeming lets you burn 1 MUSD to receive $1 in BTC (minus a 0.75% redemption fee and gas fees). The system redeems starting from the trove with the lowest collateral ratio above 110%.

If the amount of MUSD exceeds a single trove, it will continue to redeem in ascending order of collateralization ratio. Troves with collateralization ratios below 110% are eligible for liquidation, and cannot be redeemed against.

Prerequisites

Before you start, verify:

1. Check System Status

   Go to TroveManager → “Read as Proxy” → call getTCR() with current BTC price. Must show ≥ 1100000000000000000 (110%)

2. Verify MUSD Balance

   Check your balance on the MUSD token contract

3. Get BTC Price

   Go to PriceFeed → “Read as Proxy” → call fetchPrice()

4. Get Contract Addresses

   See contract addresses at the bottom for both Mainnet and Testnet

Redemption Methods

Option A: Quick & Simple (Higher Gas)

Use this if you want to redeem quickly without calculating hints.

1. Go to TroveManager Contract

   Open the TroveManager contract in your block explorer and click the “Write as Proxy” tab.

2. Find Function 11: redeemCollateral

   You’ll see 6 input fields. Fill them as follows:

_amount · uint256 · required

Your amount in wei (see conversion below)

_firstRedemptionHint · address · required

0x0000000000000000000000000000000000000000

_upperPartialRedemptionHint · address · required

Your wallet address

_lowerPartialRedemptionHint · address · required

Your wallet address

_partialRedemptionHintNICR · uint256 · required

1100000000000000000000

_maxIterations · uint256 · required

0

Converting MUSD to Wei

JavaScript

// Formula: Your amount × 1e18
const musdAmount = 100;
const weiAmount = musdAmount * 1e18;
// Result: 100000000000000000000

Option B: With Hints (Lower Gas)

Use this to save on gas costs by providing optimal hints.

1. Get Redemption Hints

   Go to HintHelpers → “Read as Proxy” → getRedemptionHints()

   Fill in:

   • _amount: Your amount in wei
   • _price: Current BTC price from PriceFeed
   • _maxIterations: 50

   Copy the returned values:

   • firstRedemptionHint
   • partialRedemptionHintNICR
2. Get Position Hints

   Go to SortedTroves → “Read as Proxy” → findInsertPosition()

   Fill in:

   • _NICR: Use the partialRedemptionHintNICR from Step 1
   • _prevId: Your wallet address
   • _nextId: Your wallet address

   Copy the returned values:

   • upperHint
   • lowerHint
3. Call redeemCollateral

   Go back to TroveManager → “Write as Proxy” → redeemCollateral

   • _amount: Your amount in wei
   • _firstRedemptionHint: from Step 1
   • _upperPartialRedemptionHint: upperHint from Step 2
   • _lowerPartialRedemptionHint: lowerHint from Step 2
   • _partialRedemptionHintNICR: from Step 1
   • _maxIterations: 50

Smart Contract Integration

TypeScript Example

With Hints

import { ethers } from 'ethers';

async function redeemMUSDWithHints(
  contracts: {
    troveManager: Contract,
    hintHelpers: Contract,
    sortedTroves: Contract,
    priceFeed: Contract
  },
  wallet: Wallet,
  musdAmount: bigint
) {
  // Get current BTC price
  const price = await contracts.priceFeed.fetchPrice();
  
  // Get redemption hints
  const { 
    firstRedemptionHint,
    partialRedemptionHintNICR 
  } = await contracts.hintHelpers.getRedemptionHints(
    musdAmount,
    price,
    50 // maxIterations
  );
  
  // Get position hints
  const { upperHint, lowerHint } = 
    await contracts.sortedTroves.findInsertPosition(
      partialRedemptionHintNICR,
      wallet.address,
      wallet.address
    );
  
  // Execute redemption
  const tx = await contracts.troveManager
    .connect(wallet)
    .redeemCollateral(
      musdAmount,
      firstRedemptionHint,
      upperHint,
      lowerHint,
      partialRedemptionHintNICR,
      50 // maxIterations
    );
  
  await tx.wait();
  return tx;
}

Calculation Example

Redeeming 100 MUSD:

1. Burn MUSD

   You burn: 100 MUSD

2. Calculate BTC

   Formula: (Your MUSD Amount ÷ BTC Price) × 0.9925 = BTC received

   Example: (100 ÷ 100000) × 0.9925 = 0.0009925 BTC

3. Receive BTC

   You receive: $99.25 worth of BTC (0.75% fee goes to protocol)

Common Issues

”Cannot redeem when TCR < MCR”

System TCR is below 110%. Wait until it recovers before attempting redemptions.

”Unable to redeem any amount”

This can happen for several reasons:

• No troves available with collateral ratio above 110%
• Hints are out of date (specifically the NICR hint)
• The redemption amount would leave the target trove with less than the minimum debt requirement of 1,800 MUSD
• Max iterations set too low for the redemption size

Transaction runs out of gas

Lower _maxIterations to 10 or split into smaller redemptions.

Transaction reverts unexpectedly

Get fresh hints and try again. Someone may have redeemed before you.

Received less than expected

Check the Redemption event in your transaction. Some MUSD may have been returned if the last trove would go below 1,800 MUSD minimum.

Best Practices

• Generate hints immediately before redeeming - They become stale if someone else redeems first
• Use Option A for small amounts (< $10,000) - The higher gas cost is negligible
• Use Option B for large amounts - Saves significant gas on big redemptions
• Set higher maxIterations for larger redemptions:
  • Small (< 10 troves): 10
  • Medium (10-30 troves): 50
  • Large (30+ troves): 100

Contract Addresses

Mainnet

TroveManager · address

0x94AfB503dBca74aC3E4929BACEeDfCe19B93c193

HintHelpers · address

0xD267b3bE2514375A075fd03C3D9CBa6b95317DC3

SortedTroves · address

0x8C5DB4C62BF29c1C4564390d10c20a47E0b2749f

BorrowerOperations · address

0x44b1bac67dDA612a41a58AAf779143B181dEe031

PriceFeed · address

0xc5aC5A8892230E0A3e1c473881A2de7353fFcA88

MUSD Token · address

0xdD468A1DDc392dcdbEf6db6e34E89AA338F9F186

Testnet

TroveManager · address

0xE47c80e8c23f6B4A1aE41c34837a0599D5D16bb0

HintHelpers · address

0x4e4cBA3779d56386ED43631b4dCD6d8EacEcBCF6

SortedTroves · address

0x722E4D24FD6Ff8b0AC679450F3D91294607268fA

BorrowerOperations · address

0xCdF7028ceAB81fA0C6971208e83fa7872994beE5

PriceFeed · address

0x86bCF0841622a5dAC14A313a15f96A95421b9366

MUSD Token · address

0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503

All addresses are proxy contracts. Always use “Read as Proxy” or “Write as Proxy” tabs.

Need Help?

• Check your transaction on the block explorer to see events and error messages
• Join our Discord and open a ticket: https://discord.com/invite/mezo