@oydual31/more-vaults-sdk 0.1.2 → 0.1.3

package/dist/viem/index.d.ts

@@ -1,5 +1,6 @@
 import { Hash, Address, WalletClient, PublicClient } from 'viem';
 export { PublicClient as SdkPublicClient } from 'viem';
+export { A as AsyncRequestStatus, a as AsyncRequestStatusInfo, D as DepositBlockReason, b as DepositEligibility, M as MaxWithdrawable, U as UserBalances, c as UserPosition, V as VaultMetadata, d as VaultMode, e as VaultStatus, f as VaultSummary, g as canDeposit, h as ensureAllowance, i as getAsyncRequestStatus, j as getAsyncRequestStatusLabel, k as getMaxWithdrawable, l as getUserBalances, m as getUserPosition, n as getVaultMetadata, o as getVaultStatus, p as getVaultSummary, q as isAsyncMode, r as previewDeposit, s as previewRedeem, t as quoteLzFee } from '../userHelpers-CZLB9oQ4.js';
 
 /** EVM Chain IDs for chains supported by MoreVaults */
 declare const CHAIN_IDS: {
@@ -978,154 +979,6 @@ declare function bridgeSharesToHub(walletClient: WalletClient, publicClient: Pub
     txHash: Hash;
 }>;
 
-type VaultMode = 'local' | 'cross-chain-oracle' | 'cross-chain-async' | 'paused' | 'full';
-interface VaultStatus {
-    /** Vault operating mode — determines which SDK flow to use */
-    mode: VaultMode;
-    /** Which deposit function to call given the current configuration */
-    recommendedDepositFlow: 'depositSimple' | 'depositAsync' | 'mintAsync' | 'none';
-    /** Which redeem function to call given the current configuration */
-    recommendedRedeemFlow: 'redeemShares' | 'redeemAsync' | 'none';
-    isHub: boolean;
-    isPaused: boolean;
-    oracleAccountingEnabled: boolean;
-    /** address(0) means CCManager is not set — async flows will fail */
-    ccManager: Address;
-    /** address(0) means escrow is not configured in the registry */
-    escrow: Address;
-    withdrawalQueueEnabled: boolean;
-    /** Timelock duration in seconds (0 = no timelock) */
-    withdrawalTimelockSeconds: bigint;
-    /**
-     * Remaining deposit capacity in underlying token decimals.
-     * `type(uint256).max` = no cap configured (unlimited).
-     * `0n` = vault is full — no more deposits accepted.
-     * If `depositAccessRestricted = true`, this value is `type(uint256).max` but
-     * deposits are still gated by whitelist or other access control.
-     */
-    remainingDepositCapacity: bigint;
-    /**
-     * True when `maxDeposit(address(0))` reverted, indicating the vault uses
-     * whitelist or other access control to restrict who can deposit.
-     * Deposit flows will succeed only for addresses the vault operator has approved.
-     */
-    depositAccessRestricted: boolean;
-    underlying: Address;
-    totalAssets: bigint;
-    totalSupply: bigint;
-    /** Vault share token decimals. Use this for display — never hardcode 18. */
-    decimals: number;
-    /**
-     * Price of 1 full share expressed in underlying token units.
-     * = convertToAssets(10^decimals). Grows over time as the vault earns yield.
-     */
-    sharePrice: bigint;
-    /**
-     * Underlying token balance held directly on the hub chain.
-     * This is the only portion that can be paid out to redeeming users immediately.
-     * (= ERC-20.balanceOf(vault) on the hub)
-     */
-    hubLiquidBalance: bigint;
-    /**
-     * Approximate value deployed to spoke chains (totalAssets − hubLiquidBalance).
-     * These funds are NOT immediately redeemable — the vault curator must
-     * call executeBridging to repatriate them before large redeems can succeed.
-     */
-    spokesDeployedBalance: bigint;
-    /**
-     * Maximum assets that can be redeemed right now without curator intervention.
-     * - For hub vaults: equals `hubLiquidBalance` (only what the hub holds).
-     * - For local/oracle vaults: equals `totalAssets` (all assets are local).
-     * Attempting to redeem more than this will revert (R1) or be auto-refunded (R5).
-     */
-    maxImmediateRedeemAssets: bigint;
-    /**
-     * Human-readable list of configuration problems that would cause transactions
-     * to fail.  Empty array = vault is ready to use.
-     */
-    issues: string[];
-}
-/**
- * Read the full configuration and operational status of a vault in a single
- * multicall-friendly batch.
- *
- * Use this to:
- * - Determine which SDK flow to use (`recommendedDepositFlow`)
- * - Show a configuration checklist in an admin dashboard
- * - Surface `issues` to the developer before any transaction
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address (diamond proxy)
- * @returns             Full vault status snapshot
- *
- * @example
- * ```ts
- * const status = await getVaultStatus(publicClient, VAULT)
- * if (status.issues.length) {
- *   console.warn('Vault misconfigured:', status.issues)
- * }
- * // Use recommended flow:
- * if (status.recommendedDepositFlow === 'depositAsync') {
- *   await depositAsync(walletClient, publicClient, { vault: VAULT, escrow: status.escrow }, ...)
- * }
- * ```
- */
-declare function getVaultStatus(publicClient: PublicClient, vault: Address): Promise<VaultStatus>;
-/**
- * Ensure the spender has sufficient ERC-20 allowance; approve if not.
- *
- * Checks the current allowance and only sends an approve transaction if
- * the existing allowance is less than the required amount.
- *
- * @param walletClient  Wallet client with account attached
- * @param publicClient  Public client for reads
- * @param token         ERC-20 token address
- * @param spender       Address to approve
- * @param amount        Minimum required allowance
- */
-declare function ensureAllowance(walletClient: WalletClient, publicClient: PublicClient, token: Address, spender: Address, amount: bigint): Promise<void>;
-/**
- * Quote the LayerZero native fee required for async vault actions.
- *
- * Call this before `depositAsync`, `mintAsync`, or `redeemAsync` to get the
- * exact `lzFee` (msg.value) needed.
- *
- * @param publicClient   Public client for reads
- * @param vault          Vault address (diamond proxy)
- * @param extraOptions   Optional LZ extra options bytes (default 0x)
- * @returns              Required native fee in wei
- */
-declare function quoteLzFee(publicClient: PublicClient, vault: Address, extraOptions?: `0x${string}`): Promise<bigint>;
-/**
- * Check if a vault is operating in async mode (cross-chain hub with oracle OFF).
- *
- * When this returns `true`, deposits and redeems must use the async flows
- * (D4/D5/R5) which go through `initVaultActionRequest`.
- * When `false`, the vault either uses oracle-based accounting (sync) or is
- * a single-chain vault.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @returns             `true` if the vault requires async cross-chain flows
- */
-declare function isAsyncMode(publicClient: PublicClient, vault: Address): Promise<boolean>;
-/**
- * Poll for async request completion status.
- *
- * After calling an async flow (D4/D5/R5), use this to check whether the
- * LZ callback has resolved and `executeRequest` has been called.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @param guid          Request GUID returned by the async flow
- * @returns             Whether the request is fulfilled and the finalization result
- */
-declare function getAsyncRequestStatus(publicClient: PublicClient, vault: Address, guid: `0x${string}`): Promise<{
-    fulfilled: boolean;
-    finalized: boolean;
-    result: bigint;
-}>;
-
 /**
  * Pre-flight validation helpers for MoreVaults SDK flows.
  *
@@ -1184,141 +1037,6 @@ declare function preflightRedeemLiquidity(publicClient: PublicClient, vault: Add
  */
 declare function preflightSync(publicClient: PublicClient, vault: Address): Promise<void>;
 
-interface UserPosition {
-    /** Vault share balance */
-    shares: bigint;
-    /** convertToAssets(shares) — what they'd get if they redeemed now */
-    estimatedAssets: bigint;
-    /** Price of 1 full share in underlying (convertToAssets(10n ** decimals)) */
-    sharePrice: bigint;
-    /** Vault decimals (for display) */
-    decimals: number;
-    pendingWithdrawal: {
-        shares: bigint;
-        timelockEndsAt: bigint;
-        /** block.timestamp >= timelockEndsAt (or timelockEndsAt === 0n) */
-        canRedeemNow: boolean;
-    } | null;
-}
-/**
- * Read the user's current position in the vault.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address (diamond proxy)
- * @param user          User wallet address
- * @returns             Full user position snapshot
- */
-declare function getUserPosition(publicClient: PublicClient, vault: Address, user: Address): Promise<UserPosition>;
-/**
- * Preview how many shares a given asset amount would mint.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @param assets        Amount of underlying tokens to deposit
- * @returns             Estimated shares to be minted
- */
-declare function previewDeposit(publicClient: PublicClient, vault: Address, assets: bigint): Promise<bigint>;
-/**
- * Preview how many underlying assets a given share amount would redeem.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @param shares        Amount of vault shares to redeem
- * @returns             Estimated assets to be returned
- */
-declare function previewRedeem(publicClient: PublicClient, vault: Address, shares: bigint): Promise<bigint>;
-type DepositBlockReason = 'paused' | 'capacity-full' | 'not-whitelisted' | 'ok';
-interface DepositEligibility {
-    allowed: boolean;
-    reason: DepositBlockReason;
-}
-/**
- * Check whether a user is eligible to deposit into the vault right now.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @param user          User wallet address
- * @returns             Eligibility result with reason
- */
-declare function canDeposit(publicClient: PublicClient, vault: Address, user: Address): Promise<DepositEligibility>;
-interface VaultMetadata {
-    name: string;
-    symbol: string;
-    decimals: number;
-    underlying: Address;
-    underlyingSymbol: string;
-    underlyingDecimals: number;
-}
-/**
- * Read display metadata for a vault and its underlying token.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @returns             Vault and underlying token metadata
- */
-declare function getVaultMetadata(publicClient: PublicClient, vault: Address): Promise<VaultMetadata>;
-type AsyncRequestStatus = 'pending' | 'ready-to-execute' | 'completed' | 'refunded';
-interface AsyncRequestStatusInfo {
-    status: AsyncRequestStatus;
-    /** Human-readable description */
-    label: string;
-    /** Shares minted or assets returned (0 if still pending) */
-    result: bigint;
-}
-/**
- * Get the human-readable status of an async cross-chain request.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @param guid          Request GUID returned by depositAsync / mintAsync / redeemAsync
- * @returns             Status info with label and result
- */
-declare function getAsyncRequestStatusLabel(publicClient: PublicClient, vault: Address, guid: `0x${string}`): Promise<AsyncRequestStatusInfo>;
-interface UserBalances {
-    /** Vault shares the user holds */
-    shareBalance: bigint;
-    /** Underlying token balance in wallet (for deposit input) */
-    underlyingBalance: bigint;
-    /** convertToAssets(shareBalance) — vault position value */
-    estimatedAssets: bigint;
-}
-/**
- * Read the user's token balances relevant to a vault.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @param user          User wallet address
- * @returns             Share balance, underlying wallet balance, and estimated assets
- */
-declare function getUserBalances(publicClient: PublicClient, vault: Address, user: Address): Promise<UserBalances>;
-interface MaxWithdrawable {
-    /** How many shares can be redeemed right now */
-    shares: bigint;
-    /** How many underlying assets that corresponds to */
-    assets: bigint;
-}
-/**
- * Calculate the maximum amount a user can withdraw from a vault right now.
- *
- * For hub vaults without oracle accounting, this is limited by hub liquidity.
- * For local and oracle vaults, all assets are immediately redeemable.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @param user          User wallet address
- * @returns             Maximum withdrawable shares and assets
- */
-declare function getMaxWithdrawable(publicClient: PublicClient, vault: Address, user: Address): Promise<MaxWithdrawable>;
-type VaultSummary = VaultStatus & VaultMetadata;
-/**
- * Get a combined snapshot of vault status and metadata in one call.
- *
- * @param publicClient  Public client for reads
- * @param vault         Vault address
- * @returns             Merged VaultStatus and VaultMetadata
- */
-declare function getVaultSummary(publicClient: PublicClient, vault: Address): Promise<VaultSummary>;
-
 /**
  * Cast a wagmi PublicClient to the SDK's expected type.
  * Use this in React components to avoid `as any` casts:
@@ -1333,4 +1051,4 @@ declare function getVaultSummary(publicClient: PublicClient, vault: Address): Pr
  */
 declare function asSdkClient(client: unknown): PublicClient;
 
-export { ActionType, type ActionTypeValue, type AsyncRequestResult, type AsyncRequestStatus, type AsyncRequestStatusInfo, BRIDGE_ABI, CCManagerNotConfiguredError, CHAIN_IDS, CHAIN_ID_TO_EID, CONFIG_ABI, CapacityFullError, type CrossChainRequestInfo, type DepositBlockReason, type DepositEligibility, type DepositResult, EID_TO_CHAIN_ID, ERC20_ABI, EscrowNotConfiguredError, InsufficientLiquidityError, LZ_EIDS, METADATA_ABI, type MaxWithdrawable, MissingEscrowAddressError, MoreVaultsError, NotHubVaultError, NotWhitelistedError, OFT_ABI, type RedeemResult, type UserBalances, type UserPosition, VAULT_ABI, type VaultAddresses, type VaultMetadata, type VaultMode, VaultPausedError, type VaultStatus, type VaultSummary, WrongChainError, asSdkClient, bridgeSharesToHub, canDeposit, depositAsync, depositSimple as depositCrossChainOracleOn, depositFromSpoke, depositFromSpoke as depositFromSpokeAsync, depositMultiAsset, depositSimple, ensureAllowance, getAsyncRequestStatus, getAsyncRequestStatusLabel, getMaxWithdrawable, getUserBalances, getUserPosition, getVaultMetadata, getVaultStatus, getVaultSummary, getWithdrawalRequest, isAsyncMode, mintAsync, preflightAsync, preflightRedeemLiquidity, preflightSync, previewDeposit, previewRedeem, quoteDepositFromSpokeFee, quoteLzFee, redeemAsync, redeemShares, requestRedeem, smartDeposit, withdrawAssets };
+export { ActionType, type ActionTypeValue, type AsyncRequestResult, BRIDGE_ABI, CCManagerNotConfiguredError, CHAIN_IDS, CHAIN_ID_TO_EID, CONFIG_ABI, CapacityFullError, type CrossChainRequestInfo, type DepositResult, EID_TO_CHAIN_ID, ERC20_ABI, EscrowNotConfiguredError, InsufficientLiquidityError, LZ_EIDS, METADATA_ABI, MissingEscrowAddressError, MoreVaultsError, NotHubVaultError, NotWhitelistedError, OFT_ABI, type RedeemResult, VAULT_ABI, type VaultAddresses, VaultPausedError, WrongChainError, asSdkClient, bridgeSharesToHub, depositAsync, depositSimple as depositCrossChainOracleOn, depositFromSpoke, depositFromSpoke as depositFromSpokeAsync, depositMultiAsset, depositSimple, getWithdrawalRequest, mintAsync, preflightAsync, preflightRedeemLiquidity, preflightSync, quoteDepositFromSpokeFee, redeemAsync, redeemShares, requestRedeem, smartDeposit, withdrawAssets };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oydual31/more-vaults-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "TypeScript SDK for MoreVaults protocol — viem/wagmi and ethers.js",
   "type": "module",
   "exports": {
@@ -13,6 +13,11 @@
       "types": "./dist/ethers/index.d.ts",
       "import": "./dist/ethers/index.js",
       "require": "./dist/ethers/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
     }
   },
   "files": [
@@ -26,18 +31,25 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "viem": "^2.21.0",
-    "ethers": "^6.13.0"
+    "ethers": ">=6.0.0",
+    "viem": ">=2.0.0"
   },
   "devDependencies": {
+    "@tanstack/react-query": "^5.90.21",
     "@types/node": "^22.0.0",
+    "@types/react": "^18.3.28",
+    "react": "^18.3.1",
     "tsup": "^8.0.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "wagmi": "^2.19.5"
   },
   "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "ethers": ">=6.0.0",
