@oydual31/more-vaults-sdk 0.1.0

package/src/viem/depositFlows.ts

@@ -0,0 +1,331 @@
+import {
+  type Address,
+  type PublicClient,
+  type WalletClient,
+  encodeAbiParameters,
+  getAddress,
+} from 'viem'
+import { VAULT_ABI, BRIDGE_ABI, ERC20_ABI } from './abis'
+import type {
+  VaultAddresses,
+  DepositResult,
+  AsyncRequestResult,
+} from './types'
+import { ActionType } from './types'
+import { ensureAllowance, getVaultStatus, quoteLzFee } from './utils'
+import { preflightSync, preflightAsync } from './preflight'
+import { MissingEscrowAddressError, VaultPausedError, CapacityFullError } from './errors'
+
+/**
+ * D1 / D3 — Simple deposit (ERC-4626 standard).
+ *
+ * Works for both local vaults and cross-chain hubs with oracle accounting ON.
+ * When oracle accounting is enabled the cross-chain accounting is transparent
+ * to the caller — the vault resolves totalAssets synchronously.
+ *
+ * **User transactions**: 1 approve (skipped if allowance sufficient) + 1 deposit.
+ *
+ * @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        Amount of underlying token to deposit (in token decimals)
+ * @param receiver      Address that will receive the minted vault shares
+ * @returns             Transaction hash and amount of shares minted
+ */
+export async function depositSimple(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  assets: bigint,
+  receiver: Address,
+): Promise<DepositResult> {
+  const account = walletClient.account!
+  const vault = getAddress(addresses.vault)
+
+  // Pre-flight: validate vault is operational and accepting deposits
+  await preflightSync(publicClient, vault)
+
+  // Resolve underlying asset
+  const underlying = await publicClient.readContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'asset',
+  })
+
+  // Approve vault if needed
+  await ensureAllowance(walletClient, publicClient, underlying, vault, assets)
+
+  // Simulate then send
+  const { result: shares } = await publicClient.simulateContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'deposit',
+    args: [assets, getAddress(receiver)],
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'deposit',
+    args: [assets, getAddress(receiver)],
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash, shares }
+}
+
+/**
+ * Alias: D3 — Cross-chain hub deposit when oracle accounting is ON.
+ * Exactly the same UX as depositSimple because the vault resolves accounting synchronously.
+ */
+export { depositSimple as depositCrossChainOracleOn }
+
+/**
+ * D2 — Multi-asset deposit.
+ *
+ * Deposits multiple ERC-20 tokens into the vault in a single vault call.
+ * The vault converts each token to the underlying via oracle pricing.
+ *
+ * **User transactions**: N approves (one per token, skipped if sufficient) + 1 deposit.
+ *
+ * @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 tokens        Array of token addresses to deposit
+ * @param amounts       Array of amounts (one per token, in each token's decimals)
+ * @param receiver      Address that will receive the minted vault shares
+ * @param minShares     Minimum shares to accept (slippage protection)
+ * @returns             Transaction hash and amount of shares minted
+ */
+export async function depositMultiAsset(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  tokens: Address[],
+  amounts: bigint[],
+  receiver: Address,
+  minShares: bigint,
+): Promise<DepositResult> {
+  const account = walletClient.account!
+  const vault = getAddress(addresses.vault)
+
+  // Approve each token
+  for (let i = 0; i < tokens.length; i++) {
+    await ensureAllowance(walletClient, publicClient, tokens[i], vault, amounts[i])
+  }
+
+  const { result: shares } = await publicClient.simulateContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'deposit',
+    args: [tokens, amounts, getAddress(receiver), minShares],
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'deposit',
+    args: [tokens, amounts, getAddress(receiver), minShares],
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash, shares }
+}
+
+/**
+ * D4 — Async deposit (cross-chain hub, oracle OFF).
+ *
+ * Sends assets to the escrow and initiates a cross-chain accounting request via
+ * `initVaultActionRequest(DEPOSIT, ...)`. The LZ Read callback will resolve
+ * accounting and `executeRequest` will mint shares.
+ *
+ * **User transactions**: 1 approve (to ESCROW, not vault!) + 1 initVaultActionRequest.
+ * **Wait**: Shares arrive after the LZ callback + executeRequest (automated by keeper).
+ *
+ * @param walletClient   Wallet client with account attached
+ * @param publicClient   Public client for reads and simulation
+ * @param addresses      Vault address set (`vault` + `escrow` required)
+ * @param assets         Amount of underlying to deposit
+ * @param receiver       Address that will receive shares after resolution
+ * @param lzFee          msg.value for LZ Read fee (quote first with `quoteLzFee`)
+ * @param extraOptions   Optional LZ extra options bytes (default 0x)
+ * @returns              Transaction hash and GUID for tracking
+ */
+export async function depositAsync(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  assets: bigint,
+  receiver: 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)
+
+  // Resolve underlying asset
+  const underlying = await publicClient.readContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'asset',
+  })
+
+  // Approve ESCROW (not vault!) for the deposit amount
+  await ensureAllowance(walletClient, publicClient, underlying, escrow, assets)
+
+  // Encode parameters only (no selector) — contracts use abi.decode on these bytes
+  const actionCallData = encodeAbiParameters(
+    [{ type: 'uint256', name: 'assets' }, { type: 'address', name: 'receiver' }],
+    [assets, getAddress(receiver)],
+  ) as `0x${string}`
+
+  const { result: guid } = await publicClient.simulateContract({
+    address: vault,
+    abi: BRIDGE_ABI,
+    functionName: 'initVaultActionRequest',
+    args: [ActionType.DEPOSIT, actionCallData, 0n, extraOptions],
+    value: lzFee,
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: BRIDGE_ABI,
+    functionName: 'initVaultActionRequest',
+    args: [ActionType.DEPOSIT, actionCallData, 0n, extraOptions],
+    value: lzFee,
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash, guid: guid as `0x${string}` }
+}
+
+/**
+ * D5 — Async mint (cross-chain hub, oracle OFF).
+ *
+ * Mints an exact amount of shares by depositing up to `maxAssets` of underlying.
+ * Similar flow to D4 but uses MINT action type.
+ *
+ * **User transactions**: 1 approve (to ESCROW for maxAssets) + 1 initVaultActionRequest.
+ * **Wait**: Shares arrive after the 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         Exact number of shares to mint
+ * @param maxAssets      Maximum assets to spend (slippage protection)
+ * @param receiver       Address that will receive the minted shares
+ * @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 mintAsync(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  shares: bigint,
+  maxAssets: bigint,
+  receiver: 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)
+
+  const underlying = await publicClient.readContract({
+    address: vault,
+    abi: VAULT_ABI,
+    functionName: 'asset',
+  })
+
+  // Approve ESCROW for maxAssets
+  await ensureAllowance(walletClient, publicClient, underlying, escrow, maxAssets)
+
+  // Encode parameters only (no selector) — contracts use abi.decode on these bytes
+  const actionCallData = encodeAbiParameters(
+    [{ type: 'uint256', name: 'shares' }, { type: 'address', name: 'receiver' }],
+    [shares, getAddress(receiver)],
+  ) as `0x${string}`
+
+  // amountLimit = maxAssets (slippage check: actual assets spent must be <= maxAssets)
+  const { result: guid } = await publicClient.simulateContract({
+    address: vault,
+    abi: BRIDGE_ABI,
+    functionName: 'initVaultActionRequest',
+    args: [ActionType.MINT, actionCallData, maxAssets, extraOptions],
+    value: lzFee,
+    account: account.address,
+  })
+
+  const txHash = await walletClient.writeContract({
+    address: vault,
+    abi: BRIDGE_ABI,
+    functionName: 'initVaultActionRequest',
+    args: [ActionType.MINT, actionCallData, maxAssets, extraOptions],
+    value: lzFee,
+    account,
+    chain: walletClient.chain,
+  })
+
+  return { txHash, guid: guid as `0x${string}` }
+}
+
+/**
+ * Smart deposit — auto-selects the correct flow based on vault configuration.
+ *
+ * Calls getVaultStatus internally to determine the vault mode, then dispatches
+ * to the appropriate flow:
+ * - local / cross-chain-oracle → depositSimple
+ * - cross-chain-async → depositAsync (quotes LZ fee automatically)
+ *
+ * @param walletClient   Wallet client with account attached
+ * @param publicClient   Public client for reads
+ * @param addresses      Vault address set (`escrow` required for async vaults)
+ * @param assets         Amount of underlying to deposit
+ * @param receiver       Address that will receive shares
+ * @param extraOptions   Optional LZ extra options (only used for async vaults)
+ * @returns              DepositResult or AsyncRequestResult depending on vault mode
+ * @throws               VaultPausedError if vault is paused
+ * @throws               CapacityFullError if vault is full
+ */
+export async function smartDeposit(
+  walletClient: WalletClient,
+  publicClient: PublicClient,
+  addresses: VaultAddresses,
+  assets: bigint,
+  receiver: Address,
+  extraOptions: `0x${string}` = '0x',
+): Promise<DepositResult | AsyncRequestResult> {
+  const vault = getAddress(addresses.vault)
+  const status = await getVaultStatus(publicClient, vault)
+
+  if (status.mode === 'paused') {
+    throw new VaultPausedError(vault)
+  }
+  if (status.mode === 'full') {
+    throw new CapacityFullError(vault)
+  }
+
+  if (status.recommendedDepositFlow === 'depositAsync') {
+    const lzFee = await quoteLzFee(publicClient, vault, extraOptions)
+    return depositAsync(walletClient, publicClient, addresses, assets, receiver, lzFee, extraOptions)
+  }
+
+  // local or cross-chain-oracle
+  return depositSimple(walletClient, publicClient, addresses, assets, receiver)
+}

