@oydual31/more-vaults-sdk 0.3.3 → 0.4.1

package/src/ethers/spokeRoutes.ts

@@ -0,0 +1,361 @@
+/**
+ * Spoke route helpers for the MoreVaults ethers.js v6 SDK.
+ *
+ * Provides functions to discover inbound/outbound cross-chain deposit and
+ * redemption routes, and to quote LayerZero fees for those routes.
+ */
+
+import { Contract, ZeroAddress } from "ethers";
+import type { Provider } from "ethers";
+import { OFT_ROUTES, CHAIN_ID_TO_EID, createChainProvider } from "./chains";
+import { OFT_ABI, ERC20_ABI } from "./abis";
+import { isAsyncMode, quoteLzFee } from "./utils";
+import { getVaultTopology } from "./topology";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface OutboundRoute {
+  /** Chain ID where user can receive shares/assets */
+  chainId: number;
+  /** Whether this chain is the hub (direct redeem) or a spoke (shares bridged back) */
+  routeType: "hub" | "spoke";
+  /** LZ EID for this chain */
+  eid: number;
+  /** Native gas symbol */
+  nativeSymbol: string;
+}
+
+export interface InboundRoute {
+  /** Internal route identifier from OFT_ROUTES (e.g. 'stgUSDC') — do NOT show to users */
+  symbol: string;
+  /** Chain ID where user sends from */
+  spokeChainId: number;
+  /**
+   * How the deposit is executed:
+   * - 'direct'       → user is on the hub chain, vault uses standard ERC-4626 (depositSimple). No LZ fee.
+   * - 'direct-async' → user is on the hub chain, vault uses async accounting (depositAsync). LZ fee required.
+   * - 'oft-compose'  → user is on a spoke chain, use depositFromSpoke via OFT compose. LZ fee required.
+   */
+  depositType: "direct" | "direct-async" | "oft-compose";
+  /** OFT contract on spoke chain — pass as `spokeOFT` to depositFromSpoke. Null for direct deposits. */
+  spokeOft: string | null;
+  /** Token user must approve on spoke chain (ZeroAddress = native ETH) */
+  spokeToken: string;
+  /**
+   * Human-readable symbol of the token the user needs to hold on the spoke chain.
+   * For OFTAdapters this is the underlying token symbol (e.g. 'USDC', 'weETH').
+   * For pure OFTs this is the OFT's own symbol (e.g. 'sUSDe', 'USDe').
+   * Use this — not `symbol` — when displaying the token name to users.
+   */
+  sourceTokenSymbol: string;
+  /** OFT contract on hub chain — receives tokens for the composer. Null for direct deposits. */
+  hubOft: string | null;
+  /** oftCmd to use in SendParam (0x01 for Stargate taxi, 0x for standard OFT) */
+  oftCmd: string;
+  /** LZ fee estimate in native wei of the SPOKE chain (not always ETH — e.g. FLOW on Flow EVM) */
+  lzFeeEstimate: bigint;
+  /** Native gas token symbol for the spoke chain — use this when displaying the fee */
+  nativeSymbol: string;
+}
+
+export interface InboundRouteWithBalance extends InboundRoute {
+  /** User's token balance on the spoke chain */
+  userBalance: bigint;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Native gas token symbol per chain ID — lzFeeEstimate is denominated in this token */
+export const NATIVE_SYMBOL: Partial<Record<number, string>> = {
+  1:     "ETH",
+  10:    "ETH",
+  42161: "ETH",
+  8453:  "ETH",
+  747:   "FLOW",
+  146:   "S",
+  56:    "BNB",
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SYMBOL_ABI = [
+  "function symbol() view returns (string)",
+] as const;
+
+/** Read ERC20 symbol() on-chain. Falls back to `fallbackSymbol` if the call fails. */
+async function readTokenSymbol(
+  provider: Provider | null,
+  token: string,
+  fallbackSymbol: string,
+): Promise<string> {
+  if (!provider) return fallbackSymbol;
+  try {
+    const contract = new Contract(token, SYMBOL_ABI, provider);
+    return await (contract.symbol() as Promise<string>);
+  } catch {
+    return fallbackSymbol;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Find all valid OFT inbound routes for a vault.
+ *
+ * Only returns routes for chains where the vault has a registered spoke —
+ * this is required so the composer can send shares back to the user's chain.
+ * The hub chain is always included as a 'direct' deposit option.
+ *
+ * Routes that revert on quoteSend() (no liquidity, no peer) are excluded.
+ *
+ * @param hubChainId   Chain ID of the vault hub (e.g. 8453 for Base)
+ * @param vault        Vault address (to resolve registered spoke chains)
+ * @param vaultAsset   vault.asset() address on the hub chain
+ * @param userAddress  User address (used as receiver for fee quote)
+ */
+export async function getInboundRoutes(
+  hubChainId: number,
+  vault: string,
+  vaultAsset: string,
+  userAddress: string,
+): Promise<InboundRoute[]> {
+  const hubEid = CHAIN_ID_TO_EID[hubChainId];
+  if (!hubEid) throw new Error(`No LZ EID for hub chainId ${hubChainId}`);
+
+  // Fetch vault topology to get registered spoke chains
+  const hubProvider = createChainProvider(hubChainId);
+  if (!hubProvider) throw new Error(`No public RPC for hub chainId ${hubChainId}`);
+  const topology = await getVaultTopology(hubProvider, vault);
+  const registeredSpokes = new Set(topology.spokeChainIds);
+
+  const results: InboundRoute[] = [];
+
+  const vaultAssetNorm = vaultAsset.toLowerCase();
+
+  for (const [symbol, chainMap] of Object.entries(OFT_ROUTES)) {
+    const hubEntry = (chainMap as Record<number, { oft: string; token: string }>)[hubChainId];
+    if (!hubEntry) continue;
+
+    // Does this OFT deliver the right asset to the hub?
+    if (hubEntry.token.toLowerCase() !== vaultAssetNorm) continue;
+
+    // oftCmd for OFT compose deposits: always '0x' (TAXI mode = immediate delivery with composeMsg).
+    const oftCmd = "0x";
+
+    // Only check chains where the vault has a registered spoke
+    const spokesToCheck = Object.keys(chainMap)
+      .map(Number)
+      .filter((id) => id !== hubChainId && registeredSpokes.has(id));
+
+    await Promise.allSettled(
+      spokesToCheck.map(async (spokeChainId) => {
+        const spokeEntry = (chainMap as Record<number, { oft: string; token: string }>)[spokeChainId];
+        if (!spokeEntry) return;
+
+        const spokeProvider = createChainProvider(spokeChainId);
+        if (!spokeProvider) return;
+
+        // Validate route via quoteSend — if it reverts, skip
+        try {
+          const receiverBytes32 =
+            "0x" + userAddress.replace(/^0x/, "").toLowerCase().padStart(64, "0");
+
+          const spokeOft = new Contract(spokeEntry.oft, OFT_ABI, spokeProvider);
+          const [feeResult, sourceTokenSymbol] = await Promise.all([
+            spokeOft.quoteSend(
+              {
+                dstEid: hubEid,
+                to: receiverBytes32,
+                amountLD: 1_000_000n,
+                minAmountLD: 0n,
+                extraOptions: "0x",
+                composeMsg: "0x",
+                oftCmd,
+              },
+              false,
+            ),
+            readTokenSymbol(spokeProvider, spokeEntry.token, symbol),
+          ]);
+
+          results.push({
+            symbol,
+            spokeChainId,
+            depositType: "oft-compose",
+            spokeOft: spokeEntry.oft,
+            spokeToken: spokeEntry.token,
+            sourceTokenSymbol,
+            hubOft: hubEntry.oft,
+            oftCmd,
+            lzFeeEstimate: feeResult.nativeFee as bigint,
+            nativeSymbol: NATIVE_SYMBOL[spokeChainId] ?? "ETH",
+          });
+        } catch {
+          // Route not available — skip silently
+        }
+      }),
+    );
+  }
+
+  // Add the hub chain itself as a deposit option.
+  // For async vaults the vault uses depositAsync which requires a LZ fee even on the hub chain.
+  const [asyncMode, ...hubOftEntries] = await Promise.all([
+    isAsyncMode(hubProvider, vault),
+    ...Object.entries(OFT_ROUTES).map(async ([sym, chainMap]) => {
+      const hubEntry = (chainMap as Record<number, { oft: string; token: string }>)[hubChainId];
+      if (!hubEntry || hubEntry.token.toLowerCase() !== vaultAssetNorm) return null;
+      return { symbol: sym, hubEntry };
+    }),
+  ]);
+
+  const hubOftEntry = hubOftEntries.find((e) => e !== null) ?? null;
+
+  if (hubOftEntry) {
+    const { symbol, hubEntry } = hubOftEntry as { symbol: string; hubEntry: { oft: string; token: string } };
+    const [sourceTokenSymbol, lzFeeEstimate] = await Promise.all([
+      readTokenSymbol(hubProvider, hubEntry.token, symbol),
+      asyncMode ? quoteLzFee(hubProvider, vault) : Promise.resolve(0n),
+    ]);
+    results.unshift({
+      symbol,
+      spokeChainId: hubChainId,
+      depositType: asyncMode ? "direct-async" : "direct",
+      spokeOft: null,
+      spokeToken: hubEntry.token,
+      sourceTokenSymbol,
+      hubOft: null,
+      oftCmd: "0x",
+      lzFeeEstimate,
+      nativeSymbol: NATIVE_SYMBOL[hubChainId] ?? "ETH",
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Fetch user token balances for each inbound route in parallel.
+ * Routes with native ETH as token (ZeroAddress) return the chain's ETH balance.
+ *
+ * @param routes       Inbound routes from getInboundRoutes()
+ * @param userAddress  User wallet address
+ */
+export async function getUserBalancesForRoutes(
+  routes: InboundRoute[],
+  userAddress: string,
+): Promise<InboundRouteWithBalance[]> {
+  return Promise.all(
+    routes.map(async (route) => {
+      const provider = createChainProvider(route.spokeChainId);
+      if (!provider) return { ...route, userBalance: 0n };
+
+      try {
+        let userBalance: bigint;
+
+        if (route.spokeToken.toLowerCase() === ZeroAddress.toLowerCase()) {
+          userBalance = await provider.getBalance(userAddress);
+        } else {
+          const erc20 = new Contract(route.spokeToken, ERC20_ABI, provider);
+          userBalance = await (erc20.balanceOf(userAddress) as Promise<bigint>);
+        }
+
+        return { ...route, userBalance };
+      } catch {
+        return { ...route, userBalance: 0n };
+      }
+    }),
+  );
+}
+
+/**
+ * Find all outbound routes for a vault — chains where a user can receive
+ * shares/assets when redeeming.
+ *
+ * The hub chain is always first (direct redeem). Spoke chains follow
+ * (shares are bridged back via the composer).
+ *
+ * @param hubChainId  Chain ID of the vault hub (e.g. 8453 for Base)
+ * @param vault       Vault address (to resolve registered spoke chains)
+ */
+export async function getOutboundRoutes(
+  hubChainId: number,
+  vault: string,
+): Promise<OutboundRoute[]> {
+  const hubEid = CHAIN_ID_TO_EID[hubChainId];
+  if (!hubEid) throw new Error(`No LZ EID for hub chainId ${hubChainId}`);
+
+  const hubProvider = createChainProvider(hubChainId);
+  if (!hubProvider) throw new Error(`No public RPC for hub chainId ${hubChainId}`);
+
+  const topology = await getVaultTopology(hubProvider, vault);
+
+  const routes: OutboundRoute[] = [
+    {
+      chainId: hubChainId,
+      routeType: "hub",
+      eid: hubEid,
+      nativeSymbol: NATIVE_SYMBOL[hubChainId] ?? "ETH",
+    },
+  ];
+
+  for (const spokeChainId of topology.spokeChainIds) {
+    const eid = CHAIN_ID_TO_EID[spokeChainId];
+    if (!eid) continue;
+
+    routes.push({
+      chainId: spokeChainId,
+      routeType: "spoke",
+      eid,
+      nativeSymbol: NATIVE_SYMBOL[spokeChainId] ?? "ETH",
+    });
+  }
+
+  return routes;
+}
+
+/**
+ * Quote the LayerZero native fee for a cross-chain deposit with a real amount.
+ *
+ * More precise than the `lzFeeEstimate` field on `InboundRoute`, which uses
+ * a dummy 1 USDC amount.
+ *
+ * @param route       An InboundRoute from `getInboundRoutes()`
+ * @param hubChainId  Chain ID of the vault hub (needed for LZ destination EID)
+ * @param amount      Real deposit amount in token decimals
+ * @param userAddress User address (used as receiver for fee quote)
+ * @returns Native fee in wei of the spoke chain's gas token, or 0n for direct deposits
+ */
+export async function quoteRouteDepositFee(
+  route: InboundRoute,
+  hubChainId: number,
+  amount: bigint,
+  userAddress: string,
+): Promise<bigint> {
+  if (route.depositType === "direct") return 0n;
+
+  const hubEid = CHAIN_ID_TO_EID[hubChainId];
+  if (!hubEid) throw new Error(`No LZ EID for hub chainId ${hubChainId}`);
+
+  if (!route.spokeOft) throw new Error("Route is oft-compose but spokeOft is null");
+
+  const spokeProvider = createChainProvider(route.spokeChainId);
+  if (!spokeProvider) throw new Error(`No public RPC for spoke chainId ${route.spokeChainId}`);
+
+  const receiverBytes32 =
+    "0x" + userAddress.replace(/^0x/, "").toLowerCase().padStart(64, "0");
+
+  const spokeOft = new Contract(route.spokeOft, OFT_ABI, spokeProvider);
+  const feeResult = await spokeOft.quoteSend(
+    {
+      dstEid: hubEid,
+      to: receiverBytes32,
+      amountLD: amount,
+      minAmountLD: 0n,
+      extraOptions: "0x",
+      composeMsg: "0x",
+      oftCmd: route.oftCmd,
+    },
+    false,
+  );
+
+  return feeResult.nativeFee as bigint;
+}

package/src/ethers/topology.ts

@@ -0,0 +1,240 @@
+/**
+ * Vault topology helpers for the MoreVaults ethers.js v6 SDK.
+ *
+ * Resolves the cross-chain hub/spoke structure of a vault using the
+ * MoreVaults OmniFactory contract (same address on every supported chain via CREATE3).
+ */
+
+import { Contract } from "ethers";
+import type { Provider } from "ethers";
+import { EID_TO_CHAIN_ID, CHAIN_IDS, createChainProvider } from "./chains";
+
+// MoreVaults OMNI factory — same address on every supported chain (CREATE3)
+export const OMNI_FACTORY_ADDRESS = "0x7bDB8B17604b03125eFAED33cA0c55FBf856BB0C";
+
+const FACTORY_ABI = [
+  "function localEid() view returns (uint32)",
+  "function isCrossChainVault(uint32 __eid, address _vault) view returns (bool)",
+  "function hubToSpokes(uint32 __eid, address _hubVault) view returns (uint32[] eids, address[] vaults)",
+  "function spokeToHub(uint32 __eid, address _spokeVault) view returns (uint32 eid, address vault)",
+] as const;
+
+export interface VaultTopology {
+  /**
+   * Role of this vault on the chain you queried:
+   * - 'hub'   → this chain holds the TVL, users deposit here
+   * - 'spoke' → this chain is a yield deployment; deposits go to the hub
+   * - 'local' → single-chain vault, no cross-chain setup
+   */
+  role: "hub" | "spoke" | "local";
+
+  /** Chain ID where the hub lives. Same as the queried chain when role='hub'. */
+  hubChainId: number;
+
+  /**
+   * All spoke chain IDs registered under this hub.
+   * Empty when role='local'.
+   * Since vaults are CREATE3-deployed, the vault address is the same on all chains.
+   */
+  spokeChainIds: number[];
+}
+
+/** All mainnet chain IDs where the OMNI_FACTORY is deployed */
+const DISCOVERY_CHAIN_IDS = Object.values(CHAIN_IDS).filter(
+  (id) => id !== 545, // exclude testnet
+) as number[];
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the cross-chain topology of a vault: hub chain + all spoke chains.
+ *
+ * Works for hub vaults, spoke vaults, and local (single-chain) vaults.
+ * Because MoreVaults uses CREATE3, the vault address is identical on every chain —
+ * only the chain IDs differ.
+ *
+ * @param provider       Connected to the chain you want to inspect
+ * @param vault          Vault address (same on all chains)
+ * @param factoryAddress MoreVaults factory (defaults to OMNI_FACTORY_ADDRESS)
+ *
+ * @example
+ * // Querying from Base — will detect hub + Ethereum/Arbitrum spokes
+ * const topo = await getVaultTopology(baseProvider, '0x8f740...')
+ * // { role: 'hub', hubChainId: 8453, spokeChainIds: [1, 42161] }
+ *
+ * // Querying from Ethereum — same vault is a spoke there
+ * const topo = await getVaultTopology(ethProvider, '0x8f740...')
+ * // { role: 'spoke', hubChainId: 8453, spokeChainIds: [1, 42161] }
+ */
+export async function getVaultTopology(
+  provider: Provider,
+  vault: string,
+  factoryAddress: string = OMNI_FACTORY_ADDRESS,
+): Promise<VaultTopology> {
+  const factory = new Contract(factoryAddress, FACTORY_ABI, provider);
+
+  // Get local EID from the factory on the queried chain
+  const localEid: number = Number(await factory.localEid());
+
+  // Check if this vault is a hub on the current chain
+  const isHub: boolean = await factory.isCrossChainVault(localEid, vault);
+
+  if (isHub) {
+    // Hub: get all registered spokes
+    const result = await factory.hubToSpokes(localEid, vault);
+    const spokeEids: bigint[] = result[0];
+
+    const localChainId = EID_TO_CHAIN_ID[localEid] ?? 0;
+    const spokeChainIds = spokeEids
+      .map((eid) => EID_TO_CHAIN_ID[Number(eid)])
+      .filter((id): id is number => id !== undefined);
+
+    return { role: "hub", hubChainId: localChainId, spokeChainIds };
+  }
+
+  // Check if this vault is a spoke on the current chain
+  const spokeResult = await factory.spokeToHub(localEid, vault);
+  const hubEid: number = Number(spokeResult[0]);
+  const hubVault: string = spokeResult[1];
+
+  if (hubEid !== 0 && hubVault !== "0x0000000000000000000000000000000000000000") {
+    // Spoke: resolve hub chain
+    const hubChainId = EID_TO_CHAIN_ID[hubEid] ?? 0;
+
+    // We only have the current chain's provider — return what we know.
+    // The hub's full spoke list requires a separate provider for the hub chain.
+    const spokeChainIds: number[] = [];
+
+    // If we happen to know the local chain mapping, include it as a spoke
+    const localChainId = EID_TO_CHAIN_ID[localEid];
+    if (localChainId !== undefined) spokeChainIds.push(localChainId);
+
+    return { role: "spoke", hubChainId, spokeChainIds };
+  }
+
+  // Local vault — no cross-chain setup
+  const localChainId = EID_TO_CHAIN_ID[localEid] ?? 0;
+  return { role: "local", hubChainId: localChainId, spokeChainIds: [] };
+}
+
+/**
+ * Resolve the FULL topology of a vault by querying the hub chain directly.
+ *
+ * Provide a provider connected to the hub chain for complete spoke data.
+ * If you don't know which chain is the hub, call `getVaultTopology` first
+ * from any chain and use the returned `hubChainId` to create the hub provider.
+ *
+ * @param hubChainProvider  Provider connected to the hub chain
+ * @param vault             Vault address
+ * @param factoryAddress    MoreVaults factory (defaults to OMNI_FACTORY_ADDRESS)
+ */
+export async function getFullVaultTopology(
+  hubChainProvider: Provider,
+  vault: string,
+  factoryAddress: string = OMNI_FACTORY_ADDRESS,
+): Promise<VaultTopology> {
+  const topo = await getVaultTopology(hubChainProvider, vault, factoryAddress);
+  if (topo.role !== "hub") {
+    throw new Error(
+      `getFullVaultTopology: provider must be connected to the hub chain (${topo.hubChainId}), ` +
+        `but got role="${topo.role}". Connect to chainId ${topo.hubChainId} instead.`,
+    );
+  }
+  return topo;
+}
+
+/**
+ * Discover a vault's topology across all supported chains.
+ *
+ * Unlike `getVaultTopology` (which queries a single chain), this function
+ * automatically iterates all supported chains when the initial query returns
+ * `role: "local"`. This handles the case where the caller doesn't know which
+ * chain the vault is deployed on, or when no provider is connected.
+ *
+ * If a `provider` is provided, it's tried first. If that returns "local",
+ * every other supported chain is probed via public RPCs.
+ * If no `provider` is provided, all chains are probed.
+ *
+ * Once a hub is found, `getFullVaultTopology` is called to get the complete
+ * spoke list.
+ *
+ * @param vault          Vault address (same on all chains via CREATE3)
+ * @param provider       Optional — provider for the "preferred" chain to try first
+ * @param factoryAddress MoreVaults factory (defaults to OMNI_FACTORY_ADDRESS)
+ *
+ * @example
+ * // No wallet connected — discovers that 0x8f74... is hub on Base
+ * const topo = await discoverVaultTopology('0x8f740...')
+ * // { role: 'hub', hubChainId: 8453, spokeChainIds: [1, 42161] }
+ */
+export async function discoverVaultTopology(
+  vault: string,
+  provider?: Provider | null,
+  factoryAddress: string = OMNI_FACTORY_ADDRESS,
+): Promise<VaultTopology> {
+  // 1. Try the provided provider first (fast path — avoids extra RPC calls)
+  let triedChainId: number | undefined;
+  if (provider) {
+    try {
+      const topo = await getVaultTopology(provider, vault, factoryAddress);
+      if (topo.role !== "local") {
+        // Found hub or spoke — if spoke, resolve full topology from hub
+        if (topo.role === "spoke") {
+          const hubProvider = createChainProvider(topo.hubChainId);
+          if (hubProvider) {
+            try {
+              return await getFullVaultTopology(hubProvider, vault, factoryAddress);
+            } catch { /* fall through to return partial */ }
+          }
+        }
+        return topo;
+      }
+      // Determine which chainId we just tried
+      const network = await provider.getNetwork();
+      triedChainId = Number(network.chainId);
+    } catch { /* provider failed — continue with discovery */ }
+  }
+
+  // 2. Iterate all supported chains
+  for (const chainId of DISCOVERY_CHAIN_IDS) {
+    if (chainId === triedChainId) continue;
+    const chainProvider = createChainProvider(chainId);
+    if (!chainProvider) continue;
+
+    try {
+      const topo = await getVaultTopology(chainProvider, vault, factoryAddress);
+      if (topo.role === "hub") return topo;
+      if (topo.role === "spoke") {
+        // Found spoke — get full topology from hub
+        const hubProvider = createChainProvider(topo.hubChainId);
+        if (hubProvider) {
+          try {
+            return await getFullVaultTopology(hubProvider, vault, factoryAddress);
+          } catch { return topo; }
+        }
+        return topo;
+      }
+    } catch { /* this chain doesn't have the factory or vault — skip */ }
+  }
+
+  // 3. Not found on any chain — return local with chainId 0
+  return { role: "local", hubChainId: 0, spokeChainIds: [] };
+}
+
+/**
+ * Check if a wallet is connected to the hub chain for a given vault.
+ * Useful for showing a "Switch to Base" prompt before deposit.
+ *
+ * @param currentChainId  Chain ID the wallet is currently connected to
+ * @param topology        Result of getVaultTopology
+ */
+export function isOnHubChain(currentChainId: number, topology: VaultTopology): boolean {
+  return currentChainId === topology.hubChainId;
+}
+
+/**
+ * Get all chain IDs where this vault is deployed (hub + all spokes).
+ */
+export function getAllVaultChainIds(topology: VaultTopology): number[] {
+  return [topology.hubChainId, ...topology.spokeChainIds];
+}

package/src/ethers/types.ts

@@ -70,4 +70,99 @@ export interface CrossChainRequestInfo {
   amountLimit: bigint;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Curator Operations Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SwapParams {
+  targetContract: string;
+  tokenIn: string;
+  tokenOut: string;
+  maxAmountIn: bigint;
+  minAmountOut: bigint;
+  swapCallData: string;
+}
+
+export interface BatchSwapParams {
+  swaps: SwapParams[];
+}
+
+export interface BridgeParams {
+  oftToken: string;
+  dstEid: number;
+  amount: bigint;
+  dstVault: string;
+  refundAddress: string;
+}
+
+export interface PendingAction {
+  nonce: bigint;
+  actionsData: string[];
+  pendingUntil: bigint;
+  isExecutable: boolean;
+}
+
+export interface SubmitActionsResult {
+  receipt: ContractTransactionReceipt;
+  nonce: bigint;
+}
+
+export type CuratorAction =
+  | { type: 'swap'; params: SwapParams }
+  | { type: 'batchSwap'; params: BatchSwapParams }
+  | { type: 'erc4626Deposit'; vault: string; assets: bigint }
+  | { type: 'erc4626Redeem'; vault: string; shares: bigint }
+  | { type: 'erc7540RequestDeposit'; vault: string; assets: bigint }
+  | { type: 'erc7540Deposit'; vault: string; assets: bigint }
+  | { type: 'erc7540RequestRedeem'; vault: string; shares: bigint }
+  | { type: 'erc7540Redeem'; vault: string; shares: bigint };
+
+export interface CuratorVaultStatus {
+  curator: string;
+  timeLockPeriod: bigint;
+  maxSlippagePercent: bigint;
+  currentNonce: bigint;
+  availableAssets: string[];
+  lzAdapter: string;
+  paused: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Vault Analysis Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AssetInfo {
+  address: string;
+  symbol: string;
+  name: string;
+  decimals: number;
+}
+
+export interface VaultAnalysis {
+  /** All tokens the vault can hold/swap (curator-managed) */
+  availableAssets: AssetInfo[];
+  /** Tokens users can deposit */
+  depositableAssets: AssetInfo[];
+  /** Whether deposit whitelist is enabled (restricts who can deposit) */
+  depositWhitelistEnabled: boolean;
+  /** Registry address for global protocol whitelist checks */
+  registryAddress: string | null;
+}
+
+export interface AssetBalance extends AssetInfo {
+  /** Raw balance held by the vault */
+  balance: bigint;
+}
+
+export interface VaultAssetBreakdown {
+  /** Per-asset balances held by the vault on the hub chain */
+  assets: AssetBalance[];
+  /** totalAssets() as reported by the vault (all positions converted to underlying) */
+  totalAssets: bigint;
+  /** totalSupply() of vault shares */
+  totalSupply: bigint;
+  /** Vault underlying token decimals */
+  underlyingDecimals: number;
+}
+
 export type { Signer, Provider, ContractTransactionReceipt };