@opendatalabs/vana-sdk 0.1.0-alpha.a25bcc7 → 0.1.0-alpha.a6b60fc

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    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;AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}
+{"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,18 +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
  */
 export declare function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T>;

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    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":"AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}
+{"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/signatureCache.cjs

@@ -145,12 +145,18 @@ class SignatureCache {
     return (0, import_viem.toHex)(hashBytes);
   }
   /**
-   * Deterministic JSON replacer that handles BigInt values and sorts object keys
-   * This ensures consistent cache key generation for EIP-712 typed data
+   * Deterministic JSON replacer for consistent cache key generation.
+   *
+   * @remarks
+   * Handles BigInt serialization and sorts object keys to ensure
+   * identical objects always produce the same hash regardless of
+   * property order.
    *
    * @param _key - The object key being serialized (unused)
    * @param value - The value to serialize
    * @returns The serialized value with sorted keys for objects
+   *
+   * @internal
    */
   static deterministicReplacer(_key, value) {
     if (typeof value === "bigint") {

package/dist/utils/signatureCache.cjs.map

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

package/dist/utils/signatureCache.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Provides signature caching to improve UX by avoiding repeated wallet prompts.
+ *
+ * @remarks
+ * This module implements a secure signature cache that stores signed messages
+ * temporarily to avoid repeatedly prompting users for the same signature.
+ * It uses platform-appropriate storage (sessionStorage in browser, memory in Node.js)
+ * and includes automatic expiration and cleanup.
+ *
+ * @category Utilities
+ * @module utils/signatureCache
+ */
 import type { Hash } from "viem";
 import type { VanaCacheAdapter } from "../platform/interface";
 /**
@@ -109,23 +121,52 @@ export declare class SignatureCache {
      */
     static hashMessage(message: object): string;
     /**
-     * Deterministic JSON replacer that handles BigInt values and sorts object keys
-     * This ensures consistent cache key generation for EIP-712 typed data
+     * Deterministic JSON replacer for consistent cache key generation.
+     *
+     * @remarks
+     * Handles BigInt serialization and sorts object keys to ensure
+     * identical objects always produce the same hash regardless of
+     * property order.
      *
      * @param _key - The object key being serialized (unused)
      * @param value - The value to serialize
      * @returns The serialized value with sorted keys for objects
+     *
+     * @internal
      */
     private static deterministicReplacer;
 }
 /**
- * Wrapper function to cache signature operations
+ * Wraps signature operations with caching to avoid repeated prompts.
  *
- * @param cache - The cache adapter to use for storage
- * @param walletAddress - The wallet address signing the message
- * @param typedData - The EIP-712 typed data being signed
- * @param signFn - Function that performs the actual signing
- * @param ttlHours - Cache TTL in hours (default 2)
+ * @remarks
+ * This helper function checks the cache before requesting a signature
+ * and stores new signatures for future use. It significantly improves
+ * UX for operations that may be retried or called multiple times.
+ *
+ * @param cache - The cache adapter to use for storage.
+ *   Obtain from platform adapter.
+ * @param walletAddress - The wallet address signing the message.
+ *   Obtain from wallet connection.
+ * @param typedData - The EIP-712 typed data being signed.
+ *   Typically permission or grant data.
+ * @param signFn - Async function that performs the actual signing.
+ *   Usually calls wallet.signTypedData().
+ * @param ttlHours - Cache TTL in hours.
+ *   Defaults to 2 hours.
  * @returns The signature (cached or newly generated)
+ *
+ * @example
+ * ```typescript
+ * const signature = await withSignatureCache(
+ *   platformAdapter.cache,
+ *   walletAddress,
+ *   typedData,
+ *   async () => wallet.signTypedData(typedData),
+ *   24 // Cache for 24 hours
+ * );
+ * ```
+ *
+ * @category Utilities
  */
 export declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: string, typedData: Record<string, unknown>, signFn: () => Promise<Hash>, ttlHours?: number): Promise<Hash>;

package/dist/utils/signatureCache.js

@@ -121,12 +121,18 @@ class SignatureCache {
     return toHex(hashBytes);
   }
   /**
-   * Deterministic JSON replacer that handles BigInt values and sorts object keys
-   * This ensures consistent cache key generation for EIP-712 typed data
+   * Deterministic JSON replacer for consistent cache key generation.
+   *
+   * @remarks
+   * Handles BigInt serialization and sorts object keys to ensure
+   * identical objects always produce the same hash regardless of
+   * property order.
    *
    * @param _key - The object key being serialized (unused)
    * @param value - The value to serialize
    * @returns The serialized value with sorted keys for objects
+   *
+   * @internal
    */
   static deterministicReplacer(_key, value) {
     if (typeof value === "bigint") {

package/dist/utils/signatureCache.js.map

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

package/dist/utils/transactionHelpers.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/transactionHelpers.ts"],"sourcesContent":["/**\n * Helper functions for creating typed transaction POJOs\n */\n\nimport type { Hash, Address } from \"viem\";\nimport type { TransactionResult } from \"../types/operations\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n/**\n * Creates a strongly-typed TransactionResult POJO.\n *\n * @remarks\n * This helper ensures all required fields are present and typed correctly,\n * reducing boilerplate and preventing mistakes.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n *\n * @example\n * ```typescript\n * return tx({\n *   hash,\n *   from: account.address,\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * ```\n */\nexport function tx<C extends Contract, F extends Fn<C>>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n\n/**\n * Creates a transaction result with literal type inference.\n * Use this when you need TypeScript to preserve exact string literals.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n *\n * @example\n * ```typescript\n * const transaction = txLiteral({\n *   hash: '0x...',\n *   from: '0x...',\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission\n * ```\n */\nexport function txLiteral<\n  const C extends Contract,\n  const F extends Fn<C>,\n>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAoCO,SAAS,GAAwC,OAS5B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;AA4BO,SAAS,UAGd,OAS0B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/transactionHelpers.ts"],"sourcesContent":["/**\n * Helper functions for creating typed transaction POJOs\n */\n\nimport type { Hash, Address } from \"viem\";\nimport type { TransactionResult } from \"../types/operations\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n/**\n * Creates typed TransactionResult with validation.\n *\n * @remarks\n * Ensures type safety for transaction results.\n * Reduces boilerplate in transaction handling.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash from the blockchain\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name being called\n * @param input.fn - Function name being executed\n * @param input.chainId - Optional chain ID for network identification\n * @param input.value - Optional transaction value in wei\n * @param input.nonce - Optional transaction nonce for ordering\n * @param input.to - Optional recipient address for the transaction\n * @returns Typed TransactionResult POJO\n *\n * @example\n * ```typescript\n * return tx({\n *   hash,\n *   from: account.address,\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\"\n * });\n * ```\n */\nexport function tx<C extends Contract, F extends Fn<C>>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n\n/**\n * Creates a transaction result with literal type inference.\n * Use this when you need TypeScript to preserve exact string literals.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n *\n * @example\n * ```typescript\n * const transaction = txLiteral({\n *   hash: '0x...',\n *   from: '0x...',\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission\n * ```\n */\nexport function txLiteral<\n  const C extends Contract,\n  const F extends Fn<C>,\n>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAoCO,SAAS,GAAwC,OAS5B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;AA4BO,SAAS,UAGd,OAS0B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;","names":[]}

package/dist/utils/transactionHelpers.d.ts

@@ -5,22 +5,22 @@ import type { Hash, Address } from "viem";
 import type { TransactionResult } from "../types/operations";
 import type { Contract, Fn } from "../generated/event-types";
 /**
- * Creates a strongly-typed TransactionResult POJO.
+ * Creates typed TransactionResult with validation.
  *
  * @remarks
- * This helper ensures all required fields are present and typed correctly,
- * reducing boilerplate and preventing mistakes.
+ * Ensures type safety for transaction results.
+ * Reduces boilerplate in transaction handling.
  *
  * @param input - Transaction details
- * @param input.hash - Transaction hash
+ * @param input.hash - Transaction hash from the blockchain
  * @param input.from - Transaction sender address
- * @param input.contract - Contract name
- * @param input.fn - Function name
- * @param input.chainId - Optional chain ID
- * @param input.value - Optional transaction value
- * @param input.nonce - Optional nonce
- * @param input.to - Optional recipient address
- * @returns Typed TransactionResult
+ * @param input.contract - Contract name being called
+ * @param input.fn - Function name being executed
+ * @param input.chainId - Optional chain ID for network identification
+ * @param input.value - Optional transaction value in wei
+ * @param input.nonce - Optional transaction nonce for ordering
+ * @param input.to - Optional recipient address for the transaction
+ * @returns Typed TransactionResult POJO
  *
  * @example
  * ```typescript
@@ -28,7 +28,7 @@ import type { Contract, Fn } from "../generated/event-types";
  *   hash,
  *   from: account.address,
  *   contract: "DataPortabilityPermissions",
- *   fn: "revokePermission",
+ *   fn: "revokePermission"
  * });
  * ```
  */

package/dist/utils/transactionHelpers.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/transactionHelpers.ts"],"sourcesContent":["/**\n * Helper functions for creating typed transaction POJOs\n */\n\nimport type { Hash, Address } from \"viem\";\nimport type { TransactionResult } from \"../types/operations\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n/**\n * Creates a strongly-typed TransactionResult POJO.\n *\n * @remarks\n * This helper ensures all required fields are present and typed correctly,\n * reducing boilerplate and preventing mistakes.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n *\n * @example\n * ```typescript\n * return tx({\n *   hash,\n *   from: account.address,\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * ```\n */\nexport function tx<C extends Contract, F extends Fn<C>>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n\n/**\n * Creates a transaction result with literal type inference.\n * Use this when you need TypeScript to preserve exact string literals.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n *\n * @example\n * ```typescript\n * const transaction = txLiteral({\n *   hash: '0x...',\n *   from: '0x...',\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission\n * ```\n */\nexport function txLiteral<\n  const C extends Contract,\n  const F extends Fn<C>,\n>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n"],"mappings":"AAoCO,SAAS,GAAwC,OAS5B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;AA4BO,SAAS,UAGd,OAS0B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/transactionHelpers.ts"],"sourcesContent":["/**\n * Helper functions for creating typed transaction POJOs\n */\n\nimport type { Hash, Address } from \"viem\";\nimport type { TransactionResult } from \"../types/operations\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n/**\n * Creates typed TransactionResult with validation.\n *\n * @remarks\n * Ensures type safety for transaction results.\n * Reduces boilerplate in transaction handling.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash from the blockchain\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name being called\n * @param input.fn - Function name being executed\n * @param input.chainId - Optional chain ID for network identification\n * @param input.value - Optional transaction value in wei\n * @param input.nonce - Optional transaction nonce for ordering\n * @param input.to - Optional recipient address for the transaction\n * @returns Typed TransactionResult POJO\n *\n * @example\n * ```typescript\n * return tx({\n *   hash,\n *   from: account.address,\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\"\n * });\n * ```\n */\nexport function tx<C extends Contract, F extends Fn<C>>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n\n/**\n * Creates a transaction result with literal type inference.\n * Use this when you need TypeScript to preserve exact string literals.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n *\n * @example\n * ```typescript\n * const transaction = txLiteral({\n *   hash: '0x...',\n *   from: '0x...',\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission\n * ```\n */\nexport function txLiteral<\n  const C extends Contract,\n  const F extends Fn<C>,\n>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n"],"mappings":"AAoCO,SAAS,GAAwC,OAS5B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;AA4BO,SAAS,UAGd,OAS0B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;","names":[]}

