@oydual31/more-vaults-sdk 0.1.0

package/src/ethers/index.ts

@@ -0,0 +1,103 @@
+// MoreVaults SDK -- ethers.js v6
+// Barrel export for all flows and utilities.
+
+// --- Types ---
+export type {
+  VaultAddresses,
+  DepositResult,
+  RedeemResult,
+  AsyncRequestResult,
+  CrossChainRequestInfo,
+  ActionTypeValue,
+  Signer,
+  Provider,
+  ContractTransactionReceipt,
+} from "./types";
+export { ActionType } from "./types";
+
+// --- ABIs ---
+export {
+  VAULT_ABI,
+  BRIDGE_ABI,
+  CONFIG_ABI,
+  ERC20_ABI,
+  OFT_ABI,
+  METADATA_ABI,
+} from "./abis";
+
+// --- Errors ---
+export {
+  MoreVaultsError,
+  VaultPausedError,
+  CapacityFullError,
+  NotWhitelistedError,
+  InsufficientLiquidityError,
+  CCManagerNotConfiguredError,
+  EscrowNotConfiguredError,
+  NotHubVaultError,
+  MissingEscrowAddressError,
+} from "./errors";
+
+// --- Deposit flows ---
+export {
+  depositSimple,
+  depositMultiAsset,
+  depositCrossChainOracleOn,
+  depositAsync,
+  mintAsync,
+  smartDeposit,
+} from "./depositFlows";
+
+// --- Cross-chain flows ---
+export {
+  depositFromSpoke,
+  depositFromSpokeAsync,
+  quoteDepositFromSpokeFee,
+} from "./crossChainFlows";
+
+// --- Redeem flows ---
+export {
+  redeemShares,
+  withdrawAssets,
+  requestRedeem,
+  getWithdrawalRequest,
+  redeemAsync,
+  bridgeSharesToHub,
+} from "./redeemFlows";
+
+// --- Utilities ---
+export {
+  ensureAllowance,
+  quoteLzFee,
+  isAsyncMode,
+  getAsyncRequestStatus,
+  getVaultStatus,
+} from "./utils";
+export type { VaultStatus, VaultMode } from "./utils";
+
+// --- Pre-flight validation ---
+export { preflightSync, preflightAsync, preflightRedeemLiquidity } from "./preflight";
+
+// --- User Helpers ---
+export {
+  getUserPosition,
+  previewDeposit,
+  previewRedeem,
+  canDeposit,
+  getVaultMetadata,
+  getAsyncRequestStatusLabel,
+  getUserBalances,
+  getMaxWithdrawable,
+  getVaultSummary,
+} from "./userHelpers";
+export type {
+  UserPosition,
+  DepositEligibility,
+  DepositBlockReason,
+  VaultMetadata,
+  AsyncRequestStatus,
+  AsyncRequestStatusInfo,
+  UserBalances,
+  MaxWithdrawable,
+  VaultSummary,
+} from "./userHelpers";

package/src/ethers/preflight.ts

