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

package/dist/utils/grants.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/grants.ts"],"sourcesContent":["import { Address } from \"viem\";\nimport type { GrantFile, GrantPermissionParams } from \"../types/permissions\";\nimport {\n  createGrantFile,\n  storeGrantFile,\n  retrieveGrantFile,\n} from \"./grantFiles\";\nimport { validateGrant, GrantValidationError } from \"./grantValidation\";\n\n/**\n * High-level utilities for working with grants in the Vana SDK\n */\n\n/**\n * Creates and validates a grant file from permission parameters\n *\n * @param params - The permission parameters to create and validate the grant from\n * @returns The validated grant file object\n */\nexport function createValidatedGrant(params: GrantPermissionParams): GrantFile {\n  const grantFile = createGrantFile(params);\n\n  // Validate the created grant file\n  try {\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: params.grantee,\n      operation: params.operation,\n    });\n  } catch (error) {\n    throw new GrantValidationError(\n      `Created grant file failed validation: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      { grantFile, params },\n    );\n  }\n\n  return grantFile;\n}\n\n/**\n * Creates a grant file and stores it in IPFS\n *\n * @param params - The permission parameters to create the grant from\n * @param relayerUrl - The URL of the relayer service for IPFS storage\n * @returns Promise resolving to an object containing the grant file and its IPFS URL\n */\nexport async function createAndStoreGrant(\n  params: GrantPermissionParams,\n  relayerUrl: string,\n): Promise<{ grantFile: GrantFile; grantUrl: string }> {\n  const grantFile = createValidatedGrant(params);\n  const grantUrl = await storeGrantFile(grantFile, relayerUrl);\n\n  return { grantFile, grantUrl };\n}\n\n/**\n * Retrieves and validates a grant file from IPFS\n *\n * @param grantUrl - The IPFS URL of the grant file to retrieve\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to the validated grant file\n */\nexport async function retrieveAndValidateGrant(\n  grantUrl: string,\n  relayerUrl?: string,\n): Promise<GrantFile> {\n  const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);\n\n  // Additional validation can be added here if needed\n  return grantFile;\n}\n\n/**\n * Checks if a grant allows access for a specific request\n *\n * @param grantUrl - The IPFS URL of the grant file to check\n * @param requestingAddress - The address making the access request\n * @param operation - The operation being requested\n * @param fileIds - Array of file IDs being accessed (currently unused but part of interface)\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to access result with allowed status, reason, and grant file\n */\nexport async function checkGrantAccess(\n  grantUrl: string,\n  requestingAddress: Address,\n  operation: string,\n  fileIds: number[],\n  relayerUrl?: string,\n): Promise<{ allowed: boolean; reason?: string; grantFile?: GrantFile }> {\n  try {\n    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);\n\n    // Validate the grant for the request\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: requestingAddress,\n      operation,\n    });\n\n    return { allowed: true, grantFile };\n  } catch (error) {\n    if (error instanceof GrantValidationError) {\n      return {\n        allowed: false,\n        reason: error.message,\n      };\n    }\n\n    return {\n      allowed: false,\n      reason: `Grant access check failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n    };\n  }\n}\n\n/**\n * Utility to check if a grant has expired\n *\n * @param grantFile - The grant file to check for expiration\n * @returns True if the grant has expired, false otherwise\n */\nexport function isGrantExpired(grantFile: GrantFile): boolean {\n  if (!grantFile.expires) {\n    return false; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  return now > grantFile.expires;\n}\n\n/**\n * Utility to get the time remaining before grant expires (in seconds)\n *\n * @param grantFile - The grant file to check time remaining for\n * @returns Number of seconds remaining, or null if no expiration is set\n */\nexport function getGrantTimeRemaining(grantFile: GrantFile): number | null {\n  if (!grantFile.expires) {\n    return null; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const remaining = grantFile.expires - now;\n  return Math.max(0, remaining);\n}\n\n/**\n * Creates a human-readable summary of a grant\n *\n * @param grantFile - The grant file to create a summary for\n * @returns A human-readable string describing the grant\n */\nexport function summarizeGrant(grantFile: GrantFile): string {\n  const expiration = grantFile.expires\n    ? new Date(grantFile.expires * 1000).toISOString()\n    : \"No expiration\";\n\n  return `Grant for ${grantFile.grantee} to perform \"${grantFile.operation}\" (expires: ${expiration})`;\n}\n"],"mappings":"AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,eAAe,4BAA4B;AAY7C,SAAS,qBAAqB,QAA0C;AAC7E,QAAM,YAAY,gBAAgB,MAAM;AAGxC,MAAI;AACF,kBAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,yCAAyC,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACjG,EAAE,WAAW,OAAO;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AASA,eAAsB,oBACpB,QACA,YACqD;AACrD,QAAM,YAAY,qBAAqB,MAAM;AAC7C,QAAM,WAAW,MAAM,eAAe,WAAW,UAAU;AAE3D,SAAO,EAAE,WAAW,SAAS;AAC/B;AASA,eAAsB,yBACpB,UACA,YACoB;AACpB,QAAM,YAAY,MAAM,kBAAkB,UAAU,UAAU;AAG9D,SAAO;AACT;AAYA,eAAsB,iBACpB,UACA,mBACA,WACA,SACA,YACuE;AACvE,MAAI;AACF,UAAM,YAAY,MAAM,yBAAyB,UAAU,UAAU;AAGrE,kBAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO,EAAE,SAAS,MAAM,UAAU;AAAA,EACpC,SAAS,OAAO;AACd,QAAI,iBAAiB,sBAAsB;AACzC,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,MAAM;AAAA,MAChB;AAAA,IACF;AAEA,WAAO;AAAA,MACL,SAAS;AAAA,MACT,QAAQ,8BAA8B,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,IAChG;AAAA,EACF;AACF;AAQO,SAAS,eAAe,WAA+B;AAC5D,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,SAAO,MAAM,UAAU;AACzB;AAQO,SAAS,sBAAsB,WAAqC;AACzE,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,YAAY,UAAU,UAAU;AACtC,SAAO,KAAK,IAAI,GAAG,SAAS;AAC9B;AAQO,SAAS,eAAe,WAA8B;AAC3D,QAAM,aAAa,UAAU,UACzB,IAAI,KAAK,UAAU,UAAU,GAAI,EAAE,YAAY,IAC/C;AAEJ,SAAO,aAAa,UAAU,OAAO,gBAAgB,UAAU,SAAS,eAAe,UAAU;AACnG;","names":[]}
+{"version":3,"sources":["../../src/utils/grants.ts"],"sourcesContent":["/**\n * Provides high-level grant management utilities for the Vana permission system.\n *\n * @remarks\n * This module simplifies grant file creation, validation, storage, and retrieval.\n * Grants are the core mechanism for permission management in Vana, allowing users\n * to delegate specific operations to applications and services.\n *\n * @category Permissions\n * @module grants\n */\n\nimport type { Address } from \"viem\";\nimport type { GrantFile, GrantPermissionParams } from \"../types/permissions\";\nimport {\n  createGrantFile,\n  storeGrantFile,\n  retrieveGrantFile,\n} from \"./grantFiles\";\nimport { validateGrant, GrantValidationError } from \"./grantValidation\";\n\n/**\n * Creates and validates a grant file from permission parameters.\n *\n * @remarks\n * Combines grant creation with immediate validation to ensure only valid\n * grants are created. Validates schema compliance, grantee address, and\n * operation parameters before returning the grant file.\n *\n * @param params - The permission parameters to create and validate the grant from.\n *   Obtain from user input or application configuration.\n * @returns The validated grant file object ready for storage\n *\n * @throws {GrantValidationError} When grant parameters are invalid.\n *   Check error message for specific validation failures.\n *\n * @example\n * ```typescript\n * const grant = createValidatedGrant({\n *   grantee: '0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb',\n *   operation: 'llm_inference',\n *   parameters: { model: 'gpt-4', maxTokens: 1000 },\n *   expiresAt: Date.now() + 86400000 // 24 hours\n * });\n * ```\n *\n * @category Permissions\n */\nexport function createValidatedGrant(params: GrantPermissionParams): GrantFile {\n  const grantFile = createGrantFile(params);\n\n  // Validate the created grant file\n  try {\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: params.grantee,\n      operation: params.operation,\n    });\n  } catch (error) {\n    throw new GrantValidationError(\n      `Created grant file failed validation: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      { grantFile, params },\n    );\n  }\n\n  return grantFile;\n}\n\n/**\n * Creates a grant file and stores it in IPFS.\n *\n * @remarks\n * Combines grant creation, validation, and IPFS storage in a single operation.\n * The grant is stored immutably on IPFS and can be referenced by its URL in\n * on-chain permission records.\n *\n * @param params - The permission parameters to create the grant from.\n *   Obtain from user input or application configuration.\n * @param relayerUrl - The URL of the relayer service for IPFS storage.\n *   Obtain from SDK configuration or environment.\n * @returns Promise resolving to an object containing the grant file and its IPFS URL\n *\n * @throws {GrantValidationError} When grant parameters are invalid.\n *   Check error message for specific validation failures.\n * @throws {Error} When IPFS storage fails.\n *   Retry with exponential backoff or check relayer status.\n *\n * @example\n * ```typescript\n * const { grantFile, grantUrl } = await createAndStoreGrant(\n *   {\n *     grantee: applicationAddress,\n *     operation: 'data_processing',\n *     parameters: { dataTypes: ['medical', 'financial'] }\n *   },\n *   'https://relayer.vana.org'\n * );\n *\n * console.log('Grant stored at:', grantUrl);\n * ```\n *\n * @category Permissions\n */\nexport async function createAndStoreGrant(\n  params: GrantPermissionParams,\n  relayerUrl: string,\n): Promise<{ grantFile: GrantFile; grantUrl: string }> {\n  const grantFile = createValidatedGrant(params);\n  const grantUrl = await storeGrantFile(grantFile, relayerUrl);\n\n  return { grantFile, grantUrl };\n}\n\n/**\n * Retrieves and validates a grant file from IPFS.\n *\n * @remarks\n * Fetches a grant file from IPFS and performs basic validation to ensure\n * the retrieved data is a valid grant structure. Use this when you need to\n * verify or process existing grants.\n *\n * @param grantUrl - The IPFS URL of the grant file to retrieve.\n *   Obtain from on-chain permission records or grant events.\n * @param relayerUrl - Optional URL of the relayer service.\n *   If not provided, uses default IPFS gateways.\n * @returns Promise resolving to the validated grant file\n *\n * @throws {Error} When grant retrieval fails.\n *   Check network connectivity or IPFS gateway availability.\n * @throws {Error} When grant file is malformed.\n *   Verify the grant URL points to a valid grant file.\n *\n * @example\n * ```typescript\n * const grant = await retrieveAndValidateGrant(\n *   'ipfs://QmXxx...'\n * );\n *\n * console.log('Grant for:', grant.grantee);\n * console.log('Operation:', grant.operation);\n * ```\n *\n * @category Permissions\n */\nexport async function retrieveAndValidateGrant(\n  grantUrl: string,\n  relayerUrl?: string,\n): Promise<GrantFile> {\n  const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);\n\n  // Additional validation can be added here if needed\n  return grantFile;\n}\n\n/**\n * Checks if a grant allows access for a specific request\n *\n * @param grantUrl - The IPFS URL of the grant file to check\n * @param requestingAddress - The address making the access request\n * @param operation - The operation being requested\n * @param _fileIds - Array of file IDs being accessed (currently unused but part of interface)\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to access result with allowed status, reason, and grant file\n */\nexport async function checkGrantAccess(\n  grantUrl: string,\n  requestingAddress: Address,\n  operation: string,\n  _fileIds: number[],\n  relayerUrl?: string,\n): Promise<{ allowed: boolean; reason?: string; grantFile?: GrantFile }> {\n  try {\n    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);\n\n    // Validate the grant for the request\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: requestingAddress,\n      operation,\n    });\n\n    return { allowed: true, grantFile };\n  } catch (error) {\n    if (error instanceof GrantValidationError) {\n      return {\n        allowed: false,\n        reason: error.message,\n      };\n    }\n\n    return {\n      allowed: false,\n      reason: `Grant access check failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n    };\n  }\n}\n\n/**\n * Utility to check if a grant has expired\n *\n * @param grantFile - The grant file to check for expiration\n * @returns True if the grant has expired, false otherwise\n */\nexport function isGrantExpired(grantFile: GrantFile): boolean {\n  if (!grantFile.expires) {\n    return false; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  return now > grantFile.expires;\n}\n\n/**\n * Utility to get the time remaining before grant expires (in seconds)\n *\n * @param grantFile - The grant file to check time remaining for\n * @returns Number of seconds remaining, or null if no expiration is set\n */\nexport function getGrantTimeRemaining(grantFile: GrantFile): number | null {\n  if (!grantFile.expires) {\n    return null; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const remaining = grantFile.expires - now;\n  return Math.max(0, remaining);\n}\n\n/**\n * Creates a human-readable summary of a grant\n *\n * @param grantFile - The grant file to create a summary for\n * @returns A human-readable string describing the grant\n */\nexport function summarizeGrant(grantFile: GrantFile): string {\n  const expiration = grantFile.expires\n    ? new Date(grantFile.expires * 1000).toISOString()\n    : \"No expiration\";\n\n  return `Grant for ${grantFile.grantee} to perform \"${grantFile.operation}\" (expires: ${expiration})`;\n}\n"],"mappings":"AAcA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,eAAe,4BAA4B;AA6B7C,SAAS,qBAAqB,QAA0C;AAC7E,QAAM,YAAY,gBAAgB,MAAM;AAGxC,MAAI;AACF,kBAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,yCAAyC,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACjG,EAAE,WAAW,OAAO;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AAqCA,eAAsB,oBACpB,QACA,YACqD;AACrD,QAAM,YAAY,qBAAqB,MAAM;AAC7C,QAAM,WAAW,MAAM,eAAe,WAAW,UAAU;AAE3D,SAAO,EAAE,WAAW,SAAS;AAC/B;AAiCA,eAAsB,yBACpB,UACA,YACoB;AACpB,QAAM,YAAY,MAAM,kBAAkB,UAAU,UAAU;AAG9D,SAAO;AACT;AAYA,eAAsB,iBACpB,UACA,mBACA,WACA,UACA,YACuE;AACvE,MAAI;AACF,UAAM,YAAY,MAAM,yBAAyB,UAAU,UAAU;AAGrE,kBAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO,EAAE,SAAS,MAAM,UAAU;AAAA,EACpC,SAAS,OAAO;AACd,QAAI,iBAAiB,sBAAsB;AACzC,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,MAAM;AAAA,MAChB;AAAA,IACF;AAEA,WAAO;AAAA,MACL,SAAS;AAAA,MACT,QAAQ,8BAA8B,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,IAChG;AAAA,EACF;AACF;AAQO,SAAS,eAAe,WAA+B;AAC5D,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,SAAO,MAAM,UAAU;AACzB;AAQO,SAAS,sBAAsB,WAAqC;AACzE,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,YAAY,UAAU,UAAU;AACtC,SAAO,KAAK,IAAI,GAAG,SAAS;AAC9B;AAQO,SAAS,eAAe,WAA8B;AAC3D,QAAM,aAAa,UAAU,UACzB,IAAI,KAAK,UAAU,UAAU,GAAI,EAAE,YAAY,IAC/C;AAEJ,SAAO,aAAa,UAAU,OAAO,gBAAgB,UAAU,SAAS,eAAe,UAAU;AACnG;","names":[]}