package/dist/utils/typedDataConverter.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["import type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.\n * This function ensures type safety when passing typed data to viem's signTypedData method.\n *\n * @param typedData - The typed data object to convert\n * @returns A properly typed TypedDataDefinition for use with viem\n */\nexport function toViemTypedDataDefinition(\n  typedData: GenericTypedData,\n): TypedDataDefinition {\n  // Transform the types to match viem's expected format with readonly arrays\n  const viemTypes: Record<string, readonly { name: string; type: string }[]> =\n    {};\n\n  for (const [typeName, typeArray] of Object.entries(typedData.types)) {\n    // Create a new readonly array for each type\n    viemTypes[typeName] = typeArray.map((field) => ({\n      name: field.name,\n      type: field.type,\n    })) as readonly { name: string; type: string }[];\n  }\n\n  return {\n    domain: typedData.domain,\n    types: viemTypes as TypedDataDefinition[\"types\"],\n    primaryType: typedData.primaryType,\n    message: typedData.message,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,SAAS,0BACd,WACqB;AAErB,QAAM,YACJ,CAAC;AAEH,aAAW,CAAC,UAAU,SAAS,KAAK,OAAO,QAAQ,UAAU,KAAK,GAAG;AAEnE,cAAU,QAAQ,IAAI,UAAU,IAAI,CAAC,WAAW;AAAA,MAC9C,MAAM,MAAM;AAAA,MACZ,MAAM,MAAM;AAAA,IACd,EAAE;AAAA,EACJ;AAEA,SAAO;AAAA,IACL,QAAQ,UAAU;AAAA,IAClB,OAAO;AAAA,IACP,aAAa,UAAU;AAAA,IACvB,SAAS,UAAU;AAAA,EACrB;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["/**\n * Provides type-safe conversion between Vana and viem typed data formats.\n *\n * @remarks\n * This module bridges the gap between Vana's generic typed data structure\n * and viem's strict TypedDataDefinition format, ensuring compatibility\n * for EIP-712 signature operations.\n *\n * @category Utilities\n * @module typedDataConverter\n */\n\nimport type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a viem-compatible TypedDataDefinition.\n *\n * @remarks\n * Transforms Vana's flexible typed data format into viem's strict format\n * with readonly arrays. This ensures type safety when passing typed data\n * to viem's `signTypedData` method for EIP-712 signatures.\n *\n * @param typedData - The typed data object to convert.\n *   Obtain from permission operations or server responses.\n * @returns A properly typed TypedDataDefinition for use with viem\n *\n * @example\n * ```typescript\n * const vanTypedData: GenericTypedData = {\n *   domain: { name: 'Vana', version: '1', chainId: 14800 },\n *   types: {\n *     Permission: [\n *       { name: 'grantee', type: 'address' },\n *       { name: 'operation', type: 'string' }\n *     ]\n *   },\n *   primaryType: 'Permission',\n *   message: { grantee: '0x...', operation: 'read' }\n * };\n *\n * const viemTypedData = toViemTypedDataDefinition(vanaTypedData);\n * const signature = await walletClient.signTypedData(viemTypedData);\n * ```\n *\n * @category Utilities\n */\nexport function toViemTypedDataDefinition(\n  typedData: GenericTypedData,\n): TypedDataDefinition {\n  // Transform the types to match viem's expected format with readonly arrays\n  const viemTypes: Record<string, readonly { name: string; type: string }[]> =\n    {};\n\n  for (const [typeName, typeArray] of Object.entries(typedData.types)) {\n    // Create a new readonly array for each type\n    viemTypes[typeName] = typeArray.map((field) => ({\n      name: field.name,\n      type: field.type,\n    })) as readonly { name: string; type: string }[];\n  }\n\n  return {\n    domain: typedData.domain,\n    types: viemTypes as TypedDataDefinition[\"types\"],\n    primaryType: typedData.primaryType,\n    message: typedData.message,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA+CO,SAAS,0BACd,WACqB;AAErB,QAAM,YACJ,CAAC;AAEH,aAAW,CAAC,UAAU,SAAS,KAAK,OAAO,QAAQ,UAAU,KAAK,GAAG;AAEnE,cAAU,QAAQ,IAAI,UAAU,IAAI,CAAC,WAAW;AAAA,MAC9C,MAAM,MAAM;AAAA,MACZ,MAAM,MAAM;AAAA,IACd,EAAE;AAAA,EACJ;AAEA,SAAO;AAAA,IACL,QAAQ,UAAU;AAAA,IAClB,OAAO;AAAA,IACP,aAAa,UAAU;AAAA,IACvB,SAAS,UAAU;AAAA,EACrB;AACF;","names":[]}

package/dist/utils/typedDataConverter.d.ts

@@ -1,10 +1,46 @@
+/**
+ * Provides type-safe conversion between Vana and viem typed data formats.
+ *
+ * @remarks
+ * This module bridges the gap between Vana's generic typed data structure
+ * and viem's strict TypedDataDefinition format, ensuring compatibility
+ * for EIP-712 signature operations.
+ *
+ * @category Utilities
+ * @module typedDataConverter
+ */
 import type { TypedDataDefinition } from "viem";
 import type { GenericTypedData } from "../types/permissions";
 /**
- * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.
- * This function ensures type safety when passing typed data to viem's signTypedData method.
+ * Converts a GenericTypedData object to a viem-compatible TypedDataDefinition.
  *
- * @param typedData - The typed data object to convert
+ * @remarks
+ * Transforms Vana's flexible typed data format into viem's strict format
+ * with readonly arrays. This ensures type safety when passing typed data
+ * to viem's `signTypedData` method for EIP-712 signatures.
+ *
+ * @param typedData - The typed data object to convert.
+ *   Obtain from permission operations or server responses.
  * @returns A properly typed TypedDataDefinition for use with viem
+ *
+ * @example
+ * ```typescript
+ * const vanTypedData: GenericTypedData = {
+ *   domain: { name: 'Vana', version: '1', chainId: 14800 },
+ *   types: {
+ *     Permission: [
+ *       { name: 'grantee', type: 'address' },
+ *       { name: 'operation', type: 'string' }
+ *     ]
+ *   },
+ *   primaryType: 'Permission',
+ *   message: { grantee: '0x...', operation: 'read' }
+ * };
+ *
+ * const viemTypedData = toViemTypedDataDefinition(vanaTypedData);
+ * const signature = await walletClient.signTypedData(viemTypedData);
+ * ```
+ *
+ * @category Utilities
  */
 export declare function toViemTypedDataDefinition(typedData: GenericTypedData): TypedDataDefinition;

package/dist/utils/typedDataConverter.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["import type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.\n * This function ensures type safety when passing typed data to viem's signTypedData method.\n *\n * @param typedData - The typed data object to convert\n * @returns A properly typed TypedDataDefinition for use with viem\n */\nexport function toViemTypedDataDefinition(\n  typedData: GenericTypedData,\n): TypedDataDefinition {\n  // Transform the types to match viem's expected format with readonly arrays\n  const viemTypes: Record<string, readonly { name: string; type: string }[]> =\n    {};\n\n  for (const [typeName, typeArray] of Object.entries(typedData.types)) {\n    // Create a new readonly array for each type\n    viemTypes[typeName] = typeArray.map((field) => ({\n      name: field.name,\n      type: field.type,\n    })) as readonly { name: string; type: string }[];\n  }\n\n  return {\n    domain: typedData.domain,\n    types: viemTypes as TypedDataDefinition[\"types\"],\n    primaryType: typedData.primaryType,\n    message: typedData.message,\n  };\n}\n"],"mappings":"AAUO,SAAS,0BACd,WACqB;AAErB,QAAM,YACJ,CAAC;AAEH,aAAW,CAAC,UAAU,SAAS,KAAK,OAAO,QAAQ,UAAU,KAAK,GAAG;AAEnE,cAAU,QAAQ,IAAI,UAAU,IAAI,CAAC,WAAW;AAAA,MAC9C,MAAM,MAAM;AAAA,MACZ,MAAM,MAAM;AAAA,IACd,EAAE;AAAA,EACJ;AAEA,SAAO;AAAA,IACL,QAAQ,UAAU;AAAA,IAClB,OAAO;AAAA,IACP,aAAa,UAAU;AAAA,IACvB,SAAS,UAAU;AAAA,EACrB;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["/**\n * Provides type-safe conversion between Vana and viem typed data formats.\n *\n * @remarks\n * This module bridges the gap between Vana's generic typed data structure\n * and viem's strict TypedDataDefinition format, ensuring compatibility\n * for EIP-712 signature operations.\n *\n * @category Utilities\n * @module typedDataConverter\n */\n\nimport type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a viem-compatible TypedDataDefinition.\n *\n * @remarks\n * Transforms Vana's flexible typed data format into viem's strict format\n * with readonly arrays. This ensures type safety when passing typed data\n * to viem's `signTypedData` method for EIP-712 signatures.\n *\n * @param typedData - The typed data object to convert.\n *   Obtain from permission operations or server responses.\n * @returns A properly typed TypedDataDefinition for use with viem\n *\n * @example\n * ```typescript\n * const vanTypedData: GenericTypedData = {\n *   domain: { name: 'Vana', version: '1', chainId: 14800 },\n *   types: {\n *     Permission: [\n *       { name: 'grantee', type: 'address' },\n *       { name: 'operation', type: 'string' }\n *     ]\n *   },\n *   primaryType: 'Permission',\n *   message: { grantee: '0x...', operation: 'read' }\n * };\n *\n * const viemTypedData = toViemTypedDataDefinition(vanaTypedData);\n * const signature = await walletClient.signTypedData(viemTypedData);\n * ```\n *\n * @category Utilities\n */\nexport function toViemTypedDataDefinition(\n  typedData: GenericTypedData,\n): TypedDataDefinition {\n  // Transform the types to match viem's expected format with readonly arrays\n  const viemTypes: Record<string, readonly { name: string; type: string }[]> =\n    {};\n\n  for (const [typeName, typeArray] of Object.entries(typedData.types)) {\n    // Create a new readonly array for each type\n    viemTypes[typeName] = typeArray.map((field) => ({\n      name: field.name,\n      type: field.type,\n    })) as readonly { name: string; type: string }[];\n  }\n\n  return {\n    domain: typedData.domain,\n    types: viemTypes as TypedDataDefinition[\"types\"],\n    primaryType: typedData.primaryType,\n    message: typedData.message,\n  };\n}\n"],"mappings":"AA+CO,SAAS,0BACd,WACqB;AAErB,QAAM,YACJ,CAAC;AAEH,aAAW,CAAC,UAAU,SAAS,KAAK,OAAO,QAAQ,UAAU,KAAK,GAAG;AAEnE,cAAU,QAAQ,IAAI,UAAU,IAAI,CAAC,WAAW;AAAA,MAC9C,MAAM,MAAM;AAAA,MACZ,MAAM,MAAM;AAAA,IACd,EAAE;AAAA,EACJ;AAEA,SAAO;AAAA,IACL,QAAQ,UAAU;AAAA,IAClB,OAAO;AAAA,IACP,aAAa,UAAU;AAAA,IACvB,SAAS,UAAU;AAAA,EACrB;AACF;","names":[]}

package/dist/utils/urlResolver.cjs

@@ -24,6 +24,13 @@ __export(urlResolver_exports, {
 module.exports = __toCommonJS(urlResolver_exports);
 var import_download = require("./download");
 class UrlResolutionError extends Error {
+  /**
+   * Creates a new URL resolution error.
+   *
+   * @param message - Description of what went wrong
+   * @param url - The URL that failed to resolve
+   * @param cause - The underlying error that caused the failure
+   */
   constructor(message, url, cause) {
     super(message);
     this.url = url;

package/dist/utils/urlResolver.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Universal URL resolver for the Vana SDK\n *\n * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)\n * in a consistent, reliable way.\n */\n\nimport { universalFetch } from \"./download\";\n\n/**\n * Error thrown when URL resolution fails\n */\nexport class UrlResolutionError extends Error {\n  constructor(\n    message: string,\n    public readonly url: string,\n    public override readonly cause?: Error,\n  ) {\n    super(message);\n    this.name = \"UrlResolutionError\";\n  }\n}\n\n/**\n * Fetches and parses JSON data from any supported URL protocol\n *\n * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns Promise resolving to the parsed JSON data\n * @throws {UrlResolutionError} When the URL cannot be resolved or parsed\n *\n * @example\n * ```typescript\n * // Fetch from IPFS\n * const data = await fetchFromUrl(\"ipfs://QmXxx...\");\n *\n * // Fetch from HTTPS\n * const data = await fetchFromUrl(\"https://example.com/data.json\");\n *\n * // Handles protocol conversion internally\n * const schema = await fetchFromUrl(schemaDefinitionUrl);\n * ```\n */\nexport async function fetchFromUrl(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<unknown> {\n  try {\n    // Use unified download utility with automatic fallbacks\n    const response = await universalFetch(url, downloadRelayer);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n\n    // Parse JSON response\n    const data = await response.json();\n    return data;\n  } catch (error) {\n    throw new UrlResolutionError(\n      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      url,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,sBAA+B;AAKxB,MAAM,2BAA2B,MAAM;AAAA,EAC5C,YACE,SACgB,KACS,OACzB;AACA,UAAM,OAAO;AAHG;AACS;AAGzB,SAAK,OAAO;AAAA,EACd;AACF;AAuBA,eAAsB,aACpB,KACA,iBACkB;AAClB,MAAI;AAEF,UAAM,WAAW,UAAM,gCAAe,KAAK,eAAe;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,QAAQ,SAAS,MAAM,KAAK,SAAS,UAAU,EAAE;AAAA,IACnE;AAGA,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,wBAAwB,GAAG,KAAK,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACxF;AAAA,MACA,iBAAiB,QAAQ,QAAQ;AAAA,IACnC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Provides universal URL resolution across multiple protocols.\n *\n * @remarks\n * This module enables fetching data from various protocols including IPFS,\n * HTTP/HTTPS, and Arweave through a unified interface. It handles protocol\n * conversion, gateway selection, and fallback strategies automatically.\n *\n * @category Utilities\n * @module utils/urlResolver\n */\n\nimport { universalFetch } from \"./download\";\n\n/**\n * Indicates that URL resolution or data fetching failed.\n *\n * @remarks\n * This error provides context about which URL failed and why,\n * making it easier to debug issues with external resources.\n *\n * @category Errors\n */\nexport class UrlResolutionError extends Error {\n  /**\n   * Creates a new URL resolution error.\n   *\n   * @param message - Description of what went wrong\n   * @param url - The URL that failed to resolve\n   * @param cause - The underlying error that caused the failure\n   */\n  constructor(\n    message: string,\n    public readonly url: string,\n    public override readonly cause?: Error,\n  ) {\n    super(message);\n    this.name = \"UrlResolutionError\";\n  }\n}\n\n/**\n * Fetches and parses JSON data from any supported URL protocol\n *\n * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns Promise resolving to the parsed JSON data\n * @throws {UrlResolutionError} When the URL cannot be resolved or parsed\n *\n * @example\n * ```typescript\n * // Fetch from IPFS\n * const data = await fetchFromUrl(\"ipfs://QmXxx...\");\n *\n * // Fetch from HTTPS\n * const data = await fetchFromUrl(\"https://example.com/data.json\");\n *\n * // Handles protocol conversion internally\n * const schema = await fetchFromUrl(schemaDefinitionUrl);\n * ```\n */\nexport async function fetchFromUrl(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<unknown> {\n  try {\n    // Use unified download utility with automatic fallbacks\n    const response = await universalFetch(url, downloadRelayer);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n\n    // Parse JSON response\n    const data = await response.json();\n    return data;\n  } catch (error) {\n    throw new UrlResolutionError(\n      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      url,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYA,sBAA+B;AAWxB,MAAM,2BAA2B,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ5C,YACE,SACgB,KACS,OACzB;AACA,UAAM,OAAO;AAHG;AACS;AAGzB,SAAK,OAAO;AAAA,EACd;AACF;AAuBA,eAAsB,aACpB,KACA,iBACkB;AAClB,MAAI;AAEF,UAAM,WAAW,UAAM,gCAAe,KAAK,eAAe;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,QAAQ,SAAS,MAAM,KAAK,SAAS,UAAU,EAAE;AAAA,IACnE;AAGA,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,wBAAwB,GAAG,KAAK,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACxF;AAAA,MACA,iBAAiB,QAAQ,QAAQ;AAAA,IACnC;AAAA,EACF;AACF;","names":[]}

package/dist/utils/urlResolver.d.ts

@@ -1,15 +1,33 @@
 /**
- * Universal URL resolver for the Vana SDK
+ * Provides universal URL resolution across multiple protocols.
  *
- * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)
- * in a consistent, reliable way.
+ * @remarks
+ * This module enables fetching data from various protocols including IPFS,
+ * HTTP/HTTPS, and Arweave through a unified interface. It handles protocol
+ * conversion, gateway selection, and fallback strategies automatically.
+ *
+ * @category Utilities
+ * @module utils/urlResolver
  */
 /**
- * Error thrown when URL resolution fails
+ * Indicates that URL resolution or data fetching failed.
+ *
+ * @remarks
+ * This error provides context about which URL failed and why,
+ * making it easier to debug issues with external resources.
+ *
+ * @category Errors
  */
 export declare class UrlResolutionError extends Error {
     readonly url: string;
     readonly cause?: Error | undefined;
+    /**
+     * Creates a new URL resolution error.
+     *
+     * @param message - Description of what went wrong
+     * @param url - The URL that failed to resolve
+     * @param cause - The underlying error that caused the failure
+     */
     constructor(message: string, url: string, cause?: Error | undefined);
 }
 /**

package/dist/utils/urlResolver.js

@@ -1,5 +1,12 @@
 import { universalFetch } from "./download";
 class UrlResolutionError extends Error {
+  /**
+   * Creates a new URL resolution error.
+   *
+   * @param message - Description of what went wrong
+   * @param url - The URL that failed to resolve
+   * @param cause - The underlying error that caused the failure
+   */
   constructor(message, url, cause) {
     super(message);
     this.url = url;

package/dist/utils/urlResolver.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Universal URL resolver for the Vana SDK\n *\n * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)\n * in a consistent, reliable way.\n */\n\nimport { universalFetch } from \"./download\";\n\n/**\n * Error thrown when URL resolution fails\n */\nexport class UrlResolutionError extends Error {\n  constructor(\n    message: string,\n    public readonly url: string,\n    public override readonly cause?: Error,\n  ) {\n    super(message);\n    this.name = \"UrlResolutionError\";\n  }\n}\n\n/**\n * Fetches and parses JSON data from any supported URL protocol\n *\n * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns Promise resolving to the parsed JSON data\n * @throws {UrlResolutionError} When the URL cannot be resolved or parsed\n *\n * @example\n * ```typescript\n * // Fetch from IPFS\n * const data = await fetchFromUrl(\"ipfs://QmXxx...\");\n *\n * // Fetch from HTTPS\n * const data = await fetchFromUrl(\"https://example.com/data.json\");\n *\n * // Handles protocol conversion internally\n * const schema = await fetchFromUrl(schemaDefinitionUrl);\n * ```\n */\nexport async function fetchFromUrl(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<unknown> {\n  try {\n    // Use unified download utility with automatic fallbacks\n    const response = await universalFetch(url, downloadRelayer);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n\n    // Parse JSON response\n    const data = await response.json();\n    return data;\n  } catch (error) {\n    throw new UrlResolutionError(\n      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      url,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n"],"mappings":"AAOA,SAAS,sBAAsB;AAKxB,MAAM,2BAA2B,MAAM;AAAA,EAC5C,YACE,SACgB,KACS,OACzB;AACA,UAAM,OAAO;AAHG;AACS;AAGzB,SAAK,OAAO;AAAA,EACd;AACF;AAuBA,eAAsB,aACpB,KACA,iBACkB;AAClB,MAAI;AAEF,UAAM,WAAW,MAAM,eAAe,KAAK,eAAe;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,QAAQ,SAAS,MAAM,KAAK,SAAS,UAAU,EAAE;AAAA,IACnE;AAGA,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,wBAAwB,GAAG,KAAK,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACxF;AAAA,MACA,iBAAiB,QAAQ,QAAQ;AAAA,IACnC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Provides universal URL resolution across multiple protocols.\n *\n * @remarks\n * This module enables fetching data from various protocols including IPFS,\n * HTTP/HTTPS, and Arweave through a unified interface. It handles protocol\n * conversion, gateway selection, and fallback strategies automatically.\n *\n * @category Utilities\n * @module utils/urlResolver\n */\n\nimport { universalFetch } from \"./download\";\n\n/**\n * Indicates that URL resolution or data fetching failed.\n *\n * @remarks\n * This error provides context about which URL failed and why,\n * making it easier to debug issues with external resources.\n *\n * @category Errors\n */\nexport class UrlResolutionError extends Error {\n  /**\n   * Creates a new URL resolution error.\n   *\n   * @param message - Description of what went wrong\n   * @param url - The URL that failed to resolve\n   * @param cause - The underlying error that caused the failure\n   */\n  constructor(\n    message: string,\n    public readonly url: string,\n    public override readonly cause?: Error,\n  ) {\n    super(message);\n    this.name = \"UrlResolutionError\";\n  }\n}\n\n/**\n * Fetches and parses JSON data from any supported URL protocol\n *\n * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns Promise resolving to the parsed JSON data\n * @throws {UrlResolutionError} When the URL cannot be resolved or parsed\n *\n * @example\n * ```typescript\n * // Fetch from IPFS\n * const data = await fetchFromUrl(\"ipfs://QmXxx...\");\n *\n * // Fetch from HTTPS\n * const data = await fetchFromUrl(\"https://example.com/data.json\");\n *\n * // Handles protocol conversion internally\n * const schema = await fetchFromUrl(schemaDefinitionUrl);\n * ```\n */\nexport async function fetchFromUrl(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<unknown> {\n  try {\n    // Use unified download utility with automatic fallbacks\n    const response = await universalFetch(url, downloadRelayer);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n\n    // Parse JSON response\n    const data = await response.json();\n    return data;\n  } catch (error) {\n    throw new UrlResolutionError(\n      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      url,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n"],"mappings":"AAYA,SAAS,sBAAsB;AAWxB,MAAM,2BAA2B,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ5C,YACE,SACgB,KACS,OACzB;AACA,UAAM,OAAO;AAHG;AACS;AAGzB,SAAK,OAAO;AAAA,EACd;AACF;AAuBA,eAAsB,aACpB,KACA,iBACkB;AAClB,MAAI;AAEF,UAAM,WAAW,MAAM,eAAe,KAAK,eAAe;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,QAAQ,SAAS,MAAM,KAAK,SAAS,UAAU,EAAE;AAAA,IACnE;AAGA,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,wBAAwB,GAAG,KAAK,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACxF;AAAA,MACA,iBAAiB,QAAQ,QAAQ;AAAA,IACnC;AAAA,EACF;AACF;","names":[]}

package/dist/utils/wallet.cjs

@@ -48,7 +48,8 @@ function hasAddress(account) {
     return /^0x[a-fA-F0-9]{40}$/.test(account);
   }
   if (typeof account === "object" && "address" in account) {
-    const addr = account.address;
+    const accountWithAddress = account;
+    const addr = accountWithAddress.address;
     return typeof addr === "string" && /^0x[a-fA-F0-9]{40}$/.test(addr);
   }
   return false;