@@ -0,0 +1,156 @@
+/**
+ * Pre-flight validation helpers for MoreVaults ethers.js v6 SDK flows.
+ *
+ * Each function reads on-chain state and throws a descriptive error BEFORE
+ * the actual contract call, so developers see a clear, actionable message
+ * instead of a raw VM revert.
+ */
+
+import { Contract, ZeroAddress } from "ethers";
+import type { Provider } from "ethers";
+import { CONFIG_ABI, BRIDGE_ABI, VAULT_ABI, ERC20_ABI } from "./abis";
+
+/**
+ * Pre-flight checks for async cross-chain flows (D4 / D5 / R5).
+ *
+ * Validates that:
+ * 1. The CCManager is configured on the vault.
+ * 2. An escrow is registered in the vault's registry.
+ * 3. The vault is a hub (required for async flows).
+ * 4. The vault does NOT have oracle-based cross-chain accounting enabled
+ *    (oracle-on vaults should use depositSimple / depositCrossChainOracleOn).
+ * 5. The vault is not paused.
+ *
+ * All reads that are independent of each other are executed in parallel via
+ * Promise.all to minimise latency.
+ *
+ * @param provider  Read-only provider for contract reads
+ * @param vault     Vault address (diamond proxy)
+ * @param escrow    Escrow address from VaultAddresses
+ */
+export async function preflightAsync(
+  provider: Provider,
+  vault: string,
+  escrow: string
+): Promise<void> {
+  const config = new Contract(vault, CONFIG_ABI, provider);
+  const bridge = new Contract(vault, BRIDGE_ABI, provider);
+
+  // Parallel read: ccManager, escrow, isHub, oraclesCrossChainAccounting, paused
+  const [ccManager, registeredEscrow, isHub, oraclesEnabled, isPaused] =
+    await Promise.all([
+      config.getCrossChainAccountingManager() as Promise<string>,
+      config.getEscrow() as Promise<string>,
+      config.isHub() as Promise<boolean>,
+      bridge.oraclesCrossChainAccounting() as Promise<boolean>,
+      config.paused() as Promise<boolean>,
+    ]);
+
+  if (ccManager === ZeroAddress) {
+    throw new Error(
+      `[MoreVaults] CCManager not configured on vault ${vault}. Call setCrossChainAccountingManager(ccManagerAddress) as vault owner first.`
+    );
+  }
+
+  if (registeredEscrow === ZeroAddress) {
+    throw new Error(
+      `[MoreVaults] Escrow not configured for vault ${vault}. The registry must have an escrow set for this vault.`
+    );
+  }
+
+  if (!isHub) {
+    throw new Error(
+      `[MoreVaults] Vault ${vault} is not a hub vault. Async flows (D4/D5/R5) only work on hub vaults.`
+    );
+  }
+
+  if (oraclesEnabled) {
+    throw new Error(
+      `[MoreVaults] Vault ${vault} has oracle-based cross-chain accounting enabled. Use depositSimple/depositCrossChainOracleOn instead of async flows.`
+    );
+  }
+
+  if (isPaused) {
+    throw new Error(
+      `[MoreVaults] Vault ${vault} is paused. Cannot perform any actions.`
+    );
+  }
+}
+
+/**
+ * Pre-flight liquidity check for async redeem (R5).
+ *
+ * Reads the hub's liquid balance of the underlying token and compares it
+ * against the assets the user expects to receive. If the hub does not hold
+ * enough liquid assets the redeem will be auto-refunded after the LZ round-trip,
+ * wasting the LayerZero fee.
+ *
+ * @param provider  Read-only provider for contract reads
+ * @param vault     Vault address (diamond proxy)
+ * @param shares    Shares the user intends to redeem
+ */
+export async function preflightRedeemLiquidity(
+  provider: Provider,
+  vault: string,
+  shares: bigint
+): Promise<void> {
+  const vaultContract = new Contract(vault, VAULT_ABI, provider);
+
+  const underlying: string = await vaultContract.asset();
+
+  const underlyingContract = new Contract(underlying, ERC20_ABI, provider);
+  const [hubLiquid, assetsNeeded]: [bigint, bigint] = await Promise.all([
+    underlyingContract.balanceOf(vault),
+    vaultContract.convertToAssets(shares),
+  ]);
+
+  if (hubLiquid < assetsNeeded) {
+    throw new Error(
+      `[MoreVaults] Insufficient hub liquidity for redeem.\n` +
+      `  Hub liquid balance : ${hubLiquid}\n` +
+      `  Estimated required : ${assetsNeeded}\n` +
+      `Submitting this redeem will waste the LayerZero fee — the request will be auto-refunded.\n` +
+      `Ask the vault curator to repatriate liquidity from spoke chains first.`
+    );
+  }
+}
+
+/**
+ * Pre-flight checks for synchronous deposit flows (D1 / D3).
+ *
+ * Validates that:
+ * 1. The vault is not paused.
+ * 2. The vault still has deposit capacity (maxDeposit > 0).
+ *
+ * Both reads are executed in parallel.
+ *
+ * @param provider  Read-only provider for contract reads
+ * @param vault     Vault address (diamond proxy)
+ */
+export async function preflightSync(
+  provider: Provider,
+  vault: string
+): Promise<void> {
+  const config = new Contract(vault, CONFIG_ABI, provider);
+
+  // Run paused and maxDeposit in parallel.
+  // maxDeposit(ZeroAddress) may REVERT on whitelisted vaults — catch separately.
+  const [isPaused, depositCapResult] = await Promise.all([
+    config.paused() as Promise<boolean>,
+    (config.maxDeposit(ZeroAddress) as Promise<bigint>).catch(() => null as null),
+  ]);
+
+  if (isPaused) {
+    throw new Error(
+      `[MoreVaults] Vault ${vault} is paused. Cannot perform any actions.`
+    );
+  }
+
+  // null means maxDeposit reverted → whitelist vault — skip capacity check
+  // (the user may still be whitelisted; canDeposit will do user-specific check)
+  if (depositCapResult !== null && depositCapResult === 0n) {
+    throw new Error(
+      `[MoreVaults] Vault ${vault} has reached deposit capacity. No more deposits accepted.`
+    );
+  }
+}

