@oydual31/more-vaults-sdk 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oydual31/more-vaults-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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/ethers/utils.ts

@@ -265,10 +265,14 @@ export async function getVaultStatus(
 
   const spokesDeployedBalance: bigint = totalAssets > hubLiquidBalance ? totalAssets - hubLiquidBalance : 0n;
 
-  // null = maxDeposit reverted → whitelist/ACL vault
+  // null = maxDeposit reverted.
+  // For cross-chain-async hubs this is expected — the contract reverts with
+  // NotAnERC4626CompatibleVault because maxDeposit is not meaningful in async mode.
+  // Only treat the revert as "whitelist/ACL" when the vault is NOT a hub.
   const MAX_UINT256 = BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff');
-  const depositAccessRestricted = maxDepositRaw === null;
-  const effectiveCapacity: bigint = depositAccessRestricted ? MAX_UINT256 : maxDepositRaw!;
+  const isCrossChainAsync = isHub && !oraclesEnabled;
+  const depositAccessRestricted = maxDepositRaw === null && !isCrossChainAsync;
+  const effectiveCapacity: bigint = maxDepositRaw === null ? MAX_UINT256 : maxDepositRaw!;
 
   // ── Derive mode ────────────────────────────────────────────────────────────
   let mode: VaultMode;

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 }
+}

package/src/react/useOmniRedeem.ts

