@stablechain/sdk 0.1.1 → 1.0.1

package/dist/index.js

@@ -1,13 +1,25 @@
 // src/stable.ts
 import {
-  createPublicClient as createPublicClient2,
-  createWalletClient as createWalletClient2,
-  erc20Abi as erc20Abi2,
-  http as http2,
-  isAddress as isAddress2,
-  parseUnits as parseUnits2
+  createPublicClient as createPublicClient4,
+  createWalletClient as createWalletClient3,
+  erc20Abi as erc20Abi4,
+  http as http4,
+  isAddress as isAddress3,
+  parseUnits as parseUnits4
+} from "viem";
+import { stable as stableMainnet2, stableTestnet as stableTestnet2 } from "viem/chains";
+
+// src/earn/reader.ts
+import {
+  createPublicClient,
+  erc20Abi,
+  formatUnits,
+  http,
+  isAddress,
+  parseUnits
 } from "viem";
 import { stable as stableMainnet, stableTestnet } from "viem/chains";
+import { MorphoClient } from "@morpho-org/morpho-sdk";
 
 // src/errors.ts
 import { BaseError } from "viem";
@@ -67,6 +79,14 @@ var StableNetworkError = class extends StableError {
     this.url = args.url;
   }
 };
+var StableBulkError = class extends StableError {
+  constructor(args) {
+    super(args.shortMessage, { name: "StableBulkError" });
+    this.results = args.results;
+    this.succeeded = args.succeeded;
+    this.failed = args.failed;
+  }
+};
 function formatValue(v) {
   if (typeof v === "bigint") return `${v}n`;
   if (typeof v === "string") return JSON.stringify(v);
@@ -79,17 +99,6 @@ function formatValue(v) {
   }
 }
 
