@oydual31/more-vaults-sdk 0.3.3 → 0.4.1

package/src/ethers/userHelpers.ts

@@ -10,6 +10,8 @@ import { BRIDGE_ABI, CONFIG_ABI, ERC20_ABI, VAULT_ABI, METADATA_ABI } from "./ab
 import type { CrossChainRequestInfo } from "./types";
 import { getVaultStatus } from "./utils";
 import type { VaultStatus } from "./utils";
+import { CHAIN_ID_TO_EID, OFT_ROUTES, createChainProvider } from "./chains";
+import { discoverVaultTopology, OMNI_FACTORY_ADDRESS } from "./topology";
 
 // Multicall3 — deployed at the same address on every EVM chain
 const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
@@ -478,3 +480,194 @@ export async function getVaultSummary(
   ]);
   return { ...status, ...metadata };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Minimal ABIs for SHARE_OFT discovery in getUserPositionMultiChain */
+const FACTORY_COMPOSER_ABI_UH = [
+  "function vaultComposer(address _vault) view returns (address)",
+] as const;
+
+const COMPOSER_SHARE_OFT_ABI_UH = [
+  "function SHARE_OFT() view returns (address)",
+] as const;
+
+const OFT_PEERS_ABI_UH = [
+  "function peers(uint32 eid) view returns (bytes32)",
+] as const;
+
+export interface MultiChainUserPosition {
+  /** Shares held directly on the hub vault (vault.balanceOf) */
+  hubShares: bigint;
+  /** Per-spoke SHARE_OFT balances normalized to vault decimals: { [chainId]: bigint } */
+  spokeShares: Record<number, bigint>;
+  /** Per-spoke SHARE_OFT raw balances in OFT native decimals: { [chainId]: bigint }
+   *  Use these for bridgeSharesToHub() and quoteShareBridgeFee() */
+  rawSpokeShares: Record<number, bigint>;
+  /** hubShares + sum of all spokeShares (in vault decimals) */
+  totalShares: bigint;
+  /** convertToAssets(totalShares) on the hub */
+  estimatedAssets: bigint;
+  /** Share price: convertToAssets(10^decimals) */
+  sharePrice: bigint;
+  /** Vault decimals */
+  decimals: number;
+  /** Pending async withdrawal request on hub, or null */
+  pendingWithdrawal: {
+    shares: bigint;
+    timelockEndsAt: bigint;
+    canRedeemNow: boolean;
+  } | null;
+}
+
+/**
+ * Read the user's position across all chains of an omni vault.
+ *
+ * Discovers topology automatically, reads hub shares + pending withdrawal,
+ * then reads SHARE_OFT balances on each spoke chain in parallel.
+ *
+ * For local (single-chain) vaults, spokeShares will be empty and this
+ * behaves identically to getUserPosition.
+ *
+ * @param vault  Vault address (same on all chains via CREATE3)
+ * @param user   User wallet address
+ * @returns      Aggregated position across all chains
+ */
+export async function getUserPositionMultiChain(
+  vault: string,
+  user: string,
+): Promise<MultiChainUserPosition> {
+  // Step 1: discover topology
+  const topo = await discoverVaultTopology(vault);
+  const hubProvider = createChainProvider(topo.hubChainId);
+  if (!hubProvider) throw new Error(`No public RPC for hub chainId ${topo.hubChainId}`);
+
+  // Step 2: read hub data (shares, decimals, withdrawal request)
+  const mc = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, hubProvider);
+  const vaultIface = new Interface(VAULT_ABI as unknown as string[]);
+  const decimalsIface = new Interface(["function decimals() view returns (uint8)"]);
+
+  const b1Calls = [
+    { target: vault, allowFailure: false, callData: vaultIface.encodeFunctionData("balanceOf", [user]) },
+    { target: vault, allowFailure: false, callData: decimalsIface.encodeFunctionData("decimals") },
+    { target: vault, allowFailure: false, callData: vaultIface.encodeFunctionData("getWithdrawalRequest", [user]) },
+  ];
+
+  const [b1Raw, block] = await Promise.all([
+    mc.aggregate3.staticCall(b1Calls) as Promise<{ success: boolean; returnData: string }[]>,
+    hubProvider.getBlock("latest"),
+  ]);
+
+  const hubShares = vaultIface.decodeFunctionResult("balanceOf", b1Raw[0].returnData)[0] as bigint;
+  const decimals = Number(decimalsIface.decodeFunctionResult("decimals", b1Raw[1].returnData)[0]);
+  const withdrawalResult = vaultIface.decodeFunctionResult("getWithdrawalRequest", b1Raw[2].returnData);
+  const withdrawShares = withdrawalResult[0] as bigint;
+  const timelockEndsAt = withdrawalResult[1] as bigint;
+
+  // Step 3: resolve SHARE_OFT addresses for spokes (if any)
+  const spokeShares: Record<number, bigint> = {};
+  const rawSpokeShares: Record<number, bigint> = {};
+
+  if (topo.spokeChainIds.length > 0) {
+    let hubShareOft: string | null = null;
+    try {
+      const factory = new Contract(OMNI_FACTORY_ADDRESS, FACTORY_COMPOSER_ABI_UH, hubProvider);
+      const composerAddress: string = await factory.vaultComposer(vault);
+
+      if (composerAddress !== "0x0000000000000000000000000000000000000000") {
+        const composer = new Contract(composerAddress, COMPOSER_SHARE_OFT_ABI_UH, hubProvider);
+        hubShareOft = await composer.SHARE_OFT();
+      }
+    } catch { /* no composer — skip spoke reads */ }
+
+    if (hubShareOft) {
+      const hubShareOftContract = new Contract(hubShareOft, OFT_PEERS_ABI_UH, hubProvider);
+
+      const spokePromises = topo.spokeChainIds.map(async (spokeChainId) => {
+        try {
+          const spokeEid = CHAIN_ID_TO_EID[spokeChainId];
+          if (!spokeEid) return { chainId: spokeChainId, balance: 0n, rawBalance: 0n };
+
+          const spokeOftBytes32: string = await hubShareOftContract.peers(spokeEid);
+          const spokeOft = `0x${spokeOftBytes32.slice(-40)}`;
+
+          if (spokeOft === "0x0000000000000000000000000000000000000000") {
+            return { chainId: spokeChainId, balance: 0n, rawBalance: 0n };
+          }
+
+          const spokeProvider = createChainProvider(spokeChainId);
+          if (!spokeProvider) return { chainId: spokeChainId, balance: 0n, rawBalance: 0n };
+
+          // Read balance + decimals on spoke chain via Multicall3
+          const spokeMc = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, spokeProvider);
+          const erc20Iface = new Interface(ERC20_ABI as unknown as string[]);
+          const spokeDecimalsIface = new Interface(["function decimals() view returns (uint8)"]);
+
+          const spokeCalls = [
+            { target: spokeOft, allowFailure: false, callData: erc20Iface.encodeFunctionData("balanceOf", [user]) },
+            { target: spokeOft, allowFailure: false, callData: spokeDecimalsIface.encodeFunctionData("decimals") },
+          ];
+          const spokeRaw: { success: boolean; returnData: string }[] =
+            await spokeMc.aggregate3.staticCall(spokeCalls);
+
+          const rawBalance = erc20Iface.decodeFunctionResult("balanceOf", spokeRaw[0].returnData)[0] as bigint;
+          const spokeOftDecimals = Number(spokeDecimalsIface.decodeFunctionResult("decimals", spokeRaw[1].returnData)[0]);
+
+          // Normalize to vault decimals
+          let balance: bigint;
+          if (spokeOftDecimals > decimals) {
+            balance = rawBalance / (10n ** BigInt(spokeOftDecimals - decimals));
+          } else if (spokeOftDecimals < decimals) {
+            balance = rawBalance * (10n ** BigInt(decimals - spokeOftDecimals));
+          } else {
+            balance = rawBalance;
+          }
+
+          return { chainId: spokeChainId, balance, rawBalance };
+        } catch {
+          return { chainId: spokeChainId, balance: 0n, rawBalance: 0n };
+        }
+      });
+
+      const results = await Promise.all(spokePromises);
+      for (const { chainId, balance, rawBalance } of results) {
+        spokeShares[chainId] = balance;
+        rawSpokeShares[chainId] = rawBalance;
+      }
+    }
+  }
+
+  // Step 4: compute totals
+  const totalSpokeShares = Object.values(spokeShares).reduce((sum, b) => sum + b, 0n);
+  const totalShares = hubShares + totalSpokeShares;
+
+  const oneShare = 10n ** BigInt(decimals);
+  const vaultContract = new Contract(vault, VAULT_ABI, hubProvider);
+  const [estimatedAssets, sharePrice]: [bigint, bigint] = await Promise.all([
+    totalShares === 0n
+      ? Promise.resolve(0n)
+      : (vaultContract.convertToAssets(totalShares) as Promise<bigint>),
+    vaultContract.convertToAssets(oneShare) as Promise<bigint>,
+  ]);
+
+  // Step 5: pending withdrawal
+  const currentTimestamp = BigInt(block?.timestamp ?? 0);
+  const pendingWithdrawal = withdrawShares === 0n
+    ? null
+    : {
+        shares: withdrawShares,
+        timelockEndsAt,
+        canRedeemNow: timelockEndsAt === 0n || currentTimestamp >= timelockEndsAt,
+      };
+
+  return {
+    hubShares,
+    spokeShares,
+    rawSpokeShares,
+    totalShares,
+    estimatedAssets,
+    sharePrice,
+    decimals,
+    pendingWithdrawal,
+  };
+}

