@opendatalabs/vana-sdk 0.1.0-alpha.273dc39 → 0.1.0-alpha.276ea01

package/dist/utils/signatureCache.cjs

@@ -0,0 +1,187 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var signatureCache_exports = {};
+__export(signatureCache_exports, {
+  SignatureCache: () => SignatureCache,
+  withSignatureCache: () => withSignatureCache
+});
+module.exports = __toCommonJS(signatureCache_exports);
+var import_viem = require("viem");
+var import_sha256 = require("@noble/hashes/sha256");
+var import_utils = require("@noble/hashes/utils");
+class SignatureCache {
+  static PREFIX = "vana_sig_";
+  static DEFAULT_TTL_HOURS = 2;
+  /**
+   * Get a cached signature if it exists and hasn't expired
+   *
+   * @param cache - Platform cache adapter instance
+   * @param walletAddress - Wallet address that created the signature
+   * @param messageHash - Hash of the message that was signed
+   * @returns The cached signature if valid, null if expired or not found
+   * @example
+   * ```typescript
+   * const messageHash = SignatureCache.hashMessage(typedData);
+   * const cached = SignatureCache.get(cache, '0x123...', messageHash);
+   * if (cached) {
+   *   console.log('Using cached signature:', cached);
+   * }
+   * ```
+   */
+  static get(cache, walletAddress, messageHash) {
+    const key = this.getCacheKey(walletAddress, messageHash);
+    try {
+      const stored = cache.get(key);
+      if (!stored) return null;
+      const cached = JSON.parse(stored);
+      if (Date.now() > cached.expires) {
+        cache.delete(key);
+        return null;
+      }
+      return cached.signature;
+    } catch {
+      try {
+        cache.delete(key);
+      } catch {
+      }
+      return null;
+    }
+  }
+  /**
+   * Store a signature in the cache with configurable TTL
+   *
+   * @param cache - Platform cache adapter instance
+   * @param walletAddress - Wallet address that created the signature
+   * @param messageHash - Hash of the message that was signed
+   * @param signature - The signature to cache
+   * @param ttlHours - Time to live in hours (default: 2)
+   * @example
+   * ```typescript
+   * const signature = await wallet.signTypedData(typedData);
+   * const messageHash = SignatureCache.hashMessage(typedData);
+   *
+   * // Cache for default 2 hours
+   * SignatureCache.set(cache, walletAddress, messageHash, signature);
+   *
+   * // Cache for 24 hours
+   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);
+   * ```
+   */
+  static set(cache, walletAddress, messageHash, signature, ttlHours = this.DEFAULT_TTL_HOURS) {
+    const key = this.getCacheKey(walletAddress, messageHash);
+    const cached = {
+      signature,
+      expires: Date.now() + ttlHours * 36e5
+      // Convert hours to milliseconds
+    };
+    try {
+      cache.set(key, JSON.stringify(cached));
+    } catch {
+    }
+  }
+  /**
+   * Clear all cached signatures (useful for testing or explicit cleanup)
+   *
+   * @param cache - Platform cache adapter instance
+   * @example
+   * ```typescript
+   * // Clear all signatures when user logs out
+   * SignatureCache.clear(cache);
+   *
+   * // Clear before running tests
+   * beforeEach(() => {
+   *   SignatureCache.clear(cache);
+   * });
+   * ```
+   */
+  static clear(cache) {
+    try {
+      cache.clear();
+    } catch {
+    }
+  }
+  static getCacheKey(walletAddress, messageHash) {
+    return `${this.PREFIX}${(0, import_viem.getAddress)(walletAddress)}:${messageHash}`;
+  }
+  /**
+   * Generate a deterministic hash of a message object for cache key generation
+   *
+   * @remarks
+   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.
+   * Uses SHA-256 for collision resistance and deterministic key generation.
+   * Handles BigInt serialization and sorts object keys for consistency.
+   *
+   * @param message - The message object to hash (typically EIP-712 typed data)
+   * @returns A hex string hash (SHA-256) suitable for cache keys
+   * @example
+   * ```typescript
+   * const typedData = {
+   *   domain: { name: 'Vana', version: '1' },
+   *   message: { nonce: 123n, grant: '...' }
+   * };
+   *
+   * const hash = SignatureCache.hashMessage(typedData);
+   * // Returns SHA-256 hash like: "a1b2c3d4e5f6..."
+   * ```
+   */
+  static hashMessage(message) {
+    const jsonString = JSON.stringify(message, this.deterministicReplacer);
+    const hashBytes = (0, import_sha256.sha256)(new TextEncoder().encode(jsonString));
+    return (0, import_utils.bytesToHex)(hashBytes);
+  }
+  /**
+   * Deterministic JSON replacer that handles BigInt values and sorts object keys
+   * This ensures consistent cache key generation for EIP-712 typed data
+   *
+   * @param _key - The object key being serialized (unused)
+   * @param value - The value to serialize
+   * @returns The serialized value with sorted keys for objects
+   */
+  static deterministicReplacer(_key, value) {
+    if (typeof value === "bigint") {
+      return `__BIGINT__${value.toString()}`;
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce(
+        (sorted, key) => {
+          sorted[key] = value[key];
+          return sorted;
+        },
+        {}
+      );
+    }
+    return value;
+  }
+}
+async function withSignatureCache(cache, walletAddress, typedData, signFn, ttlHours) {
+  const messageHash = SignatureCache.hashMessage(typedData);
+  const cached = SignatureCache.get(cache, walletAddress, messageHash);
+  if (cached) {
+    return cached;
+  }
+  const signature = await signFn();
+  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);
+  return signature;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SignatureCache,
+  withSignatureCache
+});
+//# sourceMappingURL=signatureCache.cjs.map

