@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 2.0.0

package/dist/lib/__tests__/redisAtomicStore.test.d.ts

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

package/dist/lib/redisAtomicStore.cjs

@@ -0,0 +1,201 @@
+"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 redisAtomicStore_exports = {};
+__export(redisAtomicStore_exports, {
+  RedisAtomicStore: () => RedisAtomicStore
+});
+module.exports = __toCommonJS(redisAtomicStore_exports);
+class RedisAtomicStore {
+  redis;
+  // ioredis instance
+  keyPrefix;
+  /**
+   * Lua script for safe lock release.
+   * This ensures we only delete a lock if the value matches our lock ID.
+   */
+  UNLOCK_SCRIPT = `
+    if redis.call("GET", KEYS[1]) == ARGV[1] then
+      return redis.call("DEL", KEYS[1])
+    else
+      return 0
+    end
+  `;
+  constructor(config) {
+    if (typeof config.redis === "string") {
+      throw new Error(
+        "RedisAtomicStore requires an initialized Redis client instance. Please create the Redis client in your application and pass it to the constructor."
+      );
+    }
+    this.redis = config.redis;
+    this.keyPrefix = config.keyPrefix ?? "vana-sdk:atomic";
+    if (!this.redis || typeof this.redis.incr !== "function" || typeof this.redis.set !== "function" || typeof this.redis.get !== "function" || typeof this.redis.eval !== "function") {
+      throw new Error(
+        "Invalid Redis client instance provided to RedisAtomicStore"
+      );
+    }
+  }
+  /**
+   * Atomically increments a counter.
+   */
+  async incr(key) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    return await this.redis.incr(fullKey);
+  }
+  /**
+   * Acquires a distributed lock using SET NX EX.
+   */
+  async acquireLock(key, ttlSeconds) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    const lockId = `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+    const result = await this.redis.set(
+      fullKey,
+      lockId,
+      "EX",
+      ttlSeconds,
+      "NX"
+    );
+    if (result === "OK") {
+      console.log(`[RedisAtomicStore] Lock acquired: ${key} with ID ${lockId}`);
+      return lockId;
+    }
+    return null;
+  }
+  /**
+   * Releases a lock using a Lua script for atomicity.
+   */
+  async releaseLock(key, lockId) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    const result = await this.redis.eval(
+      this.UNLOCK_SCRIPT,
+      1,
+      // Number of keys
+      fullKey,
+      // KEYS[1]
+      lockId
+      // ARGV[1]
+    );
+    if (result === 1) {
+      console.log(`[RedisAtomicStore] Lock released: ${key}`);
+    } else {
+      console.warn(
+        `[RedisAtomicStore] Lock release failed: ${key} (lock not held or expired)`
+      );
+    }
+  }
+  /**
+   * Gets a value from Redis.
+   */
+  async get(key) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    return await this.redis.get(fullKey);
+  }
+  /**
+   * Sets a value in Redis.
+   */
+  async set(key, value) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    await this.redis.set(fullKey, value);
+  }
+  /**
+   * Sets a value with TTL for automatic expiration.
+   */
+  async setWithTTL(key, value, ttlSeconds) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    await this.redis.setex(fullKey, ttlSeconds, value);
+  }
+  /**
+   * Deletes a key from Redis.
+   */
+  async delete(key) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    await this.redis.del(fullKey);
+  }
+  /**
+   * Executes a Lua script atomically.
+   *
+   * @remarks
+   * This provides generic script execution for complex atomic operations.
+   * Keys passed to the script will be automatically prefixed.
+   *
+   * @param script - The Lua script to execute
+   * @param keys - Array of keys (will be prefixed)
+   * @param args - Array of arguments
+   * @returns The script's return value
+   */
+  async eval(script, keys, args) {
+    const prefixedKeys = keys.map((key) => `${this.keyPrefix}:${key}`);
+    const result = await this.redis.eval(
+      script,
+      keys.length,
+      ...prefixedKeys,
+      ...args
+    );
+    return result;
+  }
+  /**
+   * Atomically assigns a nonce using Vana App's battle-tested logic.
+   *
+   * @remarks
+   * This is a Redis-specific optimization that uses a Lua script for
+   * atomic nonce assignment with gap prevention. This method is called
+   * by DistributedNonceManager when it detects a Redis store.
+   *
+   * Ported from apps/web/app/api/relay/route.ts (Vana App production code)
+   * DO NOT MODIFY without thorough testing in production environment.
+   *
+   * @param key - The key for storing the last used nonce
+   * @param pendingCount - The current pending transaction count from blockchain
+   * @returns The assigned nonce
+   */
+  async atomicAssignNonce(key, pendingCount) {
+    const LUA_ASSIGN_NONCE = `
+      -- KEYS[1] = lastUsedKey
+      -- ARGV[1] = pendingCount (integer)
+
+      local last = tonumber(redis.call("GET", KEYS[1]) or "-1")
+      local pending = tonumber(ARGV[1])
+      local candidate = last + 1
+      if pending > candidate or (candidate - pending > 500) then
+        -- If pending is ahead OR if candidate is too far ahead (>500 nonces), reset to pending
+        candidate = pending
+      end
+
+      -- IMPORTANT: Atomically update the last used nonce
+      redis.call("SET", KEYS[1], candidate)
+
+      return candidate
+    `;
+    const fullKey = `${this.keyPrefix}:${key}`;
+    const nonce = await this.redis.eval(
+      LUA_ASSIGN_NONCE,
+      1,
+      // Number of keys
+      fullKey,
+      // KEYS[1]
+      pendingCount.toString()
+      // ARGV[1]
+    );
+    return nonce;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RedisAtomicStore
+});
+//# sourceMappingURL=redisAtomicStore.cjs.map

package/dist/lib/redisAtomicStore.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/redisAtomicStore.ts"],"sourcesContent":["/**\n * Redis implementation of IAtomicStore for production use.\n *\n * @remarks\n * This is a Node.js-only implementation that requires the ioredis package.\n * It will not be included in browser bundles.\n *\n * @module\n */\n\nimport type { IAtomicStoreWithNonceSupport } from \"../types/atomicStore\";\n\n/**\n * Configuration for RedisAtomicStore\n */\nexport interface RedisAtomicStoreConfig {\n  /** Redis connection URL or ioredis options */\n  redis: string | any;\n  /** Key prefix for all operations (default: 'vana-sdk:atomic') */\n  keyPrefix?: string;\n}\n\n/**\n * Redis-backed implementation of IAtomicStore.\n *\n * @remarks\n * This implementation uses Redis's native atomic operations:\n * - INCR for atomic counter increments\n * - SET NX EX for distributed locking\n * - Lua script for safe lock release\n *\n * Redis is ideal for this use case because:\n * - All operations are atomic by design\n * - Built-in TTL support for automatic cleanup\n * - High performance (sub-millisecond operations)\n * - Battle-tested in production environments\n *\n * @example\n * ```typescript\n * import Redis from 'ioredis';\n * import { RedisAtomicStore } from '@opendatalabs/vana-sdk/node';\n *\n * const redis = new Redis(process.env.REDIS_URL);\n * const atomicStore = new RedisAtomicStore({\n *   redis: redis\n * });\n *\n * const vana = Vana({\n *   walletClient,\n *   atomicStore,\n *   operationStore\n * });\n * ```\n *\n * @category Storage\n */\nexport class RedisAtomicStore implements IAtomicStoreWithNonceSupport {\n  private redis: any; // ioredis instance\n  private keyPrefix: string;\n\n  /**\n   * Lua script for safe lock release.\n   * This ensures we only delete a lock if the value matches our lock ID.\n   */\n  private readonly UNLOCK_SCRIPT = `\n    if redis.call(\"GET\", KEYS[1]) == ARGV[1] then\n      return redis.call(\"DEL\", KEYS[1])\n    else\n      return 0\n    end\n  `;\n\n  constructor(config: RedisAtomicStoreConfig) {\n    // Dynamic import to avoid bundling ioredis in browser builds\n    // The actual Redis instance should be passed in already created\n    if (typeof config.redis === \"string\") {\n      throw new Error(\n        \"RedisAtomicStore requires an initialized Redis client instance. \" +\n          \"Please create the Redis client in your application and pass it to the constructor.\",\n      );\n    }\n\n    this.redis = config.redis;\n    this.keyPrefix = config.keyPrefix ?? \"vana-sdk:atomic\";\n\n    // Validate that the redis instance has the methods we need\n    if (\n      !this.redis ||\n      typeof this.redis.incr !== \"function\" ||\n      typeof this.redis.set !== \"function\" ||\n      typeof this.redis.get !== \"function\" ||\n      typeof this.redis.eval !== \"function\"\n    ) {\n      throw new Error(\n        \"Invalid Redis client instance provided to RedisAtomicStore\",\n      );\n    }\n  }\n\n  /**\n   * Atomically increments a counter.\n   */\n  async incr(key: string): Promise<number> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    return await this.redis.incr(fullKey);\n  }\n\n  /**\n   * Acquires a distributed lock using SET NX EX.\n   */\n  async acquireLock(key: string, ttlSeconds: number): Promise<string | null> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    const lockId = `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;\n\n    // SET key value NX EX ttl\n    const result = await this.redis.set(\n      fullKey,\n      lockId,\n      \"EX\",\n      ttlSeconds,\n      \"NX\",\n    );\n\n    if (result === \"OK\") {\n      console.log(`[RedisAtomicStore] Lock acquired: ${key} with ID ${lockId}`);\n      return lockId;\n    }\n\n    return null;\n  }\n\n  /**\n   * Releases a lock using a Lua script for atomicity.\n   */\n  async releaseLock(key: string, lockId: string): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n\n    // Use Lua script for atomic compare-and-delete\n    const result = (await this.redis.eval(\n      this.UNLOCK_SCRIPT,\n      1, // Number of keys\n      fullKey, // KEYS[1]\n      lockId, // ARGV[1]\n    )) as number;\n\n    if (result === 1) {\n      console.log(`[RedisAtomicStore] Lock released: ${key}`);\n    } else {\n      console.warn(\n        `[RedisAtomicStore] Lock release failed: ${key} (lock not held or expired)`,\n      );\n    }\n  }\n\n  /**\n   * Gets a value from Redis.\n   */\n  async get(key: string): Promise<string | null> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    return await this.redis.get(fullKey);\n  }\n\n  /**\n   * Sets a value in Redis.\n   */\n  async set(key: string, value: string): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    await this.redis.set(fullKey, value);\n  }\n\n  /**\n   * Sets a value with TTL for automatic expiration.\n   */\n  async setWithTTL?(\n    key: string,\n    value: string,\n    ttlSeconds: number,\n  ): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    await this.redis.setex(fullKey, ttlSeconds, value);\n  }\n\n  /**\n   * Deletes a key from Redis.\n   */\n  async delete?(key: string): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    await this.redis.del(fullKey);\n  }\n\n  /**\n   * Executes a Lua script atomically.\n   *\n   * @remarks\n   * This provides generic script execution for complex atomic operations.\n   * Keys passed to the script will be automatically prefixed.\n   *\n   * @param script - The Lua script to execute\n   * @param keys - Array of keys (will be prefixed)\n   * @param args - Array of arguments\n   * @returns The script's return value\n   */\n  async eval(script: string, keys: string[], args: string[]): Promise<any> {\n    // Apply key prefix to all keys\n    const prefixedKeys = keys.map((key) => `${this.keyPrefix}:${key}`);\n\n    // Execute the Lua script\n    const result = await this.redis.eval(\n      script,\n      keys.length,\n      ...prefixedKeys,\n      ...args,\n    );\n\n    return result;\n  }\n\n  /**\n   * Atomically assigns a nonce using Vana App's battle-tested logic.\n   *\n   * @remarks\n   * This is a Redis-specific optimization that uses a Lua script for\n   * atomic nonce assignment with gap prevention. This method is called\n   * by DistributedNonceManager when it detects a Redis store.\n   *\n   * Ported from apps/web/app/api/relay/route.ts (Vana App production code)\n   * DO NOT MODIFY without thorough testing in production environment.\n   *\n   * @param key - The key for storing the last used nonce\n   * @param pendingCount - The current pending transaction count from blockchain\n   * @returns The assigned nonce\n   */\n  async atomicAssignNonce(key: string, pendingCount: number): Promise<number> {\n    const LUA_ASSIGN_NONCE = `\n      -- KEYS[1] = lastUsedKey\n      -- ARGV[1] = pendingCount (integer)\n\n      local last = tonumber(redis.call(\"GET\", KEYS[1]) or \"-1\")\n      local pending = tonumber(ARGV[1])\n      local candidate = last + 1\n      if pending > candidate or (candidate - pending > 500) then\n        -- If pending is ahead OR if candidate is too far ahead (>500 nonces), reset to pending\n        candidate = pending\n      end\n\n      -- IMPORTANT: Atomically update the last used nonce\n      redis.call(\"SET\", KEYS[1], candidate)\n\n      return candidate\n    `;\n\n    const fullKey = `${this.keyPrefix}:${key}`;\n    const nonce = (await this.redis.eval(\n      LUA_ASSIGN_NONCE,\n      1, // Number of keys\n      fullKey, // KEYS[1]\n      pendingCount.toString(), // ARGV[1]\n    )) as number;\n\n    return nonce;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/lib/redisAtomicStore.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Redis implementation of IAtomicStore for production use.
+ *
+ * @remarks
+ * This is a Node.js-only implementation that requires the ioredis package.
+ * It will not be included in browser bundles.
+ *
+ * @module
+ */
+import type { IAtomicStoreWithNonceSupport } from "../types/atomicStore";
+/**
+ * Configuration for RedisAtomicStore
+ */
+export interface RedisAtomicStoreConfig {
+    /** Redis connection URL or ioredis options */
+    redis: string | any;
+    /** Key prefix for all operations (default: 'vana-sdk:atomic') */
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed implementation of IAtomicStore.
+ *
+ * @remarks
+ * This implementation uses Redis's native atomic operations:
+ * - INCR for atomic counter increments
+ * - SET NX EX for distributed locking
+ * - Lua script for safe lock release
+ *
+ * Redis is ideal for this use case because:
+ * - All operations are atomic by design
+ * - Built-in TTL support for automatic cleanup
+ * - High performance (sub-millisecond operations)
+ * - Battle-tested in production environments
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { RedisAtomicStore } from '@opendatalabs/vana-sdk/node';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const atomicStore = new RedisAtomicStore({
+ *   redis: redis
+ * });
+ *
+ * const vana = Vana({
+ *   walletClient,
+ *   atomicStore,
+ *   operationStore
+ * });
+ * ```
+ *
+ * @category Storage
+ */
+export declare class RedisAtomicStore implements IAtomicStoreWithNonceSupport {
+    private redis;
+    private keyPrefix;
+    /**
+     * Lua script for safe lock release.
+     * This ensures we only delete a lock if the value matches our lock ID.
+     */
+    private readonly UNLOCK_SCRIPT;
+    constructor(config: RedisAtomicStoreConfig);
+    /**
+     * Atomically increments a counter.
+     */
+    incr(key: string): Promise<number>;
+    /**
+     * Acquires a distributed lock using SET NX EX.
+     */
+    acquireLock(key: string, ttlSeconds: number): Promise<string | null>;
+    /**
+     * Releases a lock using a Lua script for atomicity.
+     */
+    releaseLock(key: string, lockId: string): Promise<void>;
+    /**
+     * Gets a value from Redis.
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Sets a value in Redis.
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Sets a value with TTL for automatic expiration.
+     */
+    setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Deletes a key from Redis.
+     */
+    delete?(key: string): Promise<void>;
+    /**
+     * Executes a Lua script atomically.
+     *
+     * @remarks
+     * This provides generic script execution for complex atomic operations.
+     * Keys passed to the script will be automatically prefixed.
+     *
+     * @param script - The Lua script to execute
+     * @param keys - Array of keys (will be prefixed)
+     * @param args - Array of arguments
+     * @returns The script's return value
+     */
+    eval(script: string, keys: string[], args: string[]): Promise<any>;
+    /**
+     * Atomically assigns a nonce using Vana App's battle-tested logic.
+     *
+     * @remarks
+     * This is a Redis-specific optimization that uses a Lua script for
+     * atomic nonce assignment with gap prevention. This method is called
+     * by DistributedNonceManager when it detects a Redis store.
+     *
+     * Ported from apps/web/app/api/relay/route.ts (Vana App production code)
+     * DO NOT MODIFY without thorough testing in production environment.
+     *
+     * @param key - The key for storing the last used nonce
+     * @param pendingCount - The current pending transaction count from blockchain
+     * @returns The assigned nonce
+     */
+    atomicAssignNonce(key: string, pendingCount: number): Promise<number>;
+}

package/dist/lib/redisAtomicStore.js

@@ -0,0 +1,177 @@
+class RedisAtomicStore {
+  redis;
+  // ioredis instance
+  keyPrefix;
+  /**
+   * Lua script for safe lock release.
+   * This ensures we only delete a lock if the value matches our lock ID.
+   */
+  UNLOCK_SCRIPT = `
+    if redis.call("GET", KEYS[1]) == ARGV[1] then
+      return redis.call("DEL", KEYS[1])
+    else
+      return 0
+    end
+  `;
+  constructor(config) {
+    if (typeof config.redis === "string") {
+      throw new Error(
+        "RedisAtomicStore requires an initialized Redis client instance. Please create the Redis client in your application and pass it to the constructor."
+      );
+    }
+    this.redis = config.redis;
+    this.keyPrefix = config.keyPrefix ?? "vana-sdk:atomic";
+    if (!this.redis || typeof this.redis.incr !== "function" || typeof this.redis.set !== "function" || typeof this.redis.get !== "function" || typeof this.redis.eval !== "function") {
+      throw new Error(
+        "Invalid Redis client instance provided to RedisAtomicStore"
+      );
+    }
+  }
+  /**
+   * Atomically increments a counter.
+   */
+  async incr(key) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    return await this.redis.incr(fullKey);
+  }
+  /**
+   * Acquires a distributed lock using SET NX EX.
+   */
+  async acquireLock(key, ttlSeconds) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    const lockId = `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+    const result = await this.redis.set(
+      fullKey,
+      lockId,
+      "EX",
+      ttlSeconds,
+      "NX"
+    );
+    if (result === "OK") {
+      console.log(`[RedisAtomicStore] Lock acquired: ${key} with ID ${lockId}`);
+      return lockId;
+    }
+    return null;
+  }
+  /**
+   * Releases a lock using a Lua script for atomicity.
+   */
+  async releaseLock(key, lockId) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    const result = await this.redis.eval(
+      this.UNLOCK_SCRIPT,
+      1,
+      // Number of keys
+      fullKey,
+      // KEYS[1]
+      lockId
+      // ARGV[1]
+    );
+    if (result === 1) {
+      console.log(`[RedisAtomicStore] Lock released: ${key}`);
+    } else {
+      console.warn(
+        `[RedisAtomicStore] Lock release failed: ${key} (lock not held or expired)`
+      );
+    }
+  }
+  /**
+   * Gets a value from Redis.
+   */
+  async get(key) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    return await this.redis.get(fullKey);
+  }
+  /**
+   * Sets a value in Redis.
+   */
+  async set(key, value) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    await this.redis.set(fullKey, value);
+  }
+  /**
+   * Sets a value with TTL for automatic expiration.
+   */
+  async setWithTTL(key, value, ttlSeconds) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    await this.redis.setex(fullKey, ttlSeconds, value);
+  }
+  /**
+   * Deletes a key from Redis.
+   */
+  async delete(key) {
+    const fullKey = `${this.keyPrefix}:${key}`;
+    await this.redis.del(fullKey);
+  }
+  /**
+   * Executes a Lua script atomically.
+   *
+   * @remarks
+   * This provides generic script execution for complex atomic operations.
+   * Keys passed to the script will be automatically prefixed.
+   *
+   * @param script - The Lua script to execute
+   * @param keys - Array of keys (will be prefixed)
+   * @param args - Array of arguments
+   * @returns The script's return value
+   */
+  async eval(script, keys, args) {
+    const prefixedKeys = keys.map((key) => `${this.keyPrefix}:${key}`);
+    const result = await this.redis.eval(
+      script,
+      keys.length,
+      ...prefixedKeys,
+      ...args
+    );
+    return result;
+  }
+  /**
+   * Atomically assigns a nonce using Vana App's battle-tested logic.
+   *
+   * @remarks
+   * This is a Redis-specific optimization that uses a Lua script for
+   * atomic nonce assignment with gap prevention. This method is called
+   * by DistributedNonceManager when it detects a Redis store.
+   *
+   * Ported from apps/web/app/api/relay/route.ts (Vana App production code)
+   * DO NOT MODIFY without thorough testing in production environment.
+   *
+   * @param key - The key for storing the last used nonce
+   * @param pendingCount - The current pending transaction count from blockchain
+   * @returns The assigned nonce
+   */
+  async atomicAssignNonce(key, pendingCount) {
+    const LUA_ASSIGN_NONCE = `
+      -- KEYS[1] = lastUsedKey
+      -- ARGV[1] = pendingCount (integer)
+
+      local last = tonumber(redis.call("GET", KEYS[1]) or "-1")
+      local pending = tonumber(ARGV[1])
+      local candidate = last + 1
+      if pending > candidate or (candidate - pending > 500) then
+        -- If pending is ahead OR if candidate is too far ahead (>500 nonces), reset to pending
+        candidate = pending
+      end
+
+      -- IMPORTANT: Atomically update the last used nonce
+      redis.call("SET", KEYS[1], candidate)
+
+      return candidate
+    `;
+    const fullKey = `${this.keyPrefix}:${key}`;
+    const nonce = await this.redis.eval(
+      LUA_ASSIGN_NONCE,
+      1,
+      // Number of keys
+      fullKey,
+      // KEYS[1]
+      pendingCount.toString()
+      // ARGV[1]
+    );
+    return nonce;
+  }
+}
+export {
+  RedisAtomicStore
+};
+//# sourceMappingURL=redisAtomicStore.js.map