package/src/viem/errors.ts

@@ -0,0 +1,81 @@
+/**
+ * Typed error classes for the MoreVaults SDK.
+ *
+ * Frontend code can use instanceof checks to handle errors programmatically:
+ *   catch (e) {
+ *     if (e instanceof InsufficientLiquidityError) { ... }
+ *   }
+ */
+
+export class MoreVaultsError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'MoreVaultsError'
+  }
+}
+
+export class VaultPausedError extends MoreVaultsError {
+  constructor(vault: string) {
+    super(`[MoreVaults] Vault ${vault} is paused. Cannot perform any actions.`)
+    this.name = 'VaultPausedError'
+  }
+}
+
+export class CapacityFullError extends MoreVaultsError {
+  constructor(vault: string) {
+    super(`[MoreVaults] Vault ${vault} has reached deposit capacity. No more deposits accepted.`)
+    this.name = 'CapacityFullError'
+  }
+}
+
+export class NotWhitelistedError extends MoreVaultsError {
+  constructor(vault: string, user: string) {
+    super(`[MoreVaults] Address ${user} is not whitelisted to deposit in vault ${vault}.`)
+    this.name = 'NotWhitelistedError'
+  }
+}
+
+export class InsufficientLiquidityError extends MoreVaultsError {
+  hubLiquid: bigint
+  required: bigint
+  constructor(vault: string, hubLiquid: bigint, required: bigint) {
+    super(
+      `[MoreVaults] Insufficient hub liquidity for redeem.\n` +
+      `  Hub liquid balance : ${hubLiquid}\n` +
+      `  Estimated required : ${required}\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.`
+    )
+    this.name = 'InsufficientLiquidityError'
+    this.hubLiquid = hubLiquid
+    this.required = required
+  }
+}
+
+export class CCManagerNotConfiguredError extends MoreVaultsError {
+  constructor(vault: string) {
+    super(`[MoreVaults] CCManager not configured on vault ${vault}. Call setCrossChainAccountingManager(ccManagerAddress) as vault owner first.`)
+    this.name = 'CCManagerNotConfiguredError'
+  }
+}
+
+export class EscrowNotConfiguredError extends MoreVaultsError {
+  constructor(vault: string) {
+    super(`[MoreVaults] Escrow not configured for vault ${vault}. The registry must have an escrow set for this vault.`)
+    this.name = 'EscrowNotConfiguredError'
+  }
+}
+
+export class NotHubVaultError extends MoreVaultsError {
+  constructor(vault: string) {
+    super(`[MoreVaults] Vault ${vault} is not a hub vault. Async flows (D4/D5/R5) only work on hub vaults.`)
+    this.name = 'NotHubVaultError'
+  }
+}
+
+export class MissingEscrowAddressError extends MoreVaultsError {
+  constructor() {
+    super(`[MoreVaults] This flow requires an escrow address. Set VaultAddresses.escrow before calling async deposit/redeem flows.`)
+    this.name = 'MissingEscrowAddressError'
+  }
+}

package/src/viem/index.ts

@@ -0,0 +1,100 @@
+// MoreVaults SDK — viem/wagmi
+// Provides typed helpers for all deposit, redeem, and cross-chain vault flows.
+
+// --- ABIs ---
+export {
+  VAULT_ABI,
+  BRIDGE_ABI,
+  CONFIG_ABI,
+  ERC20_ABI,
+  OFT_ABI,
+  METADATA_ABI,
+} from './abis'
+
+// --- Types ---
+export type {
+  VaultAddresses,
+  DepositResult,
+  RedeemResult,
+  AsyncRequestResult,
+  CrossChainRequestInfo,
+  ActionTypeValue,
+} from './types'
+export { ActionType } from './types'
+
+// --- Errors ---
+export {
+  MoreVaultsError,
+  VaultPausedError,
+  CapacityFullError,
+  NotWhitelistedError,
+  InsufficientLiquidityError,
+  CCManagerNotConfiguredError,
+  EscrowNotConfiguredError,
+  NotHubVaultError,
+  MissingEscrowAddressError,
+} from './errors'
+
+// --- Deposit Flows ---
+export {
+  depositSimple,
+  depositCrossChainOracleOn,
+  depositMultiAsset,
+  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'