@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dc68f39

package/dist/utils/lazy-import.d.ts

@@ -15,6 +15,4 @@
  * const getOpenPGP = lazyImport(() => import('openpgp'));
  * const openpgp = await getOpenPGP();
  */
-declare function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T>;
-
-export { lazyImport };
+export declare function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T>;

package/dist/utils/lazy-import.js

@@ -1,12 +1,10 @@
 function lazyImport(importFn) {
   let cached = null;
   return () => {
-    if (!cached) {
-      cached = importFn().catch((err) => {
-        cached = null;
-        throw new Error("Failed to load module", { cause: err });
-      });
-    }
+    cached ??= importFn().catch((err) => {
+      cached = null;
+      throw new Error("Failed to load module", { cause: err });
+    });
     return cached;
   };
 }

package/dist/utils/lazy-import.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Utility for lazy-loading modules to avoid Turbopack TDZ issues\n *\n * WARNING: This is a workaround for Turbopack's strict module initialization.\n * Dependencies that access globals during init must be dynamically imported.\n */\n\n/**\n * Creates a lazy import function that caches the promise (not the module)\n * to avoid race conditions on concurrent first calls\n *\n * @param importFn - Function that returns a dynamic import promise\n * @returns Function that returns the cached import promise\n *\n * @example\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n * const openpgp = await getOpenPGP();\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    if (!cached) {\n      cached = importFn().catch((err) => {\n        // Clear cache on error so next attempt can retry\n        cached = null;\n        throw new Error(\"Failed to load module\", { cause: err });\n      });\n    }\n    return cached;\n  };\n}\n"],"mappings":"AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,QAAI,CAAC,QAAQ;AACX,eAAS,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEjC,iBAAS;AACT,cAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,MACzD,CAAC;AAAA,IACH;AACA,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Utility for lazy-loading modules to avoid Turbopack TDZ issues\n *\n * WARNING: This is a workaround for Turbopack's strict module initialization.\n * Dependencies that access globals during init must be dynamically imported.\n */\n\n/**\n * Creates a lazy import function that caches the promise (not the module)\n * to avoid race conditions on concurrent first calls\n *\n * @param importFn - Function that returns a dynamic import promise\n * @returns Function that returns the cached import promise\n *\n * @example\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n * const openpgp = await getOpenPGP();\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":"AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/utils/multicall.cjs

@@ -38,7 +38,7 @@ const DEFAULT_OPTIONS = {
 };
 async function gasAwareMulticall(client, parameters, options = {}) {
   const chainId = await client.getChainId();
-  const multicall3Address = options.multicallAddress || (0, import_addresses.getUtilityAddress)(chainId, "Multicall3");
+  const multicall3Address = options.multicallAddress ?? (0, import_addresses.getUtilityAddress)(chainId, "Multicall3");
   const opts = {
     ...DEFAULT_OPTIONS,
     ...options,
@@ -116,7 +116,9 @@ async function createBatches(client, contracts, options) {
           lastEstimatedGas = 0n;
         } else {
           if (!options.allowFailure) {
-            throw new Error(`Gas estimation failed for call ${i}: ${error}`);
+            throw new Error(
+              `Gas estimation failed for call ${i}: ${String(error)}`
+            );
           }
           currentBatch = [];
           currentBytes = 0;

package/dist/utils/multicall.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/multicall.ts"],"sourcesContent":["import type {\n  Address,\n  PublicClient,\n  MulticallParameters,\n  MulticallReturnType,\n  EncodeFunctionDataParameters,\n  Hex,\n  Abi,\n} from \"viem\";\nimport { encodeFunctionData, size } from \"viem\";\nimport { getUtilityAddress } from \"../config/addresses\";\nimport type { VanaChainId } from \"../types\";\n\n/**\n * Type for a contract function configuration used in multicall\n */\nexport interface ContractFunctionConfig {\n  address: Address;\n  abi: Abi;\n  functionName: string;\n  args?: readonly unknown[];\n}\n\n/**\n * Configuration options for gas-aware multicall batching.\n *\n * @remarks\n * These options control how the multicall utility splits large batches\n * to stay within gas and calldata limits. The defaults are conservative\n * to ensure compatibility across different chains and RPC providers.\n */\nexport interface GasAwareMulticallOptions {\n  /**\n   * Maximum gas per batch. Defaults to 10M (conservative for most chains).\n   *\n   * @remarks\n   * This should be set below the block gas limit of your target chain.\n   * Common values:\n   * - Vana mainnet: 30M (use 25M for safety)\n   * - Vana moksha: 30M (use 25M for safety)\n   * - Ethereum mainnet: 30M (use 25M for safety)\n   * - Arbitrum: 32M (use 25M for safety)\n   */\n  maxGasPerBatch?: bigint;\n\n  /**\n   * Maximum calldata size per batch in bytes. Defaults to 100KB.\n   *\n   * @remarks\n   * This is particularly important for L2 chains where calldata is expensive.\n   * Some RPC providers also have limits on request size.\n   */\n  maxCalldataBytes?: number;\n\n  /**\n   * How often to checkpoint gas estimates. Defaults to every 32 calls or 8KB.\n   *\n   * @remarks\n   * More frequent checkpoints give more accurate batching but require more\n   * RPC calls for gas estimation. The default balances accuracy vs performance.\n   */\n  checkpointFrequency?: {\n    /** Checkpoint after this many calls */\n    calls: number;\n    /** Checkpoint after this many bytes of calldata */\n    bytes: number;\n  };\n\n  /**\n   * Whether to allow partial batch failures. Defaults to false.\n   *\n   * @remarks\n   * When true, individual call failures won't fail the entire batch.\n   * This matches viem's multicall behavior with allowFailure option.\n   */\n  allowFailure?: boolean;\n\n  /**\n   * Optional multicall3 contract address override.\n   *\n   * @remarks\n   * By default, uses the standard multicall3 address deployed on most chains:\n   * 0xcA11bde05977b3631167028862bE2a173976CA11\n   */\n  multicallAddress?: Address;\n\n  /**\n   * Optional callback for tracking batching progress.\n   *\n   * @remarks\n   * Useful for showing progress in UI or debugging batch performance.\n   */\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Internal configuration with defaults applied\n */\ninterface NormalizedOptions {\n  maxGasPerBatch: bigint;\n  maxCalldataBytes: number;\n  checkpointFrequency: {\n    calls: number;\n    bytes: number;\n  };\n  allowFailure: boolean;\n  multicallAddress: Address;\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Default configuration values\n */\nconst DEFAULT_OPTIONS: Omit<NormalizedOptions, \"multicallAddress\"> = {\n  maxGasPerBatch: 10_000_000n, // 10M gas - conservative default\n  maxCalldataBytes: 100_000, // 100KB - works with most RPC providers\n  checkpointFrequency: {\n    calls: 32,\n    bytes: 8192, // 8KB\n  },\n  allowFailure: false,\n};\n\n/**\n * A gas-aware multicall function that automatically batches calls to stay within limits.\n *\n * @remarks\n * This function extends viem's multicall with intelligent batching based on:\n * - Actual gas costs (via periodic estimateGas calls)\n * - Calldata size limits\n * - Chain-specific constraints\n *\n * It uses a greedy algorithm with periodic checkpoints to efficiently determine\n * optimal batch sizes without making excessive RPC calls.\n *\n * @param client - The viem public client to use for RPC calls\n * @param parameters - The multicall parameters (same as viem's multicall)\n * @param options - Optional configuration for gas-aware batching\n * @returns The aggregated results from all batches\n *\n * @example\n * ```typescript\n * // Basic usage - drop-in replacement for viem's multicall\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: [\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address1] },\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address2] },\n *     // ... hundreds more calls\n *   ]\n * });\n *\n * // With custom limits for a specific chain\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: calls,\n * }, {\n *   maxGasPerBatch: 25_000_000n, // 25M for mainnet\n *   maxCalldataBytes: 128_000, // 128KB\n *   onProgress: (done, total) => console.log(`Progress: ${done}/${total}`)\n * });\n * ```\n */\nexport async function gasAwareMulticall<\n  TContracts extends readonly ContractFunctionConfig[],\n  TAllowFailure extends boolean = false,\n>(\n  client: PublicClient,\n  parameters: MulticallParameters<TContracts, TAllowFailure>,\n  options: GasAwareMulticallOptions = {},\n): Promise<MulticallReturnType<TContracts, TAllowFailure>> {\n  // Get the chain-specific Multicall3 address\n  const chainId = await client.getChainId();\n  const multicall3Address =\n    options.multicallAddress ||\n    getUtilityAddress(chainId as VanaChainId, \"Multicall3\");\n\n  // Normalize options with defaults\n  const opts: NormalizedOptions = {\n    ...DEFAULT_OPTIONS,\n    ...options,\n    multicallAddress: multicall3Address,\n    checkpointFrequency: {\n      ...DEFAULT_OPTIONS.checkpointFrequency,\n      ...options.checkpointFrequency,\n    },\n  };\n\n  // Override allowFailure if specified in parameters\n  if (parameters.allowFailure !== undefined) {\n    opts.allowFailure = parameters.allowFailure;\n  }\n\n  const { contracts } = parameters;\n  if (!contracts || contracts.length === 0) {\n    return [] as unknown as MulticallReturnType<TContracts, TAllowFailure>;\n  }\n\n  // Execute batching algorithm\n  const batches = await createBatches(\n    client,\n    contracts as readonly ContractFunctionConfig[],\n    opts,\n  );\n\n  // Execute all batches in parallel\n  const batchResults = await Promise.all(\n    batches.map((batch, index) => {\n      // Report progress if callback provided\n      if (opts.onProgress && index > 0) {\n        const completed = batches\n          .slice(0, index)\n          .reduce((sum, b) => sum + b.length, 0);\n        opts.onProgress(completed, contracts.length);\n      }\n\n      // Execute batch using viem's multicall\n      return client.multicall({\n        ...parameters,\n        contracts: batch as typeof contracts,\n        multicallAddress: opts.multicallAddress,\n        allowFailure: opts.allowFailure,\n      });\n    }),\n  );\n\n  // Report final progress\n  if (opts.onProgress) {\n    opts.onProgress(contracts.length, contracts.length);\n  }\n\n  // Flatten results\n  return batchResults.flat() as MulticallReturnType<TContracts, TAllowFailure>;\n}\n\n/**\n * Creates optimally-sized batches using greedy algorithm with checkpoints.\n *\n * @param client - The viem public client for making RPC calls\n * @param contracts - Array of contract function configurations to batch\n * @param options - Normalized batching options with limits and settings\n * @returns Array of optimally-sized contract function configuration batches\n */\nasync function createBatches(\n  client: PublicClient,\n  contracts: readonly ContractFunctionConfig[],\n  options: NormalizedOptions,\n): Promise<ContractFunctionConfig[][]> {\n  const batches: ContractFunctionConfig[][] = [];\n  let currentBatch: ContractFunctionConfig[] = [];\n  let currentBytes = 0;\n  let lastCheckpointIndex = 0;\n  let lastCheckpointBytes = 0;\n  let lastEstimatedGas = 0n;\n\n  for (let i = 0; i < contracts.length; i++) {\n    const contract = contracts[i];\n\n    // Calculate encoded size for this call\n    const encoded = encodeContractCall(contract);\n    const callBytes = size(encoded);\n\n    // Check if we need a gas checkpoint\n    const callsSinceCheckpoint = i - lastCheckpointIndex;\n    const bytesSinceCheckpoint = currentBytes - lastCheckpointBytes;\n\n    const needsCheckpoint =\n      callsSinceCheckpoint >= options.checkpointFrequency.calls ||\n      bytesSinceCheckpoint >= options.checkpointFrequency.bytes;\n\n    // Perform checkpoint if needed\n    if (needsCheckpoint && currentBatch.length > 0) {\n      try {\n        lastEstimatedGas = await estimateBatchGas(\n          client,\n          currentBatch,\n          options.multicallAddress,\n        );\n        lastCheckpointIndex = i;\n        lastCheckpointBytes = currentBytes;\n      } catch (error) {\n        // If estimation fails, finalize current batch to be safe\n        if (currentBatch.length > 1) {\n          // Try with half the batch\n          const halfBatch = currentBatch.slice(\n            0,\n            Math.floor(currentBatch.length / 2),\n          );\n          batches.push(halfBatch);\n          currentBatch = currentBatch.slice(halfBatch.length);\n          currentBytes = calculateBatchSize(currentBatch);\n          lastCheckpointIndex = i;\n          lastCheckpointBytes = currentBytes;\n          lastEstimatedGas = 0n;\n        } else {\n          // Single call failed, skip it or throw based on allowFailure\n          if (!options.allowFailure) {\n            throw new Error(`Gas estimation failed for call ${i}: ${error}`);\n          }\n          currentBatch = [];\n          currentBytes = 0;\n          continue;\n        }\n      }\n    }\n\n    // Check if adding this call would exceed limits\n    const wouldExceedCalldata =\n      currentBytes + callBytes > options.maxCalldataBytes;\n    const wouldExceedGas =\n      lastEstimatedGas > 0n &&\n      estimateNextGas(lastEstimatedGas, callsSinceCheckpoint + 1) >\n        options.maxGasPerBatch;\n\n    // If we would exceed limits, finalize current batch\n    if ((wouldExceedCalldata || wouldExceedGas) && currentBatch.length > 0) {\n      batches.push(currentBatch);\n      currentBatch = [];\n      currentBytes = 0;\n      lastCheckpointIndex = i;\n      lastCheckpointBytes = 0;\n      lastEstimatedGas = 0n;\n    }\n\n    // Add call to current batch\n    currentBatch.push(contract);\n    currentBytes += callBytes;\n  }\n\n  // Add final batch if not empty\n  if (currentBatch.length > 0) {\n    batches.push(currentBatch);\n  }\n\n  return batches;\n}\n\n/**\n * Encodes a contract call to measure its calldata size.\n *\n * @param contract - The contract function configuration to encode\n * @returns Hex-encoded function data\n */\nfunction encodeContractCall(contract: ContractFunctionConfig): Hex {\n  const { abi, functionName, args } = contract;\n\n  return encodeFunctionData({\n    abi,\n    functionName,\n    args,\n  } as EncodeFunctionDataParameters);\n}\n\n/**\n * Calculates total encoded size of a batch.\n *\n * @param batch - Array of contract function configurations to measure\n * @returns Total size in bytes of all encoded calls in the batch\n */\nfunction calculateBatchSize(batch: ContractFunctionConfig[]): number {\n  return batch.reduce((total, contract) => {\n    const encoded = encodeContractCall(contract);\n    return total + size(encoded);\n  }, 0);\n}\n\n/**\n * Estimates gas for a batch of calls via multicall3.\n *\n * @param client - The viem public client for gas estimation\n * @param batch - Array of contract calls to estimate gas for\n * @param multicallAddress - The multicall3 contract address to use\n * @returns Estimated gas cost for executing the batch\n */\nasync function estimateBatchGas(\n  client: PublicClient,\n  batch: ContractFunctionConfig[],\n  multicallAddress: Address,\n): Promise<bigint> {\n  // Encode batch as multicall3 aggregate3 call\n  const calls = batch.map((contract) => ({\n    target: contract.address,\n    allowFailure: false,\n    callData: encodeContractCall(contract),\n  }));\n\n  // Estimate gas for the multicall\n  const gas = await client.estimateGas({\n    to: multicallAddress,\n    data: encodeFunctionData({\n      abi: multicall3Abi,\n      functionName: \"aggregate3\",\n      args: [calls],\n    }),\n  });\n\n  return gas;\n}\n\n/**\n * Extrapolates gas usage for calls added since last checkpoint.\n *\n * @remarks\n * Uses a conservative 1.1x multiplier for safety to account for gas usage variations.\n *\n * @param lastGas - The gas estimate from the last checkpoint\n * @param callsSinceCheckpoint - Number of calls added since the checkpoint\n * @returns Extrapolated gas estimate with safety margin\n */\nfunction estimateNextGas(\n  lastGas: bigint,\n  callsSinceCheckpoint: number,\n): bigint {\n  if (callsSinceCheckpoint === 0) return lastGas;\n\n  // Assume linear scaling with safety factor\n  const avgGasPerCall = lastGas / BigInt(Math.max(1, callsSinceCheckpoint - 1));\n  const estimatedGas = lastGas + avgGasPerCall;\n\n  // Apply 10% safety margin\n  return (estimatedGas * 110n) / 100n;\n}\n\n/**\n * Minimal multicall3 ABI for gas estimation\n */\nconst multicall3Abi = [\n  {\n    name: \"aggregate3\",\n    type: \"function\",\n    stateMutability: \"payable\",\n    inputs: [\n      {\n        name: \"calls\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"target\", type: \"address\" },\n          { name: \"allowFailure\", type: \"bool\" },\n          { name: \"callData\", type: \"bytes\" },\n        ],\n      },\n    ],\n    outputs: [\n      {\n        name: \"returnData\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"success\", type: \"bool\" },\n          { name: \"returnData\", type: \"bytes\" },\n        ],\n      },\n    ],\n  },\n] as const;\n\n/**\n * Utility function to analyze calls and predict optimal batch configuration\n *\n * @remarks\n * This function helps determine the best configuration for a specific set of calls\n * by analyzing their characteristics. Useful for optimizing repeated operations.\n *\n * @param contracts - The calls to analyze\n * @returns Suggested configuration based on call analysis\n */\nexport function analyzeCallsForOptimalConfig(\n  contracts: readonly ContractFunctionConfig[],\n): Pick<GasAwareMulticallOptions, \"checkpointFrequency\" | \"maxCalldataBytes\"> {\n  // Calculate average call size\n  const totalBytes = contracts.reduce((sum, contract) => {\n    const encoded = encodeContractCall(contract);\n    return sum + size(encoded);\n  }, 0);\n\n  const avgBytesPerCall = totalBytes / contracts.length;\n\n  // Suggest checkpoint frequency based on call density\n  const checkpointFrequency = {\n    calls: avgBytesPerCall > 500 ? 16 : 32, // More frequent for large calls\n    bytes: avgBytesPerCall > 500 ? 4096 : 8192,\n  };\n\n  // Suggest calldata limit based on total size\n  // For 1000 calls with small arrays, totalBytes will be much less than 500KB,\n  // so use number of contracts as additional signal\n  const maxCalldataBytes =\n    totalBytes > 50_000 || contracts.length > 500 ? 128_000 : 100_000;\n\n  return {\n    checkpointFrequency,\n    maxCalldataBytes,\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/utils/multicall.ts"],"sourcesContent":["import type {\n  Address,\n  PublicClient,\n  MulticallParameters,\n  MulticallReturnType,\n  EncodeFunctionDataParameters,\n  Hex,\n  Abi,\n} from \"viem\";\nimport { encodeFunctionData, size } from \"viem\";\nimport { getUtilityAddress } from \"../config/addresses\";\nimport type { VanaChainId } from \"../types\";\n\n/**\n * Type for a contract function configuration used in multicall\n */\nexport interface ContractFunctionConfig {\n  address: Address;\n  abi: Abi;\n  functionName: string;\n  args?: readonly unknown[];\n}\n\n/**\n * Configuration options for gas-aware multicall batching.\n *\n * @remarks\n * These options control how the multicall utility splits large batches\n * to stay within gas and calldata limits. The defaults are conservative\n * to ensure compatibility across different chains and RPC providers.\n */\nexport interface GasAwareMulticallOptions {\n  /**\n   * Maximum gas per batch. Defaults to 10M (conservative for most chains).\n   *\n   * @remarks\n   * This should be set below the block gas limit of your target chain.\n   * Common values:\n   * - Vana mainnet: 30M (use 25M for safety)\n   * - Vana moksha: 30M (use 25M for safety)\n   * - Ethereum mainnet: 30M (use 25M for safety)\n   * - Arbitrum: 32M (use 25M for safety)\n   */\n  maxGasPerBatch?: bigint;\n\n  /**\n   * Maximum calldata size per batch in bytes. Defaults to 100KB.\n   *\n   * @remarks\n   * This is particularly important for L2 chains where calldata is expensive.\n   * Some RPC providers also have limits on request size.\n   */\n  maxCalldataBytes?: number;\n\n  /**\n   * How often to checkpoint gas estimates. Defaults to every 32 calls or 8KB.\n   *\n   * @remarks\n   * More frequent checkpoints give more accurate batching but require more\n   * RPC calls for gas estimation. The default balances accuracy vs performance.\n   */\n  checkpointFrequency?: {\n    /** Checkpoint after this many calls */\n    calls: number;\n    /** Checkpoint after this many bytes of calldata */\n    bytes: number;\n  };\n\n  /**\n   * Whether to allow partial batch failures. Defaults to false.\n   *\n   * @remarks\n   * When true, individual call failures won't fail the entire batch.\n   * This matches viem's multicall behavior with allowFailure option.\n   */\n  allowFailure?: boolean;\n\n  /**\n   * Optional multicall3 contract address override.\n   *\n   * @remarks\n   * By default, uses the standard multicall3 address deployed on most chains:\n   * 0xcA11bde05977b3631167028862bE2a173976CA11\n   */\n  multicallAddress?: Address;\n\n  /**\n   * Optional callback for tracking batching progress.\n   *\n   * @remarks\n   * Useful for showing progress in UI or debugging batch performance.\n   */\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Internal configuration with defaults applied\n */\ninterface NormalizedOptions {\n  maxGasPerBatch: bigint;\n  maxCalldataBytes: number;\n  checkpointFrequency: {\n    calls: number;\n    bytes: number;\n  };\n  allowFailure: boolean;\n  multicallAddress: Address;\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Default configuration values\n */\nconst DEFAULT_OPTIONS: Omit<NormalizedOptions, \"multicallAddress\"> = {\n  maxGasPerBatch: 10_000_000n, // 10M gas - conservative default\n  maxCalldataBytes: 100_000, // 100KB - works with most RPC providers\n  checkpointFrequency: {\n    calls: 32,\n    bytes: 8192, // 8KB\n  },\n  allowFailure: false,\n};\n\n/**\n * A gas-aware multicall function that automatically batches calls to stay within limits.\n *\n * @remarks\n * This function extends viem's multicall with intelligent batching based on:\n * - Actual gas costs (via periodic estimateGas calls)\n * - Calldata size limits\n * - Chain-specific constraints\n *\n * It uses a greedy algorithm with periodic checkpoints to efficiently determine\n * optimal batch sizes without making excessive RPC calls.\n *\n * @param client - The viem public client to use for RPC calls\n * @param parameters - The multicall parameters (same as viem's multicall)\n * @param options - Optional configuration for gas-aware batching\n * @returns The aggregated results from all batches\n *\n * @example\n * ```typescript\n * // Basic usage - drop-in replacement for viem's multicall\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: [\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address1] },\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address2] },\n *     // ... hundreds more calls\n *   ]\n * });\n *\n * // With custom limits for a specific chain\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: calls,\n * }, {\n *   maxGasPerBatch: 25_000_000n, // 25M for mainnet\n *   maxCalldataBytes: 128_000, // 128KB\n *   onProgress: (done, total) => console.log(`Progress: ${done}/${total}`)\n * });\n * ```\n */\nexport async function gasAwareMulticall<\n  TContracts extends readonly ContractFunctionConfig[],\n  TAllowFailure extends boolean = false,\n>(\n  client: PublicClient,\n  parameters: MulticallParameters<TContracts, TAllowFailure>,\n  options: GasAwareMulticallOptions = {},\n): Promise<MulticallReturnType<TContracts, TAllowFailure>> {\n  // Get the chain-specific Multicall3 address\n  const chainId = await client.getChainId();\n  const multicall3Address =\n    options.multicallAddress ??\n    getUtilityAddress(chainId as VanaChainId, \"Multicall3\");\n\n  // Normalize options with defaults\n  const opts: NormalizedOptions = {\n    ...DEFAULT_OPTIONS,\n    ...options,\n    multicallAddress: multicall3Address,\n    checkpointFrequency: {\n      ...DEFAULT_OPTIONS.checkpointFrequency,\n      ...options.checkpointFrequency,\n    },\n  };\n\n  // Override allowFailure if specified in parameters\n  if (parameters.allowFailure !== undefined) {\n    opts.allowFailure = parameters.allowFailure;\n  }\n\n  const { contracts } = parameters;\n  if (!contracts || contracts.length === 0) {\n    // TODO(TYPES): Empty array needs to match complex generic return type.\n    // Future improvement: Use conditional types to properly type empty results\n    // based on TAllowFailure parameter. Consider creating utility type helper.\n    return [] as unknown as MulticallReturnType<TContracts, TAllowFailure>;\n  }\n\n  // Execute batching algorithm\n  const batches = await createBatches(\n    client,\n    contracts as readonly ContractFunctionConfig[],\n    opts,\n  );\n\n  // Execute all batches in parallel\n  const batchResults = await Promise.all(\n    batches.map((batch, index) => {\n      // Report progress if callback provided\n      if (opts.onProgress && index > 0) {\n        const completed = batches\n          .slice(0, index)\n          .reduce((sum, b) => sum + b.length, 0);\n        opts.onProgress(completed, contracts.length);\n      }\n\n      // Execute batch using viem's multicall\n      return client.multicall({\n        ...parameters,\n        contracts: batch as typeof contracts,\n        multicallAddress: opts.multicallAddress,\n        allowFailure: opts.allowFailure,\n      });\n    }),\n  );\n\n  // Report final progress\n  if (opts.onProgress) {\n    opts.onProgress(contracts.length, contracts.length);\n  }\n\n  // Flatten results\n  return batchResults.flat() as MulticallReturnType<TContracts, TAllowFailure>;\n}\n\n/**\n * Creates optimally-sized batches using greedy algorithm with checkpoints.\n *\n * @param client - The viem public client for making RPC calls\n * @param contracts - Array of contract function configurations to batch\n * @param options - Normalized batching options with limits and settings\n * @returns Array of optimally-sized contract function configuration batches\n */\nasync function createBatches(\n  client: PublicClient,\n  contracts: readonly ContractFunctionConfig[],\n  options: NormalizedOptions,\n): Promise<ContractFunctionConfig[][]> {\n  const batches: ContractFunctionConfig[][] = [];\n  let currentBatch: ContractFunctionConfig[] = [];\n  let currentBytes = 0;\n  let lastCheckpointIndex = 0;\n  let lastCheckpointBytes = 0;\n  let lastEstimatedGas = 0n;\n\n  for (let i = 0; i < contracts.length; i++) {\n    const contract = contracts[i];\n\n    // Calculate encoded size for this call\n    const encoded = encodeContractCall(contract);\n    const callBytes = size(encoded);\n\n    // Check if we need a gas checkpoint\n    const callsSinceCheckpoint = i - lastCheckpointIndex;\n    const bytesSinceCheckpoint = currentBytes - lastCheckpointBytes;\n\n    const needsCheckpoint =\n      callsSinceCheckpoint >= options.checkpointFrequency.calls ||\n      bytesSinceCheckpoint >= options.checkpointFrequency.bytes;\n\n    // Perform checkpoint if needed\n    if (needsCheckpoint && currentBatch.length > 0) {\n      try {\n        lastEstimatedGas = await estimateBatchGas(\n          client,\n          currentBatch,\n          options.multicallAddress,\n        );\n        lastCheckpointIndex = i;\n        lastCheckpointBytes = currentBytes;\n      } catch (error) {\n        // If estimation fails, finalize current batch to be safe\n        if (currentBatch.length > 1) {\n          // Try with half the batch\n          const halfBatch = currentBatch.slice(\n            0,\n            Math.floor(currentBatch.length / 2),\n          );\n          batches.push(halfBatch);\n          currentBatch = currentBatch.slice(halfBatch.length);\n          currentBytes = calculateBatchSize(currentBatch);\n          lastCheckpointIndex = i;\n          lastCheckpointBytes = currentBytes;\n          lastEstimatedGas = 0n;\n        } else {\n          // Single call failed, skip it or throw based on allowFailure\n          if (!options.allowFailure) {\n            throw new Error(\n              `Gas estimation failed for call ${i}: ${String(error)}`,\n            );\n          }\n          currentBatch = [];\n          currentBytes = 0;\n          continue;\n        }\n      }\n    }\n\n    // Check if adding this call would exceed limits\n    const wouldExceedCalldata =\n      currentBytes + callBytes > options.maxCalldataBytes;\n    const wouldExceedGas =\n      lastEstimatedGas > 0n &&\n      estimateNextGas(lastEstimatedGas, callsSinceCheckpoint + 1) >\n        options.maxGasPerBatch;\n\n    // If we would exceed limits, finalize current batch\n    if ((wouldExceedCalldata || wouldExceedGas) && currentBatch.length > 0) {\n      batches.push(currentBatch);\n      currentBatch = [];\n      currentBytes = 0;\n      lastCheckpointIndex = i;\n      lastCheckpointBytes = 0;\n      lastEstimatedGas = 0n;\n    }\n\n    // Add call to current batch\n    currentBatch.push(contract);\n    currentBytes += callBytes;\n  }\n\n  // Add final batch if not empty\n  if (currentBatch.length > 0) {\n    batches.push(currentBatch);\n  }\n\n  return batches;\n}\n\n/**\n * Encodes a contract call to measure its calldata size.\n *\n * @param contract - The contract function configuration to encode\n * @returns Hex-encoded function data\n */\nfunction encodeContractCall(contract: ContractFunctionConfig): Hex {\n  const { abi, functionName, args } = contract;\n\n  return encodeFunctionData({\n    abi,\n    functionName,\n    args,\n  } as EncodeFunctionDataParameters);\n}\n\n/**\n * Calculates total encoded size of a batch.\n *\n * @param batch - Array of contract function configurations to measure\n * @returns Total size in bytes of all encoded calls in the batch\n */\nfunction calculateBatchSize(batch: ContractFunctionConfig[]): number {\n  return batch.reduce((total, contract) => {\n    const encoded = encodeContractCall(contract);\n    return total + size(encoded);\n  }, 0);\n}\n\n/**\n * Estimates gas for a batch of calls via multicall3.\n *\n * @param client - The viem public client for gas estimation\n * @param batch - Array of contract calls to estimate gas for\n * @param multicallAddress - The multicall3 contract address to use\n * @returns Estimated gas cost for executing the batch\n */\nasync function estimateBatchGas(\n  client: PublicClient,\n  batch: ContractFunctionConfig[],\n  multicallAddress: Address,\n): Promise<bigint> {\n  // Encode batch as multicall3 aggregate3 call\n  const calls = batch.map((contract) => ({\n    target: contract.address,\n    allowFailure: false,\n    callData: encodeContractCall(contract),\n  }));\n\n  // Estimate gas for the multicall\n  const gas = await client.estimateGas({\n    to: multicallAddress,\n    data: encodeFunctionData({\n      abi: multicall3Abi,\n      functionName: \"aggregate3\",\n      args: [calls],\n    }),\n  });\n\n  return gas;\n}\n\n/**\n * Extrapolates gas usage for calls added since last checkpoint.\n *\n * @remarks\n * Uses a conservative 1.1x multiplier for safety to account for gas usage variations.\n *\n * @param lastGas - The gas estimate from the last checkpoint\n * @param callsSinceCheckpoint - Number of calls added since the checkpoint\n * @returns Extrapolated gas estimate with safety margin\n */\nfunction estimateNextGas(\n  lastGas: bigint,\n  callsSinceCheckpoint: number,\n): bigint {\n  if (callsSinceCheckpoint === 0) return lastGas;\n\n  // Assume linear scaling with safety factor\n  const avgGasPerCall = lastGas / BigInt(Math.max(1, callsSinceCheckpoint - 1));\n  const estimatedGas = lastGas + avgGasPerCall;\n\n  // Apply 10% safety margin\n  return (estimatedGas * 110n) / 100n;\n}\n\n/**\n * Minimal multicall3 ABI for gas estimation\n */\nconst multicall3Abi = [\n  {\n    name: \"aggregate3\",\n    type: \"function\",\n    stateMutability: \"payable\",\n    inputs: [\n      {\n        name: \"calls\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"target\", type: \"address\" },\n          { name: \"allowFailure\", type: \"bool\" },\n          { name: \"callData\", type: \"bytes\" },\n        ],\n      },\n    ],\n    outputs: [\n      {\n        name: \"returnData\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"success\", type: \"bool\" },\n          { name: \"returnData\", type: \"bytes\" },\n        ],\n      },\n    ],\n  },\n] as const;\n\n/**\n * Utility function to analyze calls and predict optimal batch configuration\n *\n * @remarks\n * This function helps determine the best configuration for a specific set of calls\n * by analyzing their characteristics. Useful for optimizing repeated operations.\n *\n * @param contracts - The calls to analyze\n * @returns Suggested configuration based on call analysis\n */\nexport function analyzeCallsForOptimalConfig(\n  contracts: readonly ContractFunctionConfig[],\n): Pick<GasAwareMulticallOptions, \"checkpointFrequency\" | \"maxCalldataBytes\"> {\n  // Calculate average call size\n  const totalBytes = contracts.reduce((sum, contract) => {\n    const encoded = encodeContractCall(contract);\n    return sum + size(encoded);\n  }, 0);\n\n  const avgBytesPerCall = totalBytes / contracts.length;\n\n  // Suggest checkpoint frequency based on call density\n  const checkpointFrequency = {\n    calls: avgBytesPerCall > 500 ? 16 : 32, // More frequent for large calls\n    bytes: avgBytesPerCall > 500 ? 4096 : 8192,\n  };\n\n  // Suggest calldata limit based on total size\n  // For 1000 calls with small arrays, totalBytes will be much less than 500KB,\n  // so use number of contracts as additional signal\n  const maxCalldataBytes =\n    totalBytes > 50_000 || contracts.length > 500 ? 128_000 : 100_000;\n\n  return {\n    checkpointFrequency,\n    maxCalldataBytes,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,kBAAyC;AACzC,uBAAkC;AAuGlC,MAAM,kBAA+D;AAAA,EACnE,gBAAgB;AAAA;AAAA,EAChB,kBAAkB;AAAA;AAAA,EAClB,qBAAqB;AAAA,IACnB,OAAO;AAAA,IACP,OAAO;AAAA;AAAA,EACT;AAAA,EACA,cAAc;AAChB;AAwCA,eAAsB,kBAIpB,QACA,YACA,UAAoC,CAAC,GACoB;AAEzD,QAAM,UAAU,MAAM,OAAO,WAAW;AACxC,QAAM,oBACJ,QAAQ,wBACR,oCAAkB,SAAwB,YAAY;AAGxD,QAAM,OAA0B;AAAA,IAC9B,GAAG;AAAA,IACH,GAAG;AAAA,IACH,kBAAkB;AAAA,IAClB,qBAAqB;AAAA,MACnB,GAAG,gBAAgB;AAAA,MACnB,GAAG,QAAQ;AAAA,IACb;AAAA,EACF;AAGA,MAAI,WAAW,iBAAiB,QAAW;AACzC,SAAK,eAAe,WAAW;AAAA,EACjC;AAEA,QAAM,EAAE,UAAU,IAAI;AACtB,MAAI,CAAC,aAAa,UAAU,WAAW,GAAG;AAIxC,WAAO,CAAC;AAAA,EACV;AAGA,QAAM,UAAU,MAAM;AAAA,IACpB;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAGA,QAAM,eAAe,MAAM,QAAQ;AAAA,IACjC,QAAQ,IAAI,CAAC,OAAO,UAAU;AAE5B,UAAI,KAAK,cAAc,QAAQ,GAAG;AAChC,cAAM,YAAY,QACf,MAAM,GAAG,KAAK,EACd,OAAO,CAAC,KAAK,MAAM,MAAM,EAAE,QAAQ,CAAC;AACvC,aAAK,WAAW,WAAW,UAAU,MAAM;AAAA,MAC7C;AAGA,aAAO,OAAO,UAAU;AAAA,QACtB,GAAG;AAAA,QACH,WAAW;AAAA,QACX,kBAAkB,KAAK;AAAA,QACvB,cAAc,KAAK;AAAA,MACrB,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AAGA,MAAI,KAAK,YAAY;AACnB,SAAK,WAAW,UAAU,QAAQ,UAAU,MAAM;AAAA,EACpD;AAGA,SAAO,aAAa,KAAK;AAC3B;AAUA,eAAe,cACb,QACA,WACA,SACqC;AACrC,QAAM,UAAsC,CAAC;AAC7C,MAAI,eAAyC,CAAC;AAC9C,MAAI,eAAe;AACnB,MAAI,sBAAsB;AAC1B,MAAI,sBAAsB;AAC1B,MAAI,mBAAmB;AAEvB,WAAS,IAAI,GAAG,IAAI,UAAU,QAAQ,KAAK;AACzC,UAAM,WAAW,UAAU,CAAC;AAG5B,UAAM,UAAU,mBAAmB,QAAQ;AAC3C,UAAM,gBAAY,kBAAK,OAAO;AAG9B,UAAM,uBAAuB,IAAI;AACjC,UAAM,uBAAuB,eAAe;AAE5C,UAAM,kBACJ,wBAAwB,QAAQ,oBAAoB,SACpD,wBAAwB,QAAQ,oBAAoB;AAGtD,QAAI,mBAAmB,aAAa,SAAS,GAAG;AAC9C,UAAI;AACF,2BAAmB,MAAM;AAAA,UACvB;AAAA,UACA;AAAA,UACA,QAAQ;AAAA,QACV;AACA,8BAAsB;AACtB,8BAAsB;AAAA,MACxB,SAAS,OAAO;AAEd,YAAI,aAAa,SAAS,GAAG;AAE3B,gBAAM,YAAY,aAAa;AAAA,YAC7B;AAAA,YACA,KAAK,MAAM,aAAa,SAAS,CAAC;AAAA,UACpC;AACA,kBAAQ,KAAK,SAAS;AACtB,yBAAe,aAAa,MAAM,UAAU,MAAM;AAClD,yBAAe,mBAAmB,YAAY;AAC9C,gCAAsB;AACtB,gCAAsB;AACtB,6BAAmB;AAAA,QACrB,OAAO;AAEL,cAAI,CAAC,QAAQ,cAAc;AACzB,kBAAM,IAAI;AAAA,cACR,kCAAkC,CAAC,KAAK,OAAO,KAAK,CAAC;AAAA,YACvD;AAAA,UACF;AACA,yBAAe,CAAC;AAChB,yBAAe;AACf;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAGA,UAAM,sBACJ,eAAe,YAAY,QAAQ;AACrC,UAAM,iBACJ,mBAAmB,MACnB,gBAAgB,kBAAkB,uBAAuB,CAAC,IACxD,QAAQ;AAGZ,SAAK,uBAAuB,mBAAmB,aAAa,SAAS,GAAG;AACtE,cAAQ,KAAK,YAAY;AACzB,qBAAe,CAAC;AAChB,qBAAe;AACf,4BAAsB;AACtB,4BAAsB;AACtB,yBAAmB;AAAA,IACrB;AAGA,iBAAa,KAAK,QAAQ;AAC1B,oBAAgB;AAAA,EAClB;AAGA,MAAI,aAAa,SAAS,GAAG;AAC3B,YAAQ,KAAK,YAAY;AAAA,EAC3B;AAEA,SAAO;AACT;AAQA,SAAS,mBAAmB,UAAuC;AACjE,QAAM,EAAE,KAAK,cAAc,KAAK,IAAI;AAEpC,aAAO,gCAAmB;AAAA,IACxB;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAiC;AACnC;AAQA,SAAS,mBAAmB,OAAyC;AACnE,SAAO,MAAM,OAAO,CAAC,OAAO,aAAa;AACvC,UAAM,UAAU,mBAAmB,QAAQ;AAC3C,WAAO,YAAQ,kBAAK,OAAO;AAAA,EAC7B,GAAG,CAAC;AACN;AAUA,eAAe,iBACb,QACA,OACA,kBACiB;AAEjB,QAAM,QAAQ,MAAM,IAAI,CAAC,cAAc;AAAA,IACrC,QAAQ,SAAS;AAAA,IACjB,cAAc;AAAA,IACd,UAAU,mBAAmB,QAAQ;AAAA,EACvC,EAAE;AAGF,QAAM,MAAM,MAAM,OAAO,YAAY;AAAA,IACnC,IAAI;AAAA,IACJ,UAAM,gCAAmB;AAAA,MACvB,KAAK;AAAA,MACL,cAAc;AAAA,MACd,MAAM,CAAC,KAAK;AAAA,IACd,CAAC;AAAA,EACH,CAAC;AAED,SAAO;AACT;AAYA,SAAS,gBACP,SACA,sBACQ;AACR,MAAI,yBAAyB,EAAG,QAAO;AAGvC,QAAM,gBAAgB,UAAU,OAAO,KAAK,IAAI,GAAG,uBAAuB,CAAC,CAAC;AAC5E,QAAM,eAAe,UAAU;AAG/B,SAAQ,eAAe,OAAQ;AACjC;AAKA,MAAM,gBAAgB;AAAA,EACpB;AAAA,IACE,MAAM;AAAA,IACN,MAAM;AAAA,IACN,iBAAiB;AAAA,IACjB,QAAQ;AAAA,MACN;AAAA,QACE,MAAM;AAAA,QACN,MAAM;AAAA,QACN,YAAY;AAAA,UACV,EAAE,MAAM,UAAU,MAAM,UAAU;AAAA,UAClC,EAAE,MAAM,gBAAgB,MAAM,OAAO;AAAA,UACrC,EAAE,MAAM,YAAY,MAAM,QAAQ;AAAA,QACpC;AAAA,MACF;AAAA,IACF;AAAA,IACA,SAAS;AAAA,MACP;AAAA,QACE,MAAM;AAAA,QACN,MAAM;AAAA,QACN,YAAY;AAAA,UACV,EAAE,MAAM,WAAW,MAAM,OAAO;AAAA,UAChC,EAAE,MAAM,cAAc,MAAM,QAAQ;AAAA,QACtC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAYO,SAAS,6BACd,WAC4E;AAE5E,QAAM,aAAa,UAAU,OAAO,CAAC,KAAK,aAAa;AACrD,UAAM,UAAU,mBAAmB,QAAQ;AAC3C,WAAO,UAAM,kBAAK,OAAO;AAAA,EAC3B,GAAG,CAAC;AAEJ,QAAM,kBAAkB,aAAa,UAAU;AAG/C,QAAM,sBAAsB;AAAA,IAC1B,OAAO,kBAAkB,MAAM,KAAK;AAAA;AAAA,IACpC,OAAO,kBAAkB,MAAM,OAAO;AAAA,EACxC;AAKA,QAAM,mBACJ,aAAa,OAAU,UAAU,SAAS,MAAM,QAAU;AAE5D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,EACF;AACF;","names":[]}

package/dist/utils/multicall.d.ts

@@ -1,9 +1,8 @@
-import { Address, Abi, PublicClient, MulticallParameters, MulticallReturnType } from 'viem';
-
+import type { Address, PublicClient, MulticallParameters, MulticallReturnType, Abi } from "viem";
 /**
  * Type for a contract function configuration used in multicall
  */
-interface ContractFunctionConfig {
+export interface ContractFunctionConfig {
     address: Address;
     abi: Abi;
     functionName: string;
@@ -17,7 +16,7 @@ interface ContractFunctionConfig {
  * to stay within gas and calldata limits. The defaults are conservative
  * to ensure compatibility across different chains and RPC providers.
  */
-interface GasAwareMulticallOptions {
+export interface GasAwareMulticallOptions {
     /**
      * Maximum gas per batch. Defaults to 10M (conservative for most chains).
      *
@@ -113,7 +112,7 @@ interface GasAwareMulticallOptions {
  * });
  * ```
  */
-declare function gasAwareMulticall<TContracts extends readonly ContractFunctionConfig[], TAllowFailure extends boolean = false>(client: PublicClient, parameters: MulticallParameters<TContracts, TAllowFailure>, options?: GasAwareMulticallOptions): Promise<MulticallReturnType<TContracts, TAllowFailure>>;
+export declare function gasAwareMulticall<TContracts extends readonly ContractFunctionConfig[], TAllowFailure extends boolean = false>(client: PublicClient, parameters: MulticallParameters<TContracts, TAllowFailure>, options?: GasAwareMulticallOptions): Promise<MulticallReturnType<TContracts, TAllowFailure>>;
 /**
  * Utility function to analyze calls and predict optimal batch configuration
  *
@@ -124,6 +123,4 @@ declare function gasAwareMulticall<TContracts extends readonly ContractFunctionC
  * @param contracts - The calls to analyze
  * @returns Suggested configuration based on call analysis
  */
-declare function analyzeCallsForOptimalConfig(contracts: readonly ContractFunctionConfig[]): Pick<GasAwareMulticallOptions, "checkpointFrequency" | "maxCalldataBytes">;
-
-export { type ContractFunctionConfig, type GasAwareMulticallOptions, analyzeCallsForOptimalConfig, gasAwareMulticall };
+export declare function analyzeCallsForOptimalConfig(contracts: readonly ContractFunctionConfig[]): Pick<GasAwareMulticallOptions, "checkpointFrequency" | "maxCalldataBytes">;

package/dist/utils/multicall.js

@@ -14,7 +14,7 @@ const DEFAULT_OPTIONS = {
 };
 async function gasAwareMulticall(client, parameters, options = {}) {
   const chainId = await client.getChainId();
-  const multicall3Address = options.multicallAddress || getUtilityAddress(chainId, "Multicall3");
+  const multicall3Address = options.multicallAddress ?? getUtilityAddress(chainId, "Multicall3");
   const opts = {
     ...DEFAULT_OPTIONS,
     ...options,
@@ -92,7 +92,9 @@ async function createBatches(client, contracts, options) {
           lastEstimatedGas = 0n;
         } else {
           if (!options.allowFailure) {
-            throw new Error(`Gas estimation failed for call ${i}: ${error}`);
+            throw new Error(
+              `Gas estimation failed for call ${i}: ${String(error)}`
+            );
           }
           currentBatch = [];
           currentBytes = 0;

package/dist/utils/multicall.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/multicall.ts"],"sourcesContent":["import type {\n  Address,\n  PublicClient,\n  MulticallParameters,\n  MulticallReturnType,\n  EncodeFunctionDataParameters,\n  Hex,\n  Abi,\n} from \"viem\";\nimport { encodeFunctionData, size } from \"viem\";\nimport { getUtilityAddress } from \"../config/addresses\";\nimport type { VanaChainId } from \"../types\";\n\n/**\n * Type for a contract function configuration used in multicall\n */\nexport interface ContractFunctionConfig {\n  address: Address;\n  abi: Abi;\n  functionName: string;\n  args?: readonly unknown[];\n}\n\n/**\n * Configuration options for gas-aware multicall batching.\n *\n * @remarks\n * These options control how the multicall utility splits large batches\n * to stay within gas and calldata limits. The defaults are conservative\n * to ensure compatibility across different chains and RPC providers.\n */\nexport interface GasAwareMulticallOptions {\n  /**\n   * Maximum gas per batch. Defaults to 10M (conservative for most chains).\n   *\n   * @remarks\n   * This should be set below the block gas limit of your target chain.\n   * Common values:\n   * - Vana mainnet: 30M (use 25M for safety)\n   * - Vana moksha: 30M (use 25M for safety)\n   * - Ethereum mainnet: 30M (use 25M for safety)\n   * - Arbitrum: 32M (use 25M for safety)\n   */\n  maxGasPerBatch?: bigint;\n\n  /**\n   * Maximum calldata size per batch in bytes. Defaults to 100KB.\n   *\n   * @remarks\n   * This is particularly important for L2 chains where calldata is expensive.\n   * Some RPC providers also have limits on request size.\n   */\n  maxCalldataBytes?: number;\n\n  /**\n   * How often to checkpoint gas estimates. Defaults to every 32 calls or 8KB.\n   *\n   * @remarks\n   * More frequent checkpoints give more accurate batching but require more\n   * RPC calls for gas estimation. The default balances accuracy vs performance.\n   */\n  checkpointFrequency?: {\n    /** Checkpoint after this many calls */\n    calls: number;\n    /** Checkpoint after this many bytes of calldata */\n    bytes: number;\n  };\n\n  /**\n   * Whether to allow partial batch failures. Defaults to false.\n   *\n   * @remarks\n   * When true, individual call failures won't fail the entire batch.\n   * This matches viem's multicall behavior with allowFailure option.\n   */\n  allowFailure?: boolean;\n\n  /**\n   * Optional multicall3 contract address override.\n   *\n   * @remarks\n   * By default, uses the standard multicall3 address deployed on most chains:\n   * 0xcA11bde05977b3631167028862bE2a173976CA11\n   */\n  multicallAddress?: Address;\n\n  /**\n   * Optional callback for tracking batching progress.\n   *\n   * @remarks\n   * Useful for showing progress in UI or debugging batch performance.\n   */\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Internal configuration with defaults applied\n */\ninterface NormalizedOptions {\n  maxGasPerBatch: bigint;\n  maxCalldataBytes: number;\n  checkpointFrequency: {\n    calls: number;\n    bytes: number;\n  };\n  allowFailure: boolean;\n  multicallAddress: Address;\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Default configuration values\n */\nconst DEFAULT_OPTIONS: Omit<NormalizedOptions, \"multicallAddress\"> = {\n  maxGasPerBatch: 10_000_000n, // 10M gas - conservative default\n  maxCalldataBytes: 100_000, // 100KB - works with most RPC providers\n  checkpointFrequency: {\n    calls: 32,\n    bytes: 8192, // 8KB\n  },\n  allowFailure: false,\n};\n\n/**\n * A gas-aware multicall function that automatically batches calls to stay within limits.\n *\n * @remarks\n * This function extends viem's multicall with intelligent batching based on:\n * - Actual gas costs (via periodic estimateGas calls)\n * - Calldata size limits\n * - Chain-specific constraints\n *\n * It uses a greedy algorithm with periodic checkpoints to efficiently determine\n * optimal batch sizes without making excessive RPC calls.\n *\n * @param client - The viem public client to use for RPC calls\n * @param parameters - The multicall parameters (same as viem's multicall)\n * @param options - Optional configuration for gas-aware batching\n * @returns The aggregated results from all batches\n *\n * @example\n * ```typescript\n * // Basic usage - drop-in replacement for viem's multicall\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: [\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address1] },\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address2] },\n *     // ... hundreds more calls\n *   ]\n * });\n *\n * // With custom limits for a specific chain\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: calls,\n * }, {\n *   maxGasPerBatch: 25_000_000n, // 25M for mainnet\n *   maxCalldataBytes: 128_000, // 128KB\n *   onProgress: (done, total) => console.log(`Progress: ${done}/${total}`)\n * });\n * ```\n */\nexport async function gasAwareMulticall<\n  TContracts extends readonly ContractFunctionConfig[],\n  TAllowFailure extends boolean = false,\n>(\n  client: PublicClient,\n  parameters: MulticallParameters<TContracts, TAllowFailure>,\n  options: GasAwareMulticallOptions = {},\n): Promise<MulticallReturnType<TContracts, TAllowFailure>> {\n  // Get the chain-specific Multicall3 address\n  const chainId = await client.getChainId();\n  const multicall3Address =\n    options.multicallAddress ||\n    getUtilityAddress(chainId as VanaChainId, \"Multicall3\");\n\n  // Normalize options with defaults\n  const opts: NormalizedOptions = {\n    ...DEFAULT_OPTIONS,\n    ...options,\n    multicallAddress: multicall3Address,\n    checkpointFrequency: {\n      ...DEFAULT_OPTIONS.checkpointFrequency,\n      ...options.checkpointFrequency,\n    },\n  };\n\n  // Override allowFailure if specified in parameters\n  if (parameters.allowFailure !== undefined) {\n    opts.allowFailure = parameters.allowFailure;\n  }\n\n  const { contracts } = parameters;\n  if (!contracts || contracts.length === 0) {\n    return [] as unknown as MulticallReturnType<TContracts, TAllowFailure>;\n  }\n\n  // Execute batching algorithm\n  const batches = await createBatches(\n    client,\n    contracts as readonly ContractFunctionConfig[],\n    opts,\n  );\n\n  // Execute all batches in parallel\n  const batchResults = await Promise.all(\n    batches.map((batch, index) => {\n      // Report progress if callback provided\n      if (opts.onProgress && index > 0) {\n        const completed = batches\n          .slice(0, index)\n          .reduce((sum, b) => sum + b.length, 0);\n        opts.onProgress(completed, contracts.length);\n      }\n\n      // Execute batch using viem's multicall\n      return client.multicall({\n        ...parameters,\n        contracts: batch as typeof contracts,\n        multicallAddress: opts.multicallAddress,\n        allowFailure: opts.allowFailure,\n      });\n    }),\n  );\n\n  // Report final progress\n  if (opts.onProgress) {\n    opts.onProgress(contracts.length, contracts.length);\n  }\n\n  // Flatten results\n  return batchResults.flat() as MulticallReturnType<TContracts, TAllowFailure>;\n}\n\n/**\n * Creates optimally-sized batches using greedy algorithm with checkpoints.\n *\n * @param client - The viem public client for making RPC calls\n * @param contracts - Array of contract function configurations to batch\n * @param options - Normalized batching options with limits and settings\n * @returns Array of optimally-sized contract function configuration batches\n */\nasync function createBatches(\n  client: PublicClient,\n  contracts: readonly ContractFunctionConfig[],\n  options: NormalizedOptions,\n): Promise<ContractFunctionConfig[][]> {\n  const batches: ContractFunctionConfig[][] = [];\n  let currentBatch: ContractFunctionConfig[] = [];\n  let currentBytes = 0;\n  let lastCheckpointIndex = 0;\n  let lastCheckpointBytes = 0;\n  let lastEstimatedGas = 0n;\n\n  for (let i = 0; i < contracts.length; i++) {\n    const contract = contracts[i];\n\n    // Calculate encoded size for this call\n    const encoded = encodeContractCall(contract);\n    const callBytes = size(encoded);\n\n    // Check if we need a gas checkpoint\n    const callsSinceCheckpoint = i - lastCheckpointIndex;\n    const bytesSinceCheckpoint = currentBytes - lastCheckpointBytes;\n\n    const needsCheckpoint =\n      callsSinceCheckpoint >= options.checkpointFrequency.calls ||\n      bytesSinceCheckpoint >= options.checkpointFrequency.bytes;\n\n    // Perform checkpoint if needed\n    if (needsCheckpoint && currentBatch.length > 0) {\n      try {\n        lastEstimatedGas = await estimateBatchGas(\n          client,\n          currentBatch,\n          options.multicallAddress,\n        );\n        lastCheckpointIndex = i;\n        lastCheckpointBytes = currentBytes;\n      } catch (error) {\n        // If estimation fails, finalize current batch to be safe\n        if (currentBatch.length > 1) {\n          // Try with half the batch\n          const halfBatch = currentBatch.slice(\n            0,\n            Math.floor(currentBatch.length / 2),\n          );\n          batches.push(halfBatch);\n          currentBatch = currentBatch.slice(halfBatch.length);\n          currentBytes = calculateBatchSize(currentBatch);\n          lastCheckpointIndex = i;\n          lastCheckpointBytes = currentBytes;\n          lastEstimatedGas = 0n;\n        } else {\n          // Single call failed, skip it or throw based on allowFailure\n          if (!options.allowFailure) {\n            throw new Error(`Gas estimation failed for call ${i}: ${error}`);\n          }\n          currentBatch = [];\n          currentBytes = 0;\n          continue;\n        }\n      }\n    }\n\n    // Check if adding this call would exceed limits\n    const wouldExceedCalldata =\n      currentBytes + callBytes > options.maxCalldataBytes;\n    const wouldExceedGas =\n      lastEstimatedGas > 0n &&\n      estimateNextGas(lastEstimatedGas, callsSinceCheckpoint + 1) >\n        options.maxGasPerBatch;\n\n    // If we would exceed limits, finalize current batch\n    if ((wouldExceedCalldata || wouldExceedGas) && currentBatch.length > 0) {\n      batches.push(currentBatch);\n      currentBatch = [];\n      currentBytes = 0;\n      lastCheckpointIndex = i;\n      lastCheckpointBytes = 0;\n      lastEstimatedGas = 0n;\n    }\n\n    // Add call to current batch\n    currentBatch.push(contract);\n    currentBytes += callBytes;\n  }\n\n  // Add final batch if not empty\n  if (currentBatch.length > 0) {\n    batches.push(currentBatch);\n  }\n\n  return batches;\n}\n\n/**\n * Encodes a contract call to measure its calldata size.\n *\n * @param contract - The contract function configuration to encode\n * @returns Hex-encoded function data\n */\nfunction encodeContractCall(contract: ContractFunctionConfig): Hex {\n  const { abi, functionName, args } = contract;\n\n  return encodeFunctionData({\n    abi,\n    functionName,\n    args,\n  } as EncodeFunctionDataParameters);\n}\n\n/**\n * Calculates total encoded size of a batch.\n *\n * @param batch - Array of contract function configurations to measure\n * @returns Total size in bytes of all encoded calls in the batch\n */\nfunction calculateBatchSize(batch: ContractFunctionConfig[]): number {\n  return batch.reduce((total, contract) => {\n    const encoded = encodeContractCall(contract);\n    return total + size(encoded);\n  }, 0);\n}\n\n/**\n * Estimates gas for a batch of calls via multicall3.\n *\n * @param client - The viem public client for gas estimation\n * @param batch - Array of contract calls to estimate gas for\n * @param multicallAddress - The multicall3 contract address to use\n * @returns Estimated gas cost for executing the batch\n */\nasync function estimateBatchGas(\n  client: PublicClient,\n  batch: ContractFunctionConfig[],\n  multicallAddress: Address,\n): Promise<bigint> {\n  // Encode batch as multicall3 aggregate3 call\n  const calls = batch.map((contract) => ({\n    target: contract.address,\n    allowFailure: false,\n    callData: encodeContractCall(contract),\n  }));\n\n  // Estimate gas for the multicall\n  const gas = await client.estimateGas({\n    to: multicallAddress,\n    data: encodeFunctionData({\n      abi: multicall3Abi,\n      functionName: \"aggregate3\",\n      args: [calls],\n    }),\n  });\n\n  return gas;\n}\n\n/**\n * Extrapolates gas usage for calls added since last checkpoint.\n *\n * @remarks\n * Uses a conservative 1.1x multiplier for safety to account for gas usage variations.\n *\n * @param lastGas - The gas estimate from the last checkpoint\n * @param callsSinceCheckpoint - Number of calls added since the checkpoint\n * @returns Extrapolated gas estimate with safety margin\n */\nfunction estimateNextGas(\n  lastGas: bigint,\n  callsSinceCheckpoint: number,\n): bigint {\n  if (callsSinceCheckpoint === 0) return lastGas;\n\n  // Assume linear scaling with safety factor\n  const avgGasPerCall = lastGas / BigInt(Math.max(1, callsSinceCheckpoint - 1));\n  const estimatedGas = lastGas + avgGasPerCall;\n\n  // Apply 10% safety margin\n  return (estimatedGas * 110n) / 100n;\n}\n\n/**\n * Minimal multicall3 ABI for gas estimation\n */\nconst multicall3Abi = [\n  {\n    name: \"aggregate3\",\n    type: \"function\",\n    stateMutability: \"payable\",\n    inputs: [\n      {\n        name: \"calls\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"target\", type: \"address\" },\n          { name: \"allowFailure\", type: \"bool\" },\n          { name: \"callData\", type: \"bytes\" },\n        ],\n      },\n    ],\n    outputs: [\n      {\n        name: \"returnData\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"success\", type: \"bool\" },\n          { name: \"returnData\", type: \"bytes\" },\n        ],\n      },\n    ],\n  },\n] as const;\n\n/**\n * Utility function to analyze calls and predict optimal batch configuration\n *\n * @remarks\n * This function helps determine the best configuration for a specific set of calls\n * by analyzing their characteristics. Useful for optimizing repeated operations.\n *\n * @param contracts - The calls to analyze\n * @returns Suggested configuration based on call analysis\n */\nexport function analyzeCallsForOptimalConfig(\n  contracts: readonly ContractFunctionConfig[],\n): Pick<GasAwareMulticallOptions, \"checkpointFrequency\" | \"maxCalldataBytes\"> {\n  // Calculate average call size\n  const totalBytes = contracts.reduce((sum, contract) => {\n    const encoded = encodeContractCall(contract);\n    return sum + size(encoded);\n  }, 0);\n\n  const avgBytesPerCall = totalBytes / contracts.length;\n\n  // Suggest checkpoint frequency based on call density\n  const checkpointFrequency = {\n    calls: avgBytesPerCall > 500 ? 16 : 32, // More frequent for large calls\n    bytes: avgBytesPerCall > 500 ? 4096 : 8192,\n  };\n\n  // Suggest calldata limit based on total size\n  // For 1000 calls with small arrays, totalBytes will be much less than 500KB,\n  // so use number of contracts as additional signal\n  const maxCalldataBytes =\n    totalBytes > 50_000 || contracts.length > 500 ? 128_000 : 100_000;\n\n  return {\n    checkpointFrequency,\n    maxCalldataBytes,\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/utils/multicall.ts"],"sourcesContent":["import type {\n  Address,\n  PublicClient,\n  MulticallParameters,\n  MulticallReturnType,\n  EncodeFunctionDataParameters,\n  Hex,\n  Abi,\n} from \"viem\";\nimport { encodeFunctionData, size } from \"viem\";\nimport { getUtilityAddress } from \"../config/addresses\";\nimport type { VanaChainId } from \"../types\";\n\n/**\n * Type for a contract function configuration used in multicall\n */\nexport interface ContractFunctionConfig {\n  address: Address;\n  abi: Abi;\n  functionName: string;\n  args?: readonly unknown[];\n}\n\n/**\n * Configuration options for gas-aware multicall batching.\n *\n * @remarks\n * These options control how the multicall utility splits large batches\n * to stay within gas and calldata limits. The defaults are conservative\n * to ensure compatibility across different chains and RPC providers.\n */\nexport interface GasAwareMulticallOptions {\n  /**\n   * Maximum gas per batch. Defaults to 10M (conservative for most chains).\n   *\n   * @remarks\n   * This should be set below the block gas limit of your target chain.\n   * Common values:\n   * - Vana mainnet: 30M (use 25M for safety)\n   * - Vana moksha: 30M (use 25M for safety)\n   * - Ethereum mainnet: 30M (use 25M for safety)\n   * - Arbitrum: 32M (use 25M for safety)\n   */\n  maxGasPerBatch?: bigint;\n\n  /**\n   * Maximum calldata size per batch in bytes. Defaults to 100KB.\n   *\n   * @remarks\n   * This is particularly important for L2 chains where calldata is expensive.\n   * Some RPC providers also have limits on request size.\n   */\n  maxCalldataBytes?: number;\n\n  /**\n   * How often to checkpoint gas estimates. Defaults to every 32 calls or 8KB.\n   *\n   * @remarks\n   * More frequent checkpoints give more accurate batching but require more\n   * RPC calls for gas estimation. The default balances accuracy vs performance.\n   */\n  checkpointFrequency?: {\n    /** Checkpoint after this many calls */\n    calls: number;\n    /** Checkpoint after this many bytes of calldata */\n    bytes: number;\n  };\n\n  /**\n   * Whether to allow partial batch failures. Defaults to false.\n   *\n   * @remarks\n   * When true, individual call failures won't fail the entire batch.\n   * This matches viem's multicall behavior with allowFailure option.\n   */\n  allowFailure?: boolean;\n\n  /**\n   * Optional multicall3 contract address override.\n   *\n   * @remarks\n   * By default, uses the standard multicall3 address deployed on most chains:\n   * 0xcA11bde05977b3631167028862bE2a173976CA11\n   */\n  multicallAddress?: Address;\n\n  /**\n   * Optional callback for tracking batching progress.\n   *\n   * @remarks\n   * Useful for showing progress in UI or debugging batch performance.\n   */\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Internal configuration with defaults applied\n */\ninterface NormalizedOptions {\n  maxGasPerBatch: bigint;\n  maxCalldataBytes: number;\n  checkpointFrequency: {\n    calls: number;\n    bytes: number;\n  };\n  allowFailure: boolean;\n  multicallAddress: Address;\n  onProgress?: (completed: number, total: number) => void;\n}\n\n/**\n * Default configuration values\n */\nconst DEFAULT_OPTIONS: Omit<NormalizedOptions, \"multicallAddress\"> = {\n  maxGasPerBatch: 10_000_000n, // 10M gas - conservative default\n  maxCalldataBytes: 100_000, // 100KB - works with most RPC providers\n  checkpointFrequency: {\n    calls: 32,\n    bytes: 8192, // 8KB\n  },\n  allowFailure: false,\n};\n\n/**\n * A gas-aware multicall function that automatically batches calls to stay within limits.\n *\n * @remarks\n * This function extends viem's multicall with intelligent batching based on:\n * - Actual gas costs (via periodic estimateGas calls)\n * - Calldata size limits\n * - Chain-specific constraints\n *\n * It uses a greedy algorithm with periodic checkpoints to efficiently determine\n * optimal batch sizes without making excessive RPC calls.\n *\n * @param client - The viem public client to use for RPC calls\n * @param parameters - The multicall parameters (same as viem's multicall)\n * @param options - Optional configuration for gas-aware batching\n * @returns The aggregated results from all batches\n *\n * @example\n * ```typescript\n * // Basic usage - drop-in replacement for viem's multicall\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: [\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address1] },\n *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address2] },\n *     // ... hundreds more calls\n *   ]\n * });\n *\n * // With custom limits for a specific chain\n * const results = await gasAwareMulticall(publicClient, {\n *   contracts: calls,\n * }, {\n *   maxGasPerBatch: 25_000_000n, // 25M for mainnet\n *   maxCalldataBytes: 128_000, // 128KB\n *   onProgress: (done, total) => console.log(`Progress: ${done}/${total}`)\n * });\n * ```\n */\nexport async function gasAwareMulticall<\n  TContracts extends readonly ContractFunctionConfig[],\n  TAllowFailure extends boolean = false,\n>(\n  client: PublicClient,\n  parameters: MulticallParameters<TContracts, TAllowFailure>,\n  options: GasAwareMulticallOptions = {},\n): Promise<MulticallReturnType<TContracts, TAllowFailure>> {\n  // Get the chain-specific Multicall3 address\n  const chainId = await client.getChainId();\n  const multicall3Address =\n    options.multicallAddress ??\n    getUtilityAddress(chainId as VanaChainId, \"Multicall3\");\n\n  // Normalize options with defaults\n  const opts: NormalizedOptions = {\n    ...DEFAULT_OPTIONS,\n    ...options,\n    multicallAddress: multicall3Address,\n    checkpointFrequency: {\n      ...DEFAULT_OPTIONS.checkpointFrequency,\n      ...options.checkpointFrequency,\n    },\n  };\n\n  // Override allowFailure if specified in parameters\n  if (parameters.allowFailure !== undefined) {\n    opts.allowFailure = parameters.allowFailure;\n  }\n\n  const { contracts } = parameters;\n  if (!contracts || contracts.length === 0) {\n    // TODO(TYPES): Empty array needs to match complex generic return type.\n    // Future improvement: Use conditional types to properly type empty results\n    // based on TAllowFailure parameter. Consider creating utility type helper.\n    return [] as unknown as MulticallReturnType<TContracts, TAllowFailure>;\n  }\n\n  // Execute batching algorithm\n  const batches = await createBatches(\n    client,\n    contracts as readonly ContractFunctionConfig[],\n    opts,\n  );\n\n  // Execute all batches in parallel\n  const batchResults = await Promise.all(\n    batches.map((batch, index) => {\n      // Report progress if callback provided\n      if (opts.onProgress && index > 0) {\n        const completed = batches\n          .slice(0, index)\n          .reduce((sum, b) => sum + b.length, 0);\n        opts.onProgress(completed, contracts.length);\n      }\n\n      // Execute batch using viem's multicall\n      return client.multicall({\n        ...parameters,\n        contracts: batch as typeof contracts,\n        multicallAddress: opts.multicallAddress,\n        allowFailure: opts.allowFailure,\n      });\n    }),\n  );\n\n  // Report final progress\n  if (opts.onProgress) {\n    opts.onProgress(contracts.length, contracts.length);\n  }\n\n  // Flatten results\n  return batchResults.flat() as MulticallReturnType<TContracts, TAllowFailure>;\n}\n\n/**\n * Creates optimally-sized batches using greedy algorithm with checkpoints.\n *\n * @param client - The viem public client for making RPC calls\n * @param contracts - Array of contract function configurations to batch\n * @param options - Normalized batching options with limits and settings\n * @returns Array of optimally-sized contract function configuration batches\n */\nasync function createBatches(\n  client: PublicClient,\n  contracts: readonly ContractFunctionConfig[],\n  options: NormalizedOptions,\n): Promise<ContractFunctionConfig[][]> {\n  const batches: ContractFunctionConfig[][] = [];\n  let currentBatch: ContractFunctionConfig[] = [];\n  let currentBytes = 0;\n  let lastCheckpointIndex = 0;\n  let lastCheckpointBytes = 0;\n  let lastEstimatedGas = 0n;\n\n  for (let i = 0; i < contracts.length; i++) {\n    const contract = contracts[i];\n\n    // Calculate encoded size for this call\n    const encoded = encodeContractCall(contract);\n    const callBytes = size(encoded);\n\n    // Check if we need a gas checkpoint\n    const callsSinceCheckpoint = i - lastCheckpointIndex;\n    const bytesSinceCheckpoint = currentBytes - lastCheckpointBytes;\n\n    const needsCheckpoint =\n      callsSinceCheckpoint >= options.checkpointFrequency.calls ||\n      bytesSinceCheckpoint >= options.checkpointFrequency.bytes;\n\n    // Perform checkpoint if needed\n    if (needsCheckpoint && currentBatch.length > 0) {\n      try {\n        lastEstimatedGas = await estimateBatchGas(\n          client,\n          currentBatch,\n          options.multicallAddress,\n        );\n        lastCheckpointIndex = i;\n        lastCheckpointBytes = currentBytes;\n      } catch (error) {\n        // If estimation fails, finalize current batch to be safe\n        if (currentBatch.length > 1) {\n          // Try with half the batch\n          const halfBatch = currentBatch.slice(\n            0,\n            Math.floor(currentBatch.length / 2),\n          );\n          batches.push(halfBatch);\n          currentBatch = currentBatch.slice(halfBatch.length);\n          currentBytes = calculateBatchSize(currentBatch);\n          lastCheckpointIndex = i;\n          lastCheckpointBytes = currentBytes;\n          lastEstimatedGas = 0n;\n        } else {\n          // Single call failed, skip it or throw based on allowFailure\n          if (!options.allowFailure) {\n            throw new Error(\n              `Gas estimation failed for call ${i}: ${String(error)}`,\n            );\n          }\n          currentBatch = [];\n          currentBytes = 0;\n          continue;\n        }\n      }\n    }\n\n    // Check if adding this call would exceed limits\n    const wouldExceedCalldata =\n      currentBytes + callBytes > options.maxCalldataBytes;\n    const wouldExceedGas =\n      lastEstimatedGas > 0n &&\n      estimateNextGas(lastEstimatedGas, callsSinceCheckpoint + 1) >\n        options.maxGasPerBatch;\n\n    // If we would exceed limits, finalize current batch\n    if ((wouldExceedCalldata || wouldExceedGas) && currentBatch.length > 0) {\n      batches.push(currentBatch);\n      currentBatch = [];\n      currentBytes = 0;\n      lastCheckpointIndex = i;\n      lastCheckpointBytes = 0;\n      lastEstimatedGas = 0n;\n    }\n\n    // Add call to current batch\n    currentBatch.push(contract);\n    currentBytes += callBytes;\n  }\n\n  // Add final batch if not empty\n  if (currentBatch.length > 0) {\n    batches.push(currentBatch);\n  }\n\n  return batches;\n}\n\n/**\n * Encodes a contract call to measure its calldata size.\n *\n * @param contract - The contract function configuration to encode\n * @returns Hex-encoded function data\n */\nfunction encodeContractCall(contract: ContractFunctionConfig): Hex {\n  const { abi, functionName, args } = contract;\n\n  return encodeFunctionData({\n    abi,\n    functionName,\n    args,\n  } as EncodeFunctionDataParameters);\n}\n\n/**\n * Calculates total encoded size of a batch.\n *\n * @param batch - Array of contract function configurations to measure\n * @returns Total size in bytes of all encoded calls in the batch\n */\nfunction calculateBatchSize(batch: ContractFunctionConfig[]): number {\n  return batch.reduce((total, contract) => {\n    const encoded = encodeContractCall(contract);\n    return total + size(encoded);\n  }, 0);\n}\n\n/**\n * Estimates gas for a batch of calls via multicall3.\n *\n * @param client - The viem public client for gas estimation\n * @param batch - Array of contract calls to estimate gas for\n * @param multicallAddress - The multicall3 contract address to use\n * @returns Estimated gas cost for executing the batch\n */\nasync function estimateBatchGas(\n  client: PublicClient,\n  batch: ContractFunctionConfig[],\n  multicallAddress: Address,\n): Promise<bigint> {\n  // Encode batch as multicall3 aggregate3 call\n  const calls = batch.map((contract) => ({\n    target: contract.address,\n    allowFailure: false,\n    callData: encodeContractCall(contract),\n  }));\n\n  // Estimate gas for the multicall\n  const gas = await client.estimateGas({\n    to: multicallAddress,\n    data: encodeFunctionData({\n      abi: multicall3Abi,\n      functionName: \"aggregate3\",\n      args: [calls],\n    }),\n  });\n\n  return gas;\n}\n\n/**\n * Extrapolates gas usage for calls added since last checkpoint.\n *\n * @remarks\n * Uses a conservative 1.1x multiplier for safety to account for gas usage variations.\n *\n * @param lastGas - The gas estimate from the last checkpoint\n * @param callsSinceCheckpoint - Number of calls added since the checkpoint\n * @returns Extrapolated gas estimate with safety margin\n */\nfunction estimateNextGas(\n  lastGas: bigint,\n  callsSinceCheckpoint: number,\n): bigint {\n  if (callsSinceCheckpoint === 0) return lastGas;\n\n  // Assume linear scaling with safety factor\n  const avgGasPerCall = lastGas / BigInt(Math.max(1, callsSinceCheckpoint - 1));\n  const estimatedGas = lastGas + avgGasPerCall;\n\n  // Apply 10% safety margin\n  return (estimatedGas * 110n) / 100n;\n}\n\n/**\n * Minimal multicall3 ABI for gas estimation\n */\nconst multicall3Abi = [\n  {\n    name: \"aggregate3\",\n    type: \"function\",\n    stateMutability: \"payable\",\n    inputs: [\n      {\n        name: \"calls\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"target\", type: \"address\" },\n          { name: \"allowFailure\", type: \"bool\" },\n          { name: \"callData\", type: \"bytes\" },\n        ],\n      },\n    ],\n    outputs: [\n      {\n        name: \"returnData\",\n        type: \"tuple[]\",\n        components: [\n          { name: \"success\", type: \"bool\" },\n          { name: \"returnData\", type: \"bytes\" },\n        ],\n      },\n    ],\n  },\n] as const;\n\n/**\n * Utility function to analyze calls and predict optimal batch configuration\n *\n * @remarks\n * This function helps determine the best configuration for a specific set of calls\n * by analyzing their characteristics. Useful for optimizing repeated operations.\n *\n * @param contracts - The calls to analyze\n * @returns Suggested configuration based on call analysis\n */\nexport function analyzeCallsForOptimalConfig(\n  contracts: readonly ContractFunctionConfig[],\n): Pick<GasAwareMulticallOptions, \"checkpointFrequency\" | \"maxCalldataBytes\"> {\n  // Calculate average call size\n  const totalBytes = contracts.reduce((sum, contract) => {\n    const encoded = encodeContractCall(contract);\n    return sum + size(encoded);\n  }, 0);\n\n  const avgBytesPerCall = totalBytes / contracts.length;\n\n  // Suggest checkpoint frequency based on call density\n  const checkpointFrequency = {\n    calls: avgBytesPerCall > 500 ? 16 : 32, // More frequent for large calls\n    bytes: avgBytesPerCall > 500 ? 4096 : 8192,\n  };\n\n  // Suggest calldata limit based on total size\n  // For 1000 calls with small arrays, totalBytes will be much less than 500KB,\n  // so use number of contracts as additional signal\n  const maxCalldataBytes =\n    totalBytes > 50_000 || contracts.length > 500 ? 128_000 : 100_000;\n\n  return {\n    checkpointFrequency,\n    maxCalldataBytes,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/utils/parseTransactionPojo.cjs

@@ -0,0 +1,87 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var parseTransactionPojo_exports = {};
+__export(parseTransactionPojo_exports, {
+  parseTransaction: () => parseTransaction
+});
+module.exports = __toCommonJS(parseTransactionPojo_exports);
+var import_viem = require("viem");
+var import_eventRegistry = require("../generated/eventRegistry");
+function parseTransaction(transactionResult, receipt) {
+  const { contract: contractName, fn: functionName } = transactionResult;
+  const registryKey = `${contractName}.${functionName}`;
+  const registry = import_eventRegistry.EVENT_REGISTRY[registryKey];
+  const expectedEvents = {};
+  const allEvents = [];
+  let hasExpectedEvents = false;
+  if (receipt.logs) {
+    for (const log of receipt.logs) {
+      if (!log.topics || log.topics.length === 0) {
+        continue;
+      }
+      const eventTopic = log.topics[0];
+      const abiCandidates = import_eventRegistry.TOPIC_TO_ABIS.get(eventTopic);
+      if (abiCandidates && abiCandidates.length > 0) {
+        for (const abiEvent of abiCandidates) {
+          try {
+            const decoded = (0, import_viem.decodeEventLog)({
+              abi: [abiEvent],
+              data: log.data,
+              topics: log.topics
+            });
+            allEvents.push({
+              contractAddress: log.address || "",
+              eventName: decoded.eventName,
+              args: decoded.args,
+              logIndex: log.logIndex ?? 0
+            });
+            if (registry && registry.eventNames.includes(decoded.eventName)) {
+              expectedEvents[decoded.eventName] = decoded.args;
+              hasExpectedEvents = true;
+            }
+            break;
+          } catch {
+            continue;
+          }
+        }
+      } else {
+        allEvents.push({
+          contractAddress: log.address || "",
+          eventName: "Unknown",
+          args: { topic0: eventTopic, data: log.data },
+          logIndex: log.logIndex ?? 0
+        });
+      }
+    }
+  }
+  return {
+    hash: transactionResult.hash,
+    from: transactionResult.from,
+    contract: contractName,
+    fn: functionName,
+    expectedEvents,
+    allEvents,
+    hasExpectedEvents
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseTransaction
+});
+//# sourceMappingURL=parseTransactionPojo.cjs.map

package/dist/utils/parseTransactionPojo.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/parseTransactionPojo.ts"],"sourcesContent":["/**\n * Transaction parsing with POJO support and NO heuristics.\n *\n * @remarks\n * This is the new POJO-based parser that works with TransactionResult objects.\n * Principle: Explicit over implicit, guarantees over guesses.\n */\n\nimport { decodeEventLog, type TransactionReceipt } from \"viem\";\nimport type { TransactionResult } from \"../types/operations\";\nimport type {\n  TypedTransactionResult,\n  Contract,\n  Fn,\n  ExpectedEvents,\n} from \"../generated/event-types\";\nimport { EVENT_REGISTRY, TOPIC_TO_ABIS } from \"../generated/eventRegistry\";\n\n/**\n * Parses a transaction using TransactionResult POJO with ZERO heuristics.\n *\n * @remarks\n * - Uses function-scoped event registry for O(1) lookups\n * - Only expects events explicitly mapped for this contract.function\n * - Returns typed events matching the exact TypedTransactionResult interface\n *\n * @param transactionResult - The TransactionResult POJO with context\n * @param transactionResult.hash - Transaction hash\n * @param transactionResult.from - Transaction sender address\n * @param transactionResult.contract - Contract name\n * @param transactionResult.fn - Function name\n * @param transactionResult.chainId - Optional chain ID\n * @param transactionResult.value - Optional transaction value\n * @param transactionResult.nonce - Optional nonce\n * @param transactionResult.to - Optional recipient address\n * @param receipt - The transaction receipt from the blockchain\n * @returns Typed transaction result with parsed events\n */\nexport function parseTransaction<C extends Contract, F extends Fn<C>>(\n  transactionResult: TransactionResult<C, F>,\n  receipt: TransactionReceipt,\n): TypedTransactionResult<C, F> {\n  const { contract: contractName, fn: functionName } = transactionResult;\n\n  // Look up expected events from the function-specific registry\n  const registryKey = `${contractName}.${functionName}`;\n  const registry = EVENT_REGISTRY[registryKey];\n\n  // Initialize the expected events object with proper types\n  const expectedEvents: Record<string, unknown> = {};\n  const allEvents: Array<{\n    contractAddress: string;\n    eventName: string;\n    args: Record<string, unknown>;\n    logIndex: number;\n  }> = [];\n\n  let hasExpectedEvents = false;\n\n  if (receipt.logs) {\n    // Parse logs using the function-scoped registry\n    for (const log of receipt.logs) {\n      if (!log.topics || log.topics.length === 0) {\n        // Skip malformed logs\n        continue;\n      }\n\n      const eventTopic = log.topics[0] as `0x${string}`;\n\n      // Try to decode using TOPIC_TO_ABIS for O(1) lookup\n      const abiCandidates = TOPIC_TO_ABIS.get(eventTopic);\n\n      if (abiCandidates && abiCandidates.length > 0) {\n        // Try each ABI variant (handles collisions)\n        for (const abiEvent of abiCandidates) {\n          try {\n            const decoded = decodeEventLog({\n              abi: [abiEvent],\n              data: log.data,\n              topics: log.topics as [`0x${string}`, ...`0x${string}`[]],\n            });\n\n            // Add to allEvents\n            allEvents.push({\n              contractAddress: log.address || \"\",\n              eventName: decoded.eventName,\n              args: decoded.args as Record<string, unknown>,\n              logIndex: log.logIndex ?? 0,\n            });\n\n            // If this event is expected for this function, add to expectedEvents\n            if (registry && registry.eventNames.includes(decoded.eventName)) {\n              expectedEvents[decoded.eventName] = decoded.args;\n              hasExpectedEvents = true;\n            }\n\n            break; // Successfully decoded, don't try other variants\n          } catch {\n            // Try next ABI variant\n            continue;\n          }\n        }\n      } else {\n        // Event not decodable, add as unknown\n        allEvents.push({\n          contractAddress: log.address || \"\",\n          eventName: \"Unknown\",\n          args: { topic0: eventTopic, data: log.data },\n          logIndex: log.logIndex ?? 0,\n        });\n      }\n    }\n  }\n\n  // Return a properly typed TypedTransactionResult\n  return {\n    hash: transactionResult.hash,\n    from: transactionResult.from,\n    contract: contractName,\n    fn: functionName,\n    expectedEvents: expectedEvents as ExpectedEvents<C, F>,\n    allEvents,\n    hasExpectedEvents,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,kBAAwD;AAQxD,2BAA8C;AAsBvC,SAAS,iBACd,mBACA,SAC8B;AAC9B,QAAM,EAAE,UAAU,cAAc,IAAI,aAAa,IAAI;AAGrD,QAAM,cAAc,GAAG,YAAY,IAAI,YAAY;AACnD,QAAM,WAAW,oCAAe,WAAW;AAG3C,QAAM,iBAA0C,CAAC;AACjD,QAAM,YAKD,CAAC;AAEN,MAAI,oBAAoB;AAExB,MAAI,QAAQ,MAAM;AAEhB,eAAW,OAAO,QAAQ,MAAM;AAC9B,UAAI,CAAC,IAAI,UAAU,IAAI,OAAO,WAAW,GAAG;AAE1C;AAAA,MACF;AAEA,YAAM,aAAa,IAAI,OAAO,CAAC;AAG/B,YAAM,gBAAgB,mCAAc,IAAI,UAAU;AAElD,UAAI,iBAAiB,cAAc,SAAS,GAAG;AAE7C,mBAAW,YAAY,eAAe;AACpC,cAAI;AACF,kBAAM,cAAU,4BAAe;AAAA,cAC7B,KAAK,CAAC,QAAQ;AAAA,cACd,MAAM,IAAI;AAAA,cACV,QAAQ,IAAI;AAAA,YACd,CAAC;AAGD,sBAAU,KAAK;AAAA,cACb,iBAAiB,IAAI,WAAW;AAAA,cAChC,WAAW,QAAQ;AAAA,cACnB,MAAM,QAAQ;AAAA,cACd,UAAU,IAAI,YAAY;AAAA,YAC5B,CAAC;AAGD,gBAAI,YAAY,SAAS,WAAW,SAAS,QAAQ,SAAS,GAAG;AAC/D,6BAAe,QAAQ,SAAS,IAAI,QAAQ;AAC5C,kCAAoB;AAAA,YACtB;AAEA;AAAA,UACF,QAAQ;AAEN;AAAA,UACF;AAAA,QACF;AAAA,MACF,OAAO;AAEL,kBAAU,KAAK;AAAA,UACb,iBAAiB,IAAI,WAAW;AAAA,UAChC,WAAW;AAAA,UACX,MAAM,EAAE,QAAQ,YAAY,MAAM,IAAI,KAAK;AAAA,UAC3C,UAAU,IAAI,YAAY;AAAA,QAC5B,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAGA,SAAO;AAAA,IACL,MAAM,kBAAkB;AAAA,IACxB,MAAM,kBAAkB;AAAA,IACxB,UAAU;AAAA,IACV,IAAI;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}

package/dist/utils/parseTransactionPojo.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Transaction parsing with POJO support and NO heuristics.
+ *
+ * @remarks
+ * This is the new POJO-based parser that works with TransactionResult objects.
+ * Principle: Explicit over implicit, guarantees over guesses.
+ */
+import { type TransactionReceipt } from "viem";
+import type { TransactionResult } from "../types/operations";
+import type { TypedTransactionResult, Contract, Fn } from "../generated/event-types";
+/**
+ * Parses a transaction using TransactionResult POJO with ZERO heuristics.
+ *
+ * @remarks
+ * - Uses function-scoped event registry for O(1) lookups
+ * - Only expects events explicitly mapped for this contract.function
+ * - Returns typed events matching the exact TypedTransactionResult interface
+ *
+ * @param transactionResult - The TransactionResult POJO with context
+ * @param transactionResult.hash - Transaction hash
+ * @param transactionResult.from - Transaction sender address
+ * @param transactionResult.contract - Contract name
+ * @param transactionResult.fn - Function name
+ * @param transactionResult.chainId - Optional chain ID
+ * @param transactionResult.value - Optional transaction value
+ * @param transactionResult.nonce - Optional nonce
+ * @param transactionResult.to - Optional recipient address
+ * @param receipt - The transaction receipt from the blockchain
+ * @returns Typed transaction result with parsed events
+ */
+export declare function parseTransaction<C extends Contract, F extends Fn<C>>(transactionResult: TransactionResult<C, F>, receipt: TransactionReceipt): TypedTransactionResult<C, F>;

package/dist/utils/parseTransactionPojo.js

@@ -0,0 +1,63 @@
+import { decodeEventLog } from "viem";
+import { EVENT_REGISTRY, TOPIC_TO_ABIS } from "../generated/eventRegistry";
+function parseTransaction(transactionResult, receipt) {
+  const { contract: contractName, fn: functionName } = transactionResult;
+  const registryKey = `${contractName}.${functionName}`;
+  const registry = EVENT_REGISTRY[registryKey];
+  const expectedEvents = {};
+  const allEvents = [];
+  let hasExpectedEvents = false;
+  if (receipt.logs) {
+    for (const log of receipt.logs) {
+      if (!log.topics || log.topics.length === 0) {
+        continue;
+      }
+      const eventTopic = log.topics[0];
+      const abiCandidates = TOPIC_TO_ABIS.get(eventTopic);
+      if (abiCandidates && abiCandidates.length > 0) {
+        for (const abiEvent of abiCandidates) {
+          try {
+            const decoded = decodeEventLog({
+              abi: [abiEvent],
+              data: log.data,
+              topics: log.topics
+            });
+            allEvents.push({
+              contractAddress: log.address || "",
+              eventName: decoded.eventName,
+              args: decoded.args,
+              logIndex: log.logIndex ?? 0
+            });
+            if (registry && registry.eventNames.includes(decoded.eventName)) {
+              expectedEvents[decoded.eventName] = decoded.args;
+              hasExpectedEvents = true;
+            }
+            break;
+          } catch {
+            continue;
+          }
+        }
+      } else {
+        allEvents.push({
+          contractAddress: log.address || "",
+          eventName: "Unknown",
+          args: { topic0: eventTopic, data: log.data },
+          logIndex: log.logIndex ?? 0
+        });
+      }
+    }
+  }
+  return {
+    hash: transactionResult.hash,
+    from: transactionResult.from,
+    contract: contractName,
+    fn: functionName,
+    expectedEvents,
+    allEvents,
+    hasExpectedEvents
+  };
+}
+export {
+  parseTransaction
+};
+//# sourceMappingURL=parseTransactionPojo.js.map

package/dist/utils/parseTransactionPojo.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/parseTransactionPojo.ts"],"sourcesContent":["/**\n * Transaction parsing with POJO support and NO heuristics.\n *\n * @remarks\n * This is the new POJO-based parser that works with TransactionResult objects.\n * Principle: Explicit over implicit, guarantees over guesses.\n */\n\nimport { decodeEventLog, type TransactionReceipt } from \"viem\";\nimport type { TransactionResult } from \"../types/operations\";\nimport type {\n  TypedTransactionResult,\n  Contract,\n  Fn,\n  ExpectedEvents,\n} from \"../generated/event-types\";\nimport { EVENT_REGISTRY, TOPIC_TO_ABIS } from \"../generated/eventRegistry\";\n\n/**\n * Parses a transaction using TransactionResult POJO with ZERO heuristics.\n *\n * @remarks\n * - Uses function-scoped event registry for O(1) lookups\n * - Only expects events explicitly mapped for this contract.function\n * - Returns typed events matching the exact TypedTransactionResult interface\n *\n * @param transactionResult - The TransactionResult POJO with context\n * @param transactionResult.hash - Transaction hash\n * @param transactionResult.from - Transaction sender address\n * @param transactionResult.contract - Contract name\n * @param transactionResult.fn - Function name\n * @param transactionResult.chainId - Optional chain ID\n * @param transactionResult.value - Optional transaction value\n * @param transactionResult.nonce - Optional nonce\n * @param transactionResult.to - Optional recipient address\n * @param receipt - The transaction receipt from the blockchain\n * @returns Typed transaction result with parsed events\n */\nexport function parseTransaction<C extends Contract, F extends Fn<C>>(\n  transactionResult: TransactionResult<C, F>,\n  receipt: TransactionReceipt,\n): TypedTransactionResult<C, F> {\n  const { contract: contractName, fn: functionName } = transactionResult;\n\n  // Look up expected events from the function-specific registry\n  const registryKey = `${contractName}.${functionName}`;\n  const registry = EVENT_REGISTRY[registryKey];\n\n  // Initialize the expected events object with proper types\n  const expectedEvents: Record<string, unknown> = {};\n  const allEvents: Array<{\n    contractAddress: string;\n    eventName: string;\n    args: Record<string, unknown>;\n    logIndex: number;\n  }> = [];\n\n  let hasExpectedEvents = false;\n\n  if (receipt.logs) {\n    // Parse logs using the function-scoped registry\n    for (const log of receipt.logs) {\n      if (!log.topics || log.topics.length === 0) {\n        // Skip malformed logs\n        continue;\n      }\n\n      const eventTopic = log.topics[0] as `0x${string}`;\n\n      // Try to decode using TOPIC_TO_ABIS for O(1) lookup\n      const abiCandidates = TOPIC_TO_ABIS.get(eventTopic);\n\n      if (abiCandidates && abiCandidates.length > 0) {\n        // Try each ABI variant (handles collisions)\n        for (const abiEvent of abiCandidates) {\n          try {\n            const decoded = decodeEventLog({\n              abi: [abiEvent],\n              data: log.data,\n              topics: log.topics as [`0x${string}`, ...`0x${string}`[]],\n            });\n\n            // Add to allEvents\n            allEvents.push({\n              contractAddress: log.address || \"\",\n              eventName: decoded.eventName,\n              args: decoded.args as Record<string, unknown>,\n              logIndex: log.logIndex ?? 0,\n            });\n\n            // If this event is expected for this function, add to expectedEvents\n            if (registry && registry.eventNames.includes(decoded.eventName)) {\n              expectedEvents[decoded.eventName] = decoded.args;\n              hasExpectedEvents = true;\n            }\n\n            break; // Successfully decoded, don't try other variants\n          } catch {\n            // Try next ABI variant\n            continue;\n          }\n        }\n      } else {\n        // Event not decodable, add as unknown\n        allEvents.push({\n          contractAddress: log.address || \"\",\n          eventName: \"Unknown\",\n          args: { topic0: eventTopic, data: log.data },\n          logIndex: log.logIndex ?? 0,\n        });\n      }\n    }\n  }\n\n  // Return a properly typed TypedTransactionResult\n  return {\n    hash: transactionResult.hash,\n    from: transactionResult.from,\n    contract: contractName,\n    fn: functionName,\n    expectedEvents: expectedEvents as ExpectedEvents<C, F>,\n    allEvents,\n    hasExpectedEvents,\n  };\n}\n"],"mappings":"AAQA,SAAS,sBAA+C;AAQxD,SAAS,gBAAgB,qBAAqB;AAsBvC,SAAS,iBACd,mBACA,SAC8B;AAC9B,QAAM,EAAE,UAAU,cAAc,IAAI,aAAa,IAAI;AAGrD,QAAM,cAAc,GAAG,YAAY,IAAI,YAAY;AACnD,QAAM,WAAW,eAAe,WAAW;AAG3C,QAAM,iBAA0C,CAAC;AACjD,QAAM,YAKD,CAAC;AAEN,MAAI,oBAAoB;AAExB,MAAI,QAAQ,MAAM;AAEhB,eAAW,OAAO,QAAQ,MAAM;AAC9B,UAAI,CAAC,IAAI,UAAU,IAAI,OAAO,WAAW,GAAG;AAE1C;AAAA,MACF;AAEA,YAAM,aAAa,IAAI,OAAO,CAAC;AAG/B,YAAM,gBAAgB,cAAc,IAAI,UAAU;AAElD,UAAI,iBAAiB,cAAc,SAAS,GAAG;AAE7C,mBAAW,YAAY,eAAe;AACpC,cAAI;AACF,kBAAM,UAAU,eAAe;AAAA,cAC7B,KAAK,CAAC,QAAQ;AAAA,cACd,MAAM,IAAI;AAAA,cACV,QAAQ,IAAI;AAAA,YACd,CAAC;AAGD,sBAAU,KAAK;AAAA,cACb,iBAAiB,IAAI,WAAW;AAAA,cAChC,WAAW,QAAQ;AAAA,cACnB,MAAM,QAAQ;AAAA,cACd,UAAU,IAAI,YAAY;AAAA,YAC5B,CAAC;AAGD,gBAAI,YAAY,SAAS,WAAW,SAAS,QAAQ,SAAS,GAAG;AAC/D,6BAAe,QAAQ,SAAS,IAAI,QAAQ;AAC5C,kCAAoB;AAAA,YACtB;AAEA;AAAA,UACF,QAAQ;AAEN;AAAA,UACF;AAAA,QACF;AAAA,MACF,OAAO;AAEL,kBAAU,KAAK;AAAA,UACb,iBAAiB,IAAI,WAAW;AAAA,UAChC,WAAW;AAAA,UACX,MAAM,EAAE,QAAQ,YAAY,MAAM,IAAI,KAAK;AAAA,UAC3C,UAAU,IAAI,YAAY;AAAA,QAC5B,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAGA,SAAO;AAAA,IACL,MAAM,kBAAkB;AAAA,IACxB,MAAM,kBAAkB;AAAA,IACxB,UAAU;AAAA,IACV,IAAI;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}

package/dist/utils/schemaValidation.cjs

@@ -86,7 +86,7 @@ class SchemaValidator {
   validateDataSchemaAgainstMetaSchema(schema) {
     const isValid = this.dataSchemaValidator(schema);
     if (!isValid) {
-      const errors = this.dataSchemaValidator.errors || [];
+      const errors = this.dataSchemaValidator.errors ?? [];
       const errorMessage = `Data schema validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(", ")}`;
       throw new SchemaValidationError(errorMessage, errors);
     }
@@ -142,7 +142,7 @@ class SchemaValidator {
     const dataValidator = this.ajv.compile(schema.schema);
     const isValid = dataValidator(data);
     if (!isValid) {
-      const errors = dataValidator.errors || [];
+      const errors = dataValidator.errors ?? [];
       const errorMessage = `Data validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(", ")}`;
       throw new SchemaValidationError(errorMessage, errors);
     }
@@ -212,8 +212,8 @@ class SchemaValidator {
    */
   async fetchAndValidateSchema(url, downloadRelayer) {
     try {
-      const { fetchWithRelayer } = await import("./download");
-      const response = await fetchWithRelayer(url, downloadRelayer);
+      const { universalFetch } = await import("./download");
+      const response = await universalFetch(url, downloadRelayer);
       if (!response.ok) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
       }
@@ -241,7 +241,7 @@ function validateDataSchemaAgainstMetaSchema(schema) {
   return schema;
 }
 function validateDataAgainstSchema(data, schema) {
-  return schemaValidator.validateDataAgainstSchema(data, schema);
+  schemaValidator.validateDataAgainstSchema(data, schema);
 }
 function fetchAndValidateSchema(url, downloadRelayer) {
   return schemaValidator.fetchAndValidateSchema(url, downloadRelayer);