Morpho Docs

Introduction

The blue-sdk is the core SDK in the Morpho Stack. It provides the foundational components necessary to interact with Morpho's offchain ecosystem. This SDK is framework-agnostic, making it versatile for various applications. Key features include:

Market configuration management
Market data manipulation
User position management
Token and vault interactions

Installation

First, install the necessary dependencies:

yarn add @morpho-org/blue-sdk @morpho-org/morpho-ts

Setup

Import the necessary modules and set up your environment:

import {
  MarketParams,
  Market,
  AccrualPosition,
  Position,
} from "@morpho-org/blue-sdk";
import { Time } from "@morpho-org/morpho-ts";

Basic Usage

Here's a script that demonstrates the basic usage of the blue-sdk:

// Create a new market configuration using MarketParams
const config = new MarketParams({
  loanToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
  collateralToken: "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0", // wstETH
  oracle: "0x2a01EB9496094dA03c4E364Def50f5aD1280AD72",
  irm: "0x870aC11D48B15DB9a138Cf899d20F13F79Ba00BC", // AdaptiveCurveIrm
  lltv: 94_5000000000000000n, // 94.5%
});
 
console.log("Market Config ID:", config.id);
console.log("Liquidation Incentive Factor:", config.liquidationIncentiveFactor);
 
// Create a new market with the specified configuration
const market = new Market({
  config,
  totalSupplyAssets: 1000_000000000000000000n,
  totalBorrowAssets: 920_000000000000000000n,
  totalSupplyShares: 1000_000000000000000000000000n,
  totalBorrowShares: 920_000000000000000000000000n,
  lastUpdate: 1721000000n,
  fee: 0n,
  price: 1_100000000000000000000000000000000000n,
  rateAtTarget: 94850992095n,
});
 
console.log("Market Utilization:", market.utilization);
console.log("Market Liquidity:", market.liquidity);
console.log("Market APY at Target:", market.apyAtTarget);
 
// Accrue interest to the latest timestamp
const accruedMarket = market.accrueInterest(Time.timestamp());
 
// Convert supply shares to assets
const shares = 1000000000000000000n;
console.log("Supply Assets for Shares:", accruedMarket.toSupplyAssets(shares));
 
// Create a new position in the market
const position = new AccrualPosition(
  new Position({
    user: "0xCDB238D68d8Da74487711bC1F8f13f3d00667D1A", // Replace with actual user address
    marketId: market.id,
    supplyShares: 0n,
    borrowShares: 20_000000000000000000000000n,
    collateral: 27_000000000000000000n,
  }),
  market
);
 
console.log("Borrow Assets:", position.borrowAssets);
console.log("Is Position Healthy:", position.isHealthy);
console.log("Max Borrowable Assets:", position.maxBorrowableAssets);
 
// Accrue interest for the position to the latest timestamp
const accruedPosition = position.accrueInterest(Time.timestamp());
console.log("Accrued Borrow Assets:", accruedPosition.borrowAssets);

Key Classes

MarketParams

Represents the immutable configuration of a market on Morpho. This class replaces the previous MarketConfig class and provides:

Market configuration parameters (loan token, collateral token, oracle, IRM, LLTV)
Computed properties like liquidationIncentiveFactor
Unique market identifier

Market

Represents the state of a market on Morpho, including:

Total supply and borrow amounts
Utilization and liquidity metrics
Interest rate calculations
Share-to-asset conversions

Position

Represents a user's position on a specific market, including:

Supply and borrow shares
Collateral amounts
Health factor calculations
Maximum borrowable asset calculations

Advanced Usage

Integrating with Other SDKs

Integrate with blue-sdk-viem for onchain interactions.

Custom Address Registration

For testing or custom networks, you can register custom addresses:

import { registerCustomAddresses } from "@morpho-org/blue-sdk";
 
registerCustomAddresses({
  addresses: {
    31337: {
      morpho: "0x123...",
      // ... other required addresses
    },
  },
  unwrappedTokens: {
    31337: {
      "0xWrappedToken": "0xUnwrappedToken",
    },
  },
});

Error Handling

Always implement proper error handling and input validation in production code.

Complex Scenarios

Explore more complex scenarios such as:

Multi-market interactions
Vault allocations
Token management

Conclusion

This tutorial provides a comprehensive overview of how to use the blue-sdk to interact with Morpho markets and positions. For more detailed information, refer to the official Morpho documentation.

Full Code Example

import {
  MarketParams,
  Market,
  AccrualPosition,
  Position,
} from "@morpho-org/blue-sdk";
import { Time } from "@morpho-org/morpho-ts";
 
// Create a new market configuration using MarketParams
const config = new MarketParams({
  loanToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
  collateralToken: "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0", // wstETH
  oracle: "0x2a01EB9496094dA03c4E364Def50f5aD1280AD72",
  irm: "0x870aC11D48B15DB9a138Cf899d20F13F79Ba00BC", // AdaptiveCurveIrm
  lltv: 94_5000000000000000n, // 94.5%
});
 
console.log("Market Config ID:", config.id);
console.log("Liquidation Incentive Factor:", config.liquidationIncentiveFactor);
 
// Create a new market with the specified configuration
const market = new Market({
  params: config,
  totalSupplyAssets: 1000_000000000000000000n,
  totalBorrowAssets: 920_000000000000000000n,
  totalSupplyShares: 1000_000000000000000000000000n,
  totalBorrowShares: 920_000000000000000000000000n,
  lastUpdate: 1721000000n,
  fee: 0n,
  price: 1_100000000000000000000000000000000000n,
  rateAtTarget: 94850992095n,
});
 
console.log("Market Utilization:", market.utilization);
console.log("Market Liquidity:", market.liquidity);
console.log("Market APY at Target:", market.apyAtTarget);
 
// Accrue interest to the latest timestamp
const accruedMarket = market.accrueInterest(Time.timestamp());
 
// Convert supply shares to assets
const shares = 1000000000000000000n;
console.log("Supply Assets for Shares:", accruedMarket.toSupplyAssets(shares));
 
// Create a new position in the market
const position = new AccrualPosition(
  new Position({
    user: "0xCDB238D68d8Da74487711bC1F8f13f3d00667D1A", // Replace with actual user address
    marketId: market.id,
    supplyShares: 0n,
    borrowShares: 20_000000000000000000000000n,
    collateral: 27_000000000000000000n,
  }),
  market
);
 
console.log("Borrow Assets:", position.borrowAssets);
console.log("Is Position Healthy:", position.isHealthy);
console.log("Max Borrowable Assets:", position.maxBorrowableAssets);
 
// Accrue interest for the position to the latest timestamp
const accruedPosition = position.accrueInterest(Time.timestamp());
console.log("Accrued Borrow Assets:", accruedPosition.borrowAssets);