@opendatalabs/vana-sdk 0.1.0-alpha.f54fafd → 0.1.0-alpha.f732fa2

package/dist/utils/signatureCache.js

@@ -0,0 +1,167 @@
+import { getAddress, toHex } from "viem";
+import { sha256 } from "@noble/hashes/sha256";
+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}${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 toHex(hashBytes);
+  }
+  /**
+   * 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") {
+      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;
+}
+export {
+  SignatureCache,
+  withSignatureCache
+};
+//# sourceMappingURL=signatureCache.js.map

package/dist/utils/signatureCache.js.map

@@ -0,0 +1 @@
+{"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":"AAcA,SAAS,YAAY,aAAa;AAElC,SAAS,cAAc;AA0ChB,MAAM,eAAe;AAAA,EAC1B,OAAwB,SAAS;AAAA,EACjC,OAAwB,oBAAoB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkB5C,OAAO,IACL,OACA,eACA,aACa;AACb,UAAM,MAAM,KAAK,YAAY,eAAe,WAAW;AAEvD,QAAI;AACF,YAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,UAAI,CAAC,OAAQ,QAAO;AAEpB,YAAM,SAA0B,KAAK,MAAM,MAAM;AAGjD,UAAI,KAAK,IAAI,IAAI,OAAO,SAAS;AAC/B,cAAM,OAAO,GAAG;AAChB,eAAO;AAAA,MACT;AAEA,aAAO,OAAO;AAAA,IAChB,QAAQ;AAEN,UAAI;AACF,cAAM,OAAO,GAAG;AAAA,MAClB,QAAQ;AAAA,MAER;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,OAAO,IACL,OACA,eACA,aACA,WACA,WAAmB,KAAK,mBAClB;AACN,UAAM,MAAM,KAAK,YAAY,eAAe,WAAW;AACvD,UAAM,SAA0B;AAAA,MAC9B;AAAA,MACA,SAAS,KAAK,IAAI,IAAI,WAAW;AAAA;AAAA,IACnC;AAEA,QAAI;AACF,YAAM,IAAI,KAAK,KAAK,UAAU,MAAM,CAAC;AAAA,IACvC,QAAQ;AAAA,IAGR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,OAAO,MAAM,OAA+B;AAC1C,QAAI;AACF,YAAM,MAAM;AAAA,IACd,QAAQ;AAAA,IAER;AAAA,EACF;AAAA,EAEA,OAAe,YACb,eACA,aACQ;AACR,WAAO,GAAG,KAAK,MAAM,GAAG,WAAW,aAAa,CAAC,IAAI,WAAW;AAAA,EAClE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAuBA,OAAO,YAAY,SAAyB;AAE1C,UAAM,aAAa,KAAK,UAAU,SAAS,KAAK,qBAAqB;AAGrE,UAAM,YAAY,OAAO,IAAI,YAAY,EAAE,OAAO,UAAU,CAAC;AAC7D,WAAO,MAAM,SAAS;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgBA,OAAe,sBAAsB,MAAc,OAAyB;AAC1E,QAAI,OAAO,UAAU,UAAU;AAC7B,aAAO,aAAa,MAAM,SAAS,CAAC;AAAA,IACtC;AAEA,QAAI,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,GAAG;AACxE,aAAO,OAAO,KAAK,KAAgC,EAChD,KAAK,EACL;AAAA,QACC,CAAC,QAAQ,QAAQ;AACf,iBAAO,GAAG,IAAK,MAAkC,GAAG;AACpD,iBAAO;AAAA,QACT;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACJ;AACA,WAAO;AAAA,EACT;AACF;AAmCA,eAAsB,mBACpB,OACA,eACA,WACA,QACA,UACe;AAEf,QAAM,cAAc,eAAe,YAAY,SAAS;AAGxD,QAAM,SAAS,eAAe,IAAI,OAAO,eAAe,WAAW;AACnE,MAAI,QAAQ;AACV,WAAO;AAAA,EACT;AAGA,QAAM,YAAY,MAAM,OAAO;AAC/B,iBAAe,IAAI,OAAO,eAAe,aAAa,WAAW,QAAQ;AAEzE,SAAO;AACT;","names":[]}

package/dist/utils/signatureFormatter.cjs

@@ -0,0 +1,42 @@
+"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 signatureFormatter_exports = {};
+__export(signatureFormatter_exports, {
+  formatSignatureForContract: () => formatSignatureForContract
+});
+module.exports = __toCommonJS(signatureFormatter_exports);
+var import_viem = require("viem");
+const V_OFFSET_FOR_ETHEREUM = 27;
+function formatSignatureForContract(signature) {
+  const sigBytes = (0, import_viem.fromHex)(signature, "bytes");
+  if (sigBytes.length !== 65) {
+    return signature;
+  }
+  const v = sigBytes[64];
+  if (v < 27) {
+    sigBytes[64] = v + V_OFFSET_FOR_ETHEREUM;
+    return (0, import_viem.toHex)(sigBytes);
+  }
+  return signature;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  formatSignatureForContract
+});
+//# sourceMappingURL=signatureFormatter.cjs.map

package/dist/utils/signatureFormatter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/signatureFormatter.ts"],"sourcesContent":["import { type Hash, fromHex, toHex } from \"viem\";\n\nconst V_OFFSET_FOR_ETHEREUM = 27;\n\n/**\n * Formats a signature for Ethereum smart contract compatibility by adjusting the v-value.\n *\n * @remarks\n * This function ensures signature compatibility with Ethereum smart contracts by adjusting\n * the v-value component of ECDSA signatures. Some wallet implementations and signing methods\n * produce signatures with v-values in the range [0, 1], while Ethereum smart contracts\n * expect v-values in the range [27, 28] for proper signature verification.\n *\n * The function automatically detects signatures with low v-values and applies the standard\n * Ethereum offset (+27) to ensure compatibility. This is particularly important for gasless\n * transactions and EIP-712 signature verification in smart contracts.\n *\n * **Technical Details:**\n * - Ethereum signatures consist of r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes total\n * - Valid v-values for Ethereum are 27 or 28 (or 0/1 + chain-specific offset for EIP-155)\n * - This function handles the common case where v ∈ [0, 1] needs adjustment to [27, 28]\n *\n * @param signature - The ECDSA signature hash to format (65 bytes as hex string)\n * @returns The formatted signature with correct v-value for Ethereum contract verification\n * @example\n * ```typescript\n * // Signature with v-value that needs adjustment\n * const rawSignature = \"0x1234...5600\"; // v = 0 (last byte)\n * const formatted = formatSignatureForContract(rawSignature);\n * // Result: \"0x1234...561b\" // v = 27 (0x1b)\n *\n * // Already properly formatted signature remains unchanged\n * const goodSignature = \"0x1234...561b\"; // v = 27\n * const unchanged = formatSignatureForContract(goodSignature);\n * // Result: \"0x1234...561b\" (no change needed)\n * ```\n * @category Cryptography\n */\nexport function formatSignatureForContract(signature: Hash): Hash {\n  // Convert to bytes for safer manipulation\n  const sigBytes = fromHex(signature, \"bytes\");\n\n  if (sigBytes.length !== 65) {\n    return signature;\n  }\n\n  // Extract v value (last byte)\n  const v = sigBytes[64];\n\n  if (v < 27) {\n    // Adjust v value\n    sigBytes[64] = v + V_OFFSET_FOR_ETHEREUM;\n    // Convert back to hex\n    return toHex(sigBytes);\n  }\n\n  return signature;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAA0C;AAE1C,MAAM,wBAAwB;AAoCvB,SAAS,2BAA2B,WAAuB;AAEhE,QAAM,eAAW,qBAAQ,WAAW,OAAO;AAE3C,MAAI,SAAS,WAAW,IAAI;AAC1B,WAAO;AAAA,EACT;AAGA,QAAM,IAAI,SAAS,EAAE;AAErB,MAAI,IAAI,IAAI;AAEV,aAAS,EAAE,IAAI,IAAI;AAEnB,eAAO,mBAAM,QAAQ;AAAA,EACvB;AAEA,SAAO;AACT;","names":[]}

package/dist/utils/signatureFormatter.d.ts

@@ -0,0 +1,36 @@
+import { type Hash } from "viem";
+/**
+ * Formats a signature for Ethereum smart contract compatibility by adjusting the v-value.
+ *
+ * @remarks
+ * This function ensures signature compatibility with Ethereum smart contracts by adjusting
+ * the v-value component of ECDSA signatures. Some wallet implementations and signing methods
+ * produce signatures with v-values in the range [0, 1], while Ethereum smart contracts
+ * expect v-values in the range [27, 28] for proper signature verification.
+ *
+ * The function automatically detects signatures with low v-values and applies the standard
+ * Ethereum offset (+27) to ensure compatibility. This is particularly important for gasless
+ * transactions and EIP-712 signature verification in smart contracts.
+ *
+ * **Technical Details:**
+ * - Ethereum signatures consist of r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes total
+ * - Valid v-values for Ethereum are 27 or 28 (or 0/1 + chain-specific offset for EIP-155)
+ * - This function handles the common case where v ∈ [0, 1] needs adjustment to [27, 28]
+ *
+ * @param signature - The ECDSA signature hash to format (65 bytes as hex string)
+ * @returns The formatted signature with correct v-value for Ethereum contract verification
+ * @example
+ * ```typescript
+ * // Signature with v-value that needs adjustment
+ * const rawSignature = "0x1234...5600"; // v = 0 (last byte)
+ * const formatted = formatSignatureForContract(rawSignature);
+ * // Result: "0x1234...561b" // v = 27 (0x1b)
+ *
+ * // Already properly formatted signature remains unchanged
+ * const goodSignature = "0x1234...561b"; // v = 27
+ * const unchanged = formatSignatureForContract(goodSignature);
+ * // Result: "0x1234...561b" (no change needed)
+ * ```
+ * @category Cryptography
+ */
+export declare function formatSignatureForContract(signature: Hash): Hash;

package/dist/utils/signatureFormatter.js

@@ -0,0 +1,18 @@
+import { fromHex, toHex } from "viem";
+const V_OFFSET_FOR_ETHEREUM = 27;
+function formatSignatureForContract(signature) {
+  const sigBytes = fromHex(signature, "bytes");
+  if (sigBytes.length !== 65) {
+    return signature;
+  }
+  const v = sigBytes[64];
+  if (v < 27) {
+    sigBytes[64] = v + V_OFFSET_FOR_ETHEREUM;
+    return toHex(sigBytes);
+  }
+  return signature;
+}
+export {
+  formatSignatureForContract
+};
+//# sourceMappingURL=signatureFormatter.js.map

package/dist/utils/signatureFormatter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/signatureFormatter.ts"],"sourcesContent":["import { type Hash, fromHex, toHex } from \"viem\";\n\nconst V_OFFSET_FOR_ETHEREUM = 27;\n\n/**\n * Formats a signature for Ethereum smart contract compatibility by adjusting the v-value.\n *\n * @remarks\n * This function ensures signature compatibility with Ethereum smart contracts by adjusting\n * the v-value component of ECDSA signatures. Some wallet implementations and signing methods\n * produce signatures with v-values in the range [0, 1], while Ethereum smart contracts\n * expect v-values in the range [27, 28] for proper signature verification.\n *\n * The function automatically detects signatures with low v-values and applies the standard\n * Ethereum offset (+27) to ensure compatibility. This is particularly important for gasless\n * transactions and EIP-712 signature verification in smart contracts.\n *\n * **Technical Details:**\n * - Ethereum signatures consist of r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes total\n * - Valid v-values for Ethereum are 27 or 28 (or 0/1 + chain-specific offset for EIP-155)\n * - This function handles the common case where v ∈ [0, 1] needs adjustment to [27, 28]\n *\n * @param signature - The ECDSA signature hash to format (65 bytes as hex string)\n * @returns The formatted signature with correct v-value for Ethereum contract verification\n * @example\n * ```typescript\n * // Signature with v-value that needs adjustment\n * const rawSignature = \"0x1234...5600\"; // v = 0 (last byte)\n * const formatted = formatSignatureForContract(rawSignature);\n * // Result: \"0x1234...561b\" // v = 27 (0x1b)\n *\n * // Already properly formatted signature remains unchanged\n * const goodSignature = \"0x1234...561b\"; // v = 27\n * const unchanged = formatSignatureForContract(goodSignature);\n * // Result: \"0x1234...561b\" (no change needed)\n * ```\n * @category Cryptography\n */\nexport function formatSignatureForContract(signature: Hash): Hash {\n  // Convert to bytes for safer manipulation\n  const sigBytes = fromHex(signature, \"bytes\");\n\n  if (sigBytes.length !== 65) {\n    return signature;\n  }\n\n  // Extract v value (last byte)\n  const v = sigBytes[64];\n\n  if (v < 27) {\n    // Adjust v value\n    sigBytes[64] = v + V_OFFSET_FOR_ETHEREUM;\n    // Convert back to hex\n    return toHex(sigBytes);\n  }\n\n  return signature;\n}\n"],"mappings":"AAAA,SAAoB,SAAS,aAAa;AAE1C,MAAM,wBAAwB;AAoCvB,SAAS,2BAA2B,WAAuB;AAEhE,QAAM,WAAW,QAAQ,WAAW,OAAO;AAE3C,MAAI,SAAS,WAAW,IAAI;AAC1B,WAAO;AAAA,EACT;AAGA,QAAM,IAAI,SAAS,EAAE;AAErB,MAAI,IAAI,IAAI;AAEV,aAAS,EAAE,IAAI,IAAI;AAEnB,WAAO,MAAM,QAAQ;AAAA,EACvB;AAEA,SAAO;AACT;","names":[]}