package/src/ethers/utils.ts

@@ -8,6 +8,11 @@ import { Contract, Interface, ZeroAddress } from "ethers";
 import type { Provider, Signer } from "ethers";
 import { BRIDGE_ABI, CONFIG_ABI, ERC20_ABI, VAULT_ABI } from "./abis";
 
+// Minimal ABI for Stargate type detection
+const STARGATE_TYPE_ABI = [
+  "function stargateType() view returns (uint8)",
+] as const;
+
 // Multicall3 — deployed at the same address on every EVM chain
 const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
 const MULTICALL3_ABI = [
@@ -379,3 +384,26 @@ export async function getVaultStatus(
     issues,
   };
 }
+
+/**
+ * Detect whether an OFT address is a Stargate V2 pool by calling `stargateType()`.
+ *
+ * Stargate pools implement this function (returns 0=Pool, 1=OFT).
+ * Standard OFTs revert because they don't have it.
+ *
+ * @param provider  Read-only provider on the OFT's chain
+ * @param oft       OFT contract address
+ * @returns         true if the contract is a Stargate V2 pool/OFT
+ */
+export async function detectStargateOft(
+  provider: Provider,
+  oft: string
+): Promise<boolean> {
+  try {
+    const contract = new Contract(oft, STARGATE_TYPE_ABI, provider);
+    await contract.stargateType();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/react/index.ts

@@ -37,3 +37,28 @@ export { useSmartRedeem } from './useSmartRedeem.js'
 
 // --- Inbound Routes ---
 export { useInboundRoutes, getRouteTokenDecimals } from './useInboundRoutes.js'
+
+// --- Curator Read hooks ---
+export { useCuratorVaultStatus } from './useCuratorVaultStatus.js'
+export type { CuratorVaultStatus } from './useCuratorVaultStatus.js'
+
+export { useVaultAnalysis } from './useVaultAnalysis.js'
+export type { VaultAnalysis } from './useVaultAnalysis.js'
+
+export { useVaultAssetBreakdown } from './useVaultAssetBreakdown.js'
+export type { VaultAssetBreakdown } from './useVaultAssetBreakdown.js'
+
+export { usePendingActions } from './usePendingActions.js'
+export type { PendingAction } from './usePendingActions.js'
+
+export { useIsCurator } from './useIsCurator.js'
+
+export { useProtocolWhitelist } from './useProtocolWhitelist.js'
+
+// --- Curator Write hooks ---
+export { useSubmitActions } from './useSubmitActions.js'
+export type { CuratorAction } from './useSubmitActions.js'
+
+export { useExecuteActions } from './useExecuteActions.js'
+
+export { useVetoActions } from './useVetoActions.js'

package/src/react/useCuratorVaultStatus.ts

@@ -0,0 +1,32 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, getCuratorVaultStatus } from '../viem/index.js'
+import type { CuratorVaultStatus } from '../viem/index.js'
+
+export type { CuratorVaultStatus }
+
+interface UseCuratorVaultStatusOptions {
+  /** Refetch interval in ms. Default: 30_000 (30s) */
+  refetchInterval?: number
+}
+
+/**
+ * Read the curator vault status snapshot.
+ *
+ * @example
+ * const { data: status, isLoading } = useCuratorVaultStatus('0xVAULT', 747)
+ */
+export function useCuratorVaultStatus(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+  options?: UseCuratorVaultStatusOptions,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['curatorVaultStatus', vault, chainId],
+    queryFn: () => getCuratorVaultStatus(asSdkClient(publicClient), vault!),
+    enabled: !!vault && !!publicClient,
+    refetchInterval: options?.refetchInterval ?? 30_000,
+    staleTime: 15_000,
+  })
+}

