@opendatalabs/vana-sdk 0.1.0-alpha.7ee7635 → 0.1.0-alpha.8117ac2

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.map

@@ -1 +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 { TypedTransactionResult, Contract, Fn, ExpectedEvents } 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 as keyof typeof EVENT_REGISTRY];\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 as C,\n    fn: functionName as F,\n    expectedEvents: expectedEvents as ExpectedEvents<C, F>,\n    allEvents,\n    hasExpectedEvents,\n  };\n}"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,kBAAwD;AAGxD,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,WAA0C;AAG1E,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":[]}
+{"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

@@ -1,9 +1,3 @@
-import { TransactionReceipt } from 'viem';
-import { TransactionResult } from '../types/operations.js';
-import { Contract, Fn, TypedTransactionResult } from '../generated/event-types.js';
-import '../generated/server/server-exports.js';
-import '../generated/server/server.js';
-
 /**
  * Transaction parsing with POJO support and NO heuristics.
  *
@@ -11,7 +5,9 @@ import '../generated/server/server.js';
  * 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.
  *
@@ -32,6 +28,4 @@ import '../generated/server/server.js';
  * @param receipt - The transaction receipt from the blockchain
  * @returns Typed transaction result with parsed events
  */
-declare function parseTransaction<C extends Contract, F extends Fn<C>>(transactionResult: TransactionResult<C, F>, receipt: TransactionReceipt): TypedTransactionResult<C, F>;
-
-export { parseTransaction };
+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.map

@@ -1 +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 { TypedTransactionResult, Contract, Fn, ExpectedEvents } 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 as keyof typeof EVENT_REGISTRY];\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 as C,\n    fn: functionName as F,\n    expectedEvents: expectedEvents as ExpectedEvents<C, F>,\n    allEvents,\n    hasExpectedEvents,\n  };\n}"],"mappings":"AAQA,SAAS,sBAA+C;AAGxD,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,WAA0C;AAG1E,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":[]}
+{"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);

package/dist/utils/schemaValidation.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/schemaValidation.ts"],"sourcesContent":["import Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport dataSchemaSchema from \"../schemas/dataSchema.schema.json\";\nimport type { Schema } from \"../types/data\";\n\n/**\n * Data schema interface following the Vana schema specification\n *\n * @category Configuration\n */\nexport interface DataSchema {\n  /** The name of the data schema */\n  name: string;\n  /** The version of the data schema */\n  version: string;\n  /** Optional description of the data schema */\n  description?: string;\n  /** The dialect type - either SQLite or JSON */\n  dialect: \"sqlite\" | \"json\";\n  /** Optional version of the dialect */\n  dialectVersion?: string;\n  /** The actual schema definition as string or object */\n  schema: string | object;\n}\n\n/**\n * Error thrown when schema validation fails\n */\nexport class SchemaValidationError extends Error {\n  constructor(\n    message: string,\n    public errors: Array<{\n      instancePath: string;\n      schemaPath: string;\n      keyword: string;\n      params: Record<string, unknown>;\n      message?: string;\n    }>,\n  ) {\n    super(message);\n    this.name = \"SchemaValidationError\";\n  }\n}\n\n/**\n * Data schema validation utility class\n */\nexport class SchemaValidator {\n  private ajv: Ajv;\n  private dataSchemaValidator: ValidateFunction;\n\n  constructor() {\n    this.ajv = new Ajv({\n      allErrors: true,\n      verbose: true,\n      strict: false,\n    });\n\n    // Add format validation (e.g., date, email, uri)\n    addFormats(this.ajv);\n\n    // Compile the data schema meta-schema validator\n    this.dataSchemaValidator = this.ajv.compile(dataSchemaSchema);\n  }\n\n  /**\n   * Validates a data schema definition against the Vana meta-schema\n   *\n   * @param schema - The data schema definition to validate\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * const schema = {\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: {\n   *     type: \"object\",\n   *     properties: {\n   *       name: { type: \"string\" },\n   *       age: { type: \"number\" }\n   *     }\n   *   }\n   * };\n   *\n   * validator.validateDataSchemaAgainstMetaSchema(schema); // throws if invalid\n   * ```\n   */\n  validateDataSchemaAgainstMetaSchema(\n    schema: unknown,\n  ): asserts schema is DataSchema {\n    const isValid = this.dataSchemaValidator(schema);\n\n    if (!isValid) {\n      const errors = this.dataSchemaValidator.errors || [];\n      const errorMessage = `Data schema validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n\n    // Additional validation based on dialect\n    const typedSchema = schema as DataSchema;\n    if (\n      typedSchema.dialect === \"json\" &&\n      typeof typedSchema.schema === \"object\"\n    ) {\n      // Validate that the embedded JSON Schema is actually valid\n      try {\n        this.ajv.compile(typedSchema.schema);\n      } catch (error) {\n        const errorMessage = `Invalid JSON Schema in data schema: ${error instanceof Error ? error.message : \"Unknown schema compilation error\"}`;\n        throw new SchemaValidationError(errorMessage, []);\n      }\n    } else if (\n      typedSchema.dialect === \"sqlite\" &&\n      typeof typedSchema.schema === \"string\"\n    ) {\n      // Validate SQLite DDL syntax\n      this.validateSQLiteDDL(typedSchema.schema, typedSchema.dialectVersion);\n    }\n  }\n\n  /**\n   * Validates data against a JSON Schema\n   *\n   * @param data - The data to validate\n   * @param schema - The schema containing the validation rules (must have been validated or fetched from chain)\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * // Works with Schema from schemas.get()\n   * const schema = await vana.schemas.get(1);\n   * validator.validateDataAgainstSchema(userData, schema);\n   *\n   * // Also works with pre-validated DataSchema object\n   * const dataSchema = validator.validateDataSchemaAgainstMetaSchema({\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n   * });\n   * validator.validateDataAgainstSchema(userData, dataSchema);\n   * ```\n   */\n  validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void {\n    if (schema.dialect !== \"json\") {\n      console.warn(\n        `[SchemaValidator] Data validation skipped: dialect '${schema.dialect}' does not support data validation. ` +\n          `Only JSON schemas can validate data structure.`,\n      );\n      return;\n    }\n\n    if (typeof schema.schema !== \"object\") {\n      throw new SchemaValidationError(\n        \"JSON dialect schemas must have an object schema\",\n        [],\n      );\n    }\n\n    // Compile and validate against the data schema\n    const dataValidator = this.ajv.compile(schema.schema);\n    const isValid = dataValidator(data);\n\n    if (!isValid) {\n      const errors = dataValidator.errors || [];\n      const errorMessage = `Data validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n  }\n\n  /**\n   * Validates a SQLite DDL string for basic syntax\n   * Note: This is a basic validation, full SQL parsing would require a proper SQL parser\n   *\n   * @param ddl - The DDL string to validate\n   * @param dialectVersion - Optional SQLite version (e.g., \"3\" for SQLite v3)\n   * @throws SchemaValidationError if invalid\n   */\n  validateSQLiteDDL(ddl: string, dialectVersion?: string): void {\n    if (typeof ddl !== \"string\" || ddl.trim().length === 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must be a non-empty string\",\n        [],\n      );\n    }\n\n    // Validate dialectVersion if provided\n    if (dialectVersion !== undefined) {\n      const supportedVersions = [\"3\"];\n      if (!supportedVersions.includes(dialectVersion)) {\n        throw new SchemaValidationError(\n          `Unsupported SQLite dialect version: ${dialectVersion}. Supported versions: ${supportedVersions.join(\", \")}`,\n          [],\n        );\n      }\n    }\n\n    // Basic validation - check for CREATE TABLE statements\n    const normalizedDDL = ddl.trim().toUpperCase();\n    if (!normalizedDDL.includes(\"CREATE TABLE\")) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must contain at least one CREATE TABLE statement\",\n        [],\n      );\n    }\n\n    // Check for balanced parentheses\n    let parenCount = 0;\n    for (const char of ddl) {\n      if (char === \"(\") parenCount++;\n      if (char === \")\") parenCount--;\n      if (parenCount < 0) {\n        throw new SchemaValidationError(\n          \"SQLite DDL has unbalanced parentheses\",\n          [],\n        );\n      }\n    }\n\n    if (parenCount !== 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL has unbalanced parentheses\",\n        [],\n      );\n    }\n  }\n\n  /**\n   * Fetches and validates a data schema from a URL\n   *\n   * @param url - The URL to fetch the data schema from\n   * @param downloadRelayer - Optional download relayer for CORS bypass\n   * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n   * @returns The validated data schema\n   * @throws SchemaValidationError if invalid or fetch fails\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   * const schema = await validator.fetchAndValidateSchema(\"https://example.com/schema.json\");\n   * ```\n   */\n  async fetchAndValidateSchema(\n    url: string,\n    downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n  ): Promise<DataSchema> {\n    try {\n      const { fetchWithRelayer } = await import(\"./download\");\n      const response = await fetchWithRelayer(url, downloadRelayer);\n      if (!response.ok) {\n        throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n      }\n\n      const schema = await response.json();\n      this.validateDataSchemaAgainstMetaSchema(schema);\n\n      // Additional validation based on dialect\n      if (schema.dialect === \"sqlite\" && typeof schema.schema === \"string\") {\n        this.validateSQLiteDDL(schema.schema, schema.dialectVersion);\n      }\n\n      return schema;\n    } catch (error) {\n      if (error instanceof SchemaValidationError) {\n        throw error;\n      }\n\n      throw new SchemaValidationError(\n        `Failed to fetch and validate schema from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        [],\n      );\n    }\n  }\n}\n\n/**\n * Global schema validator instance\n */\nexport const schemaValidator = new SchemaValidator();\n\n/**\n * Convenience function to validate a data schema definition against the Vana meta-schema\n *\n * @param schema - The data schema definition to validate\n * @returns The validated DataSchema\n * @throws SchemaValidationError if invalid\n * @example\n * ```typescript\n * const schemaDefinition = {\n *   name: \"User Profile\",\n *   version: \"1.0.0\",\n *   dialect: \"json\",\n *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n * };\n *\n * const validatedSchema = validateDataSchemaAgainstMetaSchema(schemaDefinition);\n * ```\n */\nexport function validateDataSchemaAgainstMetaSchema(\n  schema: unknown,\n): DataSchema {\n  const validator: SchemaValidator = schemaValidator;\n  validator.validateDataSchemaAgainstMetaSchema(schema);\n  // If we get here, schema is valid and typed as DataSchema\n  return schema as DataSchema;\n}\n\n/**\n * Convenience function to validate data against a schema\n *\n * @param data - The data to validate\n * @param schema - The data schema containing the schema\n * @returns void - Function doesn't return a value\n * @throws SchemaValidationError if invalid\n */\nexport function validateDataAgainstSchema(\n  data: unknown,\n  schema: DataSchema | Schema,\n): void {\n  return schemaValidator.validateDataAgainstSchema(data, schema);\n}\n\n/**\n * Convenience function to fetch and validate a data schema from a URL\n *\n * @param url - The URL to fetch the data schema from\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns The validated data schema\n * @throws SchemaValidationError if invalid or fetch fails\n */\nexport function fetchAndValidateSchema(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<DataSchema> {\n  return schemaValidator.fetchAndValidateSchema(url, downloadRelayer);\n}\n"],"mappings":"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","names":["Ajv","addFormats","dataSchemaSchema"]}
+{"version":3,"sources":["../../src/utils/schemaValidation.ts"],"sourcesContent":["import Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport dataSchemaSchema from \"../schemas/dataSchema.schema.json\";\nimport type { Schema } from \"../types/data\";\n\n/**\n * Data schema interface following the Vana schema specification\n *\n * @category Configuration\n */\nexport interface DataSchema {\n  /** The name of the data schema */\n  name: string;\n  /** The version of the data schema */\n  version: string;\n  /** Optional description of the data schema */\n  description?: string;\n  /** The dialect type - either SQLite or JSON */\n  dialect: \"sqlite\" | \"json\";\n  /** Optional version of the dialect */\n  dialectVersion?: string;\n  /** The actual schema definition as string or object */\n  schema: string | object;\n}\n\n/**\n * Error thrown when schema validation fails\n */\nexport class SchemaValidationError extends Error {\n  constructor(\n    message: string,\n    public errors: Array<{\n      instancePath: string;\n      schemaPath: string;\n      keyword: string;\n      params: Record<string, unknown>;\n      message?: string;\n    }>,\n  ) {\n    super(message);\n    this.name = \"SchemaValidationError\";\n  }\n}\n\n/**\n * Data schema validation utility class\n */\nexport class SchemaValidator {\n  private ajv: Ajv;\n  private dataSchemaValidator: ValidateFunction;\n\n  constructor() {\n    this.ajv = new Ajv({\n      allErrors: true,\n      verbose: true,\n      strict: false,\n    });\n\n    // Add format validation (e.g., date, email, uri)\n    addFormats(this.ajv);\n\n    // Compile the data schema meta-schema validator\n    this.dataSchemaValidator = this.ajv.compile(dataSchemaSchema);\n  }\n\n  /**\n   * Validates a data schema definition against the Vana meta-schema\n   *\n   * @param schema - The data schema definition to validate\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * const schema = {\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: {\n   *     type: \"object\",\n   *     properties: {\n   *       name: { type: \"string\" },\n   *       age: { type: \"number\" }\n   *     }\n   *   }\n   * };\n   *\n   * validator.validateDataSchemaAgainstMetaSchema(schema); // throws if invalid\n   * ```\n   */\n  validateDataSchemaAgainstMetaSchema(\n    schema: unknown,\n  ): asserts schema is DataSchema {\n    const isValid = this.dataSchemaValidator(schema);\n\n    if (!isValid) {\n      const errors = this.dataSchemaValidator.errors ?? [];\n      const errorMessage = `Data schema validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n\n    // Additional validation based on dialect\n    const typedSchema = schema as DataSchema;\n    if (\n      typedSchema.dialect === \"json\" &&\n      typeof typedSchema.schema === \"object\"\n    ) {\n      // Validate that the embedded JSON Schema is actually valid\n      try {\n        this.ajv.compile(typedSchema.schema);\n      } catch (error) {\n        const errorMessage = `Invalid JSON Schema in data schema: ${error instanceof Error ? error.message : \"Unknown schema compilation error\"}`;\n        throw new SchemaValidationError(errorMessage, []);\n      }\n    } else if (\n      typedSchema.dialect === \"sqlite\" &&\n      typeof typedSchema.schema === \"string\"\n    ) {\n      // Validate SQLite DDL syntax\n      this.validateSQLiteDDL(typedSchema.schema, typedSchema.dialectVersion);\n    }\n  }\n\n  /**\n   * Validates data against a JSON Schema\n   *\n   * @param data - The data to validate\n   * @param schema - The schema containing the validation rules (must have been validated or fetched from chain)\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * // Works with Schema from schemas.get()\n   * const schema = await vana.schemas.get(1);\n   * validator.validateDataAgainstSchema(userData, schema);\n   *\n   * // Also works with pre-validated DataSchema object\n   * const dataSchema = validator.validateDataSchemaAgainstMetaSchema({\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n   * });\n   * validator.validateDataAgainstSchema(userData, dataSchema);\n   * ```\n   */\n  validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void {\n    if (schema.dialect !== \"json\") {\n      console.warn(\n        `[SchemaValidator] Data validation skipped: dialect '${schema.dialect}' does not support data validation. ` +\n          `Only JSON schemas can validate data structure.`,\n      );\n      return;\n    }\n\n    if (typeof schema.schema !== \"object\") {\n      throw new SchemaValidationError(\n        \"JSON dialect schemas must have an object schema\",\n        [],\n      );\n    }\n\n    // Compile and validate against the data schema\n    const dataValidator = this.ajv.compile(schema.schema);\n    const isValid = dataValidator(data);\n\n    if (!isValid) {\n      const errors = dataValidator.errors ?? [];\n      const errorMessage = `Data validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n  }\n\n  /**\n   * Validates a SQLite DDL string for basic syntax\n   * Note: This is a basic validation, full SQL parsing would require a proper SQL parser\n   *\n   * @param ddl - The DDL string to validate\n   * @param dialectVersion - Optional SQLite version (e.g., \"3\" for SQLite v3)\n   * @throws SchemaValidationError if invalid\n   */\n  validateSQLiteDDL(ddl: string, dialectVersion?: string): void {\n    if (typeof ddl !== \"string\" || ddl.trim().length === 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must be a non-empty string\",\n        [],\n      );\n    }\n\n    // Validate dialectVersion if provided\n    if (dialectVersion !== undefined) {\n      const supportedVersions = [\"3\"];\n      if (!supportedVersions.includes(dialectVersion)) {\n        throw new SchemaValidationError(\n          `Unsupported SQLite dialect version: ${dialectVersion}. Supported versions: ${supportedVersions.join(\", \")}`,\n          [],\n        );\n      }\n    }\n\n    // Basic validation - check for CREATE TABLE statements\n    const normalizedDDL = ddl.trim().toUpperCase();\n    if (!normalizedDDL.includes(\"CREATE TABLE\")) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must contain at least one CREATE TABLE statement\",\n        [],\n      );\n    }\n\n    // Check for balanced parentheses\n    let parenCount = 0;\n    for (const char of ddl) {\n      if (char === \"(\") parenCount++;\n      if (char === \")\") parenCount--;\n      if (parenCount < 0) {\n        throw new SchemaValidationError(\n          \"SQLite DDL has unbalanced parentheses\",\n          [],\n        );\n      }\n    }\n\n    if (parenCount !== 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL has unbalanced parentheses\",\n        [],\n      );\n    }\n  }\n\n  /**\n   * Fetches and validates a data schema from a URL\n   *\n   * @param url - The URL to fetch the data schema from\n   * @param downloadRelayer - Optional download relayer for CORS bypass\n   * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n   * @returns The validated data schema\n   * @throws SchemaValidationError if invalid or fetch fails\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   * const schema = await validator.fetchAndValidateSchema(\"https://example.com/schema.json\");\n   * ```\n   */\n  async fetchAndValidateSchema(\n    url: string,\n    downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n  ): Promise<DataSchema> {\n    try {\n      const { universalFetch } = await import(\"./download\");\n      const response = await universalFetch(url, downloadRelayer);\n      if (!response.ok) {\n        throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n      }\n\n      const schema = await response.json();\n      this.validateDataSchemaAgainstMetaSchema(schema);\n\n      // Additional validation based on dialect\n      if (schema.dialect === \"sqlite\" && typeof schema.schema === \"string\") {\n        this.validateSQLiteDDL(schema.schema, schema.dialectVersion);\n      }\n\n      return schema;\n    } catch (error) {\n      if (error instanceof SchemaValidationError) {\n        throw error;\n      }\n\n      throw new SchemaValidationError(\n        `Failed to fetch and validate schema from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        [],\n      );\n    }\n  }\n}\n\n/**\n * Global schema validator instance\n */\nexport const schemaValidator = new SchemaValidator();\n\n/**\n * Convenience function to validate a data schema definition against the Vana meta-schema\n *\n * @param schema - The data schema definition to validate\n * @returns The validated DataSchema\n * @throws SchemaValidationError if invalid\n * @example\n * ```typescript\n * const schemaDefinition = {\n *   name: \"User Profile\",\n *   version: \"1.0.0\",\n *   dialect: \"json\",\n *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n * };\n *\n * const validatedSchema = validateDataSchemaAgainstMetaSchema(schemaDefinition);\n * ```\n */\nexport function validateDataSchemaAgainstMetaSchema(\n  schema: unknown,\n): DataSchema {\n  const validator: SchemaValidator = schemaValidator;\n  validator.validateDataSchemaAgainstMetaSchema(schema);\n  // If we get here, schema is valid and typed as DataSchema\n  return schema;\n}\n\n/**\n * Convenience function to validate data against a schema\n *\n * @param data - The data to validate\n * @param schema - The data schema containing the schema\n * @returns void - Function doesn't return a value\n * @throws SchemaValidationError if invalid\n */\nexport function validateDataAgainstSchema(\n  data: unknown,\n  schema: DataSchema | Schema,\n): void {\n  schemaValidator.validateDataAgainstSchema(data, schema);\n}\n\n/**\n * Convenience function to fetch and validate a data schema from a URL\n *\n * @param url - The URL to fetch the data schema from\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns The validated data schema\n * @throws SchemaValidationError if invalid or fetch fails\n */\nexport function fetchAndValidateSchema(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<DataSchema> {\n  return schemaValidator.fetchAndValidateSchema(url, downloadRelayer);\n}\n"],"mappings":"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","names":["Ajv","addFormats","dataSchemaSchema"]}