package/dist/utils/tests/multicall.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/transactionHelpers.cjs

@@ -0,0 +1,54 @@
+"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 transactionHelpers_exports = {};
+__export(transactionHelpers_exports, {
+  tx: () => tx,
+  txLiteral: () => txLiteral
+});
+module.exports = __toCommonJS(transactionHelpers_exports);
+function tx(input) {
+  return {
+    hash: input.hash,
+    from: input.from,
+    contract: input.contract,
+    fn: input.fn,
+    ...input.chainId !== void 0 && { chainId: input.chainId },
+    ...input.value !== void 0 && { value: input.value },
+    ...input.nonce !== void 0 && { nonce: input.nonce },
+    ...input.to !== void 0 && { to: input.to }
+  };
+}
+function txLiteral(input) {
+  return {
+    hash: input.hash,
+    from: input.from,
+    contract: input.contract,
+    fn: input.fn,
+    ...input.chainId !== void 0 && { chainId: input.chainId },
+    ...input.value !== void 0 && { value: input.value },
+    ...input.nonce !== void 0 && { nonce: input.nonce },
+    ...input.to !== void 0 && { to: input.to }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  tx,
+  txLiteral
+});
+//# sourceMappingURL=transactionHelpers.cjs.map

package/dist/utils/transactionHelpers.cjs.map