+    "react": ">=18.0.0",
     "viem": ">=2.0.0",
-    "ethers": ">=6.0.0"
+    "wagmi": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "viem": {
@@ -45,6 +57,15 @@
     },
     "ethers": {
       "optional": true
+    },
+    "wagmi": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
     }
   }
 }

package/src/react/index.ts

@@ -0,0 +1,26 @@
+// MoreVaults SDK — React hooks (wagmi v2 + @tanstack/react-query v5)
+// Peer dependencies: react >=18, wagmi >=2, @tanstack/react-query >=5
+
+// --- Read hooks ---
+export { useVaultStatus } from './useVaultStatus.js'
+export type { VaultStatus } from './useVaultStatus.js'
+
+export { useVaultMetadata } from './useVaultMetadata.js'
+export type { VaultMetadata } from './useVaultMetadata.js'
+
+export { useUserPosition } from './useUserPosition.js'
+export type { UserPosition } from './useUserPosition.js'
+
+export { useLzFee } from './useLzFee.js'
+
+export { useAsyncRequestStatus } from './useAsyncRequestStatus.js'
+export type { AsyncRequestStatusInfo } from './useAsyncRequestStatus.js'
+
+// --- Action hooks ---
+export { useOmniDeposit } from './useOmniDeposit.js'
+export { useOmniRedeem } from './useOmniRedeem.js'
+export { useDepositSimple } from './useDepositSimple.js'
+export { useRedeemShares } from './useRedeemShares.js'
+
+// --- Smart (auto-routing) hooks ---
+export { useSmartDeposit } from './useSmartDeposit.js'