package/dist/utils/signatureCache.cjs.map

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

package/dist/utils/signatureCache.d.cts

@@ -0,0 +1,134 @@
+import { Hash } from 'viem';
+import { VanaCacheAdapter } from '../platform/interface.cjs';
+
+/**
+ * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.
+ *
+ * @remarks
+ * This cache significantly improves UX by avoiding repeated wallet signature prompts
+ * for identical operations. It's particularly useful for operations that may be
+ * retried or called multiple times with the same parameters.
+ *
+ * Features:
+ * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)
+ * - Configurable TTL (default 2 hours)
+ * - Automatic cleanup of expired entries
+ * - Cache keys based on wallet address + message hash
+ *
+ * @example
+ * ```typescript
+ * // Check cache before requesting signature
+ * const cached = SignatureCache.get(cache, walletAddress, messageHash);
+ * if (cached) {
+ *   return cached;
+ * }
+ *
+ * // Request signature and cache it
+ * const signature = await wallet.signTypedData(typedData);
+ * SignatureCache.set(cache, walletAddress, messageHash, signature);
+ * ```
+ * @category Utilities
+ */
+declare class SignatureCache {
+    private static readonly PREFIX;
+    private static readonly DEFAULT_TTL_HOURS;
+    /**
+     * Get a cached signature if it exists and hasn't expired
+     *
+     * @param cache - Platform cache adapter instance
+     * @param walletAddress - Wallet address that created the signature
+     * @param messageHash - Hash of the message that was signed
+     * @returns The cached signature if valid, null if expired or not found
+     * @example
+     * ```typescript
+     * const messageHash = SignatureCache.hashMessage(typedData);
+     * const cached = SignatureCache.get(cache, '0x123...', messageHash);
+     * if (cached) {
+     *   console.log('Using cached signature:', cached);
+     * }
+     * ```
+     */
+    static get(cache: VanaCacheAdapter, walletAddress: string, messageHash: string): Hash | null;
+    /**
+     * Store a signature in the cache with configurable TTL
+     *
+     * @param cache - Platform cache adapter instance
+     * @param walletAddress - Wallet address that created the signature
+     * @param messageHash - Hash of the message that was signed
+     * @param signature - The signature to cache
+     * @param ttlHours - Time to live in hours (default: 2)
+     * @example
+     * ```typescript
+     * const signature = await wallet.signTypedData(typedData);
+     * const messageHash = SignatureCache.hashMessage(typedData);
+     *
+     * // Cache for default 2 hours
+     * SignatureCache.set(cache, walletAddress, messageHash, signature);
+     *
+     * // Cache for 24 hours
+     * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);
+     * ```
+     */
+    static set(cache: VanaCacheAdapter, walletAddress: string, messageHash: string, signature: Hash, ttlHours?: number): void;
+    /**
+     * Clear all cached signatures (useful for testing or explicit cleanup)
+     *
+     * @param cache - Platform cache adapter instance
+     * @example
+     * ```typescript
+     * // Clear all signatures when user logs out
+     * SignatureCache.clear(cache);
+     *
+     * // Clear before running tests
+     * beforeEach(() => {
+     *   SignatureCache.clear(cache);
+     * });
+     * ```
+     */
+    static clear(cache: VanaCacheAdapter): void;
+    private static getCacheKey;
+    /**
+     * Generate a deterministic hash of a message object for cache key generation
+     *
+     * @remarks
+     * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.
+     * Uses SHA-256 for collision resistance and deterministic key generation.
+     * Handles BigInt serialization and sorts object keys for consistency.
+     *
+     * @param message - The message object to hash (typically EIP-712 typed data)
+     * @returns A hex string hash (SHA-256) suitable for cache keys
+     * @example
+     * ```typescript
+     * const typedData = {
+     *   domain: { name: 'Vana', version: '1' },
+     *   message: { nonce: 123n, grant: '...' }
+     * };
+     *
+     * const hash = SignatureCache.hashMessage(typedData);
+     * // Returns SHA-256 hash like: "a1b2c3d4e5f6..."
+     * ```
+     */
+    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
+     *
+     * @param _key - The object key being serialized (unused)
+     * @param value - The value to serialize
+     * @returns The serialized value with sorted keys for objects
+     */
+    private static deterministicReplacer;
+}
+/**
+ * Wrapper function to cache signature operations
+ *
+ * @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)
+ * @returns The signature (cached or newly generated)
+ */
+declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: string, typedData: Record<string, unknown>, signFn: () => Promise<Hash>, ttlHours?: number): Promise<Hash>;
+
+export { SignatureCache, withSignatureCache };