@@ -0,0 +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 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

@@ -0,0 +1,80 @@
+/**
+ * Helper functions for creating typed transaction POJOs
+ */
+import type { Hash, Address } from "viem";
+import type { TransactionResult } from "../types/operations";
+import type { Contract, Fn } from "../generated/event-types";
+/**
+ * Creates typed TransactionResult with validation.
+ *
+ * @remarks
+ * Ensures type safety for transaction results.
+ * Reduces boilerplate in transaction handling.
+ *
+ * @param input - Transaction details
+ * @param input.hash - Transaction hash from the blockchain
+ * @param input.from - Transaction sender address
+ * @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
+ * return tx({
+ *   hash,
+ *   from: account.address,
+ *   contract: "DataPortabilityPermissions",
+ *   fn: "revokePermission"
+ * });
+ * ```
+ */
+export declare function tx<C extends Contract, F extends Fn<C>>(input: {
+    hash: Hash;
+    from: Address;
+    contract: C;
+    fn: F;
+    chainId?: number;
+    value?: bigint;
+    nonce?: number;
+    to?: Address;
+}): TransactionResult<C, F>;
+/**
+ * Creates a transaction result with literal type inference.
+ * Use this when you need TypeScript to preserve exact string literals.
+ *
+ * @param input - Transaction details
+ * @param input.hash - Transaction hash
+ * @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
+ *
+ * @example
+ * ```typescript
+ * const transaction = txLiteral({
+ *   hash: '0x...',
+ *   from: '0x...',
+ *   contract: "DataPortabilityPermissions",
+ *   fn: "revokePermission",
+ * });
+ * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission
+ * ```
+ */
+export declare function txLiteral<const C extends Contract, const F extends Fn<C>>(input: {
+    hash: Hash;
+    from: Address;
+    contract: C;
+    fn: F;
+    chainId?: number;
+    value?: bigint;
+    nonce?: number;
+    to?: Address;
+}): TransactionResult<C, F>;

