@secondlayer/stacks 2.5.2 → 2.7.0

package/dist/src/index.d.cts

@@ -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,258 @@ 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>
+	/**
+	* Return the next nonce that {@link NonceStore.reserve} would hand out for
+	* `key` WITHOUT consuming it, or `undefined` if `key` is untracked. Used by
+	* {@link reconcileNonce} to detect drift. Optional — stores that omit it
+	* simply opt out of reconciliation.
+	*/
+	peek?(key: string): Promise<bigint | undefined> | bigint | undefined
+};
+/** 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>
+	/** Next nonce that {@link NonceManager.consume} would return without consuming it, or `undefined` if untracked. */
+	peek(params: {
+		client: Client
+		address: string
+	}): Promise<bigint | undefined>
+};
+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>;
+type ReconcileNonceParams = {
+	client: Client
+	address: string
+	/** Authoritative (ideally mempool-aware) source to reconcile against. */
+	source: NonceManagerSource
+	/**
+	* Allow resetting DOWNWARD when the source's next nonce is below what the
+	* store tracks — i.e. a previously-allocated tx is no longer pending or
+	* confirmed (dropped/GC'd), so its nonce should be reused. Default `true`.
+	*
+	* Downward resets rely on `source` being current: with a go-forward mempool
+	* source that lags broadcast, run reconciliation on an interval comfortably
+	* longer than mempool propagation so a still-missing tx is genuinely dropped.
+	* Set `false` for upward-only reconciliation (always safe).
+	*/
+	downward?: boolean
+};
+type ReconcileNonceResult = {
+	/** Whether the manager was reset (drift detected). */
+	reset: boolean
+	/** Authoritative next nonce from `source`. */
+	authoritative: bigint
+	/** Next nonce the store tracked, or `undefined` if untracked. */
+	tracked: bigint | undefined
+};
+/**
+* Reconcile a tracked nonce against an authoritative source, healing silent
+* drift that produces no broadcast error (a dropped/GC'd mempool tx leaving the
+* counter overshot, or the chain advancing past the local view).
+*
+* When the source's next nonce differs from the tracked value, the manager is
+* {@link NonceManager.reset}; the next `consume` re-seeds from `source`. A no-op
+* if the store is untracked or does not implement `peek`.
+*/
+declare function reconcileNonce(manager: NonceManager, params: ReconcileNonceParams): Promise<ReconcileNonceResult>;
+type StartNonceReconcilerParams = {
+	client: Client
+	addresses: string[]
+	source: NonceManagerSource
+	/** Reconcile interval in ms. Default 60_000. Keep well above mempool propagation. */
+	intervalMs?: number
+	downward?: boolean
+	/** Per-address callback after each reconcile (observability). */
+	onReconcile?: (address: string, result: ReconcileNonceResult) => void
+	/** Per-address error callback; reconciliation continues on the next tick. */
+	onError?: (address: string, error: unknown) => void
+};
+/**
+* Run {@link reconcileNonce} on a timer for a set of addresses.
+*
+* SINGLE-WRITER: run this in exactly ONE process. With a shared persisted store,
+* a reconciler resetting the counter while other workers allocate is racy — keep
+* reconciliation on one designated process and let the others only allocate.
+*
+* Returns a handle; call `stop()` to clear the timer.
+*/
+declare function startNonceReconciler(manager: NonceManager, params: StartNonceReconcilerParams): {
+	stop: () => void
+};
+/** 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 +964,130 @@ 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;
+/**
+* Mempool-aware {@link NonceManagerSource}s.
+*
+* The default {@link jsonRpcSource} reads only the confirmed nonce, so a tx
+* sitting in the mempool is invisible — broadcasting many quickly forces manual
+* tracking. These sources fold pending (mempool) txs into the next-nonce
+* computation. The gap-filling core is generic; where the pending set comes from
+* is pluggable, so you are never locked to any one provider:
+*
+*   - {@link mempoolAwareSource} — bring your own `getPending`.
+*   - {@link indexSource} — prebuilt over Secondlayer's `/v1/index/mempool`.
+*   - {@link hiroNonceSource} — prebuilt over Hiro's `/extended` nonces endpoint.
+*/
+type FetchImpl = typeof globalThis.fetch;
+/**
+* The next free nonce ≥ `confirmed` not already taken by a pending tx.
+*
+* Unlike Hiro's `possible_next_nonce` (which is `max(pending) + 1` and strands
+* higher txs when a lower nonce is missing), this FILLS gaps: it returns the
+* lowest unused slot, so a dropped-tx hole is reused instead of stranding the
+* chain.
+*/
+declare function nextFreeNonce(confirmed: bigint, pending: bigint[]): bigint;
+type MempoolAwareSourceParams = {
+	/** Pending (mempool) nonces for an address. */
+	getPending: (args: {
+		client: Client
+		address: string
+	}) => Promise<bigint[]>
+	/**
+	* Confirmed-nonce floor. Defaults to the node's `/v2/accounts` read — the
+	* user's own node via the client transport, no provider dependency.
+	*/
+	getConfirmed?: (args: {
+		client: Client
+		address: string
+	}) => Promise<bigint>
+};
+/**
+* Build a gap-filling, mempool-aware source from any `getPending`. The confirmed
+* floor defaults to the node read; if `getPending` throws, the source degrades
+* to confirmed-only rather than blocking a broadcast.
+*/
+declare function mempoolAwareSource(params: MempoolAwareSourceParams): NonceManagerSource;
+type IndexSourceParams = {
+	/** Secondlayer Index base URL. Default `https://api.secondlayer.tools`. */
+	baseUrl?: string
+	/** Optional API key (keyless by default; supply to raise rate limits). */
+	apiKey?: string
+	fetchImpl?: FetchImpl
+	/** Max mempool pages to page through per address. Default 10 (×200 = 2000 txs). */
+	maxPages?: number
+	/** Override the confirmed floor (defaults to the node read). */
+	getConfirmed?: (args: {
+		client: Client
+		address: string
+	}) => Promise<bigint>
+};
+/**
+* Mempool-aware source backed by Secondlayer's `/v1/index/mempool` (our node's
+* observed mempool). `baseUrl` is configurable — point it at any shape-compatible
+* endpoint. Note our mempool is a go-forward, single-node observed view (not a
+* globally-aggregated mempool), so it can lag or miss txs our node never saw.
+*/
+declare function indexSource(params?: IndexSourceParams): NonceManagerSource;
+type HiroNonceSourceParams = {
+	/** Hiro API base URL, e.g. `https://api.hiro.so` or `https://api.testnet.hiro.so`. */
+	baseUrl: string
+	apiKey?: string
+	fetchImpl?: FetchImpl
+};
+/**
+* Off-the-shelf, non-Secondlayer mempool-aware source over Hiro's
+* `/extended/v1/address/{address}/nonces`. Fills the lowest detected gap first,
+* then falls back to `possible_next_nonce`. Requires a host that serves Hiro's
+* extended API (a bare stacks-node does not).
+*/
+declare function hiroNonceSource(params: HiroNonceSourceParams): NonceManagerSource;
+/**
 * Create an HTTP transport for Stacks node RPC calls.
 * Falls back to the chain's default RPC URL, then `localhost:3999`.
 */