package/src/react/useExecuteActions.ts

@@ -0,0 +1,23 @@
+import { useMutation } from '@tanstack/react-query'
+import { usePublicClient, useWalletClient } from 'wagmi'
+import { asSdkClient, executeActions } from '../viem/index.js'
+
+/**
+ * Execute a pending curator action batch by nonce.
+ *
+ * @example
+ * const { mutateAsync } = useExecuteActions('0xVAULT', 747)
+ * await mutateAsync({ nonce: 1n })
+ */
+export function useExecuteActions(vault: `0x${string}`, chainId: number) {
+  const publicClient = usePublicClient({ chainId })
+  const { data: walletClient } = useWalletClient({ chainId })
+
+  return useMutation({
+    mutationFn: async ({ nonce }: { nonce: bigint }) => {
+      if (!walletClient || !publicClient) throw new Error('Wallet or public client not available')
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return executeActions(walletClient as any, asSdkClient(publicClient), vault, nonce)
+    },
+  })
+}

package/src/react/useIsCurator.ts

@@ -0,0 +1,30 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, isCurator } from '../viem/index.js'
+
+interface UseIsCuratorOptions {
+  /** Refetch interval in ms. Default: 30_000 (30s) */
+  refetchInterval?: number
+}
+
+/**
+ * Check whether an address is a curator of a vault.
+ *
+ * @example
+ * const { data: curator, isLoading } = useIsCurator('0xVAULT', 747, '0xADDR')
+ */
+export function useIsCurator(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+  address: `0x${string}` | undefined,
+  options?: UseIsCuratorOptions,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['isCurator', vault, chainId, address],
+    queryFn: () => isCurator(asSdkClient(publicClient), vault!, address!),
+    enabled: !!vault && !!publicClient && !!address,
+    refetchInterval: options?.refetchInterval ?? 30_000,
+    staleTime: 15_000,
+  })
+}