package/dist/utils/signatureCache.d.ts

@@ -0,0 +1,134 @@
+import { Hash } from 'viem';
+import { VanaCacheAdapter } from '../platform/interface.js';
+
+/**
+ * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.
+ *
+ * @remarks
+ * This cache significantly improves UX by avoiding repeated wallet signature prompts
+ * for identical operations. It's particularly useful for operations that may be
+ * retried or called multiple times with the same parameters.
+ *
+ * Features:
+ * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)
+ * - Configurable TTL (default 2 hours)
+ * - Automatic cleanup of expired entries
+ * - Cache keys based on wallet address + message hash
+ *
+ * @example
+ * ```typescript
+ * // Check cache before requesting signature
+ * const cached = SignatureCache.get(cache, walletAddress, messageHash);
+ * if (cached) {
+ *   return cached;
+ * }
+ *
+ * // Request signature and cache it
+ * const signature = await wallet.signTypedData(typedData);
+ * SignatureCache.set(cache, walletAddress, messageHash, signature);
+ * ```
+ * @category Utilities
+ */
+declare class SignatureCache {
+    private static readonly PREFIX;
+    private static readonly DEFAULT_TTL_HOURS;
+    /**
+     * Get a cached signature if it exists and hasn't expired
+     *
+     * @param cache - Platform cache adapter instance
+     * @param walletAddress - Wallet address that created the signature
+     * @param messageHash - Hash of the message that was signed
+     * @returns The cached signature if valid, null if expired or not found
+     * @example
+     * ```typescript
+     * const messageHash = SignatureCache.hashMessage(typedData);
+     * const cached = SignatureCache.get(cache, '0x123...', messageHash);
+     * if (cached) {
+     *   console.log('Using cached signature:', cached);
+     * }
+     * ```
+     */
+    static get(cache: VanaCacheAdapter, walletAddress: string, messageHash: string): Hash | null;
+    /**
+     * Store a signature in the cache with configurable TTL
+     *
+     * @param cache - Platform cache adapter instance
+     * @param walletAddress - Wallet address that created the signature
+     * @param messageHash - Hash of the message that was signed
+     * @param signature - The signature to cache
+     * @param ttlHours - Time to live in hours (default: 2)
+     * @example
+     * ```typescript
+     * const signature = await wallet.signTypedData(typedData);
+     * const messageHash = SignatureCache.hashMessage(typedData);
+     *
+     * // Cache for default 2 hours
+     * SignatureCache.set(cache, walletAddress, messageHash, signature);
+     *
+     * // Cache for 24 hours
+     * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);
+     * ```
+     */
+    static set(cache: VanaCacheAdapter, walletAddress: string, messageHash: string, signature: Hash, ttlHours?: number): void;
+    /**
+     * Clear all cached signatures (useful for testing or explicit cleanup)
+     *
+     * @param cache - Platform cache adapter instance
+     * @example
+     * ```typescript
+     * // Clear all signatures when user logs out
+     * SignatureCache.clear(cache);
+     *
+     * // Clear before running tests
+     * beforeEach(() => {
+     *   SignatureCache.clear(cache);
+     * });
+     * ```
+     */
+    static clear(cache: VanaCacheAdapter): void;
+    private static getCacheKey;
+    /**
+     * Generate a deterministic hash of a message object for cache key generation
+     *
+     * @remarks
+     * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.
+     * Uses SHA-256 for collision resistance and deterministic key generation.
+     * Handles BigInt serialization and sorts object keys for consistency.
+     *
+     * @param message - The message object to hash (typically EIP-712 typed data)
+     * @returns A hex string hash (SHA-256) suitable for cache keys
+     * @example
+     * ```typescript
+     * const typedData = {
+     *   domain: { name: 'Vana', version: '1' },
+     *   message: { nonce: 123n, grant: '...' }
+     * };
+     *
+     * const hash = SignatureCache.hashMessage(typedData);
+     * // Returns SHA-256 hash like: "a1b2c3d4e5f6..."
+     * ```
+     */
+    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
+     *
+     * @param _key - The object key being serialized (unused)
+     * @param value - The value to serialize
+     * @returns The serialized value with sorted keys for objects
+     */
+    private static deterministicReplacer;
+}
+/**
+ * Wrapper function to cache signature operations
+ *
+ * @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)
+ * @returns The signature (cached or newly generated)
+ */
+declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: string, typedData: Record<string, unknown>, signFn: () => Promise<Hash>, ttlHours?: number): Promise<Hash>;
+
+export { SignatureCache, withSignatureCache };