@@ -1069,4 +1345,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, startNonceReconciler, resolveNonce, redisStore, reconcileNonce, publicActions, providerToAccount, postgresStore, parseStx, exports_on as on, nextFreeNonce, multisigActions, mocknet, mempoolAwareSource, memoryStore, mainnet, jsonRpcSource, isValidAddress, isNonceConflictError, isAddressEqual, indexSource, http, hiroNonceSource, 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, StartNonceReconcilerParams, StacksProvider, StacksChain, SqlLike, SimulationError, SigningError, SerializationError, RequestOptions, RequestFn, RedisStoreParams, RedisLike, ReconcileNonceResult, ReconcileNonceParams, ReadOnlyCallError, PublicClientConfig, PublicClient, PublicActions, ProviderAccount, PoxFunction, PostgresStoreParams, NonceStore, NonceManagerSource, NonceManager, MultiSigClientConfig, MultiSigClient, MultiSigActions, MempoolAwareSourceParams, MICROSTX_PER_STX, LocalAccount, IndexSourceParams, HiroNonceSourceParams, FilterPrimitive, FilterOperator, FilterClause, Filter, FactoryTarget, CustomAccount, CreateNonceManagerParams, ContractCallError, ClientConfig, Client, BroadcastError, BnsAction, BaseError, AddressVersion, Account };