@oydual31/more-vaults-sdk 0.4.2 → 0.6.0

package/src/ethers/curatorSubVaults.ts

@@ -0,0 +1,443 @@
+/**
+ * Curator sub-vault read helpers for the MoreVaults ethers.js v6 SDK (Phase 5).
+ *
+ * Provides portfolio views and sub-vault analysis for curator dashboards.
+ * Supports both ERC4626 (synchronous) and ERC7540 (asynchronous) sub-vaults.
+ *
+ * All functions are read-only (no wallet needed) and use Multicall3 for
+ * batched RPC efficiency.
+ */
+
+import { Contract, Interface, ethers } from "ethers";
+import type { Provider } from "ethers";
+import {
+  SUB_VAULT_ABI,
+  ERC20_ABI,
+  METADATA_ABI,
+  VAULT_ABI,
+  VAULT_ANALYSIS_ABI,
+  REGISTRY_ABI,
+} from "./abis";
+import type {
+  SubVaultPosition,
+  SubVaultInfo,
+  ERC7540RequestStatus,
+  VaultPortfolio,
+  AssetBalance,
+} from "./types";
+
+// Multicall3 — deployed at the same address on every EVM chain
+const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
+const MULTICALL3_ABI = [
+  "function aggregate3(tuple(address target, bool allowFailure, bytes callData)[] calls) payable returns (tuple(bool success, bytes returnData)[] returnData)",
+] as const;
+
+/** keccak256("ERC4626_ID") — type ID for synchronous ERC4626 sub-vaults */
+const ERC4626_ID = ethers.keccak256(ethers.toUtf8Bytes("ERC4626_ID"));
+
+/** keccak256("ERC7540_ID") — type ID for asynchronous ERC7540 sub-vaults */
+const ERC7540_ID = ethers.keccak256(ethers.toUtf8Bytes("ERC7540_ID"));
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get active sub-vault positions held by the vault.
+ *
+ * Queries the vault's `tokensHeld` for ERC4626 and ERC7540 type IDs, then
+ * fetches balances, underlying values, and token metadata for each sub-vault.
+ * Sub-vaults with zero share balance are excluded.
+ *
+ * @param provider  Read-only provider (must be on the vault's chain)
+ * @param vault     Vault address (diamond proxy)
+ * @returns         Array of active SubVaultPosition objects
+ */
+export async function getSubVaultPositions(
+  provider: Provider,
+  vault: string
+): Promise<SubVaultPosition[]> {
+  const subVaultIface = new Interface(SUB_VAULT_ABI as unknown as string[]);
+  const vaultContract = new Contract(vault, SUB_VAULT_ABI as unknown as string[], provider);
+
+  // Step 1: fetch sub-vault lists by type in parallel
+  const [erc4626Raw, erc7540Raw] = await Promise.all([
+    (vaultContract.tokensHeld(ERC4626_ID) as Promise<string[]>).catch(() => [] as string[]),
+    (vaultContract.tokensHeld(ERC7540_ID) as Promise<string[]>).catch(() => [] as string[]),
+  ]);
+
+  const allSubVaults: Array<{ address: string; type: "erc4626" | "erc7540" }> = [
+    ...erc4626Raw.map((a) => ({ address: a, type: "erc4626" as const })),
+    ...erc7540Raw.map((a) => ({ address: a, type: "erc7540" as const })),
+  ];
+
+  if (allSubVaults.length === 0) return [];
+
+  // Step 2: multicall — balanceOf(vault), asset(), name(), symbol(), decimals() per sub-vault
+  const mc = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);
+  const erc20Iface = new Interface(ERC20_ABI as unknown as string[]);
+  const metaIface  = new Interface(METADATA_ABI as unknown as string[]);
+  const vaultIface = new Interface(VAULT_ABI as unknown as string[]);
+
+  const PER_SV = 5;
+  const subVaultCalls = allSubVaults.flatMap(({ address: sv }) => [
+    { target: sv, allowFailure: true, callData: erc20Iface.encodeFunctionData("balanceOf", [vault]) },
+    { target: sv, allowFailure: true, callData: vaultIface.encodeFunctionData("asset") },
+    { target: sv, allowFailure: true, callData: metaIface.encodeFunctionData("name") },
+    { target: sv, allowFailure: true, callData: metaIface.encodeFunctionData("symbol") },
+    { target: sv, allowFailure: true, callData: metaIface.encodeFunctionData("decimals") },
+  ]);
+
+  const subVaultResults: { success: boolean; returnData: string }[] =
+    await mc.aggregate3.staticCall(subVaultCalls);
+
+  interface PartialSV {
+    address: string;
+    type: "erc4626" | "erc7540";
+    sharesBalance: bigint;
+    underlyingAsset: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+  }
+
+  const partials: PartialSV[] = allSubVaults.map(({ address: sv, type }, i) => {
+    const base = i * PER_SV;
+    const sharesBalance = subVaultResults[base].success
+      ? (erc20Iface.decodeFunctionResult("balanceOf", subVaultResults[base].returnData)[0] as bigint)
+      : 0n;
+    const underlyingAsset = subVaultResults[base + 1].success
+      ? (vaultIface.decodeFunctionResult("asset", subVaultResults[base + 1].returnData)[0] as string)
+      : ethers.ZeroAddress;
+    const name     = subVaultResults[base + 2].success ? (metaIface.decodeFunctionResult("name",     subVaultResults[base + 2].returnData)[0] as string) : "";
+    const symbol   = subVaultResults[base + 3].success ? (metaIface.decodeFunctionResult("symbol",   subVaultResults[base + 3].returnData)[0] as string) : "";
+    const decimals = subVaultResults[base + 4].success ? (Number(metaIface.decodeFunctionResult("decimals", subVaultResults[base + 4].returnData)[0])) : 18;
+
+    return { address: sv, type, sharesBalance, underlyingAsset, name, symbol, decimals };
+  });
+
+  // Filter to positions with non-zero balance
+  const active = partials.filter((p) => p.sharesBalance > 0n);
+  if (active.length === 0) return [];
+
+  // Step 3: multicall — convertToAssets(shares) + underlying metadata per active position
+  const PER_ACTIVE = 4;
+  const activeCalls = active.flatMap(({ address: sv, sharesBalance, underlyingAsset }) => [
+    { target: sv, allowFailure: true, callData: subVaultIface.encodeFunctionData("convertToAssets", [sharesBalance]) },
+    { target: underlyingAsset, allowFailure: true, callData: metaIface.encodeFunctionData("name") },
+    { target: underlyingAsset, allowFailure: true, callData: metaIface.encodeFunctionData("symbol") },
+    { target: underlyingAsset, allowFailure: true, callData: metaIface.encodeFunctionData("decimals") },
+  ]);
+
+  const activeResults: { success: boolean; returnData: string }[] =
+    await mc.aggregate3.staticCall(activeCalls);
+
+  return active.map((p, i): SubVaultPosition => {
+    const base = i * PER_ACTIVE;
+    const underlyingValue    = activeResults[base].success
+      ? (subVaultIface.decodeFunctionResult("convertToAssets", activeResults[base].returnData)[0] as bigint)
+      : 0n;
+    const underlyingSymbol   = activeResults[base + 2].success ? (metaIface.decodeFunctionResult("symbol",   activeResults[base + 2].returnData)[0] as string) : "";
+    const underlyingDecimals = activeResults[base + 3].success ? (Number(metaIface.decodeFunctionResult("decimals", activeResults[base + 3].returnData)[0])) : 18;
+
+    return {
+      address: p.address,
+      type: p.type,
+      name: p.name,
+      symbol: p.symbol,
+      decimals: p.decimals,
+      sharesBalance: p.sharesBalance,
+      underlyingValue,
+      underlyingAsset: p.underlyingAsset,
+      underlyingSymbol,
+      underlyingDecimals,
+    };
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Detect whether a contract is an ERC7540, ERC4626, or unknown vault type.
+ *
+ * Tries to call ERC7540-specific functions first (pendingDepositRequest).
+ * Falls back to ERC4626 convertToAssets(0). Returns null if neither succeeds.
+ *
+ * @param provider  Read-only provider (must be on the same chain as subVault)
+ * @param subVault  Sub-vault contract address to probe
+ * @returns         'erc7540' | 'erc4626' | null
+ */
+export async function detectSubVaultType(
+  provider: Provider,
+  subVault: string
+): Promise<"erc4626" | "erc7540" | null> {
+  const mc = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);
+  const subVaultIface = new Interface(SUB_VAULT_ABI as unknown as string[]);
+
+  const calls = [
+    {
+      target: subVault,
+      allowFailure: true,
+      callData: subVaultIface.encodeFunctionData("pendingDepositRequest", [0n, ethers.ZeroAddress]),
+    },
+    {
+      target: subVault,
+      allowFailure: true,
+      callData: subVaultIface.encodeFunctionData("convertToAssets", [0n]),
+    },
+  ];
+
+  const results: { success: boolean; returnData: string }[] =
+    await mc.aggregate3.staticCall(calls);
+
+  if (results[0].success) return "erc7540";
+  if (results[1].success) return "erc4626";
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Analyse a specific sub-vault to understand deposit limits, metadata, type,
+ * and global-registry whitelist status.
+ *
+ * @param provider  Read-only provider (must be on the vault's chain)
+ * @param vault     Vault address (diamond proxy) — used to check maxDeposit
+ * @param subVault  Sub-vault address to analyse
+ * @returns         SubVaultInfo snapshot
+ */
+export async function getSubVaultInfo(
+  provider: Provider,
+  vault: string,
+  subVault: string
+): Promise<SubVaultInfo> {
+  const mc = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);
+  const subVaultIface     = new Interface(SUB_VAULT_ABI as unknown as string[]);
+  const metaIface         = new Interface(METADATA_ABI as unknown as string[]);
+  const vaultIface        = new Interface(VAULT_ABI as unknown as string[]);
+  const registryIface     = new Interface(REGISTRY_ABI as unknown as string[]);
+  const vaultAnalysisIface = new Interface(VAULT_ANALYSIS_ABI as unknown as string[]);
+
+  // Detect type and fetch basic metadata in parallel
+  const [type, basicResults] = await Promise.all([
+    detectSubVaultType(provider, subVault),
+    mc.aggregate3.staticCall([
+      { target: subVault, allowFailure: true, callData: metaIface.encodeFunctionData("name") },
+      { target: subVault, allowFailure: true, callData: metaIface.encodeFunctionData("symbol") },
+      { target: subVault, allowFailure: true, callData: metaIface.encodeFunctionData("decimals") },
+      { target: subVault, allowFailure: true, callData: vaultIface.encodeFunctionData("asset") },
+      { target: subVault, allowFailure: true, callData: subVaultIface.encodeFunctionData("maxDeposit", [vault]) },
+    ]) as Promise<{ success: boolean; returnData: string }[]>,
+  ]);
+
+  const name       = basicResults[0].success ? (metaIface.decodeFunctionResult("name",     basicResults[0].returnData)[0] as string) : "";
+  const symbol     = basicResults[1].success ? (metaIface.decodeFunctionResult("symbol",   basicResults[1].returnData)[0] as string) : "";
+  const decimals   = basicResults[2].success ? (Number(metaIface.decodeFunctionResult("decimals", basicResults[2].returnData)[0])) : 18;
+  const underlying = basicResults[3].success ? (vaultIface.decodeFunctionResult("asset",   basicResults[3].returnData)[0] as string) : ethers.ZeroAddress;
+  const maxDeposit = basicResults[4].success ? (subVaultIface.decodeFunctionResult("maxDeposit", basicResults[4].returnData)[0] as bigint) : 0n;
+
+  // Fetch underlying metadata and registry in parallel
+  const [underlyingResults, registryRaw] = await Promise.all([
+    mc.aggregate3.staticCall([
+      { target: underlying, allowFailure: true, callData: metaIface.encodeFunctionData("symbol") },
+      { target: underlying, allowFailure: true, callData: metaIface.encodeFunctionData("decimals") },
+    ]) as Promise<{ success: boolean; returnData: string }[]>,
+    new Contract(vault, VAULT_ANALYSIS_ABI as unknown as string[], provider)
+      .moreVaultsRegistry()
+      .catch(() => null) as Promise<string | null>,
+  ]);
+
+  const underlyingSymbol   = underlyingResults[0].success ? (metaIface.decodeFunctionResult("symbol",   underlyingResults[0].returnData)[0] as string) : "";
+  const underlyingDecimals = underlyingResults[1].success ? (Number(metaIface.decodeFunctionResult("decimals", underlyingResults[1].returnData)[0])) : 18;
+
+  let isWhitelisted = false;
+  if (registryRaw) {
+    const whitelistResult = await (new Contract(registryRaw, REGISTRY_ABI as unknown as string[], provider)
+      .isWhitelisted(subVault) as Promise<boolean>)
+      .catch(() => false);
+    isWhitelisted = whitelistResult;
+  }
+
+  return {
+    address: subVault,
+    type: type ?? "erc4626",
+    name,
+    symbol,
+    decimals,
+    underlyingAsset: underlying,
+    underlyingSymbol,
+    underlyingDecimals,
+    maxDeposit,
+    isWhitelisted,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get the ERC7540 async request status for a specific sub-vault and vault controller.
+ *
+ * @param provider  Read-only provider (must be on the vault's chain)
+ * @param vault     Vault address acting as controller in the sub-vault
+ * @param subVault  ERC7540 sub-vault address
+ * @returns         ERC7540RequestStatus with canFinalize flags
+ */
+export async function getERC7540RequestStatus(
+  provider: Provider,
+  vault: string,
+  subVault: string
+): Promise<ERC7540RequestStatus> {
+  const mc = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);
+  const subVaultIface = new Interface(SUB_VAULT_ABI as unknown as string[]);
+
+  const calls = [
+    { target: subVault, allowFailure: true, callData: subVaultIface.encodeFunctionData("pendingDepositRequest",   [0n, vault]) },
+    { target: subVault, allowFailure: true, callData: subVaultIface.encodeFunctionData("claimableDepositRequest", [0n, vault]) },
+    { target: subVault, allowFailure: true, callData: subVaultIface.encodeFunctionData("pendingRedeemRequest",    [0n, vault]) },
+    { target: subVault, allowFailure: true, callData: subVaultIface.encodeFunctionData("claimableRedeemRequest",  [0n, vault]) },
+  ];
+
+  const results: { success: boolean; returnData: string }[] =
+    await mc.aggregate3.staticCall(calls);
+
+  const pendingDeposit   = results[0].success ? (subVaultIface.decodeFunctionResult("pendingDepositRequest",   results[0].returnData)[0] as bigint) : 0n;
+  const claimableDeposit = results[1].success ? (subVaultIface.decodeFunctionResult("claimableDepositRequest", results[1].returnData)[0] as bigint) : 0n;
+  const pendingRedeem    = results[2].success ? (subVaultIface.decodeFunctionResult("pendingRedeemRequest",    results[2].returnData)[0] as bigint) : 0n;
+  const claimableRedeem  = results[3].success ? (subVaultIface.decodeFunctionResult("claimableRedeemRequest",  results[3].returnData)[0] as bigint) : 0n;
+
+  return {
+    subVault,
+    pendingDeposit,
+    claimableDeposit,
+    pendingRedeem,
+    claimableRedeem,
+    canFinalizeDeposit: claimableDeposit > 0n,
+    canFinalizeRedeem:  claimableRedeem  > 0n,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Preview how many shares the vault would receive for a given asset deposit.
+ *
+ * @param provider  Read-only provider
+ * @param subVault  Sub-vault address (ERC4626 or ERC7540)
+ * @param assets    Amount of underlying assets to preview
+ * @returns         Expected shares to be minted
+ */
+export async function previewSubVaultDeposit(
+  provider: Provider,
+  subVault: string,
+  assets: bigint
+): Promise<bigint> {
+  const contract = new Contract(subVault, SUB_VAULT_ABI as unknown as string[], provider);
+  return (await contract.previewDeposit(assets)) as bigint;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Preview how many underlying assets would be returned for redeeming shares.
+ *
+ * @param provider  Read-only provider
+ * @param subVault  Sub-vault address (ERC4626 or ERC7540)
+ * @param shares    Number of shares to preview redemption for
+ * @returns         Expected underlying assets to be returned
+ */
+export async function previewSubVaultRedeem(
+  provider: Provider,
+  subVault: string,
+  shares: bigint
+): Promise<bigint> {
+  const contract = new Contract(subVault, SUB_VAULT_ABI as unknown as string[], provider);
+  return (await contract.previewRedeem(shares)) as bigint;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get the complete portfolio view for a vault, combining liquid asset balances
+ * with active sub-vault positions and locked ERC7540 assets.
+ *
+ * @param provider  Read-only provider (must be on the vault's hub chain)
+ * @param vault     Vault address (diamond proxy)
+ * @returns         VaultPortfolio with full breakdown
+ */
+export async function getVaultPortfolio(
+  provider: Provider,
+  vault: string
+): Promise<VaultPortfolio> {
+  const mc = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);
+  const subVaultIface      = new Interface(SUB_VAULT_ABI as unknown as string[]);
+  const vaultAnalysisIface = new Interface(VAULT_ANALYSIS_ABI as unknown as string[]);
+  const vaultIface         = new Interface(VAULT_ABI as unknown as string[]);
+  const erc20Iface         = new Interface(ERC20_ABI as unknown as string[]);
+  const metaIface          = new Interface(METADATA_ABI as unknown as string[]);
+
+  // Step 1: get available assets, sub-vault positions, and vault totals in parallel
+  const [availableRaw, subVaultPositions, vaultTotals] = await Promise.all([
+    (new Contract(vault, VAULT_ANALYSIS_ABI as unknown as string[], provider).getAvailableAssets() as Promise<string[]>)
+      .catch(() => [] as string[]),
+    getSubVaultPositions(provider, vault),
+    mc.aggregate3.staticCall([
+      { target: vault, allowFailure: true, callData: vaultIface.encodeFunctionData("totalAssets") },
+      { target: vault, allowFailure: true, callData: vaultIface.encodeFunctionData("totalSupply") },
+      { target: vault, allowFailure: true, callData: vaultIface.encodeFunctionData("asset") },
+    ]) as Promise<{ success: boolean; returnData: string }[]>,
+  ]);
+
+  const totalAssets     = vaultTotals[0].success ? (vaultIface.decodeFunctionResult("totalAssets", vaultTotals[0].returnData)[0] as bigint) : 0n;
+  const totalSupply     = vaultTotals[1].success ? (vaultIface.decodeFunctionResult("totalSupply", vaultTotals[1].returnData)[0] as bigint) : 0n;
+  const underlyingAsset = vaultTotals[2].success ? (vaultIface.decodeFunctionResult("asset",       vaultTotals[2].returnData)[0] as string) : ethers.ZeroAddress;
+
+  // Exclude sub-vault share addresses from liquid asset list
+  const subVaultAddressSet = new Set(subVaultPositions.map((p) => p.address.toLowerCase()));
+  const liquidAddresses = (availableRaw as string[]).filter(
+    (addr) => !subVaultAddressSet.has(addr.toLowerCase()),
+  );
+
+  // Step 2: fetch balances + metadata for liquid assets
+  const PER_ASSET = 4;
+  let liquidAssets: AssetBalance[] = [];
+
+  if (liquidAddresses.length > 0) {
+    const liquidCalls = liquidAddresses.flatMap((addr) => [
+      { target: addr, allowFailure: true, callData: erc20Iface.encodeFunctionData("balanceOf", [vault]) },
+      { target: addr, allowFailure: true, callData: metaIface.encodeFunctionData("name") },
+      { target: addr, allowFailure: true, callData: metaIface.encodeFunctionData("symbol") },
+      { target: addr, allowFailure: true, callData: metaIface.encodeFunctionData("decimals") },
+    ]);
+
+    const liquidResults: { success: boolean; returnData: string }[] =
+      await mc.aggregate3.staticCall(liquidCalls);
+
+    liquidAssets = liquidAddresses.map((addr, i): AssetBalance => {
+      const base     = i * PER_ASSET;
+      const balance  = liquidResults[base].success     ? (erc20Iface.decodeFunctionResult("balanceOf", liquidResults[base].returnData)[0] as bigint)          : 0n;
+      const name     = liquidResults[base + 1].success ? (metaIface.decodeFunctionResult("name",       liquidResults[base + 1].returnData)[0] as string)       : "";
+      const symbol   = liquidResults[base + 2].success ? (metaIface.decodeFunctionResult("symbol",     liquidResults[base + 2].returnData)[0] as string)       : "";
+      const decimals = liquidResults[base + 3].success ? (Number(metaIface.decodeFunctionResult("decimals", liquidResults[base + 3].returnData)[0]))           : 18;
+      return { address: addr, name, symbol, decimals, balance };
+    });
+  }
+
+  // Step 3: locked assets for the vault's underlying (ERC7540 pending requests)
+  const lockedAssets = await (new Contract(vault, SUB_VAULT_ABI as unknown as string[], provider)
+    .lockedTokensAmountOfAsset(underlyingAsset) as Promise<bigint>)
+    .catch(() => 0n);
+
+  // Step 4: compute approximate total value
+  const subVaultTotal = subVaultPositions.reduce((sum, p) => sum + p.underlyingValue, 0n);
+  const underlyingBalance = liquidAssets.find(
+    (a) => a.address.toLowerCase() === underlyingAsset.toLowerCase(),
+  )?.balance ?? 0n;
+  const totalValue = underlyingBalance + subVaultTotal;
+
+  return {
+    liquidAssets,
+    subVaultPositions,
+    totalValue,
+    totalAssets,
+    totalSupply,
+    lockedAssets,
+  };
+}

package/src/ethers/index.ts

@@ -27,6 +27,11 @@ export type {
   VaultAnalysis,
   AssetBalance,
   VaultAssetBreakdown,
+  // Sub-vault types (Phase 5)
+  SubVaultPosition,
+  SubVaultInfo,
+  ERC7540RequestStatus,
+  VaultPortfolio,
 } from "./types";
 export { ActionType } from "./types";
 
@@ -49,6 +54,7 @@ export {
   LZ_ADAPTER_ABI,
   VAULT_ANALYSIS_ABI,
   REGISTRY_ABI,
+  SUB_VAULT_ABI,
 } from "./abis";
 
 // --- Errors ---
@@ -171,6 +177,26 @@ export {
   encodeUniswapV3SwapCalldata,
 } from "./curatorSwaps";
 
+// --- Curator bridge helpers ---
+export {
+  encodeBridgeParams,
+  quoteCuratorBridgeFee,
+  executeCuratorBridge,
+  findBridgeRoute,
+} from "./curatorBridge";
+export type { CuratorBridgeParams } from "./curatorBridge";
+
+// --- Curator Sub-Vault Operations (Phase 5) ---
+export {
+  getSubVaultPositions,
+  detectSubVaultType,
+  getSubVaultInfo,
+  getERC7540RequestStatus,
+  previewSubVaultDeposit,
+  previewSubVaultRedeem,
+  getVaultPortfolio,
+} from "./curatorSubVaults";
+
 // --- Topology ---
 export {
   getVaultTopology,

package/src/ethers/types.ts

@@ -165,4 +165,103 @@ export interface VaultAssetBreakdown {
   underlyingDecimals: number;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Sub-vault Types (Phase 5)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A single active sub-vault position held by the curator vault.
+ * Covers both ERC4626 (synchronous) and ERC7540 (asynchronous) sub-vaults.
+ */
+export interface SubVaultPosition {
+  /** Sub-vault contract address */
+  address: string;
+  /** Protocol type of the sub-vault */
+  type: "erc4626" | "erc7540";
+  /** Name of the sub-vault share token */
+  name: string;
+  /** Symbol of the sub-vault share token */
+  symbol: string;
+  /** Decimals of the sub-vault share token */
+  decimals: number;
+  /** Shares of the sub-vault held by the curator vault */
+  sharesBalance: bigint;
+  /** Current value of the shares in terms of the sub-vault's underlying asset */
+  underlyingValue: bigint;
+  /** Underlying asset address of the sub-vault */
+  underlyingAsset: string;
+  /** Symbol of the sub-vault's underlying asset */
+  underlyingSymbol: string;
+  /** Decimals of the sub-vault's underlying asset */
+  underlyingDecimals: number;
+}
+
+/**
+ * Metadata and capability snapshot for a potential sub-vault investment target.
+ */
+export interface SubVaultInfo {
+  /** Sub-vault contract address */
+  address: string;
+  /** Protocol type: ERC4626 (sync) or ERC7540 (async) */
+  type: "erc4626" | "erc7540";
+  /** Sub-vault share token name */
+  name: string;
+  /** Sub-vault share token symbol */
+  symbol: string;
+  /** Sub-vault share token decimals */
+  decimals: number;
+  /** Underlying asset address */
+  underlyingAsset: string;
+  /** Underlying asset symbol */
+  underlyingSymbol: string;
+  /** Underlying asset decimals */
+  underlyingDecimals: number;
+  /** Maximum amount the curator vault can deposit (from maxDeposit(vault)) */
+  maxDeposit: bigint;
+  /** Whether the sub-vault is whitelisted in the global MoreVaults registry */
+  isWhitelisted: boolean;
+}
+
+/**
+ * Status of pending and claimable ERC7540 async requests for a sub-vault.
+ * Uses requestId = 0 (the standard default for non-batch ERC7540 vaults).
+ */
+export interface ERC7540RequestStatus {
+  /** Sub-vault address these statuses belong to */
+  subVault: string;
+  /** Assets in a pending deposit request (not yet claimable) */
+  pendingDeposit: bigint;
+  /** Assets ready to be claimed/finalized as shares */
+  claimableDeposit: bigint;
+  /** Shares in a pending redeem request (not yet claimable) */
+  pendingRedeem: bigint;
+  /** Assets ready to be claimed after redeem fulfillment */
+  claimableRedeem: bigint;
+  /** True if claimableDeposit > 0 — vault can call erc7540Deposit to finalize */
+  canFinalizeDeposit: boolean;
+  /** True if claimableRedeem > 0 — vault can call erc7540Redeem to finalize */
+  canFinalizeRedeem: boolean;
+}
+
+/**
+ * Full portfolio view for a curator vault combining liquid and invested assets.
+ */
+export interface VaultPortfolio {
+  /** Liquid ERC20 asset balances held directly by the vault (excludes sub-vault share tokens) */
+  liquidAssets: AssetBalance[];
+  /** Active positions in ERC4626/ERC7540 sub-vaults */
+  subVaultPositions: SubVaultPosition[];
+  /**
+   * Approximate total value in underlying terms:
+   * liquid underlying balance + sum of sub-vault convertToAssets values.
+   */
+  totalValue: bigint;
+  /** totalAssets() from the vault — authoritative AUM figure */
+  totalAssets: bigint;
+  /** totalSupply() of vault shares */
+  totalSupply: bigint;
+  /** Assets locked in pending ERC7540 requests (lockedTokensAmountOfAsset) */
+  lockedAssets: bigint;
+}
+
 export type { Signer, Provider, ContractTransactionReceipt };

package/src/react/index.ts

@@ -62,3 +62,17 @@ export type { CuratorAction } from './useSubmitActions.js'
 export { useExecuteActions } from './useExecuteActions.js'
 
 export { useVetoActions } from './useVetoActions.js'
+
+// --- Curator Bridge hooks ---
+export { useCuratorBridgeQuote } from './useCuratorBridgeQuote.js'
+export { useExecuteBridge } from './useExecuteBridge.js'
+
+// --- Curator Sub-Vault hooks (Phase 5) ---
+export { useSubVaultPositions } from './useSubVaultPositions.js'
+export type { SubVaultPosition } from './useSubVaultPositions.js'
+
+export { useVaultPortfolio } from './useVaultPortfolio.js'
+export type { VaultPortfolio } from './useVaultPortfolio.js'
+
+export { useERC7540RequestStatus } from './useERC7540RequestStatus.js'
+export type { ERC7540RequestStatus } from './useERC7540RequestStatus.js'

package/src/react/useCuratorBridgeQuote.ts

@@ -0,0 +1,43 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, quoteCuratorBridgeFee } from '../viem/index.js'
+import type { CuratorBridgeParams } from '../viem/index.js'
+
+export type { CuratorBridgeParams }
+
+/**
+ * Quote the native fee required to bridge assets from the hub vault via LzAdapter.
+ *
+ * Refreshes every 60s — bridge fees fluctuate with LayerZero network demand.
+ *
+ * @example
+ * ```tsx
+ * const { fee, isLoading } = useCuratorBridgeQuote('0xVAULT', 8453, {
+ *   oftToken: '0x27a16dc786820B16E5c9028b75B99F6f604b5d26',
+ *   dstEid: 30101,
+ *   amount: 1_000_000n,
+ *   dstVault: '0xSpokeVault...',
+ *   refundAddress: '0xCurator...',
+ * })
+ * ```
+ */
+export function useCuratorBridgeQuote(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+  params: CuratorBridgeParams | undefined,
+) {
+  const publicClient = usePublicClient({ chainId })
+
+  const query = useQuery({
+    queryKey: ['curatorBridgeQuote', vault, chainId, params],
+    queryFn: () => quoteCuratorBridgeFee(asSdkClient(publicClient), vault!, params!),
+    enabled: !!vault && !!publicClient && !!params,
+    refetchInterval: 60_000,
+    staleTime: 30_000,
+  })
+
+  return {
+    ...query,
+    fee: query.data,
+  }
+}