package/src/react/useAsyncRequestStatus.ts

@@ -0,0 +1,36 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, getAsyncRequestStatusLabel } from '../viem/index.js'
+import type { AsyncRequestStatusInfo } from '../viem/index.js'
+
+export type { AsyncRequestStatusInfo }
+
+/**
+ * Poll the status of an async cross-chain request (D4/D5/R5) by GUID.
+ *
+ * Automatically stops polling when status reaches 'completed' or 'refunded'.
+ * Polls every 10s while the request is still pending or ready-to-execute.
+ *
+ * @example
+ * const { data } = useAsyncRequestStatus('0xVAULT', guid, 747)
+ * // data.status: 'pending' | 'ready-to-execute' | 'completed' | 'refunded'
+ * // data.label: human-readable description
+ * // data.result: shares minted or assets returned (0n while pending)
+ */
+export function useAsyncRequestStatus(
+  vault: `0x${string}` | undefined,
+  guid: `0x${string}` | undefined,
+  chainId: number,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery<AsyncRequestStatusInfo>({
+    queryKey: ['asyncRequestStatus', vault, guid, chainId],
+    queryFn: () => getAsyncRequestStatusLabel(asSdkClient(publicClient), vault!, guid!),
+    enabled: !!vault && !!guid && !!publicClient,
+    refetchInterval: (query) => {
+      const status = query.state.data?.status
+      if (status === 'completed' || status === 'refunded') return false
+      return 10_000
+    },
+  })
+}