package/src/react/usePendingActions.ts

@@ -0,0 +1,33 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, getPendingActions } from '../viem/index.js'
+import type { PendingAction } from '../viem/index.js'
+
+export type { PendingAction }
+
+interface UsePendingActionsOptions {
+  /** Refetch interval in ms. Default: 30_000 (30s) */
+  refetchInterval?: number
+}
+
+/**
+ * Read pending curator actions for a vault by nonce.
+ *
+ * @example
+ * const { data: pending, isLoading } = usePendingActions('0xVAULT', 747, 1n)
+ */
+export function usePendingActions(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+  nonce: bigint | undefined,
+  options?: UsePendingActionsOptions,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['pendingActions', vault, chainId, nonce?.toString()],
+    queryFn: () => getPendingActions(asSdkClient(publicClient), vault!, nonce!),
+    enabled: !!vault && !!publicClient && nonce !== undefined,
+    refetchInterval: options?.refetchInterval ?? 30_000,
+    staleTime: 15_000,
+  })
+}

package/src/react/useProtocolWhitelist.ts

@@ -0,0 +1,30 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, checkProtocolWhitelist } from '../viem/index.js'
+
+interface UseProtocolWhitelistOptions {
+  /** Refetch interval in ms. Default: 30_000 (30s) */
+  refetchInterval?: number
+}
+
+/**
+ * Check which protocols are whitelisted for a vault.
+ *
+ * @example
+ * const { data: whitelist, isLoading } = useProtocolWhitelist('0xVAULT', 747, ['0xPROTOCOL'])
+ */
+export function useProtocolWhitelist(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+  protocols: `0x${string}`[],
+  options?: UseProtocolWhitelistOptions,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['protocolWhitelist', vault, chainId, protocols],
+    queryFn: () => checkProtocolWhitelist(asSdkClient(publicClient), vault!, protocols),
+    enabled: !!vault && !!publicClient,
+    refetchInterval: options?.refetchInterval ?? 30_000,
+    staleTime: 15_000,
+  })
+}

package/src/react/useSubmitActions.ts