package/dist/utils/ipfs.cjs

@@ -30,12 +30,10 @@ __export(ipfs_exports, {
 module.exports = __toCommonJS(ipfs_exports);
 const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
 const IPFS_GATEWAYS = [
-  "https://dweb.link/ipfs/",
-  // Interplanetary Shipyard - highly reliable
   "https://ipfs.io/ipfs/",
   // IPFS Foundation - reliable
-  "https://cloudflare-ipfs.com/ipfs/",
-  // Cloudflare - good performance
+  "https://dweb.link/ipfs/",
+  // Interplanetary Shipyard - observed to be having issues
   "https://gateway.pinata.cloud/ipfs/",
   // Pinata - backup option (has rate limits)
   "https://ipfs.filebase.io/ipfs/"

package/dist/utils/ipfs.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - highly reliable\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://cloudflare-ipfs.com/ipfs/\", // Cloudflare - good performance\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - observed to be having issues\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}

package/dist/utils/ipfs.d.ts

@@ -7,18 +7,18 @@
 /**
  * Default IPFS gateway URL
  */
-declare const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
+export declare const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
 /**
  * Alternative IPFS gateways for fallback - ordered by reliability and rate limits
  */
-declare const IPFS_GATEWAYS: readonly ["https://dweb.link/ipfs/", "https://ipfs.io/ipfs/", "https://cloudflare-ipfs.com/ipfs/", "https://gateway.pinata.cloud/ipfs/", "https://ipfs.filebase.io/ipfs/"];
+export declare const IPFS_GATEWAYS: readonly ["https://ipfs.io/ipfs/", "https://dweb.link/ipfs/", "https://gateway.pinata.cloud/ipfs/", "https://ipfs.filebase.io/ipfs/"];
 /**
  * Check if a URL is an IPFS URL (starts with ipfs://)
  *
  * @param url - The URL to check
  * @returns True if the URL is an IPFS URL
  */
-declare function isIpfsUrl(url: string): boolean;
+export declare function isIpfsUrl(url: string): boolean;
 /**
  * Convert an IPFS URL to an HTTP gateway URL
  *
@@ -34,7 +34,7 @@ declare function isIpfsUrl(url: string): boolean;
  * // Returns: "https://gateway.pinata.cloud/ipfs/QmHash123"
  * ```
  */
-declare function convertIpfsUrl(url: string, gateway?: string): string;
+export declare function convertIpfsUrl(url: string, gateway?: string): string;
 /**
  * Extract IPFS hash from various URL formats
  *
@@ -55,21 +55,21 @@ declare function convertIpfsUrl(url: string, gateway?: string): string;
  * extractIpfsHash("ipfs://QmHash/subdirectory") // Returns: null (subdirectories not supported)
  * ```
  */
-declare function extractIpfsHash(url: string): string | null;
+export declare function extractIpfsHash(url: string): string | null;
 /**
  * Get multiple gateway URLs for an IPFS hash (useful for fallback)
  *
  * @param hash - The IPFS hash
  * @returns Array of gateway URLs
  */
-declare function getGatewayUrls(hash: string): string[];
+export declare function getGatewayUrls(hash: string): string[];
 /**
  * Convert an IPFS URL to multiple gateway URLs for fallback
  *
  * @param url - The IPFS URL
  * @returns Array of gateway URLs or original URL if not IPFS
  */
-declare function convertIpfsUrlWithFallbacks(url: string): string[];
+export declare function convertIpfsUrlWithFallbacks(url: string): string[];
 /**
  * Fetch content from IPFS with automatic gateway fallbacks
  *
@@ -85,6 +85,4 @@ declare function convertIpfsUrlWithFallbacks(url: string): string[];
  * @returns Promise resolving to Response object
  * @throws Error if all gateways fail
  */
-declare function fetchWithFallbacks(url: string, options?: RequestInit): Promise<Response>;
-
-export { DEFAULT_IPFS_GATEWAY, IPFS_GATEWAYS, convertIpfsUrl, convertIpfsUrlWithFallbacks, extractIpfsHash, fetchWithFallbacks, getGatewayUrls, isIpfsUrl };
+export declare function fetchWithFallbacks(url: string, options?: RequestInit): Promise<Response>;

package/dist/utils/ipfs.js

@@ -1,11 +1,9 @@
 const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
 const IPFS_GATEWAYS = [
-  "https://dweb.link/ipfs/",
-  // Interplanetary Shipyard - highly reliable
   "https://ipfs.io/ipfs/",
   // IPFS Foundation - reliable
-  "https://cloudflare-ipfs.com/ipfs/",
-  // Cloudflare - good performance
+  "https://dweb.link/ipfs/",
+  // Interplanetary Shipyard - observed to be having issues
   "https://gateway.pinata.cloud/ipfs/",
   // Pinata - backup option (has rate limits)
   "https://ipfs.filebase.io/ipfs/"

package/dist/utils/ipfs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - highly reliable\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://cloudflare-ipfs.com/ipfs/\", // Cloudflare - good performance\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":"AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - observed to be having issues\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":"AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}

package/dist/utils/lazy-import.cjs

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

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

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Utility for lazy-loading modules to avoid Turbopack TDZ issues\n *\n * WARNING: This is a workaround for Turbopack's strict module initialization.\n * Dependencies that access globals during init must be dynamically imported.\n */\n\n/**\n * Creates a lazy import function that caches the promise (not the module)\n * to avoid race conditions on concurrent first calls\n *\n * @param importFn - Function that returns a dynamic import promise\n * @returns Function that returns the cached import promise\n *\n * @example\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n * const openpgp = await getOpenPGP();\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    if (!cached) {\n      cached = importFn().catch((err) => {\n        // Clear cache on error so next attempt can retry\n        cached = null;\n        throw new Error(\"Failed to load module\", { cause: err });\n      });\n    }\n    return cached;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,QAAI,CAAC,QAAQ;AACX,eAAS,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEjC,iBAAS;AACT,cAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,MACzD,CAAC;AAAA,IACH;AACA,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Provides lazy module loading to avoid Temporal Dead Zone issues.\n *\n * @remarks\n * This module implements a caching lazy import pattern to work around Turbopack's\n * strict module initialization. Dependencies that access globals during initialization\n * must be dynamically imported to prevent TDZ errors in Next.js environments.\n *\n * @see {@link https://github.com/vercel/next.js/issues/82632 | Turbopack TDZ Issue}\n *\n * @category Utilities\n * @module utils/lazy-import\n */\n\n/**\n * Creates a cached lazy import function for deferred module loading.\n *\n * @remarks\n * Caches the import promise (not the module) to prevent race conditions\n * during concurrent first calls. On import failure, clears the cache to\n * allow retry on next attempt.\n *\n * @typeParam T - The type of the module being imported\n *\n * @param importFn - Function that returns a dynamic import promise.\n *   Should be a dynamic import expression like `() => import('module')`.\n * @returns A function that returns the cached import promise\n *\n * @example\n * ```typescript\n * // Create lazy loader for heavy crypto library\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n *\n * // Use when needed (first call triggers import)\n * const openpgp = await getOpenPGP();\n * const encrypted = await openpgp.encrypt(data);\n *\n * // Subsequent calls return cached promise\n * const openpgp2 = await getOpenPGP(); // Same instance\n * ```\n *\n * @category Utilities\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2CO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}

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

@@ -1,20 +1,43 @@
 /**
- * Utility for lazy-loading modules to avoid Turbopack TDZ issues
+ * Provides lazy module loading to avoid Temporal Dead Zone issues.
  *
- * WARNING: This is a workaround for Turbopack's strict module initialization.
- * Dependencies that access globals during init must be dynamically imported.
+ * @remarks
+ * This module implements a caching lazy import pattern to work around Turbopack's
+ * strict module initialization. Dependencies that access globals during initialization
+ * must be dynamically imported to prevent TDZ errors in Next.js environments.
+ *
+ * @see {@link https://github.com/vercel/next.js/issues/82632 | Turbopack TDZ Issue}
+ *
+ * @category Utilities
+ * @module utils/lazy-import
  */
 /**
- * Creates a lazy import function that caches the promise (not the module)
- * to avoid race conditions on concurrent first calls
+ * Creates a cached lazy import function for deferred module loading.
+ *
+ * @remarks
+ * Caches the import promise (not the module) to prevent race conditions
+ * during concurrent first calls. On import failure, clears the cache to
+ * allow retry on next attempt.
+ *
+ * @typeParam T - The type of the module being imported
  *
- * @param importFn - Function that returns a dynamic import promise
- * @returns Function that returns the cached import promise
+ * @param importFn - Function that returns a dynamic import promise.
+ *   Should be a dynamic import expression like `() => import('module')`.
+ * @returns A function that returns the cached import promise
  *
  * @example
+ * ```typescript
+ * // Create lazy loader for heavy crypto library
  * const getOpenPGP = lazyImport(() => import('openpgp'));
+ *
+ * // Use when needed (first call triggers import)
  * const openpgp = await getOpenPGP();
+ * const encrypted = await openpgp.encrypt(data);
+ *
+ * // Subsequent calls return cached promise
+ * const openpgp2 = await getOpenPGP(); // Same instance
+ * ```
+ *
+ * @category Utilities
  */
-declare function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T>;
-
-export { lazyImport };
+export declare function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T>;

package/dist/utils/lazy-import.js

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

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

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Utility for lazy-loading modules to avoid Turbopack TDZ issues\n *\n * WARNING: This is a workaround for Turbopack's strict module initialization.\n * Dependencies that access globals during init must be dynamically imported.\n */\n\n/**\n * Creates a lazy import function that caches the promise (not the module)\n * to avoid race conditions on concurrent first calls\n *\n * @param importFn - Function that returns a dynamic import promise\n * @returns Function that returns the cached import promise\n *\n * @example\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n * const openpgp = await getOpenPGP();\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    if (!cached) {\n      cached = importFn().catch((err) => {\n        // Clear cache on error so next attempt can retry\n        cached = null;\n        throw new Error(\"Failed to load module\", { cause: err });\n      });\n    }\n    return cached;\n  };\n}\n"],"mappings":"AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,QAAI,CAAC,QAAQ;AACX,eAAS,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEjC,iBAAS;AACT,cAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,MACzD,CAAC;AAAA,IACH;AACA,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Provides lazy module loading to avoid Temporal Dead Zone issues.\n *\n * @remarks\n * This module implements a caching lazy import pattern to work around Turbopack's\n * strict module initialization. Dependencies that access globals during initialization\n * must be dynamically imported to prevent TDZ errors in Next.js environments.\n *\n * @see {@link https://github.com/vercel/next.js/issues/82632 | Turbopack TDZ Issue}\n *\n * @category Utilities\n * @module utils/lazy-import\n */\n\n/**\n * Creates a cached lazy import function for deferred module loading.\n *\n * @remarks\n * Caches the import promise (not the module) to prevent race conditions\n * during concurrent first calls. On import failure, clears the cache to\n * allow retry on next attempt.\n *\n * @typeParam T - The type of the module being imported\n *\n * @param importFn - Function that returns a dynamic import promise.\n *   Should be a dynamic import expression like `() => import('module')`.\n * @returns A function that returns the cached import promise\n *\n * @example\n * ```typescript\n * // Create lazy loader for heavy crypto library\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n *\n * // Use when needed (first call triggers import)\n * const openpgp = await getOpenPGP();\n * const encrypted = await openpgp.encrypt(data);\n *\n * // Subsequent calls return cached promise\n * const openpgp2 = await getOpenPGP(); // Same instance\n * ```\n *\n * @category Utilities\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":"AA2CO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/utils/multicall.cjs

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

package/dist/utils/multicall.cjs.map

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

package/dist/utils/multicall.d.ts

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

package/dist/utils/multicall.js

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