@secondlayer/stacks 4.3.1 → 5.0.0

package/dist/src/index.d.ts

@@ -761,6 +761,14 @@ type NonceStore = {
 	/** Forget tracked state for `key` so the next reserve re-syncs from the floor. */
 	reset(key: string): void | Promise<void>
 	/**
+	* Hand back a nonce that {@link NonceStore.reserve} issued but that never
+	* reached the mempool. Rolls the counter back ONLY when `nonce` is the
+	* most recently issued value (`next - 1`); a stale release, or one that
+	* races a newer reservation, is a no-op. Optional: stores that omit it
+	* leave the gap for {@link reconcileNonce} to heal.
+	*/
+	release?(key: string, nonce: bigint): 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
@@ -778,6 +786,15 @@ type NonceManager = {
 		client: Client
 		address: string
 	}): void | Promise<void>
+	/**
+	* Give back a nonce from {@link NonceManager.consume} whose transaction
+	* was never accepted by the node. No-op unless it is the latest issued.
+	*/
+	release(params: {
+		client: Client
+		address: string
+		nonce: bigint
+	}): void | Promise<void>
 	/** Next nonce that {@link NonceManager.consume} would return without consuming it, or `undefined` if untracked. */
 	peek(params: {
 		client: Client
@@ -932,14 +949,32 @@ type RequestOptions = {
 	method?: "GET" | "POST" | "PUT" | "DELETE"
 	body?: unknown
 	headers?: Record<string, string>
+	/**
+	* Cancel the request from the caller's side. An aborted signal rejects
+	* with the signal's reason immediately and never retries; it is combined
+	* with the transport's own per-attempt timeout.
+	*/
+	signal?: AbortSignal
+	/**
+	* Override the transport's retry budget for this one request. Broadcasts
+	* pass `0`: re-sending a transaction the node may already hold trades a
+	* transient failure for a confusing nonce conflict.
+	*/
+	retryCount?: number
 };
 /** Shared configuration for all transport types. */
 type TransportConfig = {
 	url?: string
+	/**
+	* Per-attempt deadline in ms covering headers AND body. A stalled body
+	* rejects with `TimeoutError` instead of hanging. Default 30_000.
+	*/
 	timeout?: number
 	retryCount?: number
 	retryDelay?: number
 	fetchOptions?: RequestInit
+	/** Sent as `x-api-key`. Held in the request closure and stripped from
+	*  `Transport.config` so it never prints with the client. */
 	apiKey?: string
 };
 /** A resolved transport instance with a bound request function. */
@@ -1073,6 +1108,47 @@ type RawBlockResponse = {
 	miner_txid: string
 	txs: string[]
 };
+declare class BaseError extends Error {
+	private;
+	name: string;
+	shortMessage: string;
+	details?: string;
+	constructor(shortMessage: string, options?: {
+		cause?: Error
+		details?: string
+		code?: string
+	});
+	/**
+	* Stable identifier for programmatic handling; survives message
+	* rewording and minification. An explicit `code` option wins, else it
+	* is derived from `name` (`TimeoutError` gives `TIMEOUT_ERROR`).
+	*/
+	get code(): string;
+	set code(value: string);
+	toJSON(): {
+		name: string
+		code: string
+		message: string
+		shortMessage: string
+		details: string | undefined
+		cause: string | undefined
+	};
+}
+/** Thrown by the HTTP transport when a response's status isn't 2xx. */
+declare class HttpRequestError extends BaseError {
+	name: string;
+	status: number;
+	/** Request URL, when the transport knows it. */
+	url?: string;
+	/** Request method, when the transport knows it. */
+	method?: string;
+	constructor(status: number, options?: {
+		cause?: Error
+		details?: string
+		url?: string
+		method?: string
+	});
+}
 /**
 * Pluggable transaction-status sources for {@link getTransaction} /
 * `waitForTransactionReceipt`.
@@ -1083,9 +1159,9 @@ type RawBlockResponse = {
 *
 *   - {@link extendedApiSource} — default; `/extended/v1/tx/{txid}` on the
 *     client's transport host (Hiro API or any extended-API-compatible host).
-*   - {@link indexTxSource} — Secondlayer's `/v1/index/transactions/{txid}`;
-*     returns the chain tip in the same response, so N-confirmation waits
-*     need no second request.
+*   - {@link indexTxSource}: a Secondlayer instance's
+*     `/v1/index/transactions/{txid}`; returns the chain tip in the same
+*     response, so N-confirmation waits need no second request.
 */
 type TransactionStatus = "pending" | "success" | "abort_by_response" | "abort_by_post_condition" | "dropped";
 type TransactionReceipt = {
@@ -1112,8 +1188,23 @@ type TransactionStatusSource = {
 		client: Client
 		txid: string
 	}): Promise<TransactionSnapshot>
+	/**
+	* True when the source only knows mined transactions and reports
+	* `receipt: null` for the whole mempool life of a tx. The wait action
+	* then stretches its dropped-grace window to the full timeout, since
+	* "unknown" cannot mean "dropped" until the deadline.
+	*/
+	canonicalOnly?: boolean
 };
-type FetchImpl = typeof globalThis.fetch;
+/**
+* Thrown when an index-backed source cannot reach a Secondlayer instance
+* because of how it was configured (no URL, a Hiro host, a bare node).
+* Sources that degrade on transient failures let this one through: a
+* misconfiguration would otherwise degrade silently on every read.
+*/
+declare class IndexSourceConfigError extends Error {
+	name: string;
+}
 /**
 * Default source: `GET /extended/v1/tx/{txid}` via the client's transport.
 * Requires a host that serves Hiro's extended API (a bare stacks-node does
@@ -1122,17 +1213,25 @@ type FetchImpl = typeof globalThis.fetch;
 */
 declare function extendedApiSource(): TransactionStatusSource;
 type IndexTxSourceParams = {
-	/** Base URL of a Secondlayer-shaped index API. */
+	/**
+	* URL of your Secondlayer instance. Without it the client's transport
+	* URL is assumed to be the instance: a transport on a Hiro host throws
+	* up front, and a host that answers `/v1/index` with a non-JSON 404
+	* (a bare stacks-node) throws on the first read. Pass it whenever the
+	* transport is not the instance.
+	*/
 	baseUrl?: string
+	/** Instance token, sent as `Authorization: Bearer`. */
 	apiKey?: string
-	fetchImpl?: FetchImpl
 };
 /**
-* Source backed by Secondlayer's `/v1/index/transactions/{txid}`. The response
-* embeds the chain tip, so N-confirmation math needs no extra request. The
-* index only returns canonical (mined) transactions — while a tx is in the
-* mempool this source reports `receipt: null`, and the wait action's grace
-* window carries it until inclusion.
+* Source backed by a Secondlayer instance's `/v1/index/transactions/{txid}`.
+* The response embeds the chain tip, so N-confirmation math needs no extra
+* request. Requests go through the transport layer: same retries, timeout
+* and typed errors as every other read. The index only returns canonical
+* (mined) transactions; while a tx is in the mempool this source reports
+* `receipt: null`, and the wait action's grace window carries it until
+* inclusion.
 */
 declare function indexTxSource(params?: IndexTxSourceParams): TransactionStatusSource;
 type GetTransactionParams = {
@@ -1154,6 +1253,13 @@ type MulticallCall = {
 type MulticallParams<TAllowFailure extends boolean = true> = {
 	calls: readonly MulticallCall[]
 	allowFailure?: TAllowFailure
+	/**
+	* Reads in flight at once. Default 8. Each call is its own
+	* `/v2/contracts/call-read` request (Stacks nodes have no batch RPC), so
+	* an uncapped fan-out turns one multicall into a burst that trips rate
+	* limits and then retries in lockstep.
+	*/
+	concurrency?: number
 };
 type MulticallSuccessResult = {
 	status: "success"
@@ -1176,22 +1282,6 @@ type ReadContractParams = {
 	*/
 	tip?: string
 };
-declare class BaseError extends Error {
-	name: string;
-	shortMessage: string;
-	details?: string;
-	constructor(shortMessage: string, options?: {
-		cause?: Error
-		details?: string
-	});
-	toJSON(): {
-		name: string
-		message: string
-		shortMessage: string
-		details: string | undefined
-		cause: string | undefined
-	};
-}
 declare class SimulationError extends BaseError {
 	name: string;
 	writesDetected: boolean;
@@ -1245,8 +1335,9 @@ type WaitForTransactionReceiptParams = {
 	pollingInterval?: number
 	/**
 	* How long a tx may be unknown to the source before it counts as dropped,
-	* ms. Covers broadcast propagation lag and canonical-only sources that
-	* can't see the mempool. Default 30_000.
+	* ms. Covers broadcast propagation lag. Default 30_000, or the full
+	* `timeout` for a canonical-only source (one that cannot see the
+	* mempool, so "unknown" means "not mined yet" until the deadline).
 	*/
 	droppedGracePeriod?: number
 	/** Where to read status from. Defaults to {@link extendedApiSource}. */
@@ -1677,10 +1768,10 @@ declare function postgresStore(params: PostgresStoreParams): NonceStore;
 * 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 indexSource}: prebuilt over a Secondlayer instance's `/v1/index/mempool`.
 *   - {@link hiroNonceSource} — prebuilt over Hiro's `/extended` nonces endpoint.
 */
-type FetchImpl2 = typeof globalThis.fetch;
+type FetchImpl = typeof globalThis.fetch;
 /**
 * The next free nonce ≥ `confirmed` not already taken by a pending tx.
 *
@@ -1708,16 +1799,24 @@ type MempoolAwareSourceParams = {
 /**
 * 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.
+* to confirmed-only rather than blocking a broadcast. A misconfigured pending
+* feed ({@link IndexSourceConfigError}) is rethrown: it would fail on every
+* read, and degrading silently would hide that the mempool is never consulted.
 */
 declare function mempoolAwareSource(params: MempoolAwareSourceParams): NonceManagerSource;
 type IndexSourceParams = {
-	/** Secondlayer Index base URL. Default `https://api.secondlayer.tools`. */
+	/**
+	* URL of your Secondlayer instance. Without it the client's transport
+	* URL is assumed to be the instance: a transport on a Hiro host throws
+	* up front, and a host that answers `/v1/index` with a non-JSON 404
+	* (a bare stacks-node) throws on the first read. Neither is degraded
+	* to the confirmed floor. Pass it whenever the transport is not the
+	* instance.
+	*/
 	baseUrl?: string
-	/** Optional API key (keyless by default; supply to raise rate limits). */
+	/** Instance token, sent as `Authorization: Bearer`. */
 	apiKey?: string
-	fetchImpl?: FetchImpl2
-	/** Max mempool pages to page through per address. Default 10 (×200 = 2000 txs). */
+	/** Max mempool pages to read per address. Default 10 (×200 = 2000 txs). */
 	maxPages?: number
 	/** Override the confirmed floor (defaults to the node read). */
 	getConfirmed?: (args: {
@@ -1726,17 +1825,22 @@ type IndexSourceParams = {
 	}) => 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.
+* Mempool-aware source backed by a Secondlayer instance's `/v1/index/mempool`.
+* Requests go through the transport layer (retries, timeout, typed errors).
+* The instance's mempool is a go-forward view observed by its own node, so
+* it can lag or miss transactions that node never saw; the manager's local
+* increment still prevents same-process collisions. Past `maxPages` the
+* pending set is truncated and the next free nonce may already be taken;
+* a nonce conflict at broadcast then resets the manager. Transient failures
+* (5xx, timeout) degrade to the confirmed floor; a missing or wrong instance
+* URL throws so the misconfiguration is visible on the first read.
 */
 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?: FetchImpl2
+	fetchImpl?: FetchImpl
 };
 /**
 * Off-the-shelf, non-Secondlayer mempool-aware source over Hiro's
@@ -1856,19 +1960,24 @@ declare class SerializationError extends BaseError {
 declare class SigningError extends BaseError {
 	name: string;
 }
-declare class ContractCallError extends BaseError {
-	name: string;
-}
-declare class ReadOnlyCallError extends BaseError {
-	name: string;
-}
-/** Thrown by the HTTP transport when a response's status isn't 2xx. */
-declare class HttpRequestError extends BaseError {
+/**
+* Thrown by the HTTP transport when a request, headers and body included,
+* does not finish inside `timeout`. Carries enough to tell which endpoint
+* stalled and on which retry attempt. A caller-supplied `signal` abort is
+* NOT a timeout: that rejects with the signal's own reason and never retries.
+*/
+declare class TimeoutError extends BaseError {
 	name: string;
-	status: number;
-	constructor(status: number, options?: {
-		cause?: Error
-		details?: string
+	method: string;
+	url: string;
+	timeout: number;
+	/** Zero-based attempt index at which the timeout fired. */
+	attempt: number;
+	constructor(params: {
+		method: string
+		url: string
+		timeout: number
+		attempt: number
 	});
 }
 /** Thrown when a node/API response is missing an expected field. */
@@ -1878,4 +1987,4 @@ declare class MalformedResponseError extends BaseError {
 declare class WebSocketError extends BaseError {
 	name: string;
 }
-export { webSocket, walletActions, waitForTransactionReceipt2 as waitForTransactionReceipt, testnet, startNonceReconciler, resolveNonce, redisStore, reconcileNonce, publicActions, providerToAccount, postgresStore, parseStx, on, nextFreeNonce, multisigActions, mocknet, mempoolAwareSource, memoryStore, mainnet, jsonRpcSource, isValidAddress, isNonceConflictError, isAddressEqual, indexTxSource, indexSource, http, hiroNonceSource, getTransaction2 as getTransaction, getContractAddress, formatStx, fallback, extendedApiSource, devnet, defineChain, custom, createWalletClient, createPublicClient, createNonceManager, createMultiSigClient, createClient, broadcastWithNonceReset, ZERO_ADDRESS, WebSocketTransportConfig, WebSocketTransport, WebSocketError, WalletClientConfig, WalletClient, WalletActions, WaitForTransactionTimeoutError, WaitForTransactionReceiptParams, TxRejectionReason, TransportFactory, TransportConfig, Transport, TransactionStatusSource, TransactionStatus, TransactionSnapshot, TransactionReceipt, TransactionError, TransactionDroppedError, TransactionAbortedError, TESTNET_ZERO_ADDRESS, Subscription, StartNonceReconcilerParams, StacksProvider, StacksChain, SqlLike, SimulationError, SigningError, SerializationError, RequestOptions, RequestFn, RedisStoreParams, RedisLike, ReconcileNonceResult, ReconcileNonceParams, ReadOnlyCallError, PublicClientConfig, PublicClient, PublicActions, ProviderAccount, PostgresStoreParams, NonceStore, NonceManagerSource, NonceManager, MultiSigClientConfig, MultiSigClient, MultiSigActions, MempoolAwareSourceParams, MalformedResponseError, MICROSTX_PER_STX, LocalAccount, IndexTxSourceParams, IndexSourceParams, HttpRequestError, HiroNonceSourceParams, GetTransactionParams, CustomAccount, CreateNonceManagerParams, ContractCallError, ClientConfig, Client, ChainTriggerOf, ChainEventFilterType, ChainEventFilterSpec, ChainEventFilter, BroadcastError, BaseError, AddressVersion, Account };
+export { webSocket, walletActions, waitForTransactionReceipt2 as waitForTransactionReceipt, testnet, startNonceReconciler, resolveNonce, redisStore, reconcileNonce, publicActions, providerToAccount, postgresStore, parseStx, on, nextFreeNonce, multisigActions, mocknet, mempoolAwareSource, memoryStore, mainnet, jsonRpcSource, isValidAddress, isNonceConflictError, isAddressEqual, indexTxSource, indexSource, http, hiroNonceSource, getTransaction2 as getTransaction, getContractAddress, formatStx, fallback, extendedApiSource, devnet, defineChain, custom, createWalletClient, createPublicClient, createNonceManager, createMultiSigClient, createClient, broadcastWithNonceReset, ZERO_ADDRESS, WebSocketTransportConfig, WebSocketTransport, WebSocketError, WalletClientConfig, WalletClient, WalletActions, WaitForTransactionTimeoutError, WaitForTransactionReceiptParams, TxRejectionReason, TransportFactory, TransportConfig, Transport, TransactionStatusSource, TransactionStatus, TransactionSnapshot, TransactionReceipt, TransactionError, TransactionDroppedError, TransactionAbortedError, TimeoutError, TESTNET_ZERO_ADDRESS, Subscription, StartNonceReconcilerParams, StacksProvider, StacksChain, SqlLike, SimulationError, SigningError, SerializationError, RequestOptions, RequestFn, RedisStoreParams, RedisLike, ReconcileNonceResult, ReconcileNonceParams, PublicClientConfig, PublicClient, PublicActions, ProviderAccount, PostgresStoreParams, NonceStore, NonceManagerSource, NonceManager, MultiSigClientConfig, MultiSigClient, MultiSigActions, MempoolAwareSourceParams, MalformedResponseError, MICROSTX_PER_STX, LocalAccount, IndexTxSourceParams, IndexSourceParams, IndexSourceConfigError, HttpRequestError, HiroNonceSourceParams, GetTransactionParams, CustomAccount, CreateNonceManagerParams, ClientConfig, Client, ChainTriggerOf, ChainEventFilterType, ChainEventFilterSpec, ChainEventFilter, BroadcastError, BaseError, AddressVersion, Account };