@@ -0,0 +1,96 @@
+import { useState, useCallback } from 'react'
+import { usePublicClient, useWalletClient, useChainId } from 'wagmi'
+import {
+  asSdkClient,
+  redeemAsync,
+  getVaultStatus,
+} from '../viem/index.js'
+import type { AsyncRequestStatusInfo } from '../viem/index.js'
+import { useLzFee } from './useLzFee.js'
+import { useAsyncRequestStatus } from './useAsyncRequestStatus.js'
+
+interface UseOmniRedeemReturn {
+  /** Execute approve + redeemAsync. Handles everything internally. */
+  redeem: (sharesInWei: bigint, receiver: `0x${string}`, owner: `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 redeems on hub vaults (R5 flow).
+ *
+ * Handles: fee quote, chain validation, share approve, redeemAsync, and GUID polling.
+ *
+ * @example
+ * const { redeem, isLoading, guid, requestStatus, wrongChain } = useOmniRedeem('0xVAULT', 747)
+ *
+ * if (wrongChain) return <SwitchNetworkButton chainId={747} />
+ *
+ * await redeem(sharesInWei, userAddress, userAddress)
+ * // requestStatus.status goes: 'pending' → 'completed' | 'refunded'
+ */
+export function useOmniRedeem(
+  vault: `0x${string}` | undefined,
+  hubChainId: number,
+): UseOmniRedeemReturn {
+  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 redeem = useCallback(
+    async (sharesInWei: bigint, receiver: `0x${string}`, owner: `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 redeemAsync(
+          walletClient as any,
+          pc,
+          { vault, escrow: status.escrow, hubChainId },
+          sharesInWei,
+          receiver,
+          owner,
+          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 { redeem, isLoading, txHash, guid, requestStatus, wrongChain, error, reset }
+}

package/src/react/useRedeemShares.ts

@@ -0,0 +1,77 @@
+import { useState, useCallback } from 'react'
+import { usePublicClient, useWalletClient } from 'wagmi'
+import { asSdkClient, redeemShares } from '../viem/index.js'
+import type { RedeemResult } from '../viem/index.js'
+
+interface UseRedeemSharesReturn {
+  /** Execute redeemShares (R1 flow). */
+  redeem: (sharesInWei: bigint, receiver: `0x${string}`, owner: `0x${string}`) => Promise<void>
+  isLoading: boolean
+  txHash: `0x${string}` | undefined
+  /** Assets received. Available after tx confirmation. */
+  assets: bigint | undefined
+  error: Error | undefined
+  reset: () => void
+}
+
+/**
+ * Hook for standard ERC-4626 share redemption (R1 flow).
+ *
+ * Used for local and oracle-on cross-chain vaults.
+ * No LZ fee required — single transaction.
+ *
+ * @example
+ * const { redeem, isLoading, txHash, assets } = useRedeemShares('0xVAULT', 747)
+ * await redeem(sharesInWei, userAddress, userAddress)
+ */
+export function useRedeemShares(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+): UseRedeemSharesReturn {
+  const { data: walletClient } = useWalletClient({ chainId })
+  const publicClient = usePublicClient({ chainId })
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [result, setResult] = useState<RedeemResult | undefined>()
+  const [error, setError] = useState<Error | undefined>()
+
+  const redeem = useCallback(
+    async (sharesInWei: bigint, receiver: `0x${string}`, owner: `0x${string}`) => {
+      if (!vault || !walletClient || !publicClient) return
+      setIsLoading(true)
+      setError(undefined)
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await redeemShares(
+          walletClient as any,
+          asSdkClient(publicClient),
+          { vault, hubChainId: chainId },
+          sharesInWei,
+          receiver,
+          owner,
+        )
+        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 {
+    redeem,
+    isLoading,
+    txHash: result?.txHash,
+    assets: result?.assets,
+    error,
+    reset,
+  }
+}

package/src/react/useSmartDeposit.ts

@@ -0,0 +1,70 @@
+import type { DepositResult, AsyncRequestResult, AsyncRequestStatusInfo } from '../viem/index.js'
+import { useVaultStatus } from './useVaultStatus.js'
+import { useOmniDeposit } from './useOmniDeposit.js'
+import { useDepositSimple } from './useDepositSimple.js'
+
+interface UseSmartDepositReturn {
+  /**
+   * Execute deposit using the correct flow for this vault's mode.
+   * For async vaults: wraps depositAsync (D4) — returns guid for tracking.
+   * For local/oracle vaults: wraps depositSimple (D1/D3) — returns shares.
+   */
+  deposit: (amountInWei: bigint, receiver: `0x${string}`) => Promise<void>
+  isLoading: boolean
+  txHash: `0x${string}` | undefined
+  /** Shares minted (available for D1/D3 vaults after confirmation, undefined for D4). */
+  shares: bigint | undefined
+  /** GUID for cross-chain tracking (D4 vaults only). */
+  guid: `0x${string}` | undefined
+  /** Cross-chain request status (D4 vaults only). */
+  requestStatus: AsyncRequestStatusInfo | undefined
+  /** true when the wallet is connected to the wrong chain (D4 vaults only). */
+  wrongChain: boolean
+  /** Vault mode loaded from getVaultStatus. undefined while loading. */
+  vaultMode: 'local' | 'cross-chain-oracle' | 'cross-chain-async' | 'paused' | 'full' | undefined
+  error: Error | undefined
+  reset: () => void
+}
+
+/**
+ * Auto-selects the correct deposit flow based on vault mode.
+ * Best for frontends that support multiple vault types.
+ *
+ * Internally uses useVaultStatus to detect the mode, then delegates to:
+ * - useOmniDeposit (D4) for 'cross-chain-async' vaults
+ * - useDepositSimple (D1/D3) for 'local' and 'cross-chain-oracle' vaults
+ *
+ * @example
+ * const { deposit, isLoading, guid, requestStatus, vaultMode } = useSmartDeposit('0xVAULT', 747)
+ *
+ * if (vaultMode === 'paused') return <PausedBadge />
+ *
+ * await deposit(parseUnits('100', 6), userAddress)
+ * // For async vaults: poll requestStatus until 'completed'
+ * // For sync vaults: txHash + shares are available immediately
+ */
+export function useSmartDeposit(
+  vault: `0x${string}` | undefined,
+  hubChainId: number,
+): UseSmartDepositReturn {
+  const { data: status } = useVaultStatus(vault, hubChainId)
+  const omni = useOmniDeposit(vault, hubChainId)
+  const simple = useDepositSimple(vault, hubChainId)
+
+  const isAsync = status?.mode === 'cross-chain-async'
+
+  const deposit = isAsync ? omni.deposit : simple.deposit
+
+  return {
+    deposit,
+    isLoading: isAsync ? omni.isLoading : simple.isLoading,
+    txHash: isAsync ? omni.txHash : simple.txHash,
+    shares: isAsync ? undefined : simple.shares,
+    guid: isAsync ? omni.guid : undefined,
+    requestStatus: isAsync ? omni.requestStatus : undefined,
+    wrongChain: isAsync ? omni.wrongChain : false,
+    vaultMode: status?.mode,
+    error: isAsync ? omni.error : simple.error,
+    reset: isAsync ? omni.reset : simple.reset,
+  }
+}

package/src/react/useUserPosition.ts

@@ -0,0 +1,29 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, getUserPosition } from '../viem/index.js'
+import type { UserPosition } from '../viem/index.js'
+
+export type { UserPosition }
+
+/**
+ * Read the user's current position in a vault.
+ * Refetches every 15s to keep the balance display current.
+ *
+ * @example
+ * const { data: position } = useUserPosition('0xVAULT', '0xUSER', 747)
+ * // position.shares, position.estimatedAssets, position.pendingWithdrawal
+ */
+export function useUserPosition(
+  vault: `0x${string}` | undefined,
+  user: `0x${string}` | undefined,
+  chainId: number,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['userPosition', vault, user, chainId],
+    queryFn: () => getUserPosition(asSdkClient(publicClient), vault!, user!),
+    enabled: !!vault && !!user && !!publicClient,
+    refetchInterval: 15_000,
+    staleTime: 10_000,
+  })
+}

package/src/react/useVaultMetadata.ts

@@ -0,0 +1,29 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, getVaultMetadata } from '../viem/index.js'
+import type { VaultMetadata } from '../viem/index.js'
+
+export type { VaultMetadata }
+
+/**
+ * Read display metadata for a vault and its underlying token.
+ * Uses a long stale time (5 min) because metadata rarely changes.
+ *
+ * @example
+ * const { data: meta } = useVaultMetadata('0xVAULT', 747)
+ * // meta.name, meta.symbol, meta.underlying, meta.underlyingSymbol
+ */
+export function useVaultMetadata(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['vaultMetadata', vault, chainId],
+    queryFn: () => getVaultMetadata(asSdkClient(publicClient), vault!),
+    enabled: !!vault && !!publicClient,
+    // Metadata (name, symbol, underlying) changes very rarely — 5 min stale time
+    staleTime: 5 * 60_000,
+    refetchInterval: 5 * 60_000,
+  })
+}