package/dist/lib/redisAtomicStore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/redisAtomicStore.ts"],"sourcesContent":["/**\n * Redis implementation of IAtomicStore for production use.\n *\n * @remarks\n * This is a Node.js-only implementation that requires the ioredis package.\n * It will not be included in browser bundles.\n *\n * @module\n */\n\nimport type { IAtomicStoreWithNonceSupport } from \"../types/atomicStore\";\n\n/**\n * Configuration for RedisAtomicStore\n */\nexport interface RedisAtomicStoreConfig {\n  /** Redis connection URL or ioredis options */\n  redis: string | any;\n  /** Key prefix for all operations (default: 'vana-sdk:atomic') */\n  keyPrefix?: string;\n}\n\n/**\n * Redis-backed implementation of IAtomicStore.\n *\n * @remarks\n * This implementation uses Redis's native atomic operations:\n * - INCR for atomic counter increments\n * - SET NX EX for distributed locking\n * - Lua script for safe lock release\n *\n * Redis is ideal for this use case because:\n * - All operations are atomic by design\n * - Built-in TTL support for automatic cleanup\n * - High performance (sub-millisecond operations)\n * - Battle-tested in production environments\n *\n * @example\n * ```typescript\n * import Redis from 'ioredis';\n * import { RedisAtomicStore } from '@opendatalabs/vana-sdk/node';\n *\n * const redis = new Redis(process.env.REDIS_URL);\n * const atomicStore = new RedisAtomicStore({\n *   redis: redis\n * });\n *\n * const vana = Vana({\n *   walletClient,\n *   atomicStore,\n *   operationStore\n * });\n * ```\n *\n * @category Storage\n */\nexport class RedisAtomicStore implements IAtomicStoreWithNonceSupport {\n  private redis: any; // ioredis instance\n  private keyPrefix: string;\n\n  /**\n   * Lua script for safe lock release.\n   * This ensures we only delete a lock if the value matches our lock ID.\n   */\n  private readonly UNLOCK_SCRIPT = `\n    if redis.call(\"GET\", KEYS[1]) == ARGV[1] then\n      return redis.call(\"DEL\", KEYS[1])\n    else\n      return 0\n    end\n  `;\n\n  constructor(config: RedisAtomicStoreConfig) {\n    // Dynamic import to avoid bundling ioredis in browser builds\n    // The actual Redis instance should be passed in already created\n    if (typeof config.redis === \"string\") {\n      throw new Error(\n        \"RedisAtomicStore requires an initialized Redis client instance. \" +\n          \"Please create the Redis client in your application and pass it to the constructor.\",\n      );\n    }\n\n    this.redis = config.redis;\n    this.keyPrefix = config.keyPrefix ?? \"vana-sdk:atomic\";\n\n    // Validate that the redis instance has the methods we need\n    if (\n      !this.redis ||\n      typeof this.redis.incr !== \"function\" ||\n      typeof this.redis.set !== \"function\" ||\n      typeof this.redis.get !== \"function\" ||\n      typeof this.redis.eval !== \"function\"\n    ) {\n      throw new Error(\n        \"Invalid Redis client instance provided to RedisAtomicStore\",\n      );\n    }\n  }\n\n  /**\n   * Atomically increments a counter.\n   */\n  async incr(key: string): Promise<number> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    return await this.redis.incr(fullKey);\n  }\n\n  /**\n   * Acquires a distributed lock using SET NX EX.\n   */\n  async acquireLock(key: string, ttlSeconds: number): Promise<string | null> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    const lockId = `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;\n\n    // SET key value NX EX ttl\n    const result = await this.redis.set(\n      fullKey,\n      lockId,\n      \"EX\",\n      ttlSeconds,\n      \"NX\",\n    );\n\n    if (result === \"OK\") {\n      console.log(`[RedisAtomicStore] Lock acquired: ${key} with ID ${lockId}`);\n      return lockId;\n    }\n\n    return null;\n  }\n\n  /**\n   * Releases a lock using a Lua script for atomicity.\n   */\n  async releaseLock(key: string, lockId: string): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n\n    // Use Lua script for atomic compare-and-delete\n    const result = (await this.redis.eval(\n      this.UNLOCK_SCRIPT,\n      1, // Number of keys\n      fullKey, // KEYS[1]\n      lockId, // ARGV[1]\n    )) as number;\n\n    if (result === 1) {\n      console.log(`[RedisAtomicStore] Lock released: ${key}`);\n    } else {\n      console.warn(\n        `[RedisAtomicStore] Lock release failed: ${key} (lock not held or expired)`,\n      );\n    }\n  }\n\n  /**\n   * Gets a value from Redis.\n   */\n  async get(key: string): Promise<string | null> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    return await this.redis.get(fullKey);\n  }\n\n  /**\n   * Sets a value in Redis.\n   */\n  async set(key: string, value: string): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    await this.redis.set(fullKey, value);\n  }\n\n  /**\n   * Sets a value with TTL for automatic expiration.\n   */\n  async setWithTTL?(\n    key: string,\n    value: string,\n    ttlSeconds: number,\n  ): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    await this.redis.setex(fullKey, ttlSeconds, value);\n  }\n\n  /**\n   * Deletes a key from Redis.\n   */\n  async delete?(key: string): Promise<void> {\n    const fullKey = `${this.keyPrefix}:${key}`;\n    await this.redis.del(fullKey);\n  }\n\n  /**\n   * Executes a Lua script atomically.\n   *\n   * @remarks\n   * This provides generic script execution for complex atomic operations.\n   * Keys passed to the script will be automatically prefixed.\n   *\n   * @param script - The Lua script to execute\n   * @param keys - Array of keys (will be prefixed)\n   * @param args - Array of arguments\n   * @returns The script's return value\n   */\n  async eval(script: string, keys: string[], args: string[]): Promise<any> {\n    // Apply key prefix to all keys\n    const prefixedKeys = keys.map((key) => `${this.keyPrefix}:${key}`);\n\n    // Execute the Lua script\n    const result = await this.redis.eval(\n      script,\n      keys.length,\n      ...prefixedKeys,\n      ...args,\n    );\n\n    return result;\n  }\n\n  /**\n   * Atomically assigns a nonce using Vana App's battle-tested logic.\n   *\n   * @remarks\n   * This is a Redis-specific optimization that uses a Lua script for\n   * atomic nonce assignment with gap prevention. This method is called\n   * by DistributedNonceManager when it detects a Redis store.\n   *\n   * Ported from apps/web/app/api/relay/route.ts (Vana App production code)\n   * DO NOT MODIFY without thorough testing in production environment.\n   *\n   * @param key - The key for storing the last used nonce\n   * @param pendingCount - The current pending transaction count from blockchain\n   * @returns The assigned nonce\n   */\n  async atomicAssignNonce(key: string, pendingCount: number): Promise<number> {\n    const LUA_ASSIGN_NONCE = `\n      -- KEYS[1] = lastUsedKey\n      -- ARGV[1] = pendingCount (integer)\n\n      local last = tonumber(redis.call(\"GET\", KEYS[1]) or \"-1\")\n      local pending = tonumber(ARGV[1])\n      local candidate = last + 1\n      if pending > candidate or (candidate - pending > 500) then\n        -- If pending is ahead OR if candidate is too far ahead (>500 nonces), reset to pending\n        candidate = pending\n      end\n\n      -- IMPORTANT: Atomically update the last used nonce\n      redis.call(\"SET\", KEYS[1], candidate)\n\n      return candidate\n    `;\n\n    const fullKey = `${this.keyPrefix}:${key}`;\n    const nonce = (await this.redis.eval(\n      LUA_ASSIGN_NONCE,\n      1, // Number of keys\n      fullKey, // KEYS[1]\n      pendingCount.toString(), // ARGV[1]\n    )) as number;\n\n    return nonce;\n  }\n}\n"],"mappings":"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","names":[]}