Vaults
Entities

Vault Entities

The Vault Entities module provides classes for interacting with vault-related entities in the Mirage Protocol.

VaultCollection

Represents a Mirage Protocol vault collection that allows users to deposit collateral and borrow mirage assets.

Properties

class VaultCollection {
  // Asset Information
  readonly collateralAddress: string              // Address of collateral asset
  readonly borrowAddress: string                  // Address of borrow asset
  readonly borrowSymbol: string                   // Symbol of borrow asset
  readonly collateralSymbol: string              // Symbol of collateral asset
  readonly collateralDecimals: number            // Decimals of collateral asset
  
  // State
  readonly borrowRebase: Rebase                   // Rebase for total borrow
  readonly totalCollateral: BigNumber            // Total collateral deposited
  readonly totalBorrow: BigNumber                // Total borrowed from vault
  readonly interestPerSecond: BigNumber         // Interest rate (precision: 1e12)
  
  // Configuration
  readonly initialCollateralizationPercent: number // Min collateralization for updates
  readonly maintenanceCollateralizationPercent: number // Min collateralization to avoid liquidation
  readonly borrowFeePercent: number               // Flat borrow fee percentage
  readonly liquidationPercent: number             // Protocol/liquidator cut during liquidation
  
  // Market State
  readonly exchangeRate: BigNumber                // Last cached exchange rate (precision: 1e8)
  readonly isEmergency: boolean                   // Emergency freeze status
  
  // Oracle Information
  readonly collateralOracleAddress: string        // Collateral price feed address
  readonly borrowOracleAddress: string            // Borrow asset price feed address
  
  readonly objectAddress: string                  // Vault collection address
  readonly mirage: MirageAsset                   // Global mirage module representation
}

Methods

getInterestRatePercent

Returns the annualized interest rate for the vault collection.

getInterestRatePercent(): number // Returns annual interest rate as percentage

Example Creation

// Get required resources
const collectionResources = await aptosClient.getAccountResources({ 
  accountAddress: vaultCollectionAddr 
})
const musdResources = await aptosClient.getAccountResources({ 
  accountAddress: musdMetadataAddr
})
 
// Create vault collection instance
const vaultCollection = mirageClient.vault.entities.createVaultCollection(
  collectionResources,
  musdResources,
  vaultCollectionAddr
)

MirageAsset

Represents a Mirage Protocol asset with its associated metadata and debt tracking.

Properties

class MirageAsset {
  readonly symbol: string                         // Asset symbol
  readonly name: string                           // Asset name
  readonly decimals: number                       // Asset decimals
  readonly debtRebase: Rebase                     // Debt tracking rebase
}

Example Creation

const musdResources = await aptosClient.getAccountResources({ 
  accountAddress: musdMetadataAddr
})
 
const mirageAsset = mirageClient.vault.entities.createMirageAsset(musdResources)

Rebase

Handles elastic rebasing calculations for the protocol. Used for tracking debt and borrowing amounts that can change over time.

Properties

class Rebase {
  readonly elastic: BigNumber                     // Current elastic (total) amount
  readonly base: BigNumber                        // Base reference amount
}

Methods

toElastic

Converts a base amount to an elastic amount based on the current rebase ratio.

toElastic(base: BigNumber, roundUp: boolean): BigNumber

Parameters:

  • base: The base amount to convert
  • roundUp: Whether to round up the result
  • Returns: The converted elastic amount

toBase

Converts an elastic amount to a base amount based on the current rebase ratio.

toBase(elastic: BigNumber, roundUp: boolean): BigNumber

Parameters:

  • elastic: The elastic amount to convert
  • roundUp: Whether to round up the result
  • Returns: The converted base amount

Example Creation

const rebase = mirageClient.vault.entities.createRebase(elastic, base)

Vault

Represents an individual vault position within a vault collection.

Properties

class Vault {
  readonly collateralAmount: BigNumber           // Amount of collateral deposited
  readonly borrowAmount: BigNumber               // Amount borrowed
  readonly pnl: BigNumber                        // Profit/loss in borrow token
  readonly feesPaid: BigNumber                   // Total fees paid in borrow token
  readonly vaultCollection: VaultCollection      // Parent vault collection
  readonly objectAddress: string                 // Vault address
}

Methods

getHealth

Calculates the current health of the vault position based on provided prices.

getHealth(collateralPrice: BigNumber, borrowPrice: BigNumber): number

Parameters:

  • collateralPrice: Current price of the collateral asset
  • borrowPrice: Current price of the borrowed asset
  • Returns: Health percentage (> 0 means healthy, < 0 means liquidatable)

Example Creation

// Get vault resources
const vaultAddr = "0x456..." 
const vaultResources = await aptosClient.getAccountResources({ 
  accountAddress: vaultAddr 
})
 
// Create vault instance
const vault = mirageClient.vault.entities.createVault(
  vaultResources,
  vaultCollection, // VaultCollection instance
  vaultAddr
)

Helper Functions

calculateVaultHealth

Calculates vault health based on current prices and collateralization requirements.

function calculateVaultHealth(
  collateralAmount: BigNumber,  // Amount of collateral in the vault
  borrowAmount: BigNumber,      // Amount borrowed from the vault
  maintenanceCollateralizationPercent: number,  // Minimum collateralization ratio
  collateralPrice: BigNumber,  // Current collateral price
  borrowPrice: BigNumber,      // Current borrow token price
): number // Returns health percentage (> 0 = healthy, < 0 = liquidatable)
VaultsExamples