@morpho-org/blue-sdk

Framework-agnostic package that defines Morpho-related entity classes:

- MarketParams: represents the immutable configuration of a market on Morpho
- Market: represents the state of a market on Morpho
- Token: represents a ERC20 token
- User: represents a user of Morpho
- VaultConfig: represents the configuration of a Morpho Vault
- Vault: represents the state of a Morpho Vault
- VaultUser: represents the state of a user on a Morpho Vault
- VaultMarketAllocation: represents the allocation (and configuration) of a Morpho Vault on a Morpho market

Installation

``bash
npm install @morpho-org/blue-sdk
`

`bash
yarn add @morpho-org/blue-sdk
`

Getting Started

$3

Leverage the MarketParams class to manipulate a given market's immutable configuration:

`typescript
import { MarketParams } from "@morpho-org/blue-sdk";

const config = new MarketParams({
loanToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
collateralToken: "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0", // wstETH
oracle: "0x2a01EB9496094dA03c4E364Def50f5aD1280AD72",
irm: "0x870aC11D48B15DB9a138Cf899d20F13F79Ba00BC", // AdaptiveCurveIrm
lltv: 94_5000000000000000n, // 94.5%
});

config.liquidationIncentiveFactor; // e.g. 1_090000000000000000n (109%).
`

$3

Leverage the Market class to manipulate a specific market:

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

const market = new Market({
config: new MarketParams({
loanToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
collateralToken: "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0", // wstETH
oracle: "0x2a01EB9496094dA03c4E364Def50f5aD1280AD72",
irm: "0x870aC11D48B15DB9a138Cf899d20F13F79Ba00BC", // AdaptiveCurveIrm
lltv: 94_5000000000000000n, // 94.5%
}),
totalSupplyAssets: 1000_000000000000000000n,
totalBorrowAssets: 920_000000000000000000n,
totalSupplyShares: 1000_000000000000000000000000n,
totalBorrowShares: 920_000000000000000000000000n,
lastUpdate: 1721000000n,
fee: 0n,
price: 1_100000000000000000000000000000000000n,
rateAtTarget: 94850992095n,
});

market.utilization; // e.g. 92_0000000000000000n (92%).
market.liquidity; // e.g. 80_000000000000000000n (in loan assets).
market.apyAtTarget; // e.g. 3_0000000000000000n (3%).

const accruedMarket = market.accrueInterest(Time.timestamp()); // Accrue interest to the latest's timestamp.

accruedMarket.toSupplyAssets(shares); // Convert supply shares to assets.
`

$3

Leverage the Position class to manipulate the position of a user on a given market:

`typescript
import { Position } from "@morpho-org/blue-sdk";
import { Time } from "@morpho-org/morpho-ts";

const position = new AccrualPosition(
new Position({
user,
marketId: market.id,
supplyShares: 0n,
borrowShares: 20_000000000000000000000000n,
collateral: 27_000000000000000000n,
}),
market
);

position.borrowAssets; // e.g. 20_000000000000000000n (in loan assets).
position.isHealthy; // e.g. true.
position.maxBorrowableAssets; // e.g. 2100_000000000000000000n (in loan assets).

const accruedPosition = position.accrueInterest(Time.timestamp()); // Accrue interest to the latest's timestamp.

position.borrowAssets; // e.g. 20_400000000000000000n (in loan assets).
`

$3


#### registerCustomAddresses

Extends the default address registry and unwrapped token mapping for known or custom chains. Useful for testing or adding support for new networks.

> [!Note]
> - Custom addresses should be registered statically, at the root level.
> - Custom addresses can't be removed nor changed.

##### ✅ Use Cases

- Injecting additional or missing contract addresses on known chains.
- Providing a full set of addresses for an unknown (custom) chain.
- Registering mappings of wrapped → unwrapped tokens per chain (e.g., WETH → ETH).

---

##### Function Signature

`ts
registerCustomAddresses(options?: {
addresses?: Record; // Can be a subset of ChainAddresses if chain is known
unwrappedTokens?: Record>;
}): void
`

---

##### Parameters

- addresses (optional)
A map of chainId → ChainAddresses.
- For known chains, partial overrides are allowed (e.g., add a missing adapter).
- For unknown chains, a complete ChainAddresses object with required addresses must be provided.
- Throws an error if you attempt to override an existing address.

- unwrappedTokens (optional)
A map of chainId → { wrapped → unwrapped }.
- Throws an error if you attempt to override an existing mapping.

---

##### Behavior

- Merges user-provided addresses and unwrapped tokens into the internal registries.
- Uses a deep merge with custom logic to prevent overwriting existing values.
- Updates internal constants: addressesRegistry, addresses, and unwrappedTokensMapping.
- Applies Object.freeze() to ensure immutability.

---

##### Example

`ts
registerCustomAddresses({
addresses: {
8453: { stEth: "0xabc..." }, // provide stEth address on base
31337: {
morpho: "0x123...",
bundler3: {
bundler3: "0x456...",
...
},
...
}, // registers a new local test chain
},
unwrappedTokens: {
31337: {
"0xWrapped": "0xUnwrapped" // e.g., WETH → ETH
}
}
});
``