@oydual31/more-vaults-sdk 0.1.0

package/src/viem/preflight.ts

@@ -0,0 +1,204 @@
+/**
+ * Pre-flight validation helpers for MoreVaults 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 { type Address, type PublicClient, getAddress, zeroAddress } from 'viem'
+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 publicClient  Public client for contract reads
+ * @param vault         Vault address (diamond proxy)
+ * @param escrow        Escrow address from VaultAddresses
+ */
+export async function preflightAsync(
+  publicClient: PublicClient,
+  vault: Address,
+  escrow: Address,
+): Promise<void> {
+  const v = getAddress(vault)
+
+  // Parallel read: ccManager, escrow, isHub, oraclesCrossChainAccounting, paused
+  const [ccManager, registeredEscrow, isHub, oraclesEnabled, isPaused] =
+    await Promise.all([
+      publicClient.readContract({
+        address: v,
+        abi: CONFIG_ABI,
+        functionName: 'getCrossChainAccountingManager',
+      }),
+      publicClient.readContract({
+        address: v,
+        abi: CONFIG_ABI,
+        functionName: 'getEscrow',
+      }),
+      publicClient.readContract({
+        address: v,
+        abi: CONFIG_ABI,
+        functionName: 'isHub',
+      }),
+      publicClient.readContract({
+        address: v,
+        abi: BRIDGE_ABI,
+        functionName: 'oraclesCrossChainAccounting',
+      }),
+      publicClient.readContract({
+        address: v,
+        abi: CONFIG_ABI,
+        functionName: 'paused',
+      }),
+    ])
+
+  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.
+ *
+ * This check is best-effort: liquidity could change in the 1-5 minutes between
+ * submission and execution. But it catches the common case where the hub is
+ * already under-funded at the time of submission.
+ *
+ * @param publicClient  Public client for contract reads
+ * @param vault         Vault address (diamond proxy)
+ * @param shares        Shares the user intends to redeem
+ */
+export async function preflightRedeemLiquidity(
+  publicClient: PublicClient,
+  vault: Address,
+  shares: bigint,
+): Promise<void> {
+  const v = getAddress(vault)
+
+  // Need underlying address first
+  const underlying = await publicClient.readContract({
+    address: v,
+    abi: VAULT_ABI,
+    functionName: 'asset',
+  })
+
+  // Parallel: hub liquid balance + estimated assets for these shares
+  const [hubLiquid, assetsNeeded] = await Promise.all([
+    publicClient.readContract({
+      address: getAddress(underlying as Address),
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [v],
+    }),
+    publicClient.readContract({
+      address: v,
+      abi: VAULT_ABI,
+      functionName: 'convertToAssets',
+      args: [shares],
+    }),
+  ])
+
+  if ((hubLiquid as bigint) < (assetsNeeded as bigint)) {
+    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 publicClient  Public client for contract reads
+ * @param vault         Vault address (diamond proxy)
+ */
+export async function preflightSync(
+  publicClient: PublicClient,
+  vault: Address,
+): Promise<void> {
+  const v = getAddress(vault)
+
+  // Run paused and maxDeposit in parallel.
+  // maxDeposit(address(0)) may REVERT on whitelisted vaults — catch separately.
+  const [isPaused, depositCapResult] = await Promise.all([
+    publicClient.readContract({
+      address: v,
+      abi: CONFIG_ABI,
+      functionName: 'paused',
+    }),
+    publicClient
+      .readContract({
+        address: v,
+        abi: CONFIG_ABI,
+        functionName: 'maxDeposit',
+        args: [zeroAddress],
+      })
+      .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/viem/redeemFlows.ts

@@ -0,0 +1,337 @@
+import {
+  type Address,
+  type Hash,
+  type PublicClient,
+  type WalletClient,
+  encodeAbiParameters,
+  getAddress,
+  pad,
+} from 'viem'
+import { VAULT_ABI, BRIDGE_ABI, OFT_ABI } from './abis'
+import type {
+  VaultAddresses,
+  RedeemResult,
+  AsyncRequestResult,
+} from './types'
+import { ActionType } from './types'
+import { ensureAllowance } from './utils'
+import { preflightAsync, preflightRedeemLiquidity } from './preflight'
+import { MissingEscrowAddressError } from './errors'
+
+/**
+ * R1 — Simple share redemption (ERC-4626 standard).
+ *
+ * Burns `shares` and returns the proportional amount of underlying assets.
+ * If a withdrawal queue is enabled, the caller must have previously called
+ * `requestRedeem` and waited for the timelock to expire.
+ *
+ * **User transactions**: 1 redeem call.
+ *
+ * @param walletClient  Wallet client with account attached
+ * @param publicClient  Public client for reads and simulation
+ * @param addresses     Vault address set (only `vault` is used)
+ * @param shares        Amount of vault shares to redeem
+ * @param receiver      Address that will receive the underlying assets
+ * @param owner         Owner of the shares being redeemed
+ * @returns             Transaction hash and amount of assets received
+ */
+export async function redeemShares(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  shares: bigint,
+  receiver: Address,
+  owner: Address,
+): Promise<RedeemResult> {
+  const account = walletClient.account!
+  const vault = getAddress(addresses.vault)
+
+  const { result: assets } = await publicClient.simulateContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'redeem',
+    args: [shares, getAddress(receiver), getAddress(owner)],
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'redeem',
+    args: [shares, getAddress(receiver), getAddress(owner)],
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash, assets }
+}
+
+/**
+ * R2 — Withdraw by specifying the exact assets amount.
+ *
+ * Burns the necessary shares to withdraw exactly `assets` amount of underlying.
+ * If a withdrawal queue is enabled, the caller must have previously called
+ * `requestWithdraw` and waited for the timelock.
+ *
+ * **User transactions**: 1 withdraw call.
+ *
+ * @param walletClient  Wallet client with account attached
+ * @param publicClient  Public client for reads and simulation
+ * @param addresses     Vault address set (only `vault` is used)
+ * @param assets        Exact amount of underlying assets to withdraw
+ * @param receiver      Address that will receive the assets
+ * @param owner         Owner of the shares being burned
+ * @returns             Transaction hash and the actual assets withdrawn
+ */
+export async function withdrawAssets(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  assets: bigint,
+  receiver: Address,
+  owner: Address,
+): Promise<RedeemResult> {
+  const account = walletClient.account!
+  const vault = getAddress(addresses.vault)
+
+  const { result: sharesBurned } = await publicClient.simulateContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'withdraw',
+    args: [assets, getAddress(receiver), getAddress(owner)],
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'withdraw',
+    args: [assets, getAddress(receiver), getAddress(owner)],
+    account,
+    chain: walletClient.chain,
+  })
+
+  // For withdraw, the return is shares burned; assets is what was requested
+  return { txHash, assets }
+}
+
+/**
+ * R3 / R4 — Request redeem (queue shares for withdrawal).
+ *
+ * Places `shares` into the withdrawal queue. If a timelock is configured (R4),
+ * the user must wait until `timelockEndsAt` before calling `redeemShares`.
+ * If no timelock (R3), `redeemShares` can be called immediately after.
+ *
+ * Use `getWithdrawalRequest` to check the timelock status.
+ *
+ * **User transactions**: 1 requestRedeem call, then later 1 redeemShares call.
+ *
+ * @param walletClient  Wallet client with account attached
+ * @param publicClient  Public client for simulation
+ * @param addresses     Vault address set (only `vault` is used)
+ * @param shares        Amount of shares to queue for redemption
+ * @param owner         The address on behalf of which the request is made
+ * @returns             Transaction hash of the request
+ */
+export async function requestRedeem(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  shares: bigint,
+  owner: Address,
+): Promise<{ txHash: Hash }> {
+  const account = walletClient.account!
+  const vault = getAddress(addresses.vault)
+
+  await publicClient.simulateContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'requestRedeem',
+    args: [shares, getAddress(owner)],
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'requestRedeem',
+    args: [shares, getAddress(owner)],
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash }
+}
+
+/**
+ * Helper — Get the current withdrawal request for an owner.
+ *
+ * Returns the queued shares and timelock end timestamp.
+ * Useful for showing a countdown timer in the UI (R4 flow).
+ *
+ * @param publicClient  Public client for reading state
+ * @param vault         Vault address
+ * @param owner         Owner whose request to query
+ * @returns             Request info or null if no active request
+ */
+export async function getWithdrawalRequest(
+  publicClient: PublicClient,
+  vault: Address,
+  owner: Address,
+): Promise<{ shares: bigint; timelockEndsAt: bigint } | null> {
+  const [shares, timelockEndsAt] = await publicClient.readContract({
+    address: getAddress(vault),
+    abi: VAULT_ABI,
+    functionName: 'getWithdrawalRequest',
+    args: [getAddress(owner)],
+  })
+
+  if (shares === 0n) return null
+
+  return { shares, timelockEndsAt }
+}
+
+/**
+ * R5 — Async redeem (cross-chain hub, oracle OFF).
+ *
+ * Initiates an async redeem via `initVaultActionRequest(REDEEM, ...)`.
+ * Shares are locked in the escrow while the LZ Read resolves accounting.
+ * After `executeRequest`, assets are sent to the receiver.
+ *
+ * **IMPORTANT**: `amountLimit` MUST be 0 for REDEEM actions (not shares).
+ * The shares amount is encoded in the actionCallData. Setting amountLimit to
+ * a non-zero value would be interpreted as "max assets to receive" (inverted
+ * slippage check), which is almost never what the user wants.
+ *
+ * **User transactions**: 1 approve (shares to ESCROW) + 1 initVaultActionRequest.
+ * **Wait**: Assets arrive after LZ callback + executeRequest.
+ *
+ * @param walletClient   Wallet client with account attached
+ * @param publicClient   Public client for reads and simulation
+ * @param addresses      Vault address set (`vault` + `escrow` required)
+ * @param shares         Amount of shares to redeem
+ * @param receiver       Address that will receive the underlying assets
+ * @param owner          Owner of the shares (must match the initiator)
+ * @param lzFee          msg.value for LZ Read fee
+ * @param extraOptions   Optional LZ extra options bytes
+ * @returns              Transaction hash and GUID for tracking
+ */
+export async function redeemAsync(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  shares: bigint,
+  receiver: Address,
+  owner: Address,
+  lzFee: bigint,
+  extraOptions: `0x${string}` = '0x',
+): Promise<AsyncRequestResult> {
+  const account = walletClient.account!
+  const vault = getAddress(addresses.vault)
+  if (!addresses.escrow) throw new MissingEscrowAddressError()
+  const escrow = getAddress(addresses.escrow)
+
+  // Pre-flight: validate async cross-chain setup before sending any transaction
+  await preflightAsync(publicClient, vault, escrow)
+
+  // Pre-flight: check hub has enough liquid assets — avoids wasting LZ fee on a guaranteed refund
+  await preflightRedeemLiquidity(publicClient, vault, shares)
+
+  // Approve ESCROW for shares (vault share token is the vault itself for ERC-4626)
+  await ensureAllowance(walletClient, publicClient, vault, escrow, shares)
+
+  // Encode parameters only (no selector) — contracts use abi.decode on these bytes
+  const actionCallData = encodeAbiParameters(
+    [{ type: 'uint256', name: 'shares' }, { type: 'address', name: 'receiver' }, { type: 'address', name: 'owner' }],
+    [shares, getAddress(receiver), getAddress(owner)],
+  ) as `0x${string}`
+
+  // amountLimit MUST be 0 for REDEEM — see JSDoc above
+  const { result: guid } = await publicClient.simulateContract({
+    address: vault,
+    abi: BRIDGE_ABI,
+    functionName: 'initVaultActionRequest',
+    args: [ActionType.REDEEM, actionCallData, 0n, extraOptions],
+    value: lzFee,
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: BRIDGE_ABI,
+    functionName: 'initVaultActionRequest',
+    args: [ActionType.REDEEM, actionCallData, 0n, extraOptions],
+    value: lzFee,
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash, guid: guid as `0x${string}` }
+}
+
+/**
+ * R6 — Bridge shares from spoke to hub chain via OFT.
+ *
+ * This is step 1 of a 2-step spoke redeem flow:
+ *   1. `bridgeSharesToHub()` — send shares from spoke to hub via OFT
+ *   2. `redeemShares()` — call redeem on the hub vault (after shares arrive)
+ *
+ * The two steps happen on different chains and cannot be combined into a single
+ * SDK call. The frontend must switch chains between steps.
+ *
+ * **User transactions on spoke chain**: 1 approve (shares to shareOFT) + 1 OFT.send().
+ * **Gas**: Requires native token on spoke for LZ fees, and gas on hub for step 2.
+ *
+ * @param walletClient   Wallet client on the SPOKE chain
+ * @param publicClient   Public client on the SPOKE chain
+ * @param shareOFT       OFTAdapter address for vault shares on the spoke chain
+ * @param hubChainEid    LayerZero Endpoint ID for the hub chain (Flow EVM = 30332)
+ * @param shares         Amount of vault shares to bridge
+ * @param receiver       Receiver address on the HUB chain
+ * @param lzFee          msg.value for OFT send (quote via OFT.quoteSend)
+ * @returns              Transaction hash of the OFT.send() call
+ */
+export async function bridgeSharesToHub(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  shareOFT: Address,
+  hubChainEid: number,
+  shares: bigint,
+  receiver: Address,
+  lzFee: bigint,
+): Promise<{ txHash: Hash }> {
+  const account = walletClient.account!
+  const oft = getAddress(shareOFT)
+
+  // Approve OFT for share transfer
+  await ensureAllowance(walletClient, publicClient, oft, oft, shares)
+
+  const toBytes32 = pad(getAddress(receiver), { size: 32 })
+
+  const sendParam = {
+    dstEid: hubChainEid,
+    to: toBytes32,
+    amountLD: shares,
+    minAmountLD: shares, // shares should bridge 1:1
+    extraOptions: '0x' as `0x${string}`,
+    composeMsg: '0x' as `0x${string}`,
+    oftCmd: '0x' as `0x${string}`,
+  }
+
+  const fee = {
+    nativeFee: lzFee,
+    lzTokenFee: 0n,
+  }
+
+  const txHash = await walletClient.writeContract({
+    address: oft,
+    abi: OFT_ABI,
+    functionName: 'send',
+    args: [sendParam, fee, account.address],
+    value: lzFee,
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash }
+}

package/src/viem/types.ts

@@ -0,0 +1,56 @@
+import type { Address, Hash, PublicClient, WalletClient } from 'viem'
+
+export interface VaultAddresses {
+  /** Hub vault address (diamond proxy) */
+  vault: Address
+  /** MoreVaultsEscrow — holds locked tokens during async cross-chain flows */
+  escrow?: Address
+  /** OFTAdapter for vault shares (cross-chain redeem only) */
+  shareOFT?: Address
+  /** OFT for USDC bridging (cross-chain deposits from spoke) */
+  usdcOFT?: Address
+}
+
+export interface DepositResult {
+  txHash: Hash
+  shares: bigint
+}
+
+export interface RedeemResult {
+  txHash: Hash
+  assets: bigint
+}
+
+export interface AsyncRequestResult {
+  txHash: Hash
+  /** Cross-chain request GUID to track via getRequestInfo / getFinalizationResult */
+  guid: `0x${string}`
+}
+
+/**
+ * ActionType enum values matching MoreVaultsLib.ActionType on-chain.
+ * 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]
+
+export interface CrossChainRequestInfo {
+  initiator: Address
+  timestamp: bigint
+  actionType: number
+  actionCallData: `0x${string}`
+  fulfilled: boolean
+  finalized: boolean
+  refunded: boolean
+  totalAssets: bigint
+  finalizationResult: bigint
+  amountLimit: bigint
+}