package/dist/utils/schemaValidation.d.ts

@@ -1,12 +1,10 @@
-import { Schema } from '../types/data.js';
-import 'viem';
-
+import type { Schema } from "../types/data";
 /**
  * Data schema interface following the Vana schema specification
  *
  * @category Configuration
  */
-interface DataSchema {
+export interface DataSchema {
     /** The name of the data schema */
     name: string;
     /** The version of the data schema */
@@ -23,7 +21,7 @@ interface DataSchema {
 /**
  * Error thrown when schema validation fails
  */
-declare class SchemaValidationError extends Error {
+export declare class SchemaValidationError extends Error {
     errors: Array<{
         instancePath: string;
         schemaPath: string;
@@ -42,7 +40,7 @@ declare class SchemaValidationError extends Error {
 /**
  * Data schema validation utility class
  */
-declare class SchemaValidator {
+export declare class SchemaValidator {
     private ajv;
     private dataSchemaValidator;
     constructor();
@@ -127,7 +125,7 @@ declare class SchemaValidator {
 /**
  * Global schema validator instance
  */
-declare const schemaValidator: SchemaValidator;
+export declare const schemaValidator: SchemaValidator;
 /**
  * Convenience function to validate a data schema definition against the Vana meta-schema
  *
@@ -146,7 +144,7 @@ declare const schemaValidator: SchemaValidator;
  * const validatedSchema = validateDataSchemaAgainstMetaSchema(schemaDefinition);
  * ```
  */
-declare function validateDataSchemaAgainstMetaSchema(schema: unknown): DataSchema;
+export declare function validateDataSchemaAgainstMetaSchema(schema: unknown): DataSchema;
 /**
  * Convenience function to validate data against a schema
  *
@@ -155,7 +153,7 @@ declare function validateDataSchemaAgainstMetaSchema(schema: unknown): DataSchem
  * @returns void - Function doesn't return a value
  * @throws SchemaValidationError if invalid
  */
-declare function validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void;
+export declare function validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void;
 /**
  * Convenience function to fetch and validate a data schema from a URL
  *
@@ -165,8 +163,6 @@ declare function validateDataAgainstSchema(data: unknown, schema: DataSchema | S
  * @returns The validated data schema
  * @throws SchemaValidationError if invalid or fetch fails
  */
-declare function fetchAndValidateSchema(url: string, downloadRelayer?: {
+export declare function fetchAndValidateSchema(url: string, downloadRelayer?: {
     proxyDownload: (url: string) => Promise<Blob>;
 }): Promise<DataSchema>;
-
-export { type DataSchema, SchemaValidationError, SchemaValidator, fetchAndValidateSchema, schemaValidator, validateDataAgainstSchema, validateDataSchemaAgainstMetaSchema };

package/dist/utils/schemaValidation.js

@@ -1,6 +1,3 @@
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 import Ajv from "ajv";
 import addFormats from "ajv-formats";
 import dataSchemaSchema from "../schemas/dataSchema.schema.json";
@@ -12,9 +9,9 @@ class SchemaValidationError extends Error {
   }
 }
 class SchemaValidator {
+  ajv;
+  dataSchemaValidator;
   constructor() {
-    __publicField(this, "ajv");
-    __publicField(this, "dataSchemaValidator");
     this.ajv = new Ajv({
       allErrors: true,
       verbose: true,
@@ -51,7 +48,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);
     }
@@ -107,7 +104,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);
     }
@@ -177,8 +174,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}`);
       }
@@ -206,7 +203,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);

package/dist/utils/schemaValidation.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/schemaValidation.ts"],"sourcesContent":["import Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport dataSchemaSchema from \"../schemas/dataSchema.schema.json\";\nimport type { Schema } from \"../types/data\";\n\n/**\n * Data schema interface following the Vana schema specification\n *\n * @category Configuration\n */\nexport interface DataSchema {\n  /** The name of the data schema */\n  name: string;\n  /** The version of the data schema */\n  version: string;\n  /** Optional description of the data schema */\n  description?: string;\n  /** The dialect type - either SQLite or JSON */\n  dialect: \"sqlite\" | \"json\";\n  /** Optional version of the dialect */\n  dialectVersion?: string;\n  /** The actual schema definition as string or object */\n  schema: string | object;\n}\n\n/**\n * Error thrown when schema validation fails\n */\nexport class SchemaValidationError extends Error {\n  constructor(\n    message: string,\n    public errors: Array<{\n      instancePath: string;\n      schemaPath: string;\n      keyword: string;\n      params: Record<string, unknown>;\n      message?: string;\n    }>,\n  ) {\n    super(message);\n    this.name = \"SchemaValidationError\";\n  }\n}\n\n/**\n * Data schema validation utility class\n */\nexport class SchemaValidator {\n  private ajv: Ajv;\n  private dataSchemaValidator: ValidateFunction;\n\n  constructor() {\n    this.ajv = new Ajv({\n      allErrors: true,\n      verbose: true,\n      strict: false,\n    });\n\n    // Add format validation (e.g., date, email, uri)\n    addFormats(this.ajv);\n\n    // Compile the data schema meta-schema validator\n    this.dataSchemaValidator = this.ajv.compile(dataSchemaSchema);\n  }\n\n  /**\n   * Validates a data schema definition against the Vana meta-schema\n   *\n   * @param schema - The data schema definition to validate\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * const schema = {\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: {\n   *     type: \"object\",\n   *     properties: {\n   *       name: { type: \"string\" },\n   *       age: { type: \"number\" }\n   *     }\n   *   }\n   * };\n   *\n   * validator.validateDataSchemaAgainstMetaSchema(schema); // throws if invalid\n   * ```\n   */\n  validateDataSchemaAgainstMetaSchema(\n    schema: unknown,\n  ): asserts schema is DataSchema {\n    const isValid = this.dataSchemaValidator(schema);\n\n    if (!isValid) {\n      const errors = this.dataSchemaValidator.errors || [];\n      const errorMessage = `Data schema validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n\n    // Additional validation based on dialect\n    const typedSchema = schema as DataSchema;\n    if (\n      typedSchema.dialect === \"json\" &&\n      typeof typedSchema.schema === \"object\"\n    ) {\n      // Validate that the embedded JSON Schema is actually valid\n      try {\n        this.ajv.compile(typedSchema.schema);\n      } catch (error) {\n        const errorMessage = `Invalid JSON Schema in data schema: ${error instanceof Error ? error.message : \"Unknown schema compilation error\"}`;\n        throw new SchemaValidationError(errorMessage, []);\n      }\n    } else if (\n      typedSchema.dialect === \"sqlite\" &&\n      typeof typedSchema.schema === \"string\"\n    ) {\n      // Validate SQLite DDL syntax\n      this.validateSQLiteDDL(typedSchema.schema, typedSchema.dialectVersion);\n    }\n  }\n\n  /**\n   * Validates data against a JSON Schema\n   *\n   * @param data - The data to validate\n   * @param schema - The schema containing the validation rules (must have been validated or fetched from chain)\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * // Works with Schema from schemas.get()\n   * const schema = await vana.schemas.get(1);\n   * validator.validateDataAgainstSchema(userData, schema);\n   *\n   * // Also works with pre-validated DataSchema object\n   * const dataSchema = validator.validateDataSchemaAgainstMetaSchema({\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n   * });\n   * validator.validateDataAgainstSchema(userData, dataSchema);\n   * ```\n   */\n  validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void {\n    if (schema.dialect !== \"json\") {\n      console.warn(\n        `[SchemaValidator] Data validation skipped: dialect '${schema.dialect}' does not support data validation. ` +\n          `Only JSON schemas can validate data structure.`,\n      );\n      return;\n    }\n\n    if (typeof schema.schema !== \"object\") {\n      throw new SchemaValidationError(\n        \"JSON dialect schemas must have an object schema\",\n        [],\n      );\n    }\n\n    // Compile and validate against the data schema\n    const dataValidator = this.ajv.compile(schema.schema);\n    const isValid = dataValidator(data);\n\n    if (!isValid) {\n      const errors = dataValidator.errors || [];\n      const errorMessage = `Data validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n  }\n\n  /**\n   * Validates a SQLite DDL string for basic syntax\n   * Note: This is a basic validation, full SQL parsing would require a proper SQL parser\n   *\n   * @param ddl - The DDL string to validate\n   * @param dialectVersion - Optional SQLite version (e.g., \"3\" for SQLite v3)\n   * @throws SchemaValidationError if invalid\n   */\n  validateSQLiteDDL(ddl: string, dialectVersion?: string): void {\n    if (typeof ddl !== \"string\" || ddl.trim().length === 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must be a non-empty string\",\n        [],\n      );\n    }\n\n    // Validate dialectVersion if provided\n    if (dialectVersion !== undefined) {\n      const supportedVersions = [\"3\"];\n      if (!supportedVersions.includes(dialectVersion)) {\n        throw new SchemaValidationError(\n          `Unsupported SQLite dialect version: ${dialectVersion}. Supported versions: ${supportedVersions.join(\", \")}`,\n          [],\n        );\n      }\n    }\n\n    // Basic validation - check for CREATE TABLE statements\n    const normalizedDDL = ddl.trim().toUpperCase();\n    if (!normalizedDDL.includes(\"CREATE TABLE\")) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must contain at least one CREATE TABLE statement\",\n        [],\n      );\n    }\n\n    // Check for balanced parentheses\n    let parenCount = 0;\n    for (const char of ddl) {\n      if (char === \"(\") parenCount++;\n      if (char === \")\") parenCount--;\n      if (parenCount < 0) {\n        throw new SchemaValidationError(\n          \"SQLite DDL has unbalanced parentheses\",\n          [],\n        );\n      }\n    }\n\n    if (parenCount !== 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL has unbalanced parentheses\",\n        [],\n      );\n    }\n  }\n\n  /**\n   * Fetches and validates a data schema from a URL\n   *\n   * @param url - The URL to fetch the data schema from\n   * @param downloadRelayer - Optional download relayer for CORS bypass\n   * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n   * @returns The validated data schema\n   * @throws SchemaValidationError if invalid or fetch fails\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   * const schema = await validator.fetchAndValidateSchema(\"https://example.com/schema.json\");\n   * ```\n   */\n  async fetchAndValidateSchema(\n    url: string,\n    downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n  ): Promise<DataSchema> {\n    try {\n      const { fetchWithRelayer } = await import(\"./download\");\n      const response = await fetchWithRelayer(url, downloadRelayer);\n      if (!response.ok) {\n        throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n      }\n\n      const schema = await response.json();\n      this.validateDataSchemaAgainstMetaSchema(schema);\n\n      // Additional validation based on dialect\n      if (schema.dialect === \"sqlite\" && typeof schema.schema === \"string\") {\n        this.validateSQLiteDDL(schema.schema, schema.dialectVersion);\n      }\n\n      return schema;\n    } catch (error) {\n      if (error instanceof SchemaValidationError) {\n        throw error;\n      }\n\n      throw new SchemaValidationError(\n        `Failed to fetch and validate schema from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        [],\n      );\n    }\n  }\n}\n\n/**\n * Global schema validator instance\n */\nexport const schemaValidator = new SchemaValidator();\n\n/**\n * Convenience function to validate a data schema definition against the Vana meta-schema\n *\n * @param schema - The data schema definition to validate\n * @returns The validated DataSchema\n * @throws SchemaValidationError if invalid\n * @example\n * ```typescript\n * const schemaDefinition = {\n *   name: \"User Profile\",\n *   version: \"1.0.0\",\n *   dialect: \"json\",\n *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n * };\n *\n * const validatedSchema = validateDataSchemaAgainstMetaSchema(schemaDefinition);\n * ```\n */\nexport function validateDataSchemaAgainstMetaSchema(\n  schema: unknown,\n): DataSchema {\n  const validator: SchemaValidator = schemaValidator;\n  validator.validateDataSchemaAgainstMetaSchema(schema);\n  // If we get here, schema is valid and typed as DataSchema\n  return schema as DataSchema;\n}\n\n/**\n * Convenience function to validate data against a schema\n *\n * @param data - The data to validate\n * @param schema - The data schema containing the schema\n * @returns void - Function doesn't return a value\n * @throws SchemaValidationError if invalid\n */\nexport function validateDataAgainstSchema(\n  data: unknown,\n  schema: DataSchema | Schema,\n): void {\n  return schemaValidator.validateDataAgainstSchema(data, schema);\n}\n\n/**\n * Convenience function to fetch and validate a data schema from a URL\n *\n * @param url - The URL to fetch the data schema from\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns The validated data schema\n * @throws SchemaValidationError if invalid or fetch fails\n */\nexport function fetchAndValidateSchema(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<DataSchema> {\n  return schemaValidator.fetchAndValidateSchema(url, downloadRelayer);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/utils/schemaValidation.ts"],"sourcesContent":["import Ajv, { type ValidateFunction } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport dataSchemaSchema from \"../schemas/dataSchema.schema.json\";\nimport type { Schema } from \"../types/data\";\n\n/**\n * Data schema interface following the Vana schema specification\n *\n * @category Configuration\n */\nexport interface DataSchema {\n  /** The name of the data schema */\n  name: string;\n  /** The version of the data schema */\n  version: string;\n  /** Optional description of the data schema */\n  description?: string;\n  /** The dialect type - either SQLite or JSON */\n  dialect: \"sqlite\" | \"json\";\n  /** Optional version of the dialect */\n  dialectVersion?: string;\n  /** The actual schema definition as string or object */\n  schema: string | object;\n}\n\n/**\n * Error thrown when schema validation fails\n */\nexport class SchemaValidationError extends Error {\n  constructor(\n    message: string,\n    public errors: Array<{\n      instancePath: string;\n      schemaPath: string;\n      keyword: string;\n      params: Record<string, unknown>;\n      message?: string;\n    }>,\n  ) {\n    super(message);\n    this.name = \"SchemaValidationError\";\n  }\n}\n\n/**\n * Data schema validation utility class\n */\nexport class SchemaValidator {\n  private ajv: Ajv;\n  private dataSchemaValidator: ValidateFunction;\n\n  constructor() {\n    this.ajv = new Ajv({\n      allErrors: true,\n      verbose: true,\n      strict: false,\n    });\n\n    // Add format validation (e.g., date, email, uri)\n    addFormats(this.ajv);\n\n    // Compile the data schema meta-schema validator\n    this.dataSchemaValidator = this.ajv.compile(dataSchemaSchema);\n  }\n\n  /**\n   * Validates a data schema definition against the Vana meta-schema\n   *\n   * @param schema - The data schema definition to validate\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * const schema = {\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: {\n   *     type: \"object\",\n   *     properties: {\n   *       name: { type: \"string\" },\n   *       age: { type: \"number\" }\n   *     }\n   *   }\n   * };\n   *\n   * validator.validateDataSchemaAgainstMetaSchema(schema); // throws if invalid\n   * ```\n   */\n  validateDataSchemaAgainstMetaSchema(\n    schema: unknown,\n  ): asserts schema is DataSchema {\n    const isValid = this.dataSchemaValidator(schema);\n\n    if (!isValid) {\n      const errors = this.dataSchemaValidator.errors ?? [];\n      const errorMessage = `Data schema validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n\n    // Additional validation based on dialect\n    const typedSchema = schema as DataSchema;\n    if (\n      typedSchema.dialect === \"json\" &&\n      typeof typedSchema.schema === \"object\"\n    ) {\n      // Validate that the embedded JSON Schema is actually valid\n      try {\n        this.ajv.compile(typedSchema.schema);\n      } catch (error) {\n        const errorMessage = `Invalid JSON Schema in data schema: ${error instanceof Error ? error.message : \"Unknown schema compilation error\"}`;\n        throw new SchemaValidationError(errorMessage, []);\n      }\n    } else if (\n      typedSchema.dialect === \"sqlite\" &&\n      typeof typedSchema.schema === \"string\"\n    ) {\n      // Validate SQLite DDL syntax\n      this.validateSQLiteDDL(typedSchema.schema, typedSchema.dialectVersion);\n    }\n  }\n\n  /**\n   * Validates data against a JSON Schema\n   *\n   * @param data - The data to validate\n   * @param schema - The schema containing the validation rules (must have been validated or fetched from chain)\n   * @throws SchemaValidationError if invalid\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   *\n   * // Works with Schema from schemas.get()\n   * const schema = await vana.schemas.get(1);\n   * validator.validateDataAgainstSchema(userData, schema);\n   *\n   * // Also works with pre-validated DataSchema object\n   * const dataSchema = validator.validateDataSchemaAgainstMetaSchema({\n   *   name: \"User Profile\",\n   *   version: \"1.0.0\",\n   *   dialect: \"json\",\n   *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n   * });\n   * validator.validateDataAgainstSchema(userData, dataSchema);\n   * ```\n   */\n  validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void {\n    if (schema.dialect !== \"json\") {\n      console.warn(\n        `[SchemaValidator] Data validation skipped: dialect '${schema.dialect}' does not support data validation. ` +\n          `Only JSON schemas can validate data structure.`,\n      );\n      return;\n    }\n\n    if (typeof schema.schema !== \"object\") {\n      throw new SchemaValidationError(\n        \"JSON dialect schemas must have an object schema\",\n        [],\n      );\n    }\n\n    // Compile and validate against the data schema\n    const dataValidator = this.ajv.compile(schema.schema);\n    const isValid = dataValidator(data);\n\n    if (!isValid) {\n      const errors = dataValidator.errors ?? [];\n      const errorMessage = `Data validation failed: ${errors.map((e) => `${e.instancePath} ${e.message}`).join(\", \")}`;\n      throw new SchemaValidationError(errorMessage, errors);\n    }\n  }\n\n  /**\n   * Validates a SQLite DDL string for basic syntax\n   * Note: This is a basic validation, full SQL parsing would require a proper SQL parser\n   *\n   * @param ddl - The DDL string to validate\n   * @param dialectVersion - Optional SQLite version (e.g., \"3\" for SQLite v3)\n   * @throws SchemaValidationError if invalid\n   */\n  validateSQLiteDDL(ddl: string, dialectVersion?: string): void {\n    if (typeof ddl !== \"string\" || ddl.trim().length === 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must be a non-empty string\",\n        [],\n      );\n    }\n\n    // Validate dialectVersion if provided\n    if (dialectVersion !== undefined) {\n      const supportedVersions = [\"3\"];\n      if (!supportedVersions.includes(dialectVersion)) {\n        throw new SchemaValidationError(\n          `Unsupported SQLite dialect version: ${dialectVersion}. Supported versions: ${supportedVersions.join(\", \")}`,\n          [],\n        );\n      }\n    }\n\n    // Basic validation - check for CREATE TABLE statements\n    const normalizedDDL = ddl.trim().toUpperCase();\n    if (!normalizedDDL.includes(\"CREATE TABLE\")) {\n      throw new SchemaValidationError(\n        \"SQLite DDL must contain at least one CREATE TABLE statement\",\n        [],\n      );\n    }\n\n    // Check for balanced parentheses\n    let parenCount = 0;\n    for (const char of ddl) {\n      if (char === \"(\") parenCount++;\n      if (char === \")\") parenCount--;\n      if (parenCount < 0) {\n        throw new SchemaValidationError(\n          \"SQLite DDL has unbalanced parentheses\",\n          [],\n        );\n      }\n    }\n\n    if (parenCount !== 0) {\n      throw new SchemaValidationError(\n        \"SQLite DDL has unbalanced parentheses\",\n        [],\n      );\n    }\n  }\n\n  /**\n   * Fetches and validates a data schema from a URL\n   *\n   * @param url - The URL to fetch the data schema from\n   * @param downloadRelayer - Optional download relayer for CORS bypass\n   * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n   * @returns The validated data schema\n   * @throws SchemaValidationError if invalid or fetch fails\n   * @example\n   * ```typescript\n   * const validator = new SchemaValidator();\n   * const schema = await validator.fetchAndValidateSchema(\"https://example.com/schema.json\");\n   * ```\n   */\n  async fetchAndValidateSchema(\n    url: string,\n    downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n  ): Promise<DataSchema> {\n    try {\n      const { universalFetch } = await import(\"./download\");\n      const response = await universalFetch(url, downloadRelayer);\n      if (!response.ok) {\n        throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n      }\n\n      const schema = await response.json();\n      this.validateDataSchemaAgainstMetaSchema(schema);\n\n      // Additional validation based on dialect\n      if (schema.dialect === \"sqlite\" && typeof schema.schema === \"string\") {\n        this.validateSQLiteDDL(schema.schema, schema.dialectVersion);\n      }\n\n      return schema;\n    } catch (error) {\n      if (error instanceof SchemaValidationError) {\n        throw error;\n      }\n\n      throw new SchemaValidationError(\n        `Failed to fetch and validate schema from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        [],\n      );\n    }\n  }\n}\n\n/**\n * Global schema validator instance\n */\nexport const schemaValidator = new SchemaValidator();\n\n/**\n * Convenience function to validate a data schema definition against the Vana meta-schema\n *\n * @param schema - The data schema definition to validate\n * @returns The validated DataSchema\n * @throws SchemaValidationError if invalid\n * @example\n * ```typescript\n * const schemaDefinition = {\n *   name: \"User Profile\",\n *   version: \"1.0.0\",\n *   dialect: \"json\",\n *   schema: { type: \"object\", properties: { name: { type: \"string\" } } }\n * };\n *\n * const validatedSchema = validateDataSchemaAgainstMetaSchema(schemaDefinition);\n * ```\n */\nexport function validateDataSchemaAgainstMetaSchema(\n  schema: unknown,\n): DataSchema {\n  const validator: SchemaValidator = schemaValidator;\n  validator.validateDataSchemaAgainstMetaSchema(schema);\n  // If we get here, schema is valid and typed as DataSchema\n  return schema;\n}\n\n/**\n * Convenience function to validate data against a schema\n *\n * @param data - The data to validate\n * @param schema - The data schema containing the schema\n * @returns void - Function doesn't return a value\n * @throws SchemaValidationError if invalid\n */\nexport function validateDataAgainstSchema(\n  data: unknown,\n  schema: DataSchema | Schema,\n): void {\n  schemaValidator.validateDataAgainstSchema(data, schema);\n}\n\n/**\n * Convenience function to fetch and validate a data schema from a URL\n *\n * @param url - The URL to fetch the data schema from\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns The validated data schema\n * @throws SchemaValidationError if invalid or fetch fails\n */\nexport function fetchAndValidateSchema(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<DataSchema> {\n  return schemaValidator.fetchAndValidateSchema(url, downloadRelayer);\n}\n"],"mappings":"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","names":[]}

package/dist/utils/signatureCache.cjs

@@ -24,7 +24,6 @@ __export(signatureCache_exports, {
 module.exports = __toCommonJS(signatureCache_exports);
 var import_viem = require("viem");
 var import_sha256 = require("@noble/hashes/sha256");
-var import_utils = require("@noble/hashes/utils");
 class SignatureCache {
   static PREFIX = "vana_sig_";
   static DEFAULT_TTL_HOURS = 2;
@@ -143,15 +142,21 @@ class SignatureCache {
   static hashMessage(message) {
     const jsonString = JSON.stringify(message, this.deterministicReplacer);
     const hashBytes = (0, import_sha256.sha256)(new TextEncoder().encode(jsonString));
-    return (0, import_utils.bytesToHex)(hashBytes);
+    return (0, import_viem.toHex)(hashBytes);
   }
   /**
-   * Deterministic JSON replacer that handles BigInt values and sorts object keys
-   * This ensures consistent cache key generation for EIP-712 typed data
+   * Deterministic JSON replacer for consistent cache key generation.
+   *
+   * @remarks
+   * Handles BigInt serialization and sorts object keys to ensure
+   * identical objects always produce the same hash regardless of
+   * property order.
    *
    * @param _key - The object key being serialized (unused)
    * @param value - The value to serialize
    * @returns The serialized value with sorted keys for objects
+   *
+   * @internal
    */
   static deterministicReplacer(_key, value) {
     if (typeof value === "bigint") {

package/dist/utils/signatureCache.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/signatureCache.ts"],"sourcesContent":["import { Hash, getAddress } from \"viem\";\nimport type { VanaCacheAdapter } from \"../platform/interface\";\nimport { sha256 } from \"@noble/hashes/sha256\";\nimport { bytesToHex } from \"@noble/hashes/utils\";\n\ninterface CachedSignature {\n  signature: Hash;\n  expires: number;\n}\n\n/**\n * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.\n *\n * @remarks\n * This cache significantly improves UX by avoiding repeated wallet signature prompts\n * for identical operations. It's particularly useful for operations that may be\n * retried or called multiple times with the same parameters.\n *\n * Features:\n * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * - Configurable TTL (default 2 hours)\n * - Automatic cleanup of expired entries\n * - Cache keys based on wallet address + message hash\n *\n * @example\n * ```typescript\n * // Check cache before requesting signature\n * const cached = SignatureCache.get(cache, walletAddress, messageHash);\n * if (cached) {\n *   return cached;\n * }\n *\n * // Request signature and cache it\n * const signature = await wallet.signTypedData(typedData);\n * SignatureCache.set(cache, walletAddress, messageHash, signature);\n * ```\n * @category Utilities\n */\nexport class SignatureCache {\n  private static readonly PREFIX = \"vana_sig_\";\n  private static readonly DEFAULT_TTL_HOURS = 2;\n\n  /**\n   * Get a cached signature if it exists and hasn't expired\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @returns The cached signature if valid, null if expired or not found\n   * @example\n   * ```typescript\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   * const cached = SignatureCache.get(cache, '0x123...', messageHash);\n   * if (cached) {\n   *   console.log('Using cached signature:', cached);\n   * }\n   * ```\n   */\n  static get(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n  ): Hash | null {\n    const key = this.getCacheKey(walletAddress, messageHash);\n\n    try {\n      const stored = cache.get(key);\n      if (!stored) return null;\n\n      const cached: CachedSignature = JSON.parse(stored);\n\n      // Check if expired\n      if (Date.now() > cached.expires) {\n        cache.delete(key);\n        return null;\n      }\n\n      return cached.signature;\n    } catch {\n      // Invalid JSON or storage error, clean up\n      try {\n        cache.delete(key);\n      } catch {\n        // Ignore cache cleanup errors\n      }\n      return null;\n    }\n  }\n\n  /**\n   * Store a signature in the cache with configurable TTL\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @param signature - The signature to cache\n   * @param ttlHours - Time to live in hours (default: 2)\n   * @example\n   * ```typescript\n   * const signature = await wallet.signTypedData(typedData);\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   *\n   * // Cache for default 2 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature);\n   *\n   * // Cache for 24 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);\n   * ```\n   */\n  static set(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n    signature: Hash,\n    ttlHours: number = this.DEFAULT_TTL_HOURS,\n  ): void {\n    const key = this.getCacheKey(walletAddress, messageHash);\n    const cached: CachedSignature = {\n      signature,\n      expires: Date.now() + ttlHours * 3600000, // Convert hours to milliseconds\n    };\n\n    try {\n      cache.set(key, JSON.stringify(cached));\n    } catch {\n      // Storage quota exceeded or other error, ignore silently\n      // Better to continue without caching than to fail\n    }\n  }\n\n  /**\n   * Clear all cached signatures (useful for testing or explicit cleanup)\n   *\n   * @param cache - Platform cache adapter instance\n   * @example\n   * ```typescript\n   * // Clear all signatures when user logs out\n   * SignatureCache.clear(cache);\n   *\n   * // Clear before running tests\n   * beforeEach(() => {\n   *   SignatureCache.clear(cache);\n   * });\n   * ```\n   */\n  static clear(cache: VanaCacheAdapter): void {\n    try {\n      cache.clear();\n    } catch {\n      // Ignore storage errors\n    }\n  }\n\n  private static getCacheKey(\n    walletAddress: string,\n    messageHash: string,\n  ): string {\n    return `${this.PREFIX}${getAddress(walletAddress)}:${messageHash}`;\n  }\n\n  /**\n   * Generate a deterministic hash of a message object for cache key generation\n   *\n   * @remarks\n   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.\n   * Uses SHA-256 for collision resistance and deterministic key generation.\n   * Handles BigInt serialization and sorts object keys for consistency.\n   *\n   * @param message - The message object to hash (typically EIP-712 typed data)\n   * @returns A hex string hash (SHA-256) suitable for cache keys\n   * @example\n   * ```typescript\n   * const typedData = {\n   *   domain: { name: 'Vana', version: '1' },\n   *   message: { nonce: 123n, grant: '...' }\n   * };\n   *\n   * const hash = SignatureCache.hashMessage(typedData);\n   * // Returns SHA-256 hash like: \"a1b2c3d4e5f6...\"\n   * ```\n   */\n  static hashMessage(message: object): string {\n    // Deterministically stringify the object with sorted keys\n    const jsonString = JSON.stringify(message, this.deterministicReplacer);\n\n    // Use SHA-256 for cryptographic hashing\n    const hashBytes = sha256(new TextEncoder().encode(jsonString));\n    return bytesToHex(hashBytes);\n  }\n\n  /**\n   * Deterministic JSON replacer that handles BigInt values and sorts object keys\n   * This ensures consistent cache key generation for EIP-712 typed data\n   *\n   * @param _key - The object key being serialized (unused)\n   * @param value - The value to serialize\n   * @returns The serialized value with sorted keys for objects\n   */\n  private static deterministicReplacer(_key: string, value: unknown): unknown {\n    if (typeof value === \"bigint\") {\n      return `__BIGINT__${value.toString()}`;\n    }\n    // Sort object keys for deterministic serialization\n    if (value !== null && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce(\n          (sorted, key) => {\n            sorted[key] = (value as Record<string, unknown>)[key];\n            return sorted;\n          },\n          {} as Record<string, unknown>,\n        );\n    }\n    return value;\n  }\n}\n\n/**\n * Wrapper function to cache signature operations\n *\n * @param cache - The cache adapter to use for storage\n * @param walletAddress - The wallet address signing the message\n * @param typedData - The EIP-712 typed data being signed\n * @param signFn - Function that performs the actual signing\n * @param ttlHours - Cache TTL in hours (default 2)\n * @returns The signature (cached or newly generated)\n */\nexport async function withSignatureCache(\n  cache: VanaCacheAdapter,\n  walletAddress: string,\n  typedData: Record<string, unknown>,\n  signFn: () => Promise<Hash>,\n  ttlHours?: number,\n): Promise<Hash> {\n  // Create a hash of the typed data for the cache key\n  const messageHash = SignatureCache.hashMessage(typedData);\n\n  // Try to get from cache first\n  const cached = SignatureCache.get(cache, walletAddress, messageHash);\n  if (cached) {\n    return cached;\n  }\n\n  // Not in cache, sign and store\n  const signature = await signFn();\n  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);\n\n  return signature;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/utils/signatureCache.ts"],"sourcesContent":["/**\n * Provides signature caching to improve UX by avoiding repeated wallet prompts.\n *\n * @remarks\n * This module implements a secure signature cache that stores signed messages\n * temporarily to avoid repeatedly prompting users for the same signature.\n * It uses platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * and includes automatic expiration and cleanup.\n *\n * @category Utilities\n * @module utils/signatureCache\n */\n\nimport type { Hash } from \"viem\";\nimport { getAddress, toHex } from \"viem\";\nimport type { VanaCacheAdapter } from \"../platform/interface\";\nimport { sha256 } from \"@noble/hashes/sha256\";\n\n/**\n * Represents a cached signature with expiration metadata.\n *\n * @internal\n */\ninterface CachedSignature {\n  /** The cached signature hash */\n  signature: Hash;\n  /** Unix timestamp when this cache entry expires */\n  expires: number;\n}\n\n/**\n * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.\n *\n * @remarks\n * This cache significantly improves UX by avoiding repeated wallet signature prompts\n * for identical operations. It's particularly useful for operations that may be\n * retried or called multiple times with the same parameters.\n *\n * Features:\n * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * - Configurable TTL (default 2 hours)\n * - Automatic cleanup of expired entries\n * - Cache keys based on wallet address + message hash\n *\n * @example\n * ```typescript\n * // Check cache before requesting signature\n * const cached = SignatureCache.get(cache, walletAddress, messageHash);\n * if (cached) {\n *   return cached;\n * }\n *\n * // Request signature and cache it\n * const signature = await wallet.signTypedData(typedData);\n * SignatureCache.set(cache, walletAddress, messageHash, signature);\n * ```\n * @category Utilities\n */\nexport class SignatureCache {\n  private static readonly PREFIX = \"vana_sig_\";\n  private static readonly DEFAULT_TTL_HOURS = 2;\n\n  /**\n   * Get a cached signature if it exists and hasn't expired\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @returns The cached signature if valid, null if expired or not found\n   * @example\n   * ```typescript\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   * const cached = SignatureCache.get(cache, '0x123...', messageHash);\n   * if (cached) {\n   *   console.log('Using cached signature:', cached);\n   * }\n   * ```\n   */\n  static get(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n  ): Hash | null {\n    const key = this.getCacheKey(walletAddress, messageHash);\n\n    try {\n      const stored = cache.get(key);\n      if (!stored) return null;\n\n      const cached: CachedSignature = JSON.parse(stored);\n\n      // Check if expired\n      if (Date.now() > cached.expires) {\n        cache.delete(key);\n        return null;\n      }\n\n      return cached.signature;\n    } catch {\n      // Invalid JSON or storage error, clean up\n      try {\n        cache.delete(key);\n      } catch {\n        // Ignore cache cleanup errors\n      }\n      return null;\n    }\n  }\n\n  /**\n   * Store a signature in the cache with configurable TTL\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @param signature - The signature to cache\n   * @param ttlHours - Time to live in hours (default: 2)\n   * @example\n   * ```typescript\n   * const signature = await wallet.signTypedData(typedData);\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   *\n   * // Cache for default 2 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature);\n   *\n   * // Cache for 24 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);\n   * ```\n   */\n  static set(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n    signature: Hash,\n    ttlHours: number = this.DEFAULT_TTL_HOURS,\n  ): void {\n    const key = this.getCacheKey(walletAddress, messageHash);\n    const cached: CachedSignature = {\n      signature,\n      expires: Date.now() + ttlHours * 3600000, // Convert hours to milliseconds\n    };\n\n    try {\n      cache.set(key, JSON.stringify(cached));\n    } catch {\n      // Storage quota exceeded or other error, ignore silently\n      // Better to continue without caching than to fail\n    }\n  }\n\n  /**\n   * Clear all cached signatures (useful for testing or explicit cleanup)\n   *\n   * @param cache - Platform cache adapter instance\n   * @example\n   * ```typescript\n   * // Clear all signatures when user logs out\n   * SignatureCache.clear(cache);\n   *\n   * // Clear before running tests\n   * beforeEach(() => {\n   *   SignatureCache.clear(cache);\n   * });\n   * ```\n   */\n  static clear(cache: VanaCacheAdapter): void {\n    try {\n      cache.clear();\n    } catch {\n      // Ignore storage errors\n    }\n  }\n\n  private static getCacheKey(\n    walletAddress: string,\n    messageHash: string,\n  ): string {\n    return `${this.PREFIX}${getAddress(walletAddress)}:${messageHash}`;\n  }\n\n  /**\n   * Generate a deterministic hash of a message object for cache key generation\n   *\n   * @remarks\n   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.\n   * Uses SHA-256 for collision resistance and deterministic key generation.\n   * Handles BigInt serialization and sorts object keys for consistency.\n   *\n   * @param message - The message object to hash (typically EIP-712 typed data)\n   * @returns A hex string hash (SHA-256) suitable for cache keys\n   * @example\n   * ```typescript\n   * const typedData = {\n   *   domain: { name: 'Vana', version: '1' },\n   *   message: { nonce: 123n, grant: '...' }\n   * };\n   *\n   * const hash = SignatureCache.hashMessage(typedData);\n   * // Returns SHA-256 hash like: \"a1b2c3d4e5f6...\"\n   * ```\n   */\n  static hashMessage(message: object): string {\n    // Deterministically stringify the object with sorted keys\n    const jsonString = JSON.stringify(message, this.deterministicReplacer);\n\n    // Use SHA-256 for cryptographic hashing\n    const hashBytes = sha256(new TextEncoder().encode(jsonString));\n    return toHex(hashBytes);\n  }\n\n  /**\n   * Deterministic JSON replacer for consistent cache key generation.\n   *\n   * @remarks\n   * Handles BigInt serialization and sorts object keys to ensure\n   * identical objects always produce the same hash regardless of\n   * property order.\n   *\n   * @param _key - The object key being serialized (unused)\n   * @param value - The value to serialize\n   * @returns The serialized value with sorted keys for objects\n   *\n   * @internal\n   */\n  private static deterministicReplacer(_key: string, value: unknown): unknown {\n    if (typeof value === \"bigint\") {\n      return `__BIGINT__${value.toString()}`;\n    }\n    // Sort object keys for deterministic serialization\n    if (value !== null && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce(\n          (sorted, key) => {\n            sorted[key] = (value as Record<string, unknown>)[key];\n            return sorted;\n          },\n          {} as Record<string, unknown>,\n        );\n    }\n    return value;\n  }\n}\n\n/**\n * Wraps signature operations with caching to avoid repeated prompts.\n *\n * @remarks\n * This helper function checks the cache before requesting a signature\n * and stores new signatures for future use. It significantly improves\n * UX for operations that may be retried or called multiple times.\n *\n * @param cache - The cache adapter to use for storage.\n *   Obtain from platform adapter.\n * @param walletAddress - The wallet address signing the message.\n *   Obtain from wallet connection.\n * @param typedData - The EIP-712 typed data being signed.\n *   Typically permission or grant data.\n * @param signFn - Async function that performs the actual signing.\n *   Usually calls wallet.signTypedData().\n * @param ttlHours - Cache TTL in hours.\n *   Defaults to 2 hours.\n * @returns The signature (cached or newly generated)\n *\n * @example\n * ```typescript\n * const signature = await withSignatureCache(\n *   platformAdapter.cache,\n *   walletAddress,\n *   typedData,\n *   async () => wallet.signTypedData(typedData),\n *   24 // Cache for 24 hours\n * );\n * ```\n *\n * @category Utilities\n */\nexport async function withSignatureCache(\n  cache: VanaCacheAdapter,\n  walletAddress: string,\n  typedData: Record<string, unknown>,\n  signFn: () => Promise<Hash>,\n  ttlHours?: number,\n): Promise<Hash> {\n  // Create a hash of the typed data for the cache key\n  const messageHash = SignatureCache.hashMessage(typedData);\n\n  // Try to get from cache first\n  const cached = SignatureCache.get(cache, walletAddress, messageHash);\n  if (cached) {\n    return cached;\n  }\n\n  // Not in cache, sign and store\n  const signature = await signFn();\n  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);\n\n  return signature;\n}\n"],"mappings":"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","names":[]}