package/dist/utils/transactionHelpers.js

@@ -0,0 +1,29 @@
+function tx(input) {
+  return {
+    hash: input.hash,
+    from: input.from,
+    contract: input.contract,
+    fn: input.fn,
+    ...input.chainId !== void 0 && { chainId: input.chainId },
+    ...input.value !== void 0 && { value: input.value },
+    ...input.nonce !== void 0 && { nonce: input.nonce },
+    ...input.to !== void 0 && { to: input.to }
+  };
+}
+function txLiteral(input) {
+  return {
+    hash: input.hash,
+    from: input.from,
+    contract: input.contract,
+    fn: input.fn,
+    ...input.chainId !== void 0 && { chainId: input.chainId },
+    ...input.value !== void 0 && { value: input.value },
+    ...input.nonce !== void 0 && { nonce: input.nonce },
+    ...input.to !== void 0 && { to: input.to }
+  };
+}
+export {
+  tx,
+  txLiteral
+};
+//# sourceMappingURL=transactionHelpers.js.map

package/dist/utils/transactionHelpers.js.map

@@ -0,0 +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 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/typeGuards.cjs

@@ -0,0 +1,109 @@
+"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 typeGuards_exports = {};
+__export(typeGuards_exports, {
+  assertDefined: () => assertDefined,
+  assertHasProperties: () => assertHasProperties,
+  assertNonEmptyString: () => assertNonEmptyString,
+  ensureDefault: () => ensureDefault,
+  ensureError: () => ensureError,
+  hasProperty: () => hasProperty,
+  isArray: () => isArray,
+  isDefined: () => isDefined,
+  isNonEmptyString: () => isNonEmptyString,
+  isObject: () => isObject,
+  safeArrayAccess: () => safeArrayAccess,
+  safeGet: () => safeGet
+});
+module.exports = __toCommonJS(typeGuards_exports);
+function assertDefined(value, message) {
+  if (value === void 0 || value === null) {
+    throw new Error(message);
+  }
+}
+function isDefined(value) {
+  return value !== void 0 && value !== null;
+}
+function assertNonEmptyString(value, message) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(message);
+  }
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function safeGet(obj, key) {
+  return obj?.[key];
+}
+function ensureDefault(value, defaultValue) {
+  return isDefined(value) ? value : defaultValue;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isArray(value) {
+  return Array.isArray(value);
+}
+function safeArrayAccess(array, index) {
+  if (!array || index < 0 || index >= array.length) {
+    return void 0;
+  }
+  return array[index];
+}
+function hasProperty(obj, prop) {
+  return isObject(obj) && prop in obj;
+}
+function assertHasProperties(obj, properties, message) {
+  if (!isObject(obj)) {
+    throw new Error(`${message}: Value is not an object`);
+  }
+  for (const prop of properties) {
+    if (!(prop in obj)) {
+      throw new Error(`${message}: Missing required property '${prop}'`);
+    }
+  }
+}
+function ensureError(error, fallbackMessage) {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+  if (isObject(error) && "message" in error && typeof error.message === "string") {
+    return new Error(error.message);
+  }
+  return new Error(fallbackMessage);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertDefined,
+  assertHasProperties,
+  assertNonEmptyString,
+  ensureDefault,
+  ensureError,
+  hasProperty,
+  isArray,
+  isDefined,
+  isNonEmptyString,
+  isObject,
+  safeArrayAccess,
+  safeGet
+});
+//# sourceMappingURL=typeGuards.cjs.map

