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

package/dist/core/nonceManager.cjs

@@ -0,0 +1,304 @@
+"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 nonceManager_exports = {};
+__export(nonceManager_exports, {
+  DistributedNonceManager: () => DistributedNonceManager
+});
+module.exports = __toCommonJS(nonceManager_exports);
+var import_atomicStore = require("../types/atomicStore");
+class DistributedNonceManager {
+  store;
+  publicClient;
+  lockTTL;
+  maxLockRetries;
+  lockRetryDelay;
+  constructor(config) {
+    this.store = config.atomicStore;
+    this.publicClient = config.publicClient;
+    this.lockTTL = config.lockTTL ?? 5;
+    this.maxLockRetries = config.maxLockRetries ?? 50;
+    this.lockRetryDelay = config.lockRetryDelay ?? 100;
+  }
+  /**
+   * Atomically assigns the next available nonce for an address.
+   *
+   * @remarks
+   * This method uses two strategies depending on the atomic store capabilities:
+   * 1. If the store provides atomicAssignNonce (store-specific optimization),
+   *    it uses that for maximum reliability and performance
+   * 2. Otherwise, it falls back to the lock-based approach:
+   *    - Acquires a distributed lock to prevent race conditions
+   *    - Queries the blockchain for the current pending nonce
+   *    - Syncs the stored nonce if blockchain is ahead
+   *    - Atomically increments and returns the next nonce
+   *    - Releases the lock
+   *
+   * @param address - The address to assign a nonce for
+   * @param chainId - The chain ID for the network
+   * @returns The assigned nonce, or null if lock acquisition fails
+   */
+  async assignNonce(address, chainId) {
+    const lastUsedKey = `nonce:${chainId}:${address}:lastUsed`;
+    const lockKey = `nonce:${chainId}:${address}:lock`;
+    if ((0, import_atomicStore.hasNonceSupport)(this.store)) {
+      try {
+        const pendingCount = await this.publicClient.getTransactionCount({
+          address,
+          blockTag: "pending"
+        });
+        const nonce = await this.store.atomicAssignNonce(
+          lastUsedKey,
+          pendingCount
+        );
+        console.log(
+          `[NonceManager] Assigned nonce ${nonce} for ${address} on chain ${chainId} (using store optimization)`
+        );
+        return nonce;
+      } catch (error) {
+        console.error(
+          "[NonceManager] Error during optimized nonce assignment:",
+          error
+        );
+        throw error;
+      }
+    }
+    let lockAcquired = false;
+    let retries = 0;
+    let acquiredLockId = null;
+    while (!lockAcquired && retries < this.maxLockRetries) {
+      acquiredLockId = await this.store.acquireLock(lockKey, this.lockTTL);
+      lockAcquired = acquiredLockId !== null;
+      if (lockAcquired && acquiredLockId) {
+        try {
+          const pendingCount = await this.publicClient.getTransactionCount({
+            address,
+            blockTag: "pending"
+          });
+          const blockchainPending = pendingCount === 0 ? -1 : pendingCount - 1;
+          const currentLastUsedStr = await this.store.get(lastUsedKey);
+          const currentLastUsed = currentLastUsedStr ? parseInt(currentLastUsedStr) : -1;
+          if (blockchainPending > currentLastUsed) {
+            await this.store.set(lastUsedKey, blockchainPending.toString());
+            console.log(
+              `[NonceManager] Synced nonce for ${address} on chain ${chainId}: ${currentLastUsed} -> ${blockchainPending}`
+            );
+          }
+          const nextNonce = await this.store.incr(lastUsedKey);
+          console.log(
+            `[NonceManager] Assigned nonce ${nextNonce} for ${address} on chain ${chainId}`
+          );
+          if (this.store.setWithTTL) {
+            const assignmentKey = `nonce:${chainId}:${address}:assignment:${nextNonce}`;
+            const metadata = {
+              nonce: nextNonce,
+              assignedAt: Date.now(),
+              address,
+              chainId
+            };
+            await this.store.setWithTTL(
+              assignmentKey,
+              JSON.stringify(metadata),
+              3600
+            );
+          }
+          return nextNonce;
+        } catch (error) {
+          console.error("[NonceManager] Error during nonce assignment:", error);
+          throw error;
+        } finally {
+          await this.store.releaseLock(lockKey, acquiredLockId);
+        }
+      } else {
+        retries++;
+        if (retries < this.maxLockRetries) {
+          const delay = Math.min(
+            this.lockRetryDelay * Math.pow(1.5, retries - 1),
+            5e3
+            // Cap at 5 seconds
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    console.error(
+      `[NonceManager] Failed to acquire lock for ${address} after ${this.maxLockRetries} attempts`
+    );
+    return null;
+  }
+  /**
+   * Resets the nonce counter for an address.
+   *
+   * @remarks
+   * Use with caution - should only be called when you're certain
+   * no transactions are pending. This is useful for recovery from
+   * stuck states.
+   *
+   * @param address - The address to reset nonce for
+   * @param chainId - The chain ID for the network
+   */
+  async resetNonce(address, chainId) {
+    const lastUsedKey = `nonce:${chainId}:${address}:lastUsed`;
+    const lockKey = `nonce:${chainId}:${address}:lock`;
+    const lockId = await this.acquireLockWithRetry(lockKey);
+    if (!lockId) {
+      throw new Error("Failed to acquire lock for nonce reset");
+    }
+    try {
+      const confirmedCount = await this.publicClient.getTransactionCount({
+        address,
+        blockTag: "latest"
+      });
+      const resetValue = confirmedCount === 0 ? -1 : confirmedCount - 1;
+      await this.store.set(lastUsedKey, resetValue.toString());
+      console.log(
+        `[NonceManager] Reset nonce for ${address} on chain ${chainId} to ${resetValue}`
+      );
+    } finally {
+      await this.store.releaseLock(lockKey, lockId);
+    }
+  }
+  /**
+   * Gets the current nonce state for monitoring/debugging.
+   *
+   * @param address - The address to check
+   * @param chainId - The chain ID for the network
+   * @returns Current nonce state information
+   */
+  async getNonceState(address, chainId) {
+    const lastUsedKey = `nonce:${chainId}:${address}:lastUsed`;
+    const lastUsedStr = await this.store.get(lastUsedKey);
+    const lastUsed = lastUsedStr ? parseInt(lastUsedStr) : -1;
+    const [pendingCount, confirmedCount] = await Promise.all([
+      this.publicClient.getTransactionCount({
+        address,
+        blockTag: "pending"
+      }),
+      this.publicClient.getTransactionCount({
+        address,
+        blockTag: "latest"
+      })
+    ]);
+    return {
+      lastUsed,
+      blockchainPending: pendingCount === 0 ? -1 : pendingCount - 1,
+      blockchainConfirmed: confirmedCount === 0 ? -1 : confirmedCount - 1
+    };
+  }
+  /**
+   * Helper to acquire lock with retries.
+   *
+   * @internal
+   */
+  async acquireLockWithRetry(lockKey) {
+    let retries = 0;
+    while (retries < this.maxLockRetries) {
+      const lockId = await this.store.acquireLock(lockKey, this.lockTTL);
+      if (lockId) {
+        return lockId;
+      }
+      retries++;
+      if (retries < this.maxLockRetries) {
+        const delay = Math.min(
+          this.lockRetryDelay * Math.pow(1.5, retries - 1),
+          5e3
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    return null;
+  }
+  /**
+   * Burns a stuck nonce by sending a minimal self-transfer with higher gas.
+   *
+   * @remarks
+   * This method implements Vana App's production nonce burning strategy.
+   * It sends a zero-value transaction to the same address with elevated gas
+   * to replace a stuck transaction and unblock the nonce queue.
+   *
+   * Ported from apps/web/app/api/relay/route.ts (Vana App production code)
+   *
+   * @param walletClient - The wallet client to send the burn transaction
+   * @param nonceToBurn - The nonce to burn
+   * @param address - The address whose nonce to burn
+   * @param chainId - The chain ID for the network
+   * @param gasMultiplier - Multiplier for gas prices (default: 1.5)
+   * @returns The transaction hash of the burn transaction
+   */
+  async burnNonce(walletClient, nonceToBurn, address, chainId, gasMultiplier = 1.5) {
+    try {
+      const fees = await this.publicClient.estimateFeesPerGas();
+      const bump = (x) => x * BigInt(Math.floor(gasMultiplier * 100)) / 100n;
+      const newMaxFee = bump(fees.maxFeePerGas);
+      const newMaxPriorityFee = bump(fees.maxPriorityFeePerGas);
+      console.log(
+        `[NonceManager] Burning stuck nonce ${nonceToBurn} with high gas price: maxFee ${newMaxFee}, maxPriorityFee ${newMaxPriorityFee}`
+      );
+      const burnTx = await walletClient.sendTransaction({
+        account: walletClient.account,
+        // WalletClient should have an account
+        to: address,
+        // Self-transfer
+        value: 0n,
+        nonce: nonceToBurn,
+        gas: 21000n,
+        // Minimal gas for transfer
+        maxFeePerGas: newMaxFee,
+        maxPriorityFeePerGas: newMaxPriorityFee,
+        chain: {
+          id: chainId,
+          name: chainId === 14800 ? "Vana Moksha" : "Vana Mainnet",
+          network: chainId === 14800 ? "moksha" : "mainnet",
+          nativeCurrency: { name: "VANA", symbol: "VANA", decimals: 18 },
+          rpcUrls: {
+            default: {
+              http: [
+                chainId === 14800 ? "https://rpc.moksha.vana.org" : "https://rpc.vana.org"
+              ]
+            },
+            public: {
+              http: [
+                chainId === 14800 ? "https://rpc.moksha.vana.org" : "https://rpc.vana.org"
+              ]
+            }
+          }
+        }
+      });
+      console.log(
+        `[NonceManager] Burn nonce ${nonceToBurn} transaction sent: ${burnTx}`
+      );
+      return burnTx;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      if (errorMessage.includes("nonce too low") || errorMessage.includes("underpriced") || errorMessage.includes("already known")) {
+        console.log(`[NonceManager] Nonce ${nonceToBurn} was already used`);
+      } else {
+        console.error(
+          `[NonceManager] Error burning nonce ${nonceToBurn}:`,
+          error
+        );
+      }
+      throw error;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DistributedNonceManager
+});
+//# sourceMappingURL=nonceManager.cjs.map

package/dist/core/nonceManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/nonceManager.ts"],"sourcesContent":["/**\n * Internal distributed nonce manager for atomic transaction nonce assignment.\n *\n * @internal\n * @module\n */\n\nimport type { PublicClient, WalletClient, Address, Hash } from \"viem\";\nimport type { IAtomicStore } from \"../types/atomicStore\";\nimport { hasNonceSupport } from \"../types/atomicStore\";\n\n/**\n * Configuration for the distributed nonce manager.\n *\n * @internal\n */\nexport interface NonceManagerConfig {\n  /** Atomic store for distributed coordination */\n  atomicStore: IAtomicStore;\n  /** Public client for blockchain queries */\n  publicClient: PublicClient;\n  /** TTL for nonce locks in seconds (default: 5) */\n  lockTTL?: number;\n  /** Maximum retries to acquire lock (default: 50) */\n  maxLockRetries?: number;\n  /** Delay between lock retries in milliseconds (default: 100) */\n  lockRetryDelay?: number;\n}\n\n/**\n * Internal nonce manager that coordinates distributed nonce assignment.\n *\n * @internal\n * @remarks\n * This class implements sophisticated logic for atomic nonce assignment\n * in distributed environments. It uses the provided IAtomicStore to\n * coordinate between multiple instances and prevent nonce conflicts.\n *\n * Key features:\n * - Store-specific optimizations when available (e.g., Redis Lua scripts)\n * - Fallback to distributed locking for generic stores\n * - Syncing with blockchain pending count\n * - Nonce gap prevention\n * - Nonce burning capability for stuck transactions\n */\nexport class DistributedNonceManager {\n  private readonly store: IAtomicStore;\n  private readonly publicClient: PublicClient;\n  private readonly lockTTL: number;\n  private readonly maxLockRetries: number;\n  private readonly lockRetryDelay: number;\n\n  constructor(config: NonceManagerConfig) {\n    this.store = config.atomicStore;\n    this.publicClient = config.publicClient;\n    this.lockTTL = config.lockTTL ?? 5;\n    this.maxLockRetries = config.maxLockRetries ?? 50;\n    this.lockRetryDelay = config.lockRetryDelay ?? 100;\n  }\n\n  /**\n   * Atomically assigns the next available nonce for an address.\n   *\n   * @remarks\n   * This method uses two strategies depending on the atomic store capabilities:\n   * 1. If the store provides atomicAssignNonce (store-specific optimization),\n   *    it uses that for maximum reliability and performance\n   * 2. Otherwise, it falls back to the lock-based approach:\n   *    - Acquires a distributed lock to prevent race conditions\n   *    - Queries the blockchain for the current pending nonce\n   *    - Syncs the stored nonce if blockchain is ahead\n   *    - Atomically increments and returns the next nonce\n   *    - Releases the lock\n   *\n   * @param address - The address to assign a nonce for\n   * @param chainId - The chain ID for the network\n   * @returns The assigned nonce, or null if lock acquisition fails\n   */\n  async assignNonce(address: Address, chainId: number): Promise<number | null> {\n    const lastUsedKey = `nonce:${chainId}:${address}:lastUsed`;\n    const lockKey = `nonce:${chainId}:${address}:lock`;\n\n    // Check if the store provides an optimized atomic nonce assignment\n    if (hasNonceSupport(this.store)) {\n      try {\n        // Get pending transaction count from blockchain\n        const pendingCount = await this.publicClient.getTransactionCount({\n          address,\n          blockTag: \"pending\",\n        });\n\n        // Use store-specific optimized implementation (e.g., Redis Lua script)\n        const nonce = await this.store.atomicAssignNonce(\n          lastUsedKey,\n          pendingCount,\n        );\n\n        console.log(\n          `[NonceManager] Assigned nonce ${nonce} for ${address} on chain ${chainId} (using store optimization)`,\n        );\n\n        return nonce;\n      } catch (error) {\n        console.error(\n          \"[NonceManager] Error during optimized nonce assignment:\",\n          error,\n        );\n        throw error;\n      }\n    }\n\n    // Try to acquire lock with retries\n    let lockAcquired = false;\n    let retries = 0;\n    let acquiredLockId: string | null = null;\n\n    while (!lockAcquired && retries < this.maxLockRetries) {\n      // Try to acquire the lock\n      acquiredLockId = await this.store.acquireLock(lockKey, this.lockTTL);\n      lockAcquired = acquiredLockId !== null;\n\n      if (lockAcquired && acquiredLockId) {\n        try {\n          // Get pending transaction count from blockchain\n          const pendingCount = await this.publicClient.getTransactionCount({\n            address,\n            blockTag: \"pending\",\n          });\n\n          // Calculate the pending nonce (0-indexed)\n          // If no transactions, start at 0\n          const blockchainPending = pendingCount === 0 ? -1 : pendingCount - 1;\n\n          // Get current lastUsed from store\n          const currentLastUsedStr = await this.store.get(lastUsedKey);\n          const currentLastUsed = currentLastUsedStr\n            ? parseInt(currentLastUsedStr)\n            : -1;\n\n          // Sync lastUsed with blockchain if blockchain is ahead\n          // This handles cases where transactions were sent outside this system\n          if (blockchainPending > currentLastUsed) {\n            await this.store.set(lastUsedKey, blockchainPending.toString());\n            console.log(\n              `[NonceManager] Synced nonce for ${address} on chain ${chainId}: ${currentLastUsed} -> ${blockchainPending}`,\n            );\n          }\n\n          // Atomically increment and get next nonce\n          const nextNonce = await this.store.incr(lastUsedKey);\n\n          console.log(\n            `[NonceManager] Assigned nonce ${nextNonce} for ${address} on chain ${chainId}`,\n          );\n\n          // Store assignment metadata for debugging (optional TTL)\n          if (this.store.setWithTTL) {\n            const assignmentKey = `nonce:${chainId}:${address}:assignment:${nextNonce}`;\n            const metadata = {\n              nonce: nextNonce,\n              assignedAt: Date.now(),\n              address,\n              chainId,\n            };\n            // Store for 1 hour for debugging\n            await this.store.setWithTTL(\n              assignmentKey,\n              JSON.stringify(metadata),\n              3600,\n            );\n          }\n\n          return nextNonce;\n        } catch (error) {\n          console.error(\"[NonceManager] Error during nonce assignment:\", error);\n          throw error;\n        } finally {\n          // Always release the lock\n          await this.store.releaseLock(lockKey, acquiredLockId);\n        }\n      } else {\n        // Failed to acquire lock, wait and retry with exponential backoff\n        retries++;\n        if (retries < this.maxLockRetries) {\n          const delay = Math.min(\n            this.lockRetryDelay * Math.pow(1.5, retries - 1),\n            5000, // Cap at 5 seconds\n          );\n          await new Promise((resolve) => setTimeout(resolve, delay));\n        }\n      }\n    }\n\n    console.error(\n      `[NonceManager] Failed to acquire lock for ${address} after ${this.maxLockRetries} attempts`,\n    );\n    return null;\n  }\n\n  /**\n   * Resets the nonce counter for an address.\n   *\n   * @remarks\n   * Use with caution - should only be called when you're certain\n   * no transactions are pending. This is useful for recovery from\n   * stuck states.\n   *\n   * @param address - The address to reset nonce for\n   * @param chainId - The chain ID for the network\n   */\n  async resetNonce(address: Address, chainId: number): Promise<void> {\n    const lastUsedKey = `nonce:${chainId}:${address}:lastUsed`;\n    const lockKey = `nonce:${chainId}:${address}:lock`;\n\n    // Acquire lock before resetting\n    const lockId = await this.acquireLockWithRetry(lockKey);\n    if (!lockId) {\n      throw new Error(\"Failed to acquire lock for nonce reset\");\n    }\n\n    try {\n      // Get confirmed transaction count from blockchain\n      const confirmedCount = await this.publicClient.getTransactionCount({\n        address,\n        blockTag: \"latest\",\n      });\n\n      // Reset to blockchain state (confirmed count - 1 since we're 0-indexed)\n      const resetValue = confirmedCount === 0 ? -1 : confirmedCount - 1;\n      await this.store.set(lastUsedKey, resetValue.toString());\n\n      console.log(\n        `[NonceManager] Reset nonce for ${address} on chain ${chainId} to ${resetValue}`,\n      );\n    } finally {\n      await this.store.releaseLock(lockKey, lockId);\n    }\n  }\n\n  /**\n   * Gets the current nonce state for monitoring/debugging.\n   *\n   * @param address - The address to check\n   * @param chainId - The chain ID for the network\n   * @returns Current nonce state information\n   */\n  async getNonceState(\n    address: Address,\n    chainId: number,\n  ): Promise<{\n    lastUsed: number;\n    blockchainPending: number;\n    blockchainConfirmed: number;\n  }> {\n    const lastUsedKey = `nonce:${chainId}:${address}:lastUsed`;\n\n    // Get stored state\n    const lastUsedStr = await this.store.get(lastUsedKey);\n    const lastUsed = lastUsedStr ? parseInt(lastUsedStr) : -1;\n\n    // Get blockchain state\n    const [pendingCount, confirmedCount] = await Promise.all([\n      this.publicClient.getTransactionCount({\n        address,\n        blockTag: \"pending\",\n      }),\n      this.publicClient.getTransactionCount({\n        address,\n        blockTag: \"latest\",\n      }),\n    ]);\n\n    return {\n      lastUsed,\n      blockchainPending: pendingCount === 0 ? -1 : pendingCount - 1,\n      blockchainConfirmed: confirmedCount === 0 ? -1 : confirmedCount - 1,\n    };\n  }\n\n  /**\n   * Helper to acquire lock with retries.\n   *\n   * @internal\n   */\n  private async acquireLockWithRetry(lockKey: string): Promise<string | null> {\n    let retries = 0;\n\n    while (retries < this.maxLockRetries) {\n      const lockId = await this.store.acquireLock(lockKey, this.lockTTL);\n\n      if (lockId) {\n        return lockId;\n      }\n\n      retries++;\n      if (retries < this.maxLockRetries) {\n        const delay = Math.min(\n          this.lockRetryDelay * Math.pow(1.5, retries - 1),\n          5000,\n        );\n        await new Promise((resolve) => setTimeout(resolve, delay));\n      }\n    }\n\n    return null;\n  }\n\n  /**\n   * Burns a stuck nonce by sending a minimal self-transfer with higher gas.\n   *\n   * @remarks\n   * This method implements Vana App's production nonce burning strategy.\n   * It sends a zero-value transaction to the same address with elevated gas\n   * to replace a stuck transaction and unblock the nonce queue.\n   *\n   * Ported from apps/web/app/api/relay/route.ts (Vana App production code)\n   *\n   * @param walletClient - The wallet client to send the burn transaction\n   * @param nonceToBurn - The nonce to burn\n   * @param address - The address whose nonce to burn\n   * @param chainId - The chain ID for the network\n   * @param gasMultiplier - Multiplier for gas prices (default: 1.5)\n   * @returns The transaction hash of the burn transaction\n   */\n  async burnNonce(\n    walletClient: WalletClient,\n    nonceToBurn: number,\n    address: Address,\n    chainId: number,\n    gasMultiplier: number = 1.5,\n  ): Promise<Hash> {\n    try {\n      // Get current gas prices\n      const fees = await this.publicClient.estimateFeesPerGas();\n\n      // Bump gas prices by multiplier (Vana App's exact formula)\n      const bump = (x: bigint) =>\n        (x * BigInt(Math.floor(gasMultiplier * 100))) / 100n;\n\n      const newMaxFee = bump(fees.maxFeePerGas);\n      const newMaxPriorityFee = bump(fees.maxPriorityFeePerGas);\n\n      console.log(\n        `[NonceManager] Burning stuck nonce ${nonceToBurn} with high gas price: maxFee ${newMaxFee}, maxPriorityFee ${newMaxPriorityFee}`,\n      );\n\n      // Send minimal self-transfer to burn the nonce\n      const burnTx = await walletClient.sendTransaction({\n        account: walletClient.account!, // WalletClient should have an account\n        to: address, // Self-transfer\n        value: 0n,\n        nonce: nonceToBurn,\n        gas: 21000n, // Minimal gas for transfer\n        maxFeePerGas: newMaxFee,\n        maxPriorityFeePerGas: newMaxPriorityFee,\n        chain: {\n          id: chainId,\n          name: chainId === 14800 ? \"Vana Moksha\" : \"Vana Mainnet\",\n          network: chainId === 14800 ? \"moksha\" : \"mainnet\",\n          nativeCurrency: { name: \"VANA\", symbol: \"VANA\", decimals: 18 },\n          rpcUrls: {\n            default: {\n              http: [\n                chainId === 14800\n                  ? \"https://rpc.moksha.vana.org\"\n                  : \"https://rpc.vana.org\",\n              ],\n            },\n            public: {\n              http: [\n                chainId === 14800\n                  ? \"https://rpc.moksha.vana.org\"\n                  : \"https://rpc.vana.org\",\n              ],\n            },\n          },\n        },\n      });\n\n      console.log(\n        `[NonceManager] Burn nonce ${nonceToBurn} transaction sent: ${burnTx}`,\n      );\n\n      return burnTx;\n    } catch (error) {\n      const errorMessage =\n        error instanceof Error ? error.message : \"Unknown error\";\n\n      // Check for common errors that indicate nonce was already used\n      if (\n        errorMessage.includes(\"nonce too low\") ||\n        errorMessage.includes(\"underpriced\") ||\n        errorMessage.includes(\"already known\")\n      ) {\n        console.log(`[NonceManager] Nonce ${nonceToBurn} was already used`);\n      } else {\n        console.error(\n          `[NonceManager] Error burning nonce ${nonceToBurn}:`,\n          error,\n        );\n      }\n\n      throw error;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/core/nonceManager.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Internal distributed nonce manager for atomic transaction nonce assignment.
+ *
+ * @internal
+ * @module
+ */
+import type { PublicClient, WalletClient, Address, Hash } from "viem";
+import type { IAtomicStore } from "../types/atomicStore";
+/**
+ * Configuration for the distributed nonce manager.
+ *
+ * @internal
+ */
+export interface NonceManagerConfig {
+    /** Atomic store for distributed coordination */
+    atomicStore: IAtomicStore;
+    /** Public client for blockchain queries */
+    publicClient: PublicClient;
+    /** TTL for nonce locks in seconds (default: 5) */
+    lockTTL?: number;
+    /** Maximum retries to acquire lock (default: 50) */
+    maxLockRetries?: number;
+    /** Delay between lock retries in milliseconds (default: 100) */
+    lockRetryDelay?: number;
+}
+/**
+ * Internal nonce manager that coordinates distributed nonce assignment.
+ *
+ * @internal
+ * @remarks
+ * This class implements sophisticated logic for atomic nonce assignment
+ * in distributed environments. It uses the provided IAtomicStore to
+ * coordinate between multiple instances and prevent nonce conflicts.
+ *
+ * Key features:
+ * - Store-specific optimizations when available (e.g., Redis Lua scripts)
+ * - Fallback to distributed locking for generic stores
+ * - Syncing with blockchain pending count
+ * - Nonce gap prevention
+ * - Nonce burning capability for stuck transactions
+ */
+export declare class DistributedNonceManager {
+    private readonly store;
+    private readonly publicClient;
+    private readonly lockTTL;
+    private readonly maxLockRetries;
+    private readonly lockRetryDelay;
+    constructor(config: NonceManagerConfig);
+    /**
+     * Atomically assigns the next available nonce for an address.
+     *
+     * @remarks
+     * This method uses two strategies depending on the atomic store capabilities:
+     * 1. If the store provides atomicAssignNonce (store-specific optimization),
+     *    it uses that for maximum reliability and performance
+     * 2. Otherwise, it falls back to the lock-based approach:
+     *    - Acquires a distributed lock to prevent race conditions
+     *    - Queries the blockchain for the current pending nonce
+     *    - Syncs the stored nonce if blockchain is ahead
+     *    - Atomically increments and returns the next nonce
+     *    - Releases the lock
+     *
+     * @param address - The address to assign a nonce for
+     * @param chainId - The chain ID for the network
+     * @returns The assigned nonce, or null if lock acquisition fails
+     */
+    assignNonce(address: Address, chainId: number): Promise<number | null>;
+    /**
+     * Resets the nonce counter for an address.
+     *
+     * @remarks
+     * Use with caution - should only be called when you're certain
+     * no transactions are pending. This is useful for recovery from
+     * stuck states.
+     *
+     * @param address - The address to reset nonce for
+     * @param chainId - The chain ID for the network
+     */
+    resetNonce(address: Address, chainId: number): Promise<void>;
+    /**
+     * Gets the current nonce state for monitoring/debugging.
+     *
+     * @param address - The address to check
+     * @param chainId - The chain ID for the network
+     * @returns Current nonce state information
+     */
+    getNonceState(address: Address, chainId: number): Promise<{
+        lastUsed: number;
+        blockchainPending: number;
+        blockchainConfirmed: number;
+    }>;
+    /**
+     * Helper to acquire lock with retries.
+     *
+     * @internal
+     */
+    private acquireLockWithRetry;
+    /**
+     * Burns a stuck nonce by sending a minimal self-transfer with higher gas.
+     *
+     * @remarks
+     * This method implements Vana App's production nonce burning strategy.
+     * It sends a zero-value transaction to the same address with elevated gas
+     * to replace a stuck transaction and unblock the nonce queue.
+     *
+     * Ported from apps/web/app/api/relay/route.ts (Vana App production code)
+     *
+     * @param walletClient - The wallet client to send the burn transaction
+     * @param nonceToBurn - The nonce to burn
+     * @param address - The address whose nonce to burn
+     * @param chainId - The chain ID for the network
+     * @param gasMultiplier - Multiplier for gas prices (default: 1.5)
+     * @returns The transaction hash of the burn transaction
+     */
+    burnNonce(walletClient: WalletClient, nonceToBurn: number, address: Address, chainId: number, gasMultiplier?: number): Promise<Hash>;
+}