@morpho-org/consumer-sdk 0.3.0 → 0.5.0

package/README.md

@@ -1,4 +1,4 @@
-# Consumer sdk
+# Consumer SDK
 
 ![Beta](https://img.shields.io/badge/status-beta-orange)
 
@@ -6,82 +6,342 @@
 
 > **The abstraction layer that simplifies Morpho protocol**
 
-## ✨ How to use it? (two ways to build transactions)
+## Entities & Actions
 
-### 1️⃣ **With MorphoClient**
+| Entity       | Action                   | Route                     | Why                                                                                                 |
+| ------------ | ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------- |
+| **VaultV2**  | `deposit`                | Bundler (general adapter) | Enforces `maxSharePrice` — inflation attack prevention. Supports native token wrapping.             |
+|              | `withdraw`               | Direct vault call         | No attack surface, no bundler overhead needed                                                       |
+|              | `redeem`                 | Direct vault call         | No attack surface, no bundler overhead needed                                                       |
+|              | `forceWithdraw`          | Vault `multicall`         | N `forceDeallocate` + 1 `withdraw` in a single tx                                                   |
+|              | `forceRedeem`            | Vault `multicall`         | N `forceDeallocate` + 1 `redeem` in a single tx                                                     |
+| **VaultV1**  | `deposit`                | Bundler (general adapter) | Same ERC-4626 inflation attack prevention as V2. Supports native token wrapping.                    |
+|              | `withdraw`               | Direct vault call         | No attack surface                                                                                   |
+|              | `redeem`                 | Direct vault call         | No attack surface                                                                                   |
+| **MarketV1** | `supplyCollateral`       | Bundler (general adapter) | `erc20TransferFrom` + `morphoSupplyCollateral`. Supports native wrapping.                           |
+|              | `borrow`                 | Bundler (general adapter) | `morphoBorrow` with `minSharePrice` slippage protection. Requires GA1 auth. Supports reallocations. |
+|              | `supplyCollateralBorrow` | Bundler (general adapter) | Atomic supply + borrow. LLTV buffer prevents instant liquidation. Supports reallocations.           |
+
+## VaultV2
 
 ```typescript
 import { MorphoClient } from "@morpho-org/consumer-sdk";
-import { createWalletClient, http } from "viem";
+import { createPublicClient, http } from "viem";
+import { mainnet } from "viem/chains";
+
+const viemClient = createPublicClient({ chain: mainnet, transport: http() });
+const morpho = new MorphoClient(viemClient);
+
+const vault = morpho.vaultV2("0xVault...", 1);
+```
+
+### Deposit
+
+```typescript
+const { buildTx, getRequirements } = await vault.deposit({
+  amount: 1000000000000000000n,
+  userAddress: "0xUser...",
+});
+
+const requirements = await getRequirements();
+const tx = buildTx(requirementSignature);
+```
+
+#### Deposit with native token wrapping
+
+For vaults whose underlying asset is wNative, you can deposit native token that will be automatically wrapped:
+
+```typescript
+// Native ETH only — wraps 1 ETH to WETH and deposits
+const { buildTx, getRequirements } = await vault.deposit({
+  nativeAmount: 1000000000000000000n,
+  userAddress: "0xUser...",
+});
+
+// Mixed — 0.5 WETH (ERC-20) + 0.5 native ETH wrapped to WETH
+const { buildTx, getRequirements } = await vault.deposit({
+  amount: 500000000000000000n,
+  nativeAmount: 500000000000000000n,
+  userAddress: "0xUser...",
+});
+```
+
+The bundler atomically transfers native token, wraps it to wNative, and deposits alongside any ERC-20 amount. The transaction's `value` field is set to `nativeAmount`.
+
+### Withdraw
+
+```typescript
+const { buildTx } = vault.withdraw({
+  amount: 500000000000000000n,
+  userAddress: "0xUser...",
+});
+
+const tx = buildTx();
+```
+
+### Redeem
 
-const client = createWalletClient({
-  chain: mainnet,
-  transport: http(),
-  account: "0x...",
+```typescript
+const { buildTx } = vault.redeem({
+  shares: 1000000000000000000n,
+  userAddress: "0xUser...",
 });
 
-const morpho = new MorphoClient(client);
+const tx = buildTx();
+```
+
+### Force Withdraw
 
-const vault = morpho.vaultV2("0x1234...", 1); // vault address, chain ID
-const deposit = await vault.deposit({
-  assets: 1000000000000000000n, // vault asset amount
-  userAddress: "0x1234...", // recipient address
+```typescript
+const { buildTx } = vault.forceWithdraw({
+  deallocations: [{ adapter: "0xAdapter...", amount: 100n }],
+  withdraw: { amount: 500000000000000000n },
+  userAddress: "0xUser...",
 });
-console.log(deposit.buildTx());
-console.log(await deposit.getRequirements());
 
-const withdraw = vault.withdraw({
-  assets: 1000000000000000000n, // vault asset amount
-  userAddress: "0x1234...", // recipient address
+const tx = buildTx();
+```
+
+### Force Redeem
+
+```typescript
+const { buildTx } = vault.forceRedeem({
+  deallocations: [{ adapter: "0xAdapter...", amount: 100n }],
+  redeem: { shares: 1000000000000000000n },
+  userAddress: "0xUser...",
+});
+
+const tx = buildTx();
+```
+
+## VaultV1
+
+```typescript
+const vault = morpho.vaultV1("0xVault...", 1);
+```
+
+### Deposit
+
+```typescript
+const { buildTx, getRequirements } = await vault.deposit({
+  amount: 1000000000000000000n,
+  userAddress: "0xUser...",
 });
-console.log(withdraw.buildTx());
 
-const redeem = vault.redeem({
-  shares: 1000000000000000000n, // vault shares amount
-  userAddress: "0x1234...", // recipient address
+const requirements = await getRequirements();
+const tx = buildTx(requirementSignature);
+```
+
+### Withdraw
+
+```typescript
+const { buildTx } = vault.withdraw({
+  amount: 500000000000000000n,
+  userAddress: "0xUser...",
 });
-console.log(redeem.buildTx());
+
+const tx = buildTx();
 ```
 
-### 2️⃣ **Direct construction** (Full control)
+### Redeem
 
 ```typescript
-import { vaultV2Deposit } from "@morpho-org/consumer-sdk";
+const { buildTx } = vault.redeem({
+  shares: 1000000000000000000n,
+  userAddress: "0xUser...",
+});
+
+const tx = buildTx();
+```
 
-const deposit = vaultV2Deposit({
-  vault: {
-    chainId: mainnet.id,
-    address: "0x1234...", // vault address
-    asset: "0x1234...", // asset address
+## MarketV1
+
+```typescript
+const market = morpho.marketV1(
+  {
+    loanToken: "0xLoan...",
+    collateralToken: "0xCollateral...",
+    oracle: "0xOracle...",
+    irm: "0xIrm...",
+    lltv: 860000000000000000n,
   },
-  args: {
-    assets: 1000000000000000000n, // vault asset amount
-    maxSharePrice: 995180497664595699494513674403n,
-    recipient: "0x1234...", // recipient address
+  1
+);
+```
+
+### Supply Collateral
+
+```typescript
+const { buildTx, getRequirements } = market.supplyCollateral({
+  amount: 1000000000000000000n,
+  userAddress: "0xUser...",
+});
+
+const requirements = await getRequirements();
+const tx = buildTx(requirementSignature);
+```
+
+### Borrow
+
+```typescript
+const positionData = await market.getPositionData("0xUser...");
+
+const { buildTx, getRequirements } = market.borrow({
+  amount: 500000000000000000n,
+  userAddress: "0xUser...",
+  positionData,
+});
+
+const requirements = await getRequirements();
+const tx = buildTx();
+```
+
+### Supply Collateral & Borrow
+
+```typescript
+const positionData = await market.getPositionData("0xUser...");
+
+const { buildTx, getRequirements } = market.supplyCollateralBorrow({
+  amount: 1000000000000000000n,
+  borrowAmount: 500000000000000000n,
+  userAddress: "0xUser...",
+  positionData,
+});
+
+const requirements = await getRequirements();
+const tx = buildTx(requirementSignature);
+```
+
+### Borrow with Shared Liquidity (Reallocations)
+
+When a market lacks sufficient liquidity, you can reallocate liquidity from other markets managed by MetaMorpho Vaults via the **PublicAllocator** contract:
+
+```typescript
+import type { VaultReallocation } from "@morpho-org/consumer-sdk";
+
+const reallocations: VaultReallocation[] = [
+  {
+    vault: "0xVault...", // MetaMorpho vault to reallocate from
+    fee: 0n, // PublicAllocator fee in native token (can be 0)
+    withdrawals: [
+      {
+        marketParams: sourceMarketParams, // Source market to withdraw from
+        amount: 2000000000n, // Amount to withdraw
+      },
+    ],
   },
+];
+
+const positionData = await market.getPositionData("0xUser...");
+
+// Borrow with reallocations
+const { buildTx, getRequirements } = market.borrow({
+  amount: 500000000000000000n,
+  userAddress: "0xUser...",
+  positionData,
+  reallocations,
 });
+
+const requirements = await getRequirements();
+const tx = buildTx();
+// tx.value includes the sum of all reallocation fees
 ```
 
-## Link Integration - Local Development Guide
+Reallocations also work with `supplyCollateralBorrow`:
+
+```typescript
+const { buildTx, getRequirements } = market.supplyCollateralBorrow({
+  amount: 1000000000000000000n,
+  borrowAmount: 500000000000000000n,
+  userAddress: "0xUser...",
+  positionData,
+  reallocations,
+});
+```
+
+## Architecture
+
+```mermaid
+graph LR
+    MC[MorphoClient]
+
+    MC -->|.vaultV1| MV1
+    MC -->|.vaultV2| MV2
+    MC -->|.marketV1| MM1
+
+    subgraph VaultV1 Flow
+        MV1[MorphoVaultV1]
+        MV1 --> V1D[vaultV1Deposit]
+        MV1 --> V1W[vaultV1Withdraw]
+        MV1 --> V1R[vaultV1Redeem]
 
-This guide explains how to link this local package to your Next.js application for easier debugging.
+        V1D -->|nativeTransfer + wrapNative + erc4626Deposit| B1[Bundler3]
+        V1W -->|direct call| MM[MetaMorpho]
+        V1R -->|direct call| MM
+    end
 
-### **Step 1: Initial setup (one time only)**
+    subgraph VaultV2 Flow
+        MV2[MorphoVaultV2]
+        MV2 --> V2D[vaultV2Deposit]
+        MV2 --> V2W[vaultV2Withdraw]
+        MV2 --> V2R[vaultV2Redeem]
+        MV2 --> V2FW[vaultV2ForceWithdraw]
+        MV2 --> V2FR[vaultV2ForceRedeem]
+
+        V2D -->|nativeTransfer + wrapNative + erc4626Deposit| B2[Bundler3]
+        V2W -->|direct call| V2C[VaultV2 Contract]
+        V2R -->|direct call| V2C
+        V2FW -->|multicall| V2C
+        V2FR -->|multicall| V2C
+    end
+
+    subgraph MarketV1 Flow
+        MM1[MorphoMarketV1]
+        MM1 --> M1SC[marketV1SupplyCollateral]
+        MM1 --> M1B[marketV1Borrow]
+        MM1 --> M1SCB[marketV1SupplyCollateralBorrow]
+
+        M1SC -->|erc20TransferFrom + morphoSupplyCollateral| B3[Bundler3]
+        M1B -->|reallocateTo? + morphoBorrow| B3
+        M1SCB -->|transfer + supplyCollateral + reallocateTo? + borrow| B3
+
+        B3 -.->|reallocateTo| PA[PublicAllocator]
+    end
+
+
+    subgraph Shared
+        REQ[getRequirements]
+    end
+
+    MV1 -.->|approval / permit| REQ
+    MV2 -.->|approval / permit| REQ
+    MM1 -.->|approval / permit / authorization| REQ
+
+    style B1 fill:#e8f5e9,stroke:#4caf50
+    style B2 fill:#e8f5e9,stroke:#4caf50
+    style B3 fill:#e8f5e9,stroke:#4caf50
+    style MM fill:#fff3e0,stroke:#ff9800
+    style V2C fill:#e3f2fd,stroke:#2196f3
+    style REQ fill:#f3e5f5,stroke:#9c27b0
+    style PA fill:#fff9c4,stroke:#f9a825
+```
+
+## Local Development
+
+Link this package to your app for local debugging:
 
 ```bash
 # In this consumer-sdk project
 pnpm run build:link
 ```
 
-### **Step 2: In your other project**
+In your other project:
 
 ```bash
 # Link the local package
 pnpm link consumer-sdk
 ```
 
-## 🤝 Contributing
+## Contributing
 
 Contributions are welcome! Feel free to open an issue or PR.
-
-**Made with ❤️ by the Morpho team**

package/lib/actions/index.d.ts

@@ -1,2 +1,4 @@
+export * from "./marketV1";
 export * from "./requirements";
+export * from "./vaultV1";
 export * from "./vaultV2";

package/lib/actions/index.js

@@ -14,5 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./marketV1"), exports);
 __exportStar(require("./requirements"), exports);
+__exportStar(require("./vaultV1"), exports);
 __exportStar(require("./vaultV2"), exports);

package/lib/actions/marketV1/borrow.d.ts

@@ -0,0 +1,34 @@
+import type { MarketParams } from "@morpho-org/blue-sdk";
+import type { Address } from "viem";
+import { type MarketV1BorrowAction, type Metadata, type Transaction, type VaultReallocation } from "../../types";
+/** Parameters for {@link marketV1Borrow}. */
+export interface MarketV1BorrowParams {
+    market: {
+        readonly chainId: number;
+        readonly marketParams: MarketParams;
+    };
+    args: {
+        amount: bigint;
+        receiver: Address;
+        /** Minimum borrow share price (in ray). Protects against share price manipulation. */
+        minSharePrice: bigint;
+        /** Vault reallocations to execute before borrowing (computed by entity). */
+        reallocations?: readonly VaultReallocation[];
+    };
+    metadata?: Metadata;
+}
+/**
+ * Prepares a borrow transaction for a Morpho Blue market.
+ *
+ * Routed through bundler3 via `morphoBorrow`. The bundler uses the transaction
+ * initiator as `onBehalf`. Uses `minSharePrice` to protect against share price
+ * manipulation between transaction construction and execution.
+ *
+ * When `reallocations` are provided, `reallocateTo` actions are prepended to
+ * the bundle, moving liquidity from other markets via the PublicAllocator
+ * before borrowing. The reallocation fees are set as the transaction value.
+ *
+ * @param params - Borrow parameters.
+ * @returns Deep-frozen transaction.
+ */
+export declare const marketV1Borrow: ({ market: { chainId, marketParams }, args: { amount, receiver, minSharePrice, reallocations }, metadata, }: MarketV1BorrowParams) => Readonly<Transaction<MarketV1BorrowAction>>;

package/lib/actions/marketV1/borrow.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.marketV1Borrow = void 0;
+const bundler_sdk_viem_1 = require("@morpho-org/bundler-sdk-viem");
+const morpho_ts_1 = require("@morpho-org/morpho-ts");
+const helpers_1 = require("../../helpers");
+const types_1 = require("../../types");
+const buildReallocationActions_1 = require("./buildReallocationActions");
+/**
+ * Prepares a borrow transaction for a Morpho Blue market.
+ *
+ * Routed through bundler3 via `morphoBorrow`. The bundler uses the transaction
+ * initiator as `onBehalf`. Uses `minSharePrice` to protect against share price
+ * manipulation between transaction construction and execution.
+ *
+ * When `reallocations` are provided, `reallocateTo` actions are prepended to
+ * the bundle, moving liquidity from other markets via the PublicAllocator
+ * before borrowing. The reallocation fees are set as the transaction value.
+ *
+ * @param params - Borrow parameters.
+ * @returns Deep-frozen transaction.
+ */
+const marketV1Borrow = ({ market: { chainId, marketParams }, args: { amount, receiver, minSharePrice, reallocations }, metadata, }) => {
+    if (amount <= 0n) {
+        throw new types_1.NonPositiveBorrowAmountError(marketParams.id);
+    }
+    if (minSharePrice < 0n) {
+        throw new types_1.NonPositiveMinBorrowSharePriceError(marketParams.id);
+    }
+    const actions = [];
+    let reallocationFee = 0n;
+    if (reallocations && reallocations.length > 0) {
+        const result = (0, buildReallocationActions_1.buildReallocationActions)(reallocations, marketParams);
+        actions.push(...result.actions);
+        reallocationFee = result.fee;
+    }
+    actions.push({
+        type: "morphoBorrow",
+        args: [marketParams, amount, 0n, minSharePrice, receiver, false],
+    });
+    let tx = {
+        ...bundler_sdk_viem_1.BundlerAction.encodeBundle(chainId, actions),
+        value: reallocationFee,
+    };
+    if (metadata) {
+        tx = (0, helpers_1.addTransactionMetadata)(tx, metadata);
+    }
+    return (0, morpho_ts_1.deepFreeze)({
+        ...tx,
+        action: {
+            type: "marketV1Borrow",
+            args: {
+                market: marketParams.id,
+                amount,
+                receiver,
+                minSharePrice,
+                reallocationFee,
+            },
+        },
+    });
+};
+exports.marketV1Borrow = marketV1Borrow;

package/lib/actions/marketV1/buildReallocationActions.d.ts

@@ -0,0 +1,17 @@
+import type { MarketParams } from "@morpho-org/blue-sdk";
+import type { Action } from "@morpho-org/bundler-sdk-viem";
+import type { VaultReallocation } from "../../types";
+/**
+ * Builds reallocation bundler actions and computes the total fee.
+ *
+ * Validates the reallocations, then encodes each as a `reallocateTo` action.
+ * Caller must ensure `reallocations` is non-empty before calling.
+ *
+ * @param reallocations - The vault reallocations to encode.
+ * @param targetMarketParams - The target market params for the borrow.
+ * @returns The encoded actions and total reallocation fee.
+ */
+export declare const buildReallocationActions: (reallocations: readonly VaultReallocation[], targetMarketParams: MarketParams) => {
+    readonly actions: Action[];
+    readonly fee: bigint;
+};

package/lib/actions/marketV1/buildReallocationActions.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReallocationActions = void 0;
+const helpers_1 = require("../../helpers");
+/**
+ * Builds reallocation bundler actions and computes the total fee.
+ *
+ * Validates the reallocations, then encodes each as a `reallocateTo` action.
+ * Caller must ensure `reallocations` is non-empty before calling.
+ *
+ * @param reallocations - The vault reallocations to encode.
+ * @param targetMarketParams - The target market params for the borrow.
+ * @returns The encoded actions and total reallocation fee.
+ */
+const buildReallocationActions = (reallocations, targetMarketParams) => {
+    (0, helpers_1.validateReallocations)(reallocations, targetMarketParams.id);
+    const fee = reallocations.reduce((sum, r) => sum + r.fee, 0n);
+    const actions = [];
+    for (const r of reallocations) {
+        actions.push({
+            type: "reallocateTo",
+            args: [
+                r.vault,
+                r.fee,
+                r.withdrawals.map((w) => ({
+                    marketParams: w.marketParams,
+                    amount: w.amount,
+                })),
+                targetMarketParams,
+                false,
+            ],
+        });
+    }
+    return { actions, fee };
+};
+exports.buildReallocationActions = buildReallocationActions;

package/lib/actions/marketV1/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./borrow";
+export * from "./repay";
+export * from "./repayWithdrawCollateral";
+export * from "./supplyCollateral";
+export * from "./supplyCollateralBorrow";
+export * from "./withdrawCollateral";

package/lib/actions/marketV1/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./borrow"), exports);
+__exportStar(require("./repay"), exports);
+__exportStar(require("./repayWithdrawCollateral"), exports);
+__exportStar(require("./supplyCollateral"), exports);
+__exportStar(require("./supplyCollateralBorrow"), exports);
+__exportStar(require("./withdrawCollateral"), exports);

package/lib/actions/marketV1/repay.d.ts

@@ -0,0 +1,44 @@
+import { type MarketParams } from "@morpho-org/blue-sdk";
+import { type Address } from "viem";
+import type { MarketV1RepayAction, Metadata, RequirementSignature, Transaction } from "../../types";
+/** Parameters for {@link marketV1Repay}. */
+export interface MarketV1RepayParams {
+    market: {
+        readonly chainId: number;
+        readonly marketParams: MarketParams;
+    };
+    args: {
+        /** Repay assets amount (0n when repaying by shares). */
+        assets: bigint;
+        /** Repay shares amount (0n when repaying by assets). */
+        shares: bigint;
+        /** ERC20 amount to transfer to GeneralAdapter1. Must be greater than or equal to the repay amount to take into account the slippage. */
+        transferAmount: bigint;
+        /** Address whose debt is being repaid. */
+        onBehalf: Address;
+        /** Receives residual loan tokens in shares mode. */
+        receiver: Address;
+        /** Maximum repay share price (in ray). Protects against share price manipulation. */
+        maxSharePrice: bigint;
+        requirementSignature?: RequirementSignature;
+    };
+    metadata?: Metadata;
+}
+/**
+ * Prepares a repay transaction for a Morpho Blue market.
+ *
+ * Routed through bundler3 via GeneralAdapter1. Supports two modes:
+ * - **By assets** (`assets > 0, shares = 0`): repays an exact asset amount.
+ * - **By shares** (`assets = 0, shares > 0`): repays exact shares (full repay).
+ *
+ * Exactly one of `assets`/`shares` must be non-zero. The `transferAmount` controls
+ * how many ERC20 tokens are pulled from the user (may differ from `assets` in
+ * shares mode where the entity computes an upper-bound estimate).
+ *
+ * Uses `maxSharePrice` to protect against share price manipulation between
+ * transaction construction and execution.
+ *
+ * @param params - Repay parameters.
+ * @returns Deep-frozen transaction.
+ */
+export declare const marketV1Repay: ({ market: { chainId, marketParams }, args: { assets, shares, transferAmount, onBehalf, receiver, maxSharePrice, requirementSignature, }, metadata, }: MarketV1RepayParams) => Readonly<Transaction<MarketV1RepayAction>>;