package/dist/utils/typeGuards.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/typeGuards.ts"],"sourcesContent":["/**\n * Type guard utilities for runtime type checking and assertions.\n * These utilities provide type-safe alternatives to non-null assertions (!).\n *\n * @module typeGuards\n */\n\n/**\n * Asserts that a value is defined (not null or undefined).\n * Throws an error with a descriptive message if the assertion fails.\n *\n * @param value - The value to check\n * @param message - Error message to throw if value is not defined\n * @throws {Error} If value is null or undefined\n *\n * @example\n * ```typescript\n * const wallet = getWallet();\n * assertDefined(wallet, 'Wallet must be initialized before use');\n * // TypeScript now knows wallet is defined\n * console.log(wallet.address);\n * ```\n */\nexport function assertDefined<T>(\n  value: T | undefined | null,\n  message: string,\n): asserts value is T {\n  if (value === undefined || value === null) {\n    throw new Error(message);\n  }\n}\n\n/**\n * Type guard to check if a value is defined (not null or undefined).\n *\n * @param value - The value to check\n * @returns True if the value is defined, false otherwise\n *\n * @example\n * ```typescript\n * const values = [1, undefined, 3, null, 5];\n * const defined = values.filter(isDefined); // [1, 3, 5]\n * ```\n */\nexport function isDefined<T>(value: T | undefined | null): value is T {\n  return value !== undefined && value !== null;\n}\n\n/**\n * Asserts that a value is a non-empty string.\n *\n * @param value - The value to check\n * @param message - Error message if assertion fails\n * @throws {Error} If value is not a non-empty string\n */\nexport function assertNonEmptyString(\n  value: unknown,\n  message: string,\n): asserts value is string {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new Error(message);\n  }\n}\n\n/**\n * Type guard to check if a value is a non-empty string.\n *\n * @param value - The value to check\n * @returns True if value is a non-empty string\n */\nexport function isNonEmptyString(value: unknown): value is string {\n  return typeof value === \"string\" && value.trim().length > 0;\n}\n\n/**\n * Safely gets a property from an object, returning undefined if the property doesn't exist.\n *\n * @param obj - The object to get the property from\n * @param key - The property key\n * @returns The property value or undefined\n *\n * @example\n * ```typescript\n * const config = { wallet: { address: '0x123' } };\n * const address = safeGet(config, 'wallet')?.address;\n * ```\n */\nexport function safeGet<T, K extends keyof T>(\n  obj: T | undefined | null,\n  key: K,\n): T[K] | undefined {\n  return obj?.[key];\n}\n\n/**\n * Ensures a value is defined or returns a default value.\n *\n * @param value - The value to check\n * @param defaultValue - The default value to use if undefined\n * @returns The value if defined, otherwise the default\n *\n * @example\n * ```typescript\n * const timeout = ensureDefault(config.timeout, 5000);\n * ```\n */\nexport function ensureDefault<T>(\n  value: T | undefined | null,\n  defaultValue: T,\n): T {\n  return isDefined(value) ? value : defaultValue;\n}\n\n/**\n * Type guard for checking if a value is an object (and not null).\n *\n * @param value - The value to check\n * @returns True if value is an object\n */\nexport function isObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\n/**\n * Type guard for checking if a value is an array.\n *\n * @param value - The value to check\n * @returns True if value is an array\n */\nexport function isArray<T = unknown>(value: unknown): value is T[] {\n  return Array.isArray(value);\n}\n\n/**\n * Safely accesses an array element, returning undefined if out of bounds.\n *\n * @param array - The array to access\n * @param index - The index to access\n * @returns The element at the index or undefined\n *\n * @example\n * ```typescript\n * const items = [1, 2, 3];\n * const item = safeArrayAccess(items, 5); // undefined\n * ```\n */\nexport function safeArrayAccess<T>(\n  array: T[] | undefined | null,\n  index: number,\n): T | undefined {\n  if (!array || index < 0 || index >= array.length) {\n    return undefined;\n  }\n  return array[index];\n}\n\n/**\n * Type guard to check if a value has a specific property.\n *\n * @param obj - The object to check\n * @param prop - The property name\n * @returns True if the object has the property\n *\n * @example\n * ```typescript\n * if (hasProperty(response, 'error')) {\n *   console.error(response.error);\n * }\n * ```\n */\nexport function hasProperty<T extends string>(\n  obj: unknown,\n  prop: T,\n): obj is Record<T, unknown> {\n  return isObject(obj) && prop in obj;\n}\n\n/**\n * Asserts that an object has required properties.\n *\n * @param obj - The object to check\n * @param properties - Array of required property names\n * @param message - Error message if assertion fails\n * @throws {Error} If any required property is missing\n */\nexport function assertHasProperties<T extends string>(\n  obj: unknown,\n  properties: T[],\n  message: string,\n): asserts obj is Record<T, unknown> {\n  if (!isObject(obj)) {\n    throw new Error(`${message}: Value is not an object`);\n  }\n\n  for (const prop of properties) {\n    if (!(prop in obj)) {\n      throw new Error(`${message}: Missing required property '${prop}'`);\n    }\n  }\n}\n\n/**\n * Creates a type-safe error with a guaranteed message.\n *\n * @param error - The error or unknown value\n * @param fallbackMessage - Message to use if error doesn't have one\n * @returns An Error object with a message\n */\nexport function ensureError(error: unknown, fallbackMessage: string): Error {\n  if (error instanceof Error) {\n    return error;\n  }\n  if (typeof error === \"string\") {\n    return new Error(error);\n  }\n  if (\n    isObject(error) &&\n    \"message\" in error &&\n    typeof error.message === \"string\"\n  ) {\n    return new Error(error.message);\n  }\n  return new Error(fallbackMessage);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBO,SAAS,cACd,OACA,SACoB;AACpB,MAAI,UAAU,UAAa,UAAU,MAAM;AACzC,UAAM,IAAI,MAAM,OAAO;AAAA,EACzB;AACF;AAcO,SAAS,UAAa,OAAyC;AACpE,SAAO,UAAU,UAAa,UAAU;AAC1C;AASO,SAAS,qBACd,OACA,SACyB;AACzB,MAAI,OAAO,UAAU,YAAY,MAAM,KAAK,EAAE,WAAW,GAAG;AAC1D,UAAM,IAAI,MAAM,OAAO;AAAA,EACzB;AACF;AAQO,SAAS,iBAAiB,OAAiC;AAChE,SAAO,OAAO,UAAU,YAAY,MAAM,KAAK,EAAE,SAAS;AAC5D;AAeO,SAAS,QACd,KACA,KACkB;AAClB,SAAO,MAAM,GAAG;AAClB;AAcO,SAAS,cACd,OACA,cACG;AACH,SAAO,UAAU,KAAK,IAAI,QAAQ;AACpC;AAQO,SAAS,SAAS,OAAkD;AACzE,SAAO,OAAO,UAAU,YAAY,UAAU;AAChD;AAQO,SAAS,QAAqB,OAA8B;AACjE,SAAO,MAAM,QAAQ,KAAK;AAC5B;AAeO,SAAS,gBACd,OACA,OACe;AACf,MAAI,CAAC,SAAS,QAAQ,KAAK,SAAS,MAAM,QAAQ;AAChD,WAAO;AAAA,EACT;AACA,SAAO,MAAM,KAAK;AACpB;AAgBO,SAAS,YACd,KACA,MAC2B;AAC3B,SAAO,SAAS,GAAG,KAAK,QAAQ;AAClC;AAUO,SAAS,oBACd,KACA,YACA,SACmC;AACnC,MAAI,CAAC,SAAS,GAAG,GAAG;AAClB,UAAM,IAAI,MAAM,GAAG,OAAO,0BAA0B;AAAA,EACtD;AAEA,aAAW,QAAQ,YAAY;AAC7B,QAAI,EAAE,QAAQ,MAAM;AAClB,YAAM,IAAI,MAAM,GAAG,OAAO,gCAAgC,IAAI,GAAG;AAAA,IACnE;AAAA,EACF;AACF;AASO,SAAS,YAAY,OAAgB,iBAAgC;AAC1E,MAAI,iBAAiB,OAAO;AAC1B,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,IAAI,MAAM,KAAK;AAAA,EACxB;AACA,MACE,SAAS,KAAK,KACd,aAAa,SACb,OAAO,MAAM,YAAY,UACzB;AACA,WAAO,IAAI,MAAM,MAAM,OAAO;AAAA,EAChC;AACA,SAAO,IAAI,MAAM,eAAe;AAClC;","names":[]}