package/src/react/useDepositSimple.ts

@@ -0,0 +1,76 @@
+import { useState, useCallback } from 'react'
+import { usePublicClient, useWalletClient } from 'wagmi'
+import { asSdkClient, depositSimple } from '../viem/index.js'
+import type { DepositResult } from '../viem/index.js'
+
+interface UseDepositSimpleReturn {
+  /** Execute approve + depositSimple (D1/D3 flows). */
+  deposit: (amountInWei: bigint, receiver: `0x${string}`) => Promise<void>
+  isLoading: boolean
+  txHash: `0x${string}` | undefined
+  /** Shares minted. Available after tx confirmation. */
+  shares: bigint | undefined
+  error: Error | undefined
+  reset: () => void
+}
+
+/**
+ * Hook for local and oracle-on cross-chain vaults (D1/D3 flows).
+ *
+ * Simpler than useOmniDeposit — no LZ fee, no GUID, no polling.
+ * One approve + one deposit transaction.
+ *
+ * @example
+ * const { deposit, isLoading, txHash, shares } = useDepositSimple('0xVAULT', 747)
+ * await deposit(parseUnits('100', 6), userAddress)
+ */
+export function useDepositSimple(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+): UseDepositSimpleReturn {
+  const { data: walletClient } = useWalletClient({ chainId })
+  const publicClient = usePublicClient({ chainId })
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [result, setResult] = useState<DepositResult | undefined>()
+  const [error, setError] = useState<Error | undefined>()
+
+  const deposit = useCallback(
+    async (amountInWei: bigint, receiver: `0x${string}`) => {
+      if (!vault || !walletClient || !publicClient) return
+      setIsLoading(true)
+      setError(undefined)
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await depositSimple(
+          walletClient as any,
+          asSdkClient(publicClient),
+          { vault, hubChainId: chainId },
+          amountInWei,
+          receiver,
+        )
+        setResult(res)
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)))
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [vault, walletClient, publicClient, chainId],
+  )
+
+  const reset = useCallback(() => {
+    setResult(undefined)
+    setError(undefined)
+    setIsLoading(false)
+  }, [])
+
+  return {
+    deposit,
+    isLoading,
+    txHash: result?.txHash,
+    shares: result?.shares,
+    error,
+    reset,
+  }
+}