-// src/services/lifi.ts
-import {
-  createPublicClient,
-  createWalletClient,
-  erc20Abi,
-  formatUnits,
-  http,
-  isAddress,
-  parseUnits
-} from "viem";
-
 // src/helpers/chain.ts
 import { defineChain } from "viem";
 function makeChain(id, rpc) {
@@ -154,6 +163,177 @@ var Network = /* @__PURE__ */ ((Network2) => {
   return Network2;
 })(Network || {});
 
+// src/earn/reader.ts
+var MORPHO_API_URL = "https://blue-api.morpho.org/graphql";
+var EarnReader = class {
+  constructor(config) {
+    if (!config.earn?.vault) {
+      throw new StableValidationError(
+        "earn.vault",
+        void 0,
+        "createStableReader: earn.vault is required"
+      );
+    }
+    if (!isAddress(config.address)) {
+      throw new StableValidationError(
+        "address",
+        config.address,
+        `createStableReader: invalid user address "${config.address}"`
+      );
+    }
+    if (!isAddress(config.earn.vault)) {
+      throw new StableValidationError(
+        "earn.vault",
+        config.earn.vault,
+        `createStableReader: invalid vault address "${config.earn.vault}"`
+      );
+    }
+    const network = config.network ?? "mainnet" /* Mainnet */;
+    const viemChain = network === "mainnet" /* Mainnet */ ? stableMainnet : stableTestnet;
+    const rpc = (config.rpc ?? viemChain.rpcUrls.default.http[0]).replace(/\/$/, "");
+    this.chainId = viemChain.id;
+    this.vaultAddr = config.earn.vault;
+    this.userAddr = config.address;
+    const chain = makeChain(viemChain.id, rpc);
+    this.pc = createPublicClient({ chain, transport: http(rpc) });
+    this.morpho = new MorphoClient(this.pc);
+  }
+  async position() {
+    const vault = this.morpho.vaultV2(this.vaultAddr, this.chainId);
+    const [vaultData, shares] = await Promise.all([
+      vault.getData(),
+      this.pc.readContract({
+        address: this.vaultAddr,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: [this.userAddr]
+      })
+    ]);
+    const [tokenDecimals, shareDecimals] = await Promise.all([
+      this.pc.readContract({ address: vaultData.asset, abi: erc20Abi, functionName: "decimals" }),
+      this.pc.readContract({ address: this.vaultAddr, abi: erc20Abi, functionName: "decimals" })
+    ]);
+    const assetsRaw = vaultData.toAssets(shares);
+    return {
+      shares,
+      sharesFormatted: Number(formatUnits(shares, shareDecimals)),
+      shareDecimals,
+      assets: Number(formatUnits(assetsRaw, tokenDecimals)),
+      tokenDecimals,
+      assetAddress: vaultData.asset
+    };
+  }
+  async getYield() {
+    return this._fetchYield();
+  }
+  async preview(params) {
+    const { amount, horizonDays } = params;
+    const apy = await this._fetchNetApy();
+    return {
+      projectedYield: amount * apy * (horizonDays / 365),
+      apy,
+      horizonDays
+    };
+  }
+  async withdrawability(params) {
+    const vault = this.morpho.vaultV2(this.vaultAddr, this.chainId);
+    const vaultData = await vault.getData();
+    const tokenDecimals = params.tokenDecimals ?? await this.pc.readContract({
+      address: vaultData.asset,
+      abi: erc20Abi,
+      functionName: "decimals"
+    });
+    const requestedRaw = parseUnits(String(params.amount), tokenDecimals);
+    const availableLiquidityRaw = vaultData.assetBalance;
+    return {
+      isInstant: requestedRaw <= availableLiquidityRaw,
+      availableLiquidity: Number(formatUnits(availableLiquidityRaw, tokenDecimals)),
+      tokenDecimals
+    };
+  }
+  async _fetchNetApy() {
+    const { apy } = await this._fetchYield();
+    return apy;
+  }
+  async _fetchYield() {
+    const query = `
+      query VaultYield($address: String!, $chainId: Int!) {
+        vaultV2ByAddress(address: $address, chainId: $chainId) {
+          netApy
+          netApyExcludingRewards
+          performanceFee
+          managementFee
+          rewards {
+            asset { symbol address }
+            supplyApr
+          }
+        }
+      }
+    `;
+    let body;
+    try {
+      body = await retryWithBackoff(
+        async () => {
+          const res = await fetch(MORPHO_API_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              query,
+              variables: { address: this.vaultAddr, chainId: this.chainId }
+            })
+          });
+          if (!res.ok) {
+            const retryable = res.status === 429 || res.status >= 500;
+            throw new HttpError(
+              `earn: Morpho API returned ${res.status} \u2014 ${res.statusText}`,
+              res.status,
+              retryable
+            );
+          }
+          return res.json().catch(() => void 0);
+        },
+        (err) => err instanceof HttpError ? err.retryable : err instanceof TypeError
+      );
+    } catch (err) {
+      if (err instanceof TypeError || err instanceof HttpError) {
+        throw new StableNetworkError({
+          shortMessage: err instanceof HttpError ? `earn: Morpho API returned ${err.status} after retries` : `earn: failed to reach Morpho API after retries \u2014 ${String(err)}`,
+          url: MORPHO_API_URL,
+          cause: err
+        });
+      }
+      throw err;
+    }
+    const vault = body?.data?.vaultV2ByAddress;
+    if (!vault || typeof vault.netApy !== "number") {
+      throw new StableValidationError(
+        "apy",
+        void 0,
+        "earn: vault not found in Morpho API or unexpected response shape"
+      );
+    }
+    const rewards = vault.rewards.filter((r) => typeof r.supplyApr === "number" && r.supplyApr > 0).map((r) => ({ symbol: r.asset.symbol, address: r.asset.address, apr: r.supplyApr }));
+    return {
+      apy: vault.netApy,
+      native: vault.netApyExcludingRewards ?? 0,
+      rewards,
+      performanceFee: vault.performanceFee,
+      managementFee: vault.managementFee
+    };
+  }
+};
+
+// src/services/lifi.ts
+import {
+  createPublicClient as createPublicClient2,
+  createWalletClient,
+  erc20Abi as erc20Abi2,
+  formatUnits as formatUnits2,
+  http as http2,
+  isAddress as isAddress2,
+  parseUnits as parseUnits2
+} from "viem";
+
 // src/chains.ts
 var CHAIN_CONFIGS = {
   // ─── Testnet ──────────────────────────────────────────────────────────────
@@ -236,7 +416,7 @@ var LiFiService = class {
     const { fromToken, toToken, amount, fromDecimals = 6, toAddress } = params;
     const from = this._requireFrom();
     const chain = this.config.chainId.toString();
-    const fromAmountRaw = parseUnits(String(amount), fromDecimals).toString();
+    const fromAmountRaw = parseUnits2(String(amount), fromDecimals).toString();
     const qs = new URLSearchParams({
       fromChain: chain,
       toChain: chain,
@@ -267,7 +447,7 @@ var LiFiService = class {
       toChain: dst.id.toString(),
       fromToken,
       toToken,
-      fromAmount: parseUnits(String(amount), fromDecimals).toString(),
+      fromAmount: parseUnits2(String(amount), fromDecimals).toString(),
       fromAddress: from,
       ...recipient && { toAddress: recipient }
     });
@@ -286,7 +466,7 @@ var LiFiService = class {
     if (!dst) {
       throw new StableValidationError("toChain", toChain, `LI.FI bridge: unsupported destination chain "${toChain}"`);
     }
-    const fromAmountRaw = parseUnits(String(amount), fromDecimals).toString();
+    const fromAmountRaw = parseUnits2(String(amount), fromDecimals).toString();
     const qs = new URLSearchParams({
       fromChain: src.id.toString(),
       toChain: dst.id.toString(),
@@ -300,10 +480,10 @@ var LiFiService = class {
     return this._executeSwapQuote(quote, src.rpc, src.id);
   }
   _validateSwapParams({ fromToken, toToken, amount, toAddress }) {
-    if (!isAddress(fromToken)) {
+    if (!isAddress2(fromToken)) {
       throw new StableValidationError("fromToken", fromToken, `swap: invalid fromToken address "${fromToken}"`);
     }
-    if (!isAddress(toToken)) {
+    if (!isAddress2(toToken)) {
       throw new StableValidationError("toToken", toToken, `swap: invalid toToken address "${toToken}"`);
     }
     if (fromToken.toLowerCase() === toToken.toLowerCase()) {
@@ -312,21 +492,21 @@ var LiFiService = class {
     if (!Number.isFinite(amount) || amount <= 0) {
       throw new StableValidationError("amount", amount, "swap: amount must be a finite positive number");
     }
-    if (toAddress !== void 0 && !isAddress(toAddress)) {
+    if (toAddress !== void 0 && !isAddress2(toAddress)) {
       throw new StableValidationError("toAddress", toAddress, `swap: invalid toAddress "${toAddress}"`);
     }
   }
   _validateBridgeParams({ fromChain, toChain, fromToken, toToken, amount, recipient }) {
-    if (!isAddress(fromToken)) {
+    if (!isAddress2(fromToken)) {
       throw new StableValidationError("fromToken", fromToken, `LI.FI bridge: invalid fromToken address "${fromToken}"`);
     }
-    if (!isAddress(toToken)) {
+    if (!isAddress2(toToken)) {
       throw new StableValidationError("toToken", toToken, `LI.FI bridge: invalid toToken address "${toToken}"`);
     }
     if (!Number.isFinite(amount) || amount <= 0) {
       throw new StableValidationError("amount", amount, "LI.FI bridge: amount must be a finite positive number");
     }
-    if (recipient !== void 0 && !isAddress(recipient)) {
+    if (recipient !== void 0 && !isAddress2(recipient)) {
       throw new StableValidationError("recipient", recipient, `LI.FI bridge: invalid recipient address "${recipient}"`);
     }
     if (fromChain === toChain) {
@@ -394,7 +574,7 @@ var LiFiService = class {
   }
   _toSwapQuote(quote) {
     return {
-      toAmount: Number(formatUnits(BigInt(quote.estimate.toAmount), quote.action.toToken.decimals)),
+      toAmount: Number(formatUnits2(BigInt(quote.estimate.toAmount), quote.action.toToken.decimals)),
       fromAmount: BigInt(quote.estimate.fromAmount),
       fromToken: quote.action.fromToken.address,
       approvalAddress: quote.estimate.approvalAddress,
@@ -417,7 +597,7 @@ var LiFiService = class {
     const wc = this.config.walletClient ?? createWalletClient({
       account: this.config.account,
       chain: srcChain,
-      transport: this.config.transport ?? http(srcRpc)
+      transport: this.config.transport ?? http2(srcRpc)
     });
     try {
       await wc.switchChain({ id: srcChainId });
@@ -454,10 +634,10 @@ var LiFiService = class {
     const tokenAddr = quote.fromToken;
     const isNative = tokenAddr.toLowerCase() === "0x0000000000000000000000000000000000000000" || tokenAddr.toLowerCase() === "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
     if (isNative || !quote.approvalAddress) return;
-    const pc = createPublicClient({ chain: srcChain, transport: http(srcRpc) });
+    const pc = createPublicClient2({ chain: srcChain, transport: http2(srcRpc) });
     const allowance = await pc.readContract({
       address: tokenAddr,
-      abi: erc20Abi,
+      abi: erc20Abi2,
       functionName: "allowance",
       args: [from, quote.approvalAddress]
     });
@@ -466,7 +646,7 @@ var LiFiService = class {
     try {
       approveHash = await wc.writeContract({
         address: tokenAddr,
-        abi: erc20Abi,
+        abi: erc20Abi2,
         functionName: "approve",
         args: [quote.approvalAddress, quote.fromAmount],
         account: wc.account,
@@ -502,15 +682,387 @@ function isLiFiQuoteShape(v) {
   return isObject(tx) && typeof tx.to === "string" && typeof tx.data === "string" && typeof tx.chainId === "number" && isObject(est) && typeof est.fromAmount === "string" && typeof est.toAmount === "string" && isObject(act) && isObject(act.fromToken) && isObject(act.toToken);
 }
 
+// src/earn/morpho.ts
+import {
+  createPublicClient as createPublicClient3,
+  createWalletClient as createWalletClient2,
+  custom,
+  erc20Abi as erc20Abi3,
+  formatUnits as formatUnits3,
+  http as http3,
+  parseUnits as parseUnits3
+} from "viem";
+import {
+  MorphoClient as MorphoClient2,
+  isRequirementApproval,
+  isRequirementSignature
+} from "@morpho-org/morpho-sdk";
+var MorphoService = class {
+  constructor(config) {
+    this.config = config;
+    this.inFlight = /* @__PURE__ */ new Map();
+    this.chain = makeChain(config.chainId, config.rpc);
+    this.wc = config.walletClient ?? createWalletClient2({
+      account: config.account,
+      chain: this.chain,
+      transport: config.transport ?? http3(config.rpc)
+    });
+    const morphoWc = this.wc.chain?.id === config.chainId ? this.wc : createWalletClient2({
+      account: this.wc.account,
+      chain: this.chain,
+      transport: custom({ request: this.wc.request.bind(this.wc) })
+    });
+    this.morpho = new MorphoClient2(morphoWc, { supportSignature: true });
+    this.pc = createPublicClient3({ chain: this.chain, transport: http3(config.rpc) });
+  }
+  deposit(params) {
+    this._validateAmount(params.amount, "earn deposit");
+    if (params.depositBuffer !== void 0 && (params.depositBuffer <= 0 || params.depositBuffer > 1)) {
+      throw new StableValidationError("depositBuffer", params.depositBuffer, "earn deposit: depositBuffer must be > 0 and \u2264 1");
+    }
+    return this._withIdempotency(params.idempotencyKey, () => this._deposit(params));
+  }
+  async bulkDeposit(items, options = {}) {
+    const { idempotencyKey, stopOnError = false } = options;
+    const run = async () => {
+      const results = [];
+      for (const item of items) {
+        try {
+          const result = await this.deposit(item);
+          results.push({ status: "fulfilled", txHash: result.txHash, vault: item.vault, idempotencyKey: item.idempotencyKey });
+        } catch (err) {
+          const entry = { status: "rejected", error: String(err), vault: item.vault, idempotencyKey: item.idempotencyKey };
+          results.push(entry);
+          if (stopOnError) {
+            const succeeded2 = results.filter((r) => r.status === "fulfilled").length;
+            throw new StableBulkError({
+              shortMessage: "bulkDeposit halted on first failure",
+              results,
+              succeeded: succeeded2,
+              failed: results.length - succeeded2
+            });
+          }
+        }
+      }
+      const succeeded = results.filter((r) => r.status === "fulfilled").length;
+      return { results, succeeded, failed: results.length - succeeded, idempotencyKey };
+    };
+    return this._withIdempotency(idempotencyKey, run);
+  }
+  async bulkWithdraw(items, options = {}) {
+    const { idempotencyKey, stopOnError = false } = options;
+    const run = async () => {
+      const results = [];
+      for (const item of items) {
+        try {
+          const result = await this.withdraw(item);
+          results.push({ status: "fulfilled", txHash: result.txHash, idempotencyKey: item.idempotencyKey });
+        } catch (err) {
+          const entry = { status: "rejected", error: String(err), idempotencyKey: item.idempotencyKey };
+          results.push(entry);
+          if (stopOnError) {
+            const succeeded2 = results.filter((r) => r.status === "fulfilled").length;
+            throw new StableBulkError({
+              shortMessage: "bulkWithdraw halted on first failure",
+              results,
+              succeeded: succeeded2,
+              failed: results.length - succeeded2
+            });
+          }
+        }
+      }
+      const succeeded = results.filter((r) => r.status === "fulfilled").length;
+      return { results, succeeded, failed: results.length - succeeded, idempotencyKey };
+    };
+    return this._withIdempotency(idempotencyKey, run);
+  }
+  withdraw(params) {
+    this._validateAmount(params.amount, "earn withdraw");
+    return this._withIdempotency(params.idempotencyKey, () => this._withdraw(params));
+  }
+  redeem(params) {
+    this._validateShares(params.shares, "earn redeem");
+    return this._withIdempotency(params.idempotencyKey, () => this._redeem(params));
+  }
+  forceWithdraw(params) {
+    this._validateAmount(params.amount, "earn forceWithdraw");
+    return this._withIdempotency(params.idempotencyKey, () => this._forceWithdraw(params));
+  }
+  forceRedeem(params) {
+    this._validateShares(params.shares, "earn forceRedeem");
+    return this._withIdempotency(params.idempotencyKey, () => this._forceRedeem(params));
+  }
+  // ─── Private operations ──────────────────────────────────────────────────
+  async _deposit(params) {
+    const { amount, tokenDecimals, slippageTolerance, idempotencyKey, depositBuffer } = params;
+    const from = this._requireFrom();
+    const vaultAddr = params.vault ?? this.config.vault;
+    await this._switchChain();
+    const vault = this.morpho.vaultV2(vaultAddr, this.config.chainId);
+    const vaultData = await vault.getData();
+    const decimals = tokenDecimals ?? await this._resolveDecimals(vaultData.asset, "earn deposit");
+    const assetsRaw = parseUnits3(String(amount), decimals);
+    if (depositBuffer !== void 0) {
+      const bps = BigInt(Math.round(depositBuffer * 1e4));
+      const maxAllowed = vaultData.assetBalance * bps / 10000n;
+      if (assetsRaw > maxAllowed) {
+        const maxFormatted = Number(formatUnits3(maxAllowed, decimals));
+        const idleFormatted = Number(formatUnits3(vaultData.assetBalance, decimals));
+        throw new StableValidationError(
+          "amount",
+          amount,
+          `earn deposit: amount ${amount} exceeds deposit buffer \u2014 max ${maxFormatted} (${depositBuffer * 100}% of ${idleFormatted} idle liquidity)`
+        );
+      }
+    }
+    const depositAction = vault.deposit({
+      amount: assetsRaw,
+      userAddress: from,
+      accrualVault: vaultData,
+      slippageTolerance: slippageTolerance !== void 0 ? parseUnits3(String(slippageTolerance), 18) : void 0
+    });
+    const requirements = await depositAction.getRequirements();
+    let sig;
+    for (const req of requirements) {
+      if (isRequirementApproval(req)) {
+        const approveHash = await this._sendTx(req.to, req.data, req.value, from);
+        const approveReceipt = await this.pc.waitForTransactionReceipt({ hash: approveHash });
+        if (approveReceipt.status === "reverted") {
+          throw new StableTransactionError({
+            phase: "approve",
+            shortMessage: "earn deposit: token approval reverted on-chain",
+            txHash: approveReceipt.transactionHash,
+            chainId: this.config.chainId
+          });
+        }
+      } else if (isRequirementSignature(req)) {
+        sig = await req.sign(this.wc, from);
+      }
+    }
+    const tx = depositAction.buildTx(sig);
+    const hash = await this._sendTx(tx.to, tx.data, tx.value, from);
+    const receipt = await this.pc.waitForTransactionReceipt({ hash });
+    if (receipt.status === "reverted") {
+      throw new StableTransactionError({
+        phase: "receipt",
+        shortMessage: "earn deposit: vault deposit reverted on-chain",
+        txHash: receipt.transactionHash,
+        chainId: this.config.chainId
+      });
+    }
+    return { txHash: receipt.transactionHash, idempotencyKey };
+  }
+  async _withdraw(params) {
+    const { amount, tokenDecimals, idempotencyKey } = params;
+    const from = this._requireFrom();
+    const vaultAddr = this.config.vault;
+    await this._switchChain();
+    const vault = this.morpho.vaultV2(vaultAddr, this.config.chainId);
+    const vaultData = await vault.getData();
+    const decimals = tokenDecimals ?? await this._resolveDecimals(vaultData.asset, "earn withdraw");
+    const assetsRaw = parseUnits3(String(amount), decimals);
+    const tx = vault.withdraw({ amount: assetsRaw, userAddress: from }).buildTx();
+    const hash = await this._sendTx(tx.to, tx.data, tx.value, from);
+    const receipt = await this.pc.waitForTransactionReceipt({ hash });
+    if (receipt.status === "reverted") {
+      throw new StableTransactionError({
+        phase: "receipt",
+        shortMessage: "earn withdraw: vault withdraw reverted on-chain",
+        txHash: receipt.transactionHash,
+        chainId: this.config.chainId
+      });
+    }
+    return { txHash: receipt.transactionHash, idempotencyKey };
+  }
+  async _redeem(params) {
+    const { shares, shareDecimals, idempotencyKey } = params;
+    const from = this._requireFrom();
+    const vaultAddr = this.config.vault;
+    await this._switchChain();
+    let decimals = shareDecimals;
+    if (decimals === void 0) {
+      try {
+        decimals = await this.pc.readContract({ address: vaultAddr, abi: erc20Abi3, functionName: "decimals" });
+      } catch {
+        throw new StableValidationError(
+          "shareDecimals",
+          void 0,
+          `earn redeem: could not fetch share decimals for vault "${vaultAddr}" \u2014 pass shareDecimals explicitly`
+        );
+      }
+    }
+    const sharesRaw = parseUnits3(String(shares), decimals);
+    const vault = this.morpho.vaultV2(vaultAddr, this.config.chainId);
+    const tx = vault.redeem({ shares: sharesRaw, userAddress: from }).buildTx();
+    const hash = await this._sendTx(tx.to, tx.data, tx.value, from);
+    const receipt = await this.pc.waitForTransactionReceipt({ hash });
+    if (receipt.status === "reverted") {
+      throw new StableTransactionError({
+        phase: "receipt",
+        shortMessage: "earn redeem: vault redeem reverted on-chain",
+        txHash: receipt.transactionHash,
+        chainId: this.config.chainId
+      });
+    }
+    return { txHash: receipt.transactionHash, idempotencyKey };
+  }
+  async _forceWithdraw(params) {
+    const { amount, tokenDecimals, deallocations, idempotencyKey } = params;
+    const from = this._requireFrom();
+    const vaultAddr = this.config.vault;
+    await this._switchChain();
+    const vault = this.morpho.vaultV2(vaultAddr, this.config.chainId);
+    let decimals = tokenDecimals;
+    if (decimals === void 0) {
+      const vaultData = await vault.getData();
+      decimals = await this._resolveDecimals(vaultData.asset, "earn forceWithdraw");
+    }
+    const tx = vault.forceWithdraw({
+      deallocations: this._buildDeallocs(deallocations, decimals),
+      withdraw: { amount: parseUnits3(String(amount), decimals) },
+      userAddress: from
+    }).buildTx();
+    const hash = await this._sendTx(tx.to, tx.data, tx.value, from);
+    const receipt = await this.pc.waitForTransactionReceipt({ hash });
+    if (receipt.status === "reverted") {
+      throw new StableTransactionError({
+        phase: "receipt",
+        shortMessage: "earn forceWithdraw: vault forceWithdraw reverted on-chain",
+        txHash: receipt.transactionHash,
+        chainId: this.config.chainId
+      });
+    }
+    return { txHash: receipt.transactionHash, idempotencyKey };
+  }
+  async _forceRedeem(params) {
+    const { shares, shareDecimals, tokenDecimals, deallocations, idempotencyKey } = params;
+    const from = this._requireFrom();
+    const vaultAddr = this.config.vault;
+    await this._switchChain();
+    const vault = this.morpho.vaultV2(vaultAddr, this.config.chainId);
+    let shareDec = shareDecimals;
+    if (shareDec === void 0) {
+      try {
+        shareDec = await this.pc.readContract({ address: vaultAddr, abi: erc20Abi3, functionName: "decimals" });
+      } catch {
+        throw new StableValidationError(
+          "shareDecimals",
+          void 0,
+          `earn forceRedeem: could not fetch share decimals for vault "${vaultAddr}" \u2014 pass shareDecimals explicitly`
+        );
+      }
+    }
+    let assetDec = tokenDecimals;
+    if (assetDec === void 0) {
+      const vaultData = await vault.getData();
+      assetDec = await this._resolveDecimals(vaultData.asset, "earn forceRedeem");
+    }
+    const tx = vault.forceRedeem({
+      deallocations: this._buildDeallocs(deallocations, assetDec),
+      redeem: { shares: parseUnits3(String(shares), shareDec) },
+      userAddress: from
+    }).buildTx();
+    const hash = await this._sendTx(tx.to, tx.data, tx.value, from);
+    const receipt = await this.pc.waitForTransactionReceipt({ hash });
+    if (receipt.status === "reverted") {
+      throw new StableTransactionError({
+        phase: "receipt",
+        shortMessage: "earn forceRedeem: vault forceRedeem reverted on-chain",
+        txHash: receipt.transactionHash,
+        chainId: this.config.chainId
+      });
+    }
+    return { txHash: receipt.transactionHash, idempotencyKey };
+  }
+  _buildDeallocs(deallocations, assetDecimals) {
+    return deallocations.map((d) => ({
+      adapter: d.adapter,
+      amount: parseUnits3(String(d.amount), assetDecimals),
+      // MarketParams in the Morpho SDK has computed fields (id, liquidationIncentiveFactor)
+      // not present in our user-facing type; the plain object is structurally compatible for ABI encoding.
+      ...d.marketParams && { marketParams: d.marketParams }
+    }));
+  }
+  // ─── Helpers ─────────────────────────────────────────────────────────────
+  _requireFrom() {
+    const from = this.wc.account?.address;
+    if (!from) {
+      throw new StableValidationError(
+        "signer",
+        void 0,
+        "earn: requires a signer \u2014 set walletClient or account in StableConfig"
+      );
+    }
+    return from;
+  }
+  async _switchChain() {
+    try {
+      await this.wc.switchChain({ id: this.config.chainId });
+    } catch (err) {
+      if (err.code === 4001) {
+        throw new StableTransactionError({
+          phase: "switch_chain",
+          shortMessage: `earn: wallet rejected switch to chain ${this.config.chainId}`,
+          chainId: this.config.chainId,
+          cause: err
+        });
+      }
+    }
+  }
+  async _sendTx(to, data, value, from) {
+    try {
+      return await this.wc.sendTransaction({ to, data, value, account: from, chain: this.chain });
+    } catch (err) {
+      throw new StableTransactionError({
+        phase: "send",
+        shortMessage: "earn: transaction send failed",
+        chainId: this.config.chainId,
+        cause: err
+      });
+    }
+  }
+  async _resolveDecimals(asset, op) {
+    try {
+      return await retryWithBackoff(
+        () => this.pc.readContract({ address: asset, abi: erc20Abi3, functionName: "decimals" })
+      );
+    } catch {
+      throw new StableValidationError(
+        "tokenDecimals",
+        void 0,
+        `${op}: could not fetch decimals for asset "${asset}" \u2014 pass tokenDecimals explicitly`
+      );
+    }
+  }
+  _withIdempotency(key, fn) {
+    if (!key) return fn();
+    const existing = this.inFlight.get(key);
+    if (existing) return existing;
+    const promise = fn().finally(() => this.inFlight.delete(key));
+    this.inFlight.set(key, promise);
+    return promise;
+  }
+  _validateAmount(amount, op) {
+    if (!Number.isFinite(amount) || amount <= 0) {
+      throw new StableValidationError("amount", amount, `${op}: amount must be a finite positive number`);
+    }
+  }
+  _validateShares(shares, op) {
+    if (!Number.isFinite(shares) || shares <= 0) {
+      throw new StableValidationError("shares", shares, `${op}: shares must be a finite positive number`);
+    }
+  }
+};
+
 // src/stable.ts
 function validateTransferParams({ to, amount, token, tokenDecimals }) {
-  if (!isAddress2(to)) {
+  if (!isAddress3(to)) {
     throw new StableValidationError("to", to, `transfer: invalid recipient address "${to}"`);
   }
   if (!Number.isFinite(amount) || amount <= 0) {
     throw new StableValidationError("amount", amount, "transfer: amount must be a finite positive number");
   }
-  if (token !== void 0 && !isAddress2(token)) {
+  if (token !== void 0 && !isAddress3(token)) {
     throw new StableValidationError("token", token, `transfer: invalid token address "${token}"`);
   }
   if (tokenDecimals !== void 0 && (!Number.isInteger(tokenDecimals) || tokenDecimals < 0 || tokenDecimals > 77)) {
@@ -520,7 +1072,7 @@ function validateTransferParams({ to, amount, token, tokenDecimals }) {
 async function resolveTokenDecimals(publicClient, token, tokenDecimals) {
   if (tokenDecimals !== void 0) return tokenDecimals;
   try {
-    return await publicClient.readContract({ address: token, abi: erc20Abi2, functionName: "decimals" });
+    return await publicClient.readContract({ address: token, abi: erc20Abi4, functionName: "decimals" });
   } catch {
     throw new StableValidationError(
       "tokenDecimals",
@@ -541,9 +1093,9 @@ async function executeTokenTransfer(wc, publicClient, token, to, amount, tokenDe
   const decimals = await resolveTokenDecimals(publicClient, token, tokenDecimals);
   return wc.writeContract({
     address: token,
-    abi: erc20Abi2,
+    abi: erc20Abi4,
     functionName: "transfer",
-    args: [to, parseUnits2(String(amount), decimals)],
+    args: [to, parseUnits4(String(amount), decimals)],
     account: acc,
     chain
   });
@@ -553,20 +1105,32 @@ function createStable({
   rpc: rpcOverride,
   account,
   transport,
-  walletClient
+  walletClient,
+  earn: earnConfig
 }) {
-  const chain = network === "mainnet" /* Mainnet */ ? stableMainnet : stableTestnet;
+  const chain = network === "mainnet" /* Mainnet */ ? stableMainnet2 : stableTestnet2;
   const rpc = (rpcOverride ?? chain.rpcUrls.default.http[0]).replace(/\/$/, "");
   const signerConfig = { account, transport, walletClient };
   const lifi = new LiFiService({ ...signerConfig, rpc, chainId: chain.id });
+  const morpho = earnConfig ? new MorphoService({ ...signerConfig, rpc, chainId: chain.id, vault: earnConfig.vault }) : null;
+  function requireEarn() {
+    if (!morpho) {
+      throw new StableValidationError(
+        "earn",
+        void 0,
+        "stable.earn.*: pass earn: { vault: '0x...' } to createStable() to enable earn operations"
+      );
+    }
+    return morpho;
+  }
   async function transfer(params) {
     validateTransferParams(params);
     const { from, to, amount, token, tokenDecimals } = params;
     const acc = walletClient?.account ?? account ?? from;
-    const wc = walletClient ?? createWalletClient2({
+    const wc = walletClient ?? createWalletClient3({
       account: acc,
       chain,
-      transport: transport ?? http2(rpc)
+      transport: transport ?? http4(rpc)
     });
     try {
       await wc.switchChain({ id: chain.id });
@@ -578,8 +1142,8 @@ function createStable({
         cause: err
       });
     }
-    const publicClient = createPublicClient2({ chain, transport: http2(rpc) });
-    const hash = token !== void 0 ? await executeTokenTransfer(wc, publicClient, token, to, amount, tokenDecimals, acc, chain) : await wc.sendTransaction({ account: acc, chain, to, value: parseUnits2(String(amount), 18) });
+    const publicClient = createPublicClient4({ chain, transport: http4(rpc) });
+    const hash = token !== void 0 ? await executeTokenTransfer(wc, publicClient, token, to, amount, tokenDecimals, acc, chain) : await wc.sendTransaction({ account: acc, chain, to, value: parseUnits4(String(amount), 18) });
     const receipt = await publicClient.waitForTransactionReceipt({ hash });
     if (receipt.status === "reverted") {
       throw new StableTransactionError({
@@ -591,28 +1155,50 @@ function createStable({
     }
     return { txHash: receipt.transactionHash };
   }
-  function quoteBridge(params) {
-    return lifi.quoteBridge(params);
-  }
-  function bridge(params) {
-    return lifi.bridge(params);
-  }
   return {
     transfer,
-    quoteBridge,
-    bridge,
+    quoteBridge: (params) => lifi.quoteBridge(params),
+    bridge: (params) => lifi.bridge(params),
     quoteSwap: (params) => lifi.quoteSwap(params),
-    swap: (params) => lifi.swap(params)
+    swap: (params) => lifi.swap(params),
+    earn: {
+      deposit: (params) => requireEarn().deposit(params),
+      bulkDeposit: (items, options) => requireEarn().bulkDeposit(items, options),
+      withdraw: (params) => requireEarn().withdraw(params),
+      bulkWithdraw: (items, options) => requireEarn().bulkWithdraw(items, options),
+      redeem: (params) => requireEarn().redeem(params),
+      forceWithdraw: (params) => requireEarn().forceWithdraw(params),
+      forceRedeem: (params) => requireEarn().forceRedeem(params)
+    }
+  };
+}
+function createStableReader(config) {
+  const reader = new EarnReader(config);
+  return {
+    earn: {
+      getYield: () => reader.getYield(),
+      position: () => reader.position(),
+      preview: (params) => reader.preview(params),
+      withdrawability: (params) => reader.withdrawability(params)
+    }
   };
 }
+
+// src/constants.ts
+var STABLE_USDT_ADDRESS = "0x779ded0c9e1022225f8e0630b35a9b54be713736";
+var STABLE_VAULT_ADDRESS = "0x461eF73F640456138242398a39AB48a557A49293";
 export {
   CHAIN_CONFIGS,
   Chain,
   Network,
+  STABLE_USDT_ADDRESS,
+  STABLE_VAULT_ADDRESS,
+  StableBulkError,
   StableError,
   StableNetworkError,
   StableQuoteError,
   StableTransactionError,
   StableValidationError,
-  createStable
+  createStable,
+  createStableReader
 };