package/src/ethers/redeemFlows.ts

@@ -0,0 +1,286 @@
+import { Contract, AbiCoder, zeroPadValue, Signer, Provider } from "ethers";
+import {
+  VAULT_ABI,
+  BRIDGE_ABI,
+  ERC20_ABI,
+  OFT_ABI,
+} from "./abis";
+import {
+  VaultAddresses,
+  RedeemResult,
+  AsyncRequestResult,
+  ActionType,
+} from "./types";
+import type { ContractTransactionReceipt } from "ethers";
+import { preflightAsync, preflightRedeemLiquidity } from "./preflight";
+import { MissingEscrowAddressError } from "./errors";
+
+/**
+ * Ensure `spender` has at least `amount` allowance from `owner`.
+ */
+async function ensureAllowance(
+  signer: Signer,
+  token: string,
+  spender: string,
+  amount: bigint
+): Promise<void> {
+  const owner = await signer.getAddress();
+  const erc20 = new Contract(token, ERC20_ABI, signer);
+  const current: bigint = await erc20.allowance(owner, spender);
+  if (current < amount) {
+    const tx = await erc20.approve(spender, amount);
+    await tx.wait();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// R1 -- Simple redeem
+// ---------------------------------------------------------------------------
+
+/**
+ * Redeem `shares` for underlying assets.
+ *
+ * TXs: 1 redeem.
+ * Pre-condition: if withdrawal queue is enabled, `requestRedeem` must have
+ * been called and the timelock must have elapsed.
+ *
+ * @param signer    - Wallet holding the shares.
+ * @param addresses - Vault addresses. Only `vault` is used.
+ * @param shares    - Number of shares to redeem.
+ * @param receiver  - Address that will receive the underlying assets.
+ * @param owner     - Address that owns the shares.
+ * @returns Assets received and the transaction receipt.
+ */
+export async function redeemShares(
+  signer: Signer,
+  addresses: VaultAddresses,
+  shares: bigint,
+  receiver: string,
+  owner: string
+): Promise<RedeemResult> {
+  const vault = new Contract(addresses.vault, VAULT_ABI, signer);
+
+  // Static call to get the return value (assets) before broadcasting
+  const assets: bigint = await vault.redeem.staticCall(shares, receiver, owner);
+
+  const tx = await vault.redeem(shares, receiver, owner);
+  const receipt = await tx.wait();
+
+  return { receipt, assets };
+}
+
+// ---------------------------------------------------------------------------
+// R2 -- Simple withdraw
+// ---------------------------------------------------------------------------
+
+/**
+ * Withdraw exact `assets` amount of underlying tokens by burning shares.
+ *
+ * TXs: 1 withdraw.
+ *
+ * @param signer    - Wallet holding the shares.
+ * @param addresses - Vault addresses. Only `vault` is used.
+ * @param assets    - Exact amount of underlying tokens to withdraw.
+ * @param receiver  - Address that will receive the tokens.
+ * @param owner     - Address that owns the shares.
+ * @returns Assets received and the transaction receipt.
+ */
+export async function withdrawAssets(
+  signer: Signer,
+  addresses: VaultAddresses,
+  assets: bigint,
+  receiver: string,
+  owner: string
+): Promise<RedeemResult> {
+  const vault = new Contract(addresses.vault, VAULT_ABI, signer);
+  const tx = await vault.withdraw(assets, receiver, owner);
+  const receipt = await tx.wait();
+
+  return { receipt, assets };
+}
+
+// ---------------------------------------------------------------------------
+// R3 -- Queue redeem, no timelock (2 TXs)
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit a withdrawal queue request for `shares`.
+ *
+ * TXs: 1 requestRedeem.
+ * After this call and once any timelock elapses, call `redeemShares()` to
+ * complete the withdrawal.
+ *
+ * @param signer    - Wallet holding the shares.
+ * @param addresses - Vault addresses. Only `vault` is used.
+ * @param shares    - Number of shares to queue for redemption.
+ * @param owner     - Address on whose behalf to request.
+ * @returns Transaction receipt.
+ */
+export async function requestRedeem(
+  signer: Signer,
+  addresses: VaultAddresses,
+  shares: bigint,
+  owner: string
+): Promise<{ receipt: ContractTransactionReceipt }> {
+  const vault = new Contract(addresses.vault, VAULT_ABI, signer);
+  const tx = await vault.requestRedeem(shares, owner);
+  const receipt = await tx.wait();
+  return { receipt };
+}
+
+// ---------------------------------------------------------------------------
+// R4 -- Queue redeem with timelock (helper to check status)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the current withdrawal request for an owner.
+ * Returns null if no pending request exists.
+ *
+ * @param provider - JSON-RPC provider.
+ * @param vault    - Vault (diamond) address.
+ * @param owner    - Address of the shares owner.
+ * @returns The request details or null.
+ */
+export async function getWithdrawalRequest(
+  provider: Provider,
+  vault: string,
+  owner: string
+): Promise<{ shares: bigint; timelockEndsAt: bigint } | null> {
+  const vaultContract = new Contract(vault, VAULT_ABI, provider);
+  const [shares, timelockEndsAt]: [bigint, bigint] =
+    await vaultContract.getWithdrawalRequest(owner);
+
+  if (shares === 0n) {
+    return null;
+  }
+
+  return { shares, timelockEndsAt };
+}
+
+// ---------------------------------------------------------------------------
+// R5 -- Cross-chain oracle OFF, async redeem
+// ---------------------------------------------------------------------------
+
+/**
+ * Initiate an asynchronous cross-chain redeem request.
+ *
+ * CRITICAL: shares are approved to the **escrow** address (vault share token).
+ * amountLimit MUST be 0 for redeems.
+ *
+ * TXs: 1 approve to escrow for shares (if needed) + 1 initVaultActionRequest.
+ * Wait: LayerZero cross-chain fulfillment.
+ *
+ * @param signer       - Wallet holding the shares.
+ * @param addresses    - Must include `vault` and `escrow`.
+ * @param shares       - Number of shares to redeem.
+ * @param receiver     - Address that will receive the underlying assets.
+ * @param owner        - Address that owns the shares.
+ * @param lzFee        - Native fee for LayerZero message.
+ * @param extraOptions - Optional LZ adapter parameters (bytes).
+ * @returns The request GUID for tracking and the transaction receipt.
+ */
+export async function redeemAsync(
+  signer: Signer,
+  addresses: VaultAddresses,
+  shares: bigint,
+  receiver: string,
+  owner: string,
+  lzFee: bigint,
+  extraOptions: string = "0x"
+): Promise<AsyncRequestResult> {
+  const provider = signer.provider!;
+  if (!addresses.escrow) throw new MissingEscrowAddressError();
+  const escrow = addresses.escrow;
+
+  // Pre-flight: validate async cross-chain setup before sending any transaction
+  await preflightAsync(provider, addresses.vault, escrow);
+
+  // Pre-flight: check hub has enough liquid assets — avoids wasting LZ fee on a guaranteed refund
+  await preflightRedeemLiquidity(provider, addresses.vault, shares);
+
+  // CRITICAL: approve ESCROW for shares (the vault token itself)
+  await ensureAllowance(signer, addresses.vault, escrow, shares);
+
+  const coder = AbiCoder.defaultAbiCoder();
+  const actionCallData = coder.encode(
+    ["uint256", "address", "address"],
+    [shares, receiver, owner]
+  );
+
+  const bridge = new Contract(addresses.vault, BRIDGE_ABI, signer);
+
+  // Static call first to capture the return value (guid) before broadcasting
+  const guid: string = await bridge.initVaultActionRequest.staticCall(
+    ActionType.REDEEM,
+    actionCallData,
+    0,
+    extraOptions,
+    { value: lzFee }
+  );
+
+  const tx = await bridge.initVaultActionRequest(
+    ActionType.REDEEM,
+    actionCallData,
+    0, // amountLimit MUST be 0 for redeems
+    extraOptions,
+    { value: lzFee }
+  );
+  const receipt = await tx.wait();
+
+  return { receipt, guid };
+}
+
+// ---------------------------------------------------------------------------
+// R6 -- Spoke -> Hub redeem (step 1: bridge shares to hub)
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge shares from a spoke chain to the hub chain (step 1 of 2).
+ *
+ * After the shares arrive on the hub chain, call `redeemShares()` on the
+ * hub to complete the redemption.
+ *
+ * TXs: 1 approve (if needed) + 1 OFT.send().
+ * Wait: LayerZero delivery (typically 1-5 minutes).
+ *
+ * @param signer      - Wallet on the spoke chain holding shares.
+ * @param shareOFT    - OFTAdapter address for the share token on spoke.
+ * @param hubChainEid - LayerZero endpoint ID for the hub chain (e.g. 30332 for Flow EVM).
+ * @param shares      - Number of shares to bridge.
+ * @param receiver    - Address on hub chain that will receive the shares.
+ * @param lzFee       - Native fee for LayerZero message.
+ * @returns Transaction receipt.
+ */
+export async function bridgeSharesToHub(
+  signer: Signer,
+  shareOFT: string,
+  hubChainEid: number,
+  shares: bigint,
+  receiver: string,
+  lzFee: bigint
+): Promise<{ receipt: ContractTransactionReceipt }> {
+  await ensureAllowance(signer, shareOFT, shareOFT, shares);
+
+  const oft = new Contract(shareOFT, OFT_ABI, signer);
+  const refundAddress = await signer.getAddress();
+  const toBytes32 = zeroPadValue(receiver, 32);
+
+  const sendParam = {
+    dstEid: hubChainEid,
+    to: toBytes32,
+    amountLD: shares,
+    minAmountLD: shares, // no slippage on share bridging
+    extraOptions: "0x",
+    composeMsg: "0x",
+    oftCmd: "0x",
+  };
+
+  const msgFee = { nativeFee: lzFee, lzTokenFee: 0n };
+
+  const tx = await oft.send(sendParam, msgFee, refundAddress, {
+    value: lzFee,
+  });
+  const receipt = await tx.wait();
+
+  return { receipt };
+}

package/src/ethers/types.ts

@@ -0,0 +1,67 @@
+import type { Signer, Provider, ContractTransactionReceipt } from "ethers";
+
+/** Addresses involved in vault operations. */
+export interface VaultAddresses {
+  /** Hub vault (diamond proxy) address. */
+  vault: string;
+  /** MoreVaultsEscrow address for cross-chain locking. */
+  escrow?: string;
+  /** OFTAdapter address for share token bridging (cross-chain only). */
+  shareOFT?: string;
+  /** OFT address for USDC bridging (cross-chain only). */
+  usdcOFT?: string;
+}
+
+/** Result of a synchronous deposit or mint. */
+export interface DepositResult {
+  receipt: ContractTransactionReceipt;
+  /** Number of vault shares minted. */
+  shares: bigint;
+}
+
+/** Result of a synchronous redeem or withdraw. */
+export interface RedeemResult {
+  receipt: ContractTransactionReceipt;
+  /** Number of underlying assets returned. */
+  assets: bigint;
+}
+
+/** Result of an asynchronous cross-chain request. */
+export interface AsyncRequestResult {
+  receipt: ContractTransactionReceipt;
+  /** bytes32 request GUID for tracking fulfillment. */
+  guid: string;
+}
+
+/**
+ * ActionType enum matching MoreVaultsLib.ActionType on-chain values.
+ *
+ * DEPOSIT = 0, MINT = 1, WITHDRAW = 2, REDEEM = 3,
+ * MULTI_ASSETS_DEPOSIT = 4, ACCRUE_FEES = 5
+ */
+export const ActionType = {
+  DEPOSIT: 0,
+  MINT: 1,
+  WITHDRAW: 2,
+  REDEEM: 3,
+  MULTI_ASSETS_DEPOSIT: 4,
+  ACCRUE_FEES: 5,
+} as const;
+
+export type ActionTypeValue = (typeof ActionType)[keyof typeof ActionType];
+
+/** Cross-chain request info returned by getRequestInfo. */
+export interface CrossChainRequestInfo {
+  initiator: string;
+  timestamp: bigint;
+  actionType: number;
+  actionCallData: string;
+  fulfilled: boolean;
+  finalized: boolean;
+  refunded: boolean;
+  totalAssets: bigint;
+  finalizationResult: bigint;
+  amountLimit: bigint;
+}
+
+export type { Signer, Provider, ContractTransactionReceipt };