package/src/react/useLzFee.ts

@@ -0,0 +1,27 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, quoteLzFee } from '../viem/index.js'
+
+/**
+ * Quote the LayerZero fee required for async operations (D4, D5, R5).
+ * Refreshes every 60s — fees change with network congestion.
+ *
+ * @example
+ * const { fee, feeWithBuffer } = useLzFee('0xVAULT', 747)
+ * // feeWithBuffer adds 1% buffer automatically (fee * 101 / 100)
+ */
+export function useLzFee(vault: `0x${string}` | undefined, chainId: number) {
+  const publicClient = usePublicClient({ chainId })
+  const query = useQuery({
+    queryKey: ['lzFee', vault, chainId],
+    queryFn: () => quoteLzFee(asSdkClient(publicClient), vault!),
+    enabled: !!vault && !!publicClient,
+    refetchInterval: 60_000,
+    staleTime: 30_000,
+  })
+  return {
+    ...query,
+    fee: query.data,
+    feeWithBuffer: query.data ? (query.data * 101n) / 100n : undefined,
+  }
+}

package/src/react/useOmniDeposit.ts

@@ -0,0 +1,97 @@
+import { useState, useCallback } from 'react'
+import { usePublicClient, useWalletClient, useChainId } from 'wagmi'
+import {
+  asSdkClient,
+  depositAsync,
+  getVaultStatus,
+} from '../viem/index.js'
+import type { AsyncRequestStatusInfo } from '../viem/index.js'
+import { useLzFee } from './useLzFee.js'
+import { useAsyncRequestStatus } from './useAsyncRequestStatus.js'
+
+interface UseOmniDepositReturn {
+  /** Execute approve + depositAsync. Handles everything internally. */
+  deposit: (amountInWei: bigint, receiver: `0x${string}`) => Promise<void>
+  isLoading: boolean
+  txHash: `0x${string}` | undefined
+  /** GUID for cross-chain tracking. Available after tx confirmation. */
+  guid: `0x${string}` | undefined
+  /** Cross-chain request status. undefined until a guid is available. */
+  requestStatus: AsyncRequestStatusInfo | undefined
+  /** true when the wallet is connected to the wrong chain */
+  wrongChain: boolean
+  error: Error | undefined
+  reset: () => void
+}
+
+/**
+ * Complete hook for async deposits on hub vaults (D4 flow).
+ *
+ * Handles: fee quote, chain validation, approve, depositAsync, and GUID polling.
+ * The deposit function wraps the entire flow — callers only pass amount + receiver.
+ *
+ * @example
+ * const { deposit, isLoading, guid, requestStatus, wrongChain } = useOmniDeposit('0xVAULT', 747)
+ *
+ * if (wrongChain) return <SwitchNetworkButton chainId={747} />
+ *
+ * await deposit(parseUnits('100', 6), userAddress)
+ * // requestStatus.status goes: 'pending' → 'completed' | 'refunded'
+ */
+export function useOmniDeposit(
+  vault: `0x${string}` | undefined,
+  hubChainId: number,
+): UseOmniDepositReturn {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const { data: walletClient } = useWalletClient({ chainId: hubChainId })
+  const publicClient = usePublicClient({ chainId: hubChainId })
+  const currentChainId = useChainId()
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [txHash, setTxHash] = useState<`0x${string}` | undefined>()
+  const [guid, setGuid] = useState<`0x${string}` | undefined>()
+  const [error, setError] = useState<Error | undefined>()
+
+  const { feeWithBuffer } = useLzFee(vault, hubChainId)
+  const { data: requestStatus } = useAsyncRequestStatus(vault, guid, hubChainId)
+
+  const wrongChain = currentChainId !== hubChainId
+
+  const deposit = useCallback(
+    async (amountInWei: bigint, receiver: `0x${string}`) => {
+      if (!vault || !walletClient || !publicClient || !feeWithBuffer) return
+      setIsLoading(true)
+      setError(undefined)
+      try {
+        const pc = asSdkClient(publicClient)
+        const status = await getVaultStatus(pc, vault)
+        // walletClient from wagmi is structurally compatible with viem WalletClient
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = await depositAsync(
+          walletClient as any,
+          pc,
+          { vault, escrow: status.escrow, hubChainId },
+          amountInWei,
+          receiver,
+          feeWithBuffer,
+        )
+        setTxHash(result.txHash)
+        setGuid(result.guid)
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)))
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [vault, walletClient, publicClient, feeWithBuffer, hubChainId],
+  )
+
+  const reset = useCallback(() => {
+    setTxHash(undefined)
+    setGuid(undefined)
+    setError(undefined)
+    setIsLoading(false)
+  }, [])
+
+  return { deposit, isLoading, txHash, guid, requestStatus, wrongChain, error, reset }
+}