package/dist/utils/signatureCache.js

@@ -0,0 +1,165 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { getAddress } from "viem";
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+class SignatureCache {
+  /**
+   * Get a cached signature if it exists and hasn't expired
+   *
+   * @param cache - Platform cache adapter instance
+   * @param walletAddress - Wallet address that created the signature
+   * @param messageHash - Hash of the message that was signed
+   * @returns The cached signature if valid, null if expired or not found
+   * @example
+   * ```typescript
+   * const messageHash = SignatureCache.hashMessage(typedData);
+   * const cached = SignatureCache.get(cache, '0x123...', messageHash);
+   * if (cached) {
+   *   console.log('Using cached signature:', cached);
+   * }
+   * ```
+   */
+  static get(cache, walletAddress, messageHash) {
+    const key = this.getCacheKey(walletAddress, messageHash);
+    try {
+      const stored = cache.get(key);
+      if (!stored) return null;
+      const cached = JSON.parse(stored);
+      if (Date.now() > cached.expires) {
+        cache.delete(key);
+        return null;
+      }
+      return cached.signature;
+    } catch {
+      try {
+        cache.delete(key);
+      } catch {
+      }
+      return null;
+    }
+  }
+  /**
+   * Store a signature in the cache with configurable TTL
+   *
+   * @param cache - Platform cache adapter instance
+   * @param walletAddress - Wallet address that created the signature
+   * @param messageHash - Hash of the message that was signed
+   * @param signature - The signature to cache
+   * @param ttlHours - Time to live in hours (default: 2)
+   * @example
+   * ```typescript
+   * const signature = await wallet.signTypedData(typedData);
+   * const messageHash = SignatureCache.hashMessage(typedData);
+   *
+   * // Cache for default 2 hours
+   * SignatureCache.set(cache, walletAddress, messageHash, signature);
+   *
+   * // Cache for 24 hours
+   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);
+   * ```
+   */
+  static set(cache, walletAddress, messageHash, signature, ttlHours = this.DEFAULT_TTL_HOURS) {
+    const key = this.getCacheKey(walletAddress, messageHash);
+    const cached = {
+      signature,
+      expires: Date.now() + ttlHours * 36e5
+      // Convert hours to milliseconds
+    };
+    try {
+      cache.set(key, JSON.stringify(cached));
+    } catch {
+    }
+  }
+  /**
+   * Clear all cached signatures (useful for testing or explicit cleanup)
+   *
+   * @param cache - Platform cache adapter instance
+   * @example
+   * ```typescript
+   * // Clear all signatures when user logs out
+   * SignatureCache.clear(cache);
+   *
+   * // Clear before running tests
+   * beforeEach(() => {
+   *   SignatureCache.clear(cache);
+   * });
+   * ```
+   */
+  static clear(cache) {
+    try {
+      cache.clear();
+    } catch {
+    }
+  }
+  static getCacheKey(walletAddress, messageHash) {
+    return `${this.PREFIX}${getAddress(walletAddress)}:${messageHash}`;
+  }
+  /**
+   * Generate a deterministic hash of a message object for cache key generation
+   *
+   * @remarks
+   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.
+   * Uses SHA-256 for collision resistance and deterministic key generation.
+   * Handles BigInt serialization and sorts object keys for consistency.
+   *
+   * @param message - The message object to hash (typically EIP-712 typed data)
+   * @returns A hex string hash (SHA-256) suitable for cache keys
+   * @example
+   * ```typescript
+   * const typedData = {
+   *   domain: { name: 'Vana', version: '1' },
+   *   message: { nonce: 123n, grant: '...' }
+   * };
+   *
+   * const hash = SignatureCache.hashMessage(typedData);
+   * // Returns SHA-256 hash like: "a1b2c3d4e5f6..."
+   * ```
+   */
+  static hashMessage(message) {
+    const jsonString = JSON.stringify(message, this.deterministicReplacer);
+    const hashBytes = sha256(new TextEncoder().encode(jsonString));
+    return bytesToHex(hashBytes);
+  }
+  /**
+   * Deterministic JSON replacer that handles BigInt values and sorts object keys
+   * This ensures consistent cache key generation for EIP-712 typed data
+   *
+   * @param _key - The object key being serialized (unused)
+   * @param value - The value to serialize
+   * @returns The serialized value with sorted keys for objects
+   */
+  static deterministicReplacer(_key, value) {
+    if (typeof value === "bigint") {
+      return `__BIGINT__${value.toString()}`;
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce(
+        (sorted, key) => {
+          sorted[key] = value[key];
+          return sorted;
+        },
+        {}
+      );
+    }
+    return value;
+  }
+}
+__publicField(SignatureCache, "PREFIX", "vana_sig_");
+__publicField(SignatureCache, "DEFAULT_TTL_HOURS", 2);
+async function withSignatureCache(cache, walletAddress, typedData, signFn, ttlHours) {
+  const messageHash = SignatureCache.hashMessage(typedData);
+  const cached = SignatureCache.get(cache, walletAddress, messageHash);
+  if (cached) {
+    return cached;
+  }
+  const signature = await signFn();
+  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);
+  return signature;
+}
+export {
+  SignatureCache,
+  withSignatureCache
+};
+//# sourceMappingURL=signatureCache.js.map

package/dist/utils/signatureCache.js.map

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