@@ -0,0 +1,27 @@
+import { useMutation } from '@tanstack/react-query'
+import { usePublicClient, useWalletClient } from 'wagmi'
+import { asSdkClient, submitActions, buildCuratorBatch } from '../viem/index.js'
+import type { CuratorAction } from '../viem/index.js'
+
+export type { CuratorAction }
+
+/**
+ * Submit a batch of curator actions to the vault.
+ *
+ * @example
+ * const { mutateAsync } = useSubmitActions('0xVAULT', 747)
+ * await mutateAsync({ actions: [{ type: 'erc4626Deposit', vault: '0x...', assets: 100n }] })
+ */
+export function useSubmitActions(vault: `0x${string}`, chainId: number) {
+  const publicClient = usePublicClient({ chainId })
+  const { data: walletClient } = useWalletClient({ chainId })
+
+  return useMutation({
+    mutationFn: async ({ actions }: { actions: CuratorAction[] }) => {
+      if (!walletClient || !publicClient) throw new Error('Wallet or public client not available')
+      const encodedActions = buildCuratorBatch(actions)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return submitActions(walletClient as any, asSdkClient(publicClient), vault, encodedActions)
+    },
+  })
+}

package/src/react/useVaultAnalysis.ts

@@ -0,0 +1,32 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, getVaultAnalysis } from '../viem/index.js'
+import type { VaultAnalysis } from '../viem/index.js'
+
+export type { VaultAnalysis }
+
+interface UseVaultAnalysisOptions {
+  /** Refetch interval in ms. Default: 30_000 (30s) */
+  refetchInterval?: number
+}
+
+/**
+ * Read a detailed analysis of a vault.
+ *
+ * @example
+ * const { data: analysis, isLoading } = useVaultAnalysis('0xVAULT', 747)
+ */
+export function useVaultAnalysis(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+  options?: UseVaultAnalysisOptions,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['vaultAnalysis', vault, chainId],
+    queryFn: () => getVaultAnalysis(asSdkClient(publicClient), vault!),
+    enabled: !!vault && !!publicClient,
+    refetchInterval: options?.refetchInterval ?? 30_000,
+    staleTime: 15_000,
+  })
+}

package/src/react/useVaultAssetBreakdown.ts

@@ -0,0 +1,32 @@
+import { useQuery } from '@tanstack/react-query'
+import { usePublicClient } from 'wagmi'
+import { asSdkClient, getVaultAssetBreakdown } from '../viem/index.js'
+import type { VaultAssetBreakdown } from '../viem/index.js'
+
+export type { VaultAssetBreakdown }
+
+interface UseVaultAssetBreakdownOptions {
+  /** Refetch interval in ms. Default: 30_000 (30s) */
+  refetchInterval?: number
+}
+
+/**
+ * Read the asset breakdown of a vault.
+ *
+ * @example
+ * const { data: breakdown, isLoading } = useVaultAssetBreakdown('0xVAULT', 747)
+ */
+export function useVaultAssetBreakdown(
+  vault: `0x${string}` | undefined,
+  chainId: number,
+  options?: UseVaultAssetBreakdownOptions,
+) {
+  const publicClient = usePublicClient({ chainId })
+  return useQuery({
+    queryKey: ['vaultAssetBreakdown', vault, chainId],
+    queryFn: () => getVaultAssetBreakdown(asSdkClient(publicClient), vault!),
+    enabled: !!vault && !!publicClient,
+    refetchInterval: options?.refetchInterval ?? 30_000,
+    staleTime: 15_000,
+  })
+}

package/src/react/useVetoActions.ts

@@ -0,0 +1,23 @@
+import { useMutation } from '@tanstack/react-query'
+import { usePublicClient, useWalletClient } from 'wagmi'
+import { asSdkClient, vetoActions } from '../viem/index.js'
+
+/**
+ * Guardian-only: cancel (veto) one or more pending curator action batches.
+ *
+ * @example
+ * const { mutateAsync } = useVetoActions('0xVAULT', 747)
+ * await mutateAsync({ nonces: [1n, 2n] })
+ */
+export function useVetoActions(vault: `0x${string}`, chainId: number) {
+  const publicClient = usePublicClient({ chainId })
+  const { data: walletClient } = useWalletClient({ chainId })
+
+  return useMutation({
+    mutationFn: async ({ nonces }: { nonces: bigint[] }) => {
+      if (!walletClient || !publicClient) throw new Error('Wallet or public client not available')
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return vetoActions(walletClient as any, asSdkClient(publicClient), vault, nonces)
+    },
+  })
+}