@secondlayer/stacks 2.5.2 → 2.6.0

package/dist/src/index.d.ts

@@ -27,106 +27,6 @@ type ProviderAccount = {
 	publicKey: string
 	provider: StacksProvider
 };
-/** Full chain descriptor used by clients and transports for network-aware operations. */
-type StacksChain = {
-	/** Chain ID (e.g. 0x00000001 for mainnet) */
-	id: number
-	/** Human-readable name */
-	name: string
-	/** Network type */
-	network: "mainnet" | "testnet"
-	/** Transaction version byte for serialization */
-	transactionVersion: number
-	/** Peer network ID for P2P broadcasting */
-	peerNetworkId: number
-	/** Address version bytes */
-	addressVersion: {
-		singleSig: number
-		multiSig: number
-	}
-	/** Magic bytes for network identification */
-	magicBytes: string
-	/** Boot address (system contracts deployer) */
-	bootAddress: string
-	/** Native currency info */
-	nativeCurrency: {
-		name: string
-		symbol: string
-		decimals: number
-	}
-	/** Default RPC URLs */
-	rpcUrls: {
-		default: {
-			http: string[]
-			ws?: string[]
-		}
-	}
-	/** Block explorer URLs */
-	blockExplorers?: {
-		default: {
-			name: string
-			url: string
-		}
-	}
-};
-/** Function that sends an HTTP request to a Stacks node API path. */
-type RequestFn = (path: string, options?: RequestOptions) => Promise<any>;
-/** Options for a transport-level HTTP request. */
-type RequestOptions = {
-	method?: "GET" | "POST" | "PUT" | "DELETE"
-	body?: unknown
-	headers?: Record<string, string>
-};
-/** Shared configuration for all transport types. */
-type TransportConfig = {
-	url?: string
-	timeout?: number
-	retryCount?: number
-	retryDelay?: number
-	fetchOptions?: RequestInit
-	apiKey?: string
-};
-/** A resolved transport instance with a bound request function. */
-type Transport = {
-	type: string
-	request: RequestFn
-	config: TransportConfig
-	destroy?: () => void
-};
-/** Factory that creates a {@link Transport} given an optional chain context. */
-type TransportFactory = (params?: {
-	chain?: StacksChain
-}) => Transport;
-/** Union of all supported account types (local key, custom signer, or browser provider). */
-type Account = LocalAccount | CustomAccount | ProviderAccount;
-/**
-* Core client instance that holds chain context, transport, and extensible actions.
-* Created via {@link createClient}, {@link createPublicClient}, or {@link createWalletClient}.
-*/
-type Client<TExtended extends Record<string, unknown> = Record<string, unknown>> = {
-	chain?: StacksChain
-	account?: Account
-	transport: Transport
-	request: RequestFn
-	extend: <const TNew extends Record<string, unknown>>(fn: (client: Client<TExtended>) => TNew) => Client<TExtended & TNew> & TNew
-} & TExtended;
-/** Configuration for creating a base {@link Client}. */
-type ClientConfig = {
-	chain?: StacksChain
-	transport: TransportFactory
-	account?: Account
-};
-/** A client pre-extended with read-only {@link PublicActions}. */
-type PublicClient<TExtended extends Record<string, unknown> = Record<string, unknown>> = Client<TExtended>;
-/** A client pre-extended with {@link WalletActions} and a required account. */
-type WalletClient<TExtended extends Record<string, unknown> = Record<string, unknown>> = Client<TExtended> & {
-	account: Account
-};
-/**
-* Create a base client with transport and optional chain/account.
-* Use `.extend()` to compose action decorators (public, wallet, multisig).
-*/
-declare function createClient<TExtended extends Record<string, unknown> = Record<string, unknown>>(config: ClientConfig): Client<TExtended>;
 type IntCV = {
 	readonly type: "int"
 	readonly value: bigint
@@ -377,6 +277,187 @@ type AssetInfoWire = {
 	contractName: string
 	assetName: string
 };
+/**
+* Provides the confirmed on-chain nonce floor for an address.
+*
+* The default {@link jsonRpcSource} reads the configured node's `/v2/accounts`
+* endpoint — node-agnostic, no Hiro dependency. Other sources (mempool-aware,
+* first-party Index) can be swapped in without touching the manager.
+*/
+type NonceManagerSource = {
+	get(params: {
+		client: Client
+		address: string
+	}): Promise<bigint>
+};
+/**
+* Holds per-address allocation state and hands out the next nonce.
+*
+* `reserve` MUST be atomic per `key`: two concurrent reservations for the same
+* key must never return the same value. The in-memory {@link memoryStore}
+* serializes with a per-key promise chain; a persisted store (Redis `INCR`,
+* Postgres `SELECT ... FOR UPDATE`) becomes the cross-process lock for the
+* multi-builder / smart-wallet-as-a-service case.
+*/
+type NonceStore = {
+	/**
+	* Reserve the next nonce for `key`. `getFloor` reads the confirmed on-chain
+	* nonce; it is only invoked when the store has no tracked value (cold start
+	* or after {@link NonceStore.reset}).
+	*/
+	reserve(key: string, getFloor: () => Promise<bigint>): Promise<bigint>
+	/** Forget tracked state for `key` so the next reserve re-syncs from the floor. */
+	reset(key: string): void | Promise<void>
+};
+/** Allocates mempool-safe sequential nonces across rapid broadcasts from one account. */
+type NonceManager = {
+	consume(params: {
+		client: Client
+		address: string
+	}): Promise<bigint>
+	reset(params: {
+		client: Client
+		address: string
+	}): void | Promise<void>
+};
+type CreateNonceManagerParams = {
+	source?: NonceManagerSource
+	store?: NonceStore
+};
+/** Confirmed-nonce source backed by the configured node's `/v2/accounts` RPC (no Hiro dependency). */
+declare function jsonRpcSource(): NonceManagerSource;
+/**
+* In-memory, single-process store. Tracks the next nonce per key and serializes
+* concurrent reservations with a per-key promise chain.
+*
+* Correct only within one process — swap in a persisted store for multi-process
+* deployments that share a signing key.
+*/
+declare function memoryStore(): NonceStore;
+/**
+* Create a nonce manager that floors on a confirmed-nonce {@link NonceManagerSource}
+* and increments a {@link NonceStore} on every {@link NonceManager.consume}.
+*
+* Defaults to {@link jsonRpcSource} + {@link memoryStore} — node-agnostic,
+* single-process, zero external dependencies.
+*/
+declare function createNonceManager(params?: CreateNonceManagerParams): NonceManager;
+/** Resolve the next nonce via the client's nonce manager, falling back to a confirmed read. */
+declare function resolveNonce(client: Client, address: string): Promise<bigint>;
+/** True when a broadcast was rejected for a nonce conflict (`ConflictingNonceInMempool`, `BadNonce`). */
+declare function isNonceConflictError(error: unknown): boolean;
+/**
+* Broadcast a signed transaction; on a nonce-conflict rejection, reset the
+* manager so the next build re-syncs to the confirmed floor.
+*/
+declare function broadcastWithNonceReset(client: Client, params: {
+	transaction: StacksTransaction
+	address: string
+}): Promise<string>;
+/** Full chain descriptor used by clients and transports for network-aware operations. */
+type StacksChain = {
+	/** Chain ID (e.g. 0x00000001 for mainnet) */
+	id: number
+	/** Human-readable name */
+	name: string
+	/** Network type */
+	network: "mainnet" | "testnet"
+	/** Transaction version byte for serialization */
+	transactionVersion: number
+	/** Peer network ID for P2P broadcasting */
+	peerNetworkId: number
+	/** Address version bytes */
+	addressVersion: {
+		singleSig: number
+		multiSig: number
+	}
+	/** Magic bytes for network identification */
+	magicBytes: string
+	/** Boot address (system contracts deployer) */
+	bootAddress: string
+	/** Native currency info */
+	nativeCurrency: {
+		name: string
+		symbol: string
+		decimals: number
+	}
+	/** Default RPC URLs */
+	rpcUrls: {
+		default: {
+			http: string[]
+			ws?: string[]
+		}
+	}
+	/** Block explorer URLs */
+	blockExplorers?: {
+		default: {
+			name: string
+			url: string
+		}
+	}
+};
+/** Function that sends an HTTP request to a Stacks node API path. */
+type RequestFn = (path: string, options?: RequestOptions) => Promise<any>;
+/** Options for a transport-level HTTP request. */
+type RequestOptions = {
+	method?: "GET" | "POST" | "PUT" | "DELETE"
+	body?: unknown
+	headers?: Record<string, string>
+};
+/** Shared configuration for all transport types. */
+type TransportConfig = {
+	url?: string
+	timeout?: number
+	retryCount?: number
+	retryDelay?: number
+	fetchOptions?: RequestInit
+	apiKey?: string
+};
+/** A resolved transport instance with a bound request function. */
+type Transport = {
+	type: string
+	request: RequestFn
+	config: TransportConfig
+	destroy?: () => void
+};
+/** Factory that creates a {@link Transport} given an optional chain context. */
+type TransportFactory = (params?: {
+	chain?: StacksChain
+}) => Transport;
+/** Union of all supported account types (local key, custom signer, or browser provider). */
+type Account = LocalAccount | CustomAccount | ProviderAccount;
+/**
+* Core client instance that holds chain context, transport, and extensible actions.
+* Created via {@link createClient}, {@link createPublicClient}, or {@link createWalletClient}.
+*/
+type Client<TExtended extends Record<string, unknown> = Record<string, unknown>> = {
+	chain?: StacksChain
+	account?: Account
+	transport: Transport
+	request: RequestFn
+	/** Optional nonce manager for mempool-safe sequential nonces across rapid broadcasts. */
+	nonceManager?: NonceManager
+	extend: <const TNew extends Record<string, unknown>>(fn: (client: Client<TExtended>) => TNew) => Client<TExtended & TNew> & TNew
+} & TExtended;
+/** Configuration for creating a base {@link Client}. */
+type ClientConfig = {
+	chain?: StacksChain
+	transport: TransportFactory
+	account?: Account
+	/** Optional nonce manager threaded onto the client (see {@link createNonceManager}). */
+	nonceManager?: NonceManager
+};
+/** A client pre-extended with read-only {@link PublicActions}. */
+type PublicClient<TExtended extends Record<string, unknown> = Record<string, unknown>> = Client<TExtended>;
+/** A client pre-extended with {@link WalletActions} and a required account. */
+type WalletClient<TExtended extends Record<string, unknown> = Record<string, unknown>> = Client<TExtended> & {
+	account: Account
+};
+/**
+* Create a base client with transport and optional chain/account.
+* Use `.extend()` to compose action decorators (public, wallet, multisig).
+*/
+declare function createClient<TExtended extends Record<string, unknown> = Record<string, unknown>>(config: ClientConfig): Client<TExtended>;
 type EstimateFeeParams = {
 	transaction: StacksTransaction
 };
@@ -812,6 +893,52 @@ type MultiSigClient = Client<MultiSigActions> & MultiSigActions;
 */
 declare function createMultiSigClient(config: MultiSigClientConfig): MultiSigClient;
 /**
+* Persisted {@link NonceStore} adapters for multi-process / multi-builder
+* deployments (the smart-wallet-as-a-service case).
+*
+* The in-memory {@link memoryStore} is correct only within one process: two
+* workers sharing a signing key both read the same confirmed floor and collide.
+* These adapters move the atomic reserve into a shared datastore — Redis `INCR`
+* inside an `EVAL`, or a single Postgres upsert under a row lock — so the store
+* itself becomes the cross-process lock and the durable source of truth.
+*
+* Both are dependency-injected: pass your own `Bun.redis` / `Bun.sql` client.
+* No global `Bun` reference, so importing this module is runtime-agnostic.
+*/
+/** Minimal structural shape of a `Bun.redis` client (the `send` escape hatch). */
+type RedisLike = {
+	send(command: string, args: string[]): Promise<unknown>
+};
+type RedisStoreParams = {
+	redis: RedisLike
+	/** Key prefix for stored nonce counters. Default `"stacks:nonce:"`. */
+	prefix?: string
+};
+/**
+* Redis-backed nonce store. The atomic reserve lives in a Lua `EVAL`, so it is
+* safe across processes sharing one Redis. The confirmed floor (`getFloor`) is
+* read only once per key, on cold start.
+*/
+declare function redisStore(params: RedisStoreParams): NonceStore;
+/** Minimal structural shape of a `Bun.sql` tagged-template client. */
+type SqlLike = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Array<Record<string, unknown>>>;
+type PostgresStoreParams = {
+	sql: SqlLike
+	/**
+	* Run `CREATE TABLE IF NOT EXISTS stacks_nonce_state` lazily on first use.
+	* Default `true`. Set `false` if you manage the schema via migrations.
+	*/
+	ensureTable?: boolean
+};
+/**
+* Postgres-backed nonce store. Each reserve is a single atomic statement under
+* a row lock, so concurrent reservers on the same key serialize and never
+* collide across processes. State is durable — survives restarts.
+*
+* Uses a fixed table `stacks_nonce_state (key text primary key, next numeric)`.
+*/
+declare function postgresStore(params: PostgresStoreParams): NonceStore;
+/**
 * Create an HTTP transport for Stacks node RPC calls.
 * Falls back to the chain's default RPC URL, then `localhost:3999`.
 */
@@ -1069,4 +1196,4 @@ declare class ReadOnlyCallError extends BaseError {
 declare class WebSocketError extends BaseError {
 	name: string;
 }
-export { webSocket, walletActions, testnet, publicActions, providerToAccount, parseStx, exports_on as on, multisigActions, mocknet, mainnet, isValidAddress, isAddressEqual, http, getContractAddress, formatStx, fallback, devnet, defineChain, custom, createWalletClient, createPublicClient, createMultiSigClient, createClient, ZERO_ADDRESS, WebSocketTransportConfig, WebSocketTransport, WebSocketError, WalletClientConfig, WalletClient, WalletActions, TransportFactory, TransportConfig, Transport, TransactionError, TESTNET_ZERO_ADDRESS, SubscriptionFilterSpec, Subscription, StacksProvider, StacksChain, SimulationError, SigningError, SerializationError, RequestOptions, RequestFn, ReadOnlyCallError, PublicClientConfig, PublicClient, PublicActions, ProviderAccount, PoxFunction, MultiSigClientConfig, MultiSigClient, MultiSigActions, MICROSTX_PER_STX, LocalAccount, FilterPrimitive, FilterOperator, FilterClause, Filter, FactoryTarget, CustomAccount, ContractCallError, ClientConfig, Client, BroadcastError, BnsAction, BaseError, AddressVersion, Account };
+export { webSocket, walletActions, testnet, resolveNonce, redisStore, publicActions, providerToAccount, postgresStore, parseStx, exports_on as on, multisigActions, mocknet, memoryStore, mainnet, jsonRpcSource, isValidAddress, isNonceConflictError, isAddressEqual, http, getContractAddress, formatStx, fallback, devnet, defineChain, custom, createWalletClient, createPublicClient, createNonceManager, createMultiSigClient, createClient, broadcastWithNonceReset, ZERO_ADDRESS, WebSocketTransportConfig, WebSocketTransport, WebSocketError, WalletClientConfig, WalletClient, WalletActions, TransportFactory, TransportConfig, Transport, TransactionError, TESTNET_ZERO_ADDRESS, SubscriptionFilterSpec, Subscription, StacksProvider, StacksChain, SqlLike, SimulationError, SigningError, SerializationError, RequestOptions, RequestFn, RedisStoreParams, RedisLike, ReadOnlyCallError, PublicClientConfig, PublicClient, PublicActions, ProviderAccount, PoxFunction, PostgresStoreParams, NonceStore, NonceManagerSource, NonceManager, MultiSigClientConfig, MultiSigClient, MultiSigActions, MICROSTX_PER_STX, LocalAccount, FilterPrimitive, FilterOperator, FilterClause, Filter, FactoryTarget, CustomAccount, CreateNonceManagerParams, ContractCallError, ClientConfig, Client, BroadcastError, BnsAction, BaseError, AddressVersion, Account };

package/dist/src/index.js

@@ -22,12 +22,12 @@ import {
   simulateCall,
   simulateTransaction,
   transferStx
-} from "../shared/stacks-5th5dffx.js";
+} from "../shared/stacks-yb8xesdm.js";
 import {
   callContract,
   getMapEntry,
   readContract
-} from "../shared/stacks-yq5a5cda.js";
+} from "../shared/stacks-a9cn5ehj.js";
 import {
   WebSocketError,
   watchAddress,
@@ -39,16 +39,22 @@ import {
 } from "../shared/stacks-tjjnkt3r.js";
 import {
   sponsorTransaction
-} from "../shared/stacks-4z1jhw6y.js";
+} from "../shared/stacks-ffsv2t3t.js";
 import {
   BroadcastError,
   SerializationError,
   SigningError,
   TransactionError,
+  broadcastWithNonceReset,
+  createNonceManager,
   estimateFee,
   getNonce,
+  isNonceConflictError,
+  jsonRpcSource,
+  memoryStore,
+  resolveNonce,
   sendTransaction
-} from "../shared/stacks-y8e3gx6w.js";
+} from "../shared/stacks-gxhznn3h.js";
 import {
   BaseError
 } from "../shared/stacks-709tra19.js";
@@ -89,6 +95,7 @@ var BASE_KEYS = new Set([
   "account",
   "transport",
   "request",
+  "nonceManager",
   "extend"
 ]);
 function bindExtend(base) {
@@ -111,6 +118,7 @@ function createClient(config) {
     account: config.account,
     transport,
     request: transport.request,
+    nonceManager: config.nonceManager,
     extend: null
   };
   client.extend = bindExtend(client);
@@ -167,15 +175,17 @@ function multisigActions(client) {
   if (!msConfig)
     throw new Error("multisigActions requires a multi-sig client");
   const { signers, requiredSignatures, hashMode } = msConfig;
-  async function resolveNonce(nonce) {
+  async function resolveNonce2(nonce) {
     if (nonce !== undefined)
       return nonce;
     const address = makeMultiSigAddress(signers, requiredSignatures, client.chain);
+    if (client.nonceManager)
+      return client.nonceManager.consume({ client, address });
     return getNonce(client, { address });
   }
   return {
     async transferStx(params) {
-      const nonce = await resolveNonce(params.nonce);
+      const nonce = await resolveNonce2(params.nonce);
       const unsigned = buildTokenTransfer({
         recipient: params.to,
         amount: params.amount,
@@ -200,7 +210,7 @@ function multisigActions(client) {
     },
     async callContract(params) {
       const [contractAddress, contractName] = parseContractId(params.contract);
-      const nonce = await resolveNonce(params.nonce);
+      const nonce = await resolveNonce2(params.nonce);
       const unsigned = buildContractCall({
         contractAddress,
         contractName,
@@ -225,7 +235,7 @@ function multisigActions(client) {
       return unsigned;
     },
     async deployContract(params) {
-      const nonce = await resolveNonce(params.nonce);
+      const nonce = await resolveNonce2(params.nonce);
       const unsigned = buildContractDeploy({
         contractName: params.contractName,
         codeBody: params.codeBody,
@@ -268,6 +278,68 @@ function createMultiSigClient(config) {
   };
   return client.extend(multisigActions);
 }
+// src/actions/wallet/nonceStores.ts
+var TAKE_IF_PRESENT = `local v = redis.call('GET', KEYS[1])
+if v == false then return false end
+redis.call('INCR', KEYS[1])
+return v`;
+var SEED_OR_TAKE = `local v = redis.call('GET', KEYS[1])
+if v == false then redis.call('SET', KEYS[1], ARGV[1]); v = ARGV[1] end
+redis.call('INCR', KEYS[1])
+return v`;
+function redisStore(params) {
+  const { redis } = params;
+  const prefix = params.prefix ?? "stacks:nonce:";
+  return {
+    async reserve(key, getFloor) {
+      const k = prefix + key;
+      const present = await redis.send("EVAL", [TAKE_IF_PRESENT, "1", k]);
+      if (present != null)
+        return BigInt(present);
+      const floor = await getFloor();
+      const seeded = await redis.send("EVAL", [
+        SEED_OR_TAKE,
+        "1",
+        k,
+        floor.toString()
+      ]);
+      return BigInt(seeded);
+    },
+    async reset(key) {
+      await redis.send("DEL", [prefix + key]);
+    }
+  };
+}
+function postgresStore(params) {
+  const { sql } = params;
+  const shouldEnsure = params.ensureTable ?? true;
+  let ensured = false;
+  async function ensureTable() {
+    if (!shouldEnsure || ensured)
+      return;
+    await sql`CREATE TABLE IF NOT EXISTS stacks_nonce_state (key text PRIMARY KEY, next numeric NOT NULL)`;
+    ensured = true;
+  }
+  return {
+    async reserve(key, getFloor) {
+      await ensureTable();
+      const updated = await sql`UPDATE stacks_nonce_state SET next = next + 1 WHERE key = ${key} RETURNING next - 1 AS nonce`;
+      const warm = updated[0];
+      if (warm)
+        return BigInt(String(warm.nonce));
+      const floor = await getFloor();
+      const seeded = await sql`INSERT INTO stacks_nonce_state (key, next) VALUES (${key}, ${(floor + 1n).toString()}) ON CONFLICT (key) DO UPDATE SET next = stacks_nonce_state.next + 1 RETURNING next - 1 AS nonce`;
+      const cold = seeded[0];
+      if (!cold)
+        throw new Error("postgresStore: insert returned no row");
+      return BigInt(String(cold.nonce));
+    },
+    async reset(key) {
+      await ensureTable();
+      await sql`DELETE FROM stacks_nonce_state WHERE key = ${key}`;
+    }
+  };
+}
 // src/transports/createTransport.ts
 function createTransport(type, config) {
   return {
@@ -689,14 +761,20 @@ export {
   webSocket,
   walletActions,
   testnet,
+  resolveNonce,
+  redisStore,
   publicActions,
   providerToAccount,
+  postgresStore,
   parseStx,
   exports_on as on,
   multisigActions,
   mocknet,
+  memoryStore,
   mainnet,
+  jsonRpcSource,
   isValidAddress,
+  isNonceConflictError,
   isAddressEqual,
   http,
   getContractAddress,
@@ -707,8 +785,10 @@ export {
   custom,
   createWalletClient,
   createPublicClient,
+  createNonceManager,
   createMultiSigClient,
   createClient,
+  broadcastWithNonceReset,
   ZERO_ADDRESS,
   WebSocketError,
   TransactionError,
@@ -724,5 +804,5 @@ export {
   AddressVersion
 };
 
-//# debugId=8C2A991E317B310264756E2164756E21
+//# debugId=AD2076118DA65BC464756E2164756E21
 //# sourceMappingURL=index.js.map