@secondlayer/stacks 6.0.0 → 6.1.1

package/dist/src/index.d.ts

@@ -1,471 +1,43 @@
-declare const DECODED_EVENT_TYPES: readonly ["stx_transfer", "stx_mint", "stx_burn", "stx_lock", "ft_transfer", "ft_mint", "ft_burn", "nft_transfer", "nft_mint", "nft_burn", "print"];
-type DecodedEventType = (typeof DECODED_EVENT_TYPES)[number];
-/** Every chain-event filter member across all four surfaces: the 10 decoded
-*  token/STX types, the three contract-shaped types (spelled as subgraphs and
-*  triggers spell them — Index/Streams project `print_event` → `print`), and
-*  the five sBTC lifecycle types (Subscriptions-only). */
-declare const CHAIN_EVENT_FILTER_TYPES: readonly ["stx_transfer", "stx_mint", "stx_burn", "stx_lock", "ft_transfer", "ft_mint", "ft_burn", "nft_transfer", "nft_mint", "nft_burn", "contract_call", "contract_deploy", "print_event", "sbtc_deposit", "sbtc_withdrawal_create", "sbtc_withdrawal_accept", "sbtc_withdrawal_reject", "sbtc_withdrawal_swept_confirmed"];
-type ChainEventFilterType = (typeof CHAIN_EVENT_FILTER_TYPES)[number];
-/** C32-encoded address version bytes for single-sig and multi-sig on each network. */
-declare const AddressVersion: {
-	readonly MainnetSingleSig: 22
-	readonly MainnetMultiSig: 20
-	readonly TestnetSingleSig: 26
-	readonly TestnetMultiSig: 21
+/** Account derived from a local private key (mnemonic or raw key). */
+type LocalAccount = {
+	type: "local"
+	address: string
+	/** Compressed public key (hex) */
+	publicKey: string
+	/** Raw ECDSA sign over a hash */
+	sign(hash: Uint8Array): Uint8Array
+	/** Sign a raw UTF-8 / byte message (`sha256(bytes)`). Not SIP-018. */
+	signMessage(message: string | Uint8Array): string
 };
-type AddressVersion = (typeof AddressVersion)[keyof typeof AddressVersion];
-/** Mainnet burn address (all-zero hash160). */
-declare const ZERO_ADDRESS = "SP000000000000000000002Q6VF78";
-/** Testnet burn address (all-zero hash160). */
-declare const TESTNET_ZERO_ADDRESS = "ST000000000000000000002AMW42H";
-/** Number of microSTX per 1 STX (10^6). */
-declare const MICROSTX_PER_STX = 1000000n;
-/** Alias for validateStacksAddress — matches future.md naming. */
-declare const isValidAddress: (address: string) => boolean;
-/**
-* Compare two Stacks addresses for equality (case-insensitive, version-aware).
-* Throws if either address is invalid.
-*/
-declare function isAddressEqual(a: string, b: string): boolean;
-/**
-* Build a contract address from deployer + contract name.
-* Validates both parts; returns `deployer.contractName`.
-*/
-declare function getContractAddress(deployer: string, contractName: string): string;
-type AbiUInt128 = "uint128";
-type AbiInt128 = "int128";
-type AbiBool = "bool";
-type AbiPrincipal = "principal";
-type AbiTraitReference = "trait_reference";
-type AbiNone = "none";
-type AbiStringAscii<L extends number = number> = {
-	"string-ascii": {
-		length: L
-	}
+/** Account with a user-provided signing function (sync or async). */
+type CustomAccount = {
+	type: "custom"
+	address: string
+	publicKey: string
+	sign(hash: Uint8Array): Promise<Uint8Array> | Uint8Array
 };
-type AbiStringUtf8<L extends number = number> = {
-	"string-utf8": {
-		length: L
-	}
+/** Browser wallet provider interface (e.g. Leather, Xverse). */
+type StacksProvider = {
+	request(method: string, params?: any): Promise<any>
 };
-type AbiBuffer<L extends number = number> = {
-	buff: {
-		length: L
-	}
+/** Account backed by a browser wallet {@link StacksProvider}. */
+type ProviderAccount = {
+	type: "provider"
+	address: string
+	publicKey: string
+	provider: StacksProvider
 };
-type AbiPrimitiveType = AbiUInt128 | AbiInt128 | AbiBool | AbiPrincipal | AbiTraitReference | AbiNone | AbiStringAscii | AbiStringUtf8 | AbiBuffer;
-interface AbiListType {
-	list: {
-		type: AbiType
-		length: number
-	};
-}
-interface AbiTupleType {
-	tuple: ReadonlyArray<{
-		name: string
-		type: AbiType
-	}>;
-}
-interface AbiOptionalType {
-	optional: AbiType;
-}
-interface AbiResponseType {
-	response: {
-		ok: AbiType
-		error: AbiType
-	};
-}
-/** Discriminated union of all Clarity value types (primitives, buffers, lists, tuples, optionals, responses). */
-type AbiType = AbiPrimitiveType | AbiListType | AbiTupleType | AbiOptionalType | AbiResponseType;
-type FunctionAccess = "public" | "read-only" | "private";
-interface FunctionArg {
-	name: string;
-	type: AbiType;
-}
-/** A single Clarity function definition with name, access level, arguments, and return type. */
-interface AbiFunction {
-	name: string;
-	access: FunctionAccess;
-	args: ReadonlyArray<FunctionArg>;
-	outputs: AbiType;
-}
-type VariableAccess = "constant" | "variable";
-interface AbiVariable {
-	name: string;
-	type: AbiType;
-	access: VariableAccess;
-}
-interface AbiMap {
-	name: string;
-	key: AbiType;
-	value: AbiType;
-}
-interface AbiFungibleToken {
-	name: string;
-}
-interface AbiNonFungibleToken {
-	name: string;
-	type: AbiType;
-}
-type TraitFunctionAccess = Exclude<FunctionAccess, "private">;
-interface AbiTraitFunction {
-	name: string;
-	access: TraitFunctionAccess;
-	args: ReadonlyArray<FunctionArg>;
-	outputs: AbiType;
-}
-interface AbiTraitDefinition {
-	name: string;
-	functions: ReadonlyArray<AbiTraitFunction>;
-}
-/** Full Clarity contract ABI including functions, maps, variables, and token definitions. */
-interface AbiContract {
-	functions: ReadonlyArray<AbiFunction>;
-	maps?: ReadonlyArray<AbiMap>;
-	variables?: ReadonlyArray<AbiVariable>;
-	fungible_tokens?: ReadonlyArray<AbiFungibleToken>;
-	non_fungible_tokens?: ReadonlyArray<AbiNonFungibleToken>;
-	implemented_traits?: ReadonlyArray<string>;
-	defined_traits?: ReadonlyArray<AbiTraitDefinition>;
-}
-/**
-* `<contract>::<asset-name>` — the shape a fungible/non-fungible asset filter
-* takes, expressed so the compiler can check it.
-*
-* The most common mistake in this API is passing a CONTRACT ID
-* (`SP….sbtc-token`) where an asset identifier (`SP….sbtc-token::sbtc-token`)
-* belongs, and the failure mode is a query that quietly returns zero rows. The
-* two differ structurally by `::`, so a template-literal type catches it at the
-* call site — no brand, no cast, literals just work.
-*
-* A value that is only known at runtime (config, env) is not narrow enough on
-* purpose; run it through {@link assetId} once, which validates and narrows.
-*
-* Wildcard patterns (Subscriptions/Subgraphs-only) are admitted by the second arm — they
-* are legitimately not full identifiers (`SPB.*`), and the runtime validator
-* short-circuits on them for the same reason.
-*/
-type AssetIdentifier = `${string}::${string}` | `${string}*${string}`;
-/** Scalar print field types (structural mirror of the subgraphs `ColumnType`). */
-type PrintScalarType = "uint" | "int" | "text" | "principal" | "boolean" | "timestamp" | "jsonb";
-/**
-* One declared print field — structural mirror of `PrintField` in
-* `@secondlayer/subgraphs`. Composite forms exist because real print payloads
-* nest: a vocabulary that could only say `"jsonb"` is what let a flat-field
-* declaration type-check while every event decoded to null.
-*
-* Kept literal through `toSubgraphSource()` so handler narrowing survives.
-*/
-type PrintFieldType = PrintScalarType | {
-	type: PrintFieldType
-	optional: true
-} | {
-	tuple: Record<string, PrintFieldType>
-} | {
-	list: PrintFieldType
+type IntCV = {
+	readonly type: "int"
+	readonly value: bigint
 };
-interface StxTransferSpec {
-	type: "stx_transfer";
-	sender?: string;
-	recipient?: string;
-	minAmount?: bigint;
-	maxAmount?: bigint;
-}
-interface StxMintSpec {
-	type: "stx_mint";
-	recipient?: string;
-	minAmount?: bigint;
-}
-interface StxBurnSpec {
-	type: "stx_burn";
-	sender?: string;
-	minAmount?: bigint;
-}
-interface StxLockSpec {
-	type: "stx_lock";
-	lockedAddress?: string;
-	minAmount?: bigint;
-}
-/** Scope to contracts conforming to a trait/standard (e.g. "sip-010") instead
-*  of a fixed contract. Index + Subgraphs + Webhooks; Streams has no
-*  trait resolution — `toStreamsParams()` throws if set. */
-type TraitScope = {
-	trait?: string
+type UIntCV = {
+	readonly type: "uint"
+	readonly value: bigint
 };
-/** Scope to a DYNAMIC address set discovered from another source's events —
-*  a Subgraphs-only concept (`toSubgraphSource()` keeps it; every other
-*  projection throws). Structural mirror of the subgraphs `FactoryScope`:
-*  `stacks` is the dependency-graph leaf and cannot import it. */
-type FactoryScope = {
-	factory?: {
-		/** Source name whose events reveal the addresses. */
-		from: string
-		/** Dotted path to the address on that source's payload (e.g. "data.pool"). */
-		field: string
-	}
-};
-interface FtTransferSpec extends TraitScope {
-	type: "ft_transfer";
-	assetIdentifier?: AssetIdentifier;
-	sender?: string;
-	recipient?: string;
-	minAmount?: bigint;
-}
-interface FtMintSpec extends TraitScope {
-	type: "ft_mint";
-	assetIdentifier?: AssetIdentifier;
-	recipient?: string;
-	minAmount?: bigint;
-}
-interface FtBurnSpec extends TraitScope {
-	type: "ft_burn";
-	assetIdentifier?: AssetIdentifier;
-	sender?: string;
-	minAmount?: bigint;
-}
-interface NftTransferSpec extends TraitScope {
-	type: "nft_transfer";
-	assetIdentifier?: AssetIdentifier;
-	sender?: string;
-	recipient?: string;
-}
-interface NftMintSpec extends TraitScope {
-	type: "nft_mint";
-	assetIdentifier?: AssetIdentifier;
-	recipient?: string;
-}
-interface NftBurnSpec extends TraitScope {
-	type: "nft_burn";
-	assetIdentifier?: AssetIdentifier;
-	sender?: string;
-}
-interface ContractCallSpec extends TraitScope, FactoryScope {
-	type: "contract_call";
-	/** One contract id, or a set of them (max 20). Mirrors the subgraphs
-	*  filter — a router plus its pools is one source, not N. */
-	contractId?: string | readonly string[];
-	functionName?: string;
-	caller?: string;
-	/** Contract ABI (`as const`) — preserved literally so `toSubgraphSource()`
-	*  keeps typing `event.input` in `defineSubgraph`. */
-	abi?: AbiContract;
-}
-interface ContractDeploySpec {
-	type: "contract_deploy";
-	deployer?: string;
-	contractName?: string;
-}
-interface PrintEventSpec extends TraitScope, FactoryScope {
-	type: "print_event";
-	/** One contract id, or a set of them (max 20). */
-	contractId?: string | readonly string[];
-	topic?: string;
-	/** Per-topic field schema — preserved literally so `toSubgraphSource()`
-	*  keeps the discriminated-union narrowing of `event.data`. */
-	prints?: Record<string, Record<string, PrintFieldType>>;
-}
-interface SbtcDepositSpec {
-	type: "sbtc_deposit";
-	sender?: string;
-	minAmount?: bigint;
-	maxAmount?: bigint;
-	bitcoinTxid?: string;
-	requestId?: number;
-}
-interface SbtcWithdrawalCreateSpec {
-	type: "sbtc_withdrawal_create";
-	sender?: string;
-	minAmount?: bigint;
-	maxAmount?: bigint;
-	requestId?: number;
-}
-interface SbtcWithdrawalAcceptSpec {
-	type: "sbtc_withdrawal_accept";
-	requestId?: number;
-	sweepTxid?: string;
-}
-interface SbtcWithdrawalRejectSpec {
-	type: "sbtc_withdrawal_reject";
-	requestId?: number;
-}
-interface SbtcWithdrawalSweptConfirmedSpec {
-	type: "sbtc_withdrawal_swept_confirmed";
-	requestId?: number;
-	sweepTxid?: string;
-}
-type ChainEventFilterSpec = StxTransferSpec | StxMintSpec | StxBurnSpec | StxLockSpec | FtTransferSpec | FtMintSpec | FtBurnSpec | NftTransferSpec | NftMintSpec | NftBurnSpec | ContractCallSpec | ContractDeploySpec | PrintEventSpec | SbtcDepositSpec | SbtcWithdrawalCreateSpec | SbtcWithdrawalAcceptSpec | SbtcWithdrawalRejectSpec | SbtcWithdrawalSweptConfirmedSpec;
-type SpecFor<T extends ChainEventFilterType> = Extract<ChainEventFilterSpec, {
-	type: T
-}>;
-/** Wire shape of a chain trigger (Webhooks), derived per member from
-*  the spec: same fields, with `bigint` amounts stringified (uint128 exceeds
-*  JS safe integers) and the type-only `abi`/`prints` decorations dropped.
-*  Structurally assignable to the SDK's `ChainTrigger` union. */
-type ChainTriggerOf<S> = { [K in keyof Omit<S, "abi" | "prints" | "factory">] : Exclude<S[K], bigint | readonly string[]> | (bigint extends S[K] ? string : never) };
-/** Params fragment for `index.events.*` (spread into list/walk/consume). */
-type IndexEventsParamsShape = {
-	eventType: DecodedEventType
-	/** A spec's contract set passes through verbatim (the API takes up to 20). */
-	contractId?: string | readonly string[]
-	assetIdentifier?: AssetIdentifier
-	sender?: string
-	recipient?: string
-	trait?: string
-};
-/** Params fragment for `index.contractCalls.*`. */
-type ContractCallsParamsShape = {
-	/** A spec's contract set passes through verbatim (the API takes up to 20). */
-	contractId?: string | readonly string[]
-	functionName?: string
-	/** Populated from the spec's `caller` — the endpoint filters by tx sender,
-	*  which is the caller. */
-	sender?: string
-	trait?: string
-};
-/** Params fragment for `streams.events.*`. */
-type StreamsParamsShape = {
-	types: readonly DecodedEventType[]
-	contractId?: string | readonly string[]
-	sender?: string
-	recipient?: string
-	assetIdentifier?: AssetIdentifier
-};
-type DecodedMember = "stx_transfer" | "stx_mint" | "stx_burn" | "stx_lock" | "ft_transfer" | "ft_mint" | "ft_burn" | "nft_transfer" | "nft_mint" | "nft_burn" | "print_event";
-type ProjectionsFor<
-	T extends ChainEventFilterType,
-	S
-> = {
-	/** Wire trigger for `subscriptions.create({ triggers: [...] })`. BigInt
-	*  amounts become strings here — the one sanctioned boundary. */
-	toChainTrigger(): ChainTriggerOf<S>
-} & (T extends DecodedMember ? {
-	/** Params for `index.events.list/walk/consume` (merge your own
-	*  `limit`/`fromHeight`/`txContext` etc. on top). */
-	toIndexParams<Extra extends Record<string, unknown>>(extra?: Extra): IndexEventsParamsShape & Extra
-	/** Params for `streams.events.list/consume/stream`. Throws if the
-	*  filter uses `trait` (Streams has no trait resolution) or a
-	*  min/max amount (Streams filters have no amount predicates). */
-	toStreamsParams<Extra extends Record<string, unknown>>(extra?: Extra): StreamsParamsShape & Extra
-} : {}) & (T extends "contract_call" ? {
-	/** Params for `index.contractCalls.list/walk/consume`. */
-	toContractCallsParams<Extra extends Record<string, unknown>>(extra?: Extra): ContractCallsParamsShape & Extra
-} : {}) & (T extends Exclude<ChainEventFilterType, `sbtc_${string}`> ? {
-	/** The `sources` entry for `defineSubgraph` — literal `prints`/`abi`
-	*  types are preserved, so handler narrowing survives. */
-	toSubgraphSource(): S
-} : {});
-/**
-* A canonical chain-event filter: the spec fields plus the projections its
-* member supports. Write the filter once; project it to a query
-* (`toIndexParams`), a stream (`toStreamsParams`), a webhook trigger
-* (`toChainTrigger`), or a subgraph source (`toSubgraphSource`).
-*/
-type ChainEventFilter<
-	T extends ChainEventFilterType = ChainEventFilterType,
-	S extends {
-		type: T
-	} = SpecFor<T>
-> = S & ProjectionsFor<T, S>;
-type Fields<T extends ChainEventFilterType> = Omit<SpecFor<T>, "type">;
-/** The `on.*` namespace, annotated explicitly — bunup's dts emitter needs an
-*  annotation on exported values (an inferred object of generic factories
-*  collapses to `{}` in the emitted declarations). */
-interface OnNamespace {
-	stxTransfer(fields?: Fields<"stx_transfer">): ChainEventFilter<"stx_transfer">;
-	stxMint(fields?: Fields<"stx_mint">): ChainEventFilter<"stx_mint">;
-	stxBurn(fields?: Fields<"stx_burn">): ChainEventFilter<"stx_burn">;
-	stxLock(fields?: Fields<"stx_lock">): ChainEventFilter<"stx_lock">;
-	ftTransfer(fields?: Fields<"ft_transfer">): ChainEventFilter<"ft_transfer">;
-	ftMint(fields?: Fields<"ft_mint">): ChainEventFilter<"ft_mint">;
-	ftBurn(fields?: Fields<"ft_burn">): ChainEventFilter<"ft_burn">;
-	nftTransfer(fields?: Fields<"nft_transfer">): ChainEventFilter<"nft_transfer">;
-	nftMint(fields?: Fields<"nft_mint">): ChainEventFilter<"nft_mint">;
-	nftBurn(fields?: Fields<"nft_burn">): ChainEventFilter<"nft_burn">;
-	/** `abi` literals are preserved (`const A`) so `toSubgraphSource()` keeps
-	*  typing `event.input` inside `defineSubgraph`. */
-	contractCall<const A extends AbiContract | undefined = undefined>(fields?: Omit<SpecFor<"contract_call">, "type" | "abi"> & {
-		abi?: A
-	}): ChainEventFilter<"contract_call", {
-		type: "contract_call"
-	} & Omit<SpecFor<"contract_call">, "type" | "abi"> & {
-		abi?: A
-	}>;
-	contractDeploy(fields?: Fields<"contract_deploy">): ChainEventFilter<"contract_deploy">;
-	/** Canonical member is `print_event` (as Subgraphs and Subscriptions spell
-	*  it); `toIndexParams`/`toStreamsParams` project to `print`. `prints`
-	*  literals are preserved (`const P`) for per-topic `event.data` narrowing. */
-	print<const P extends Record<string, Record<string, PrintFieldType>> | undefined = undefined>(fields?: Omit<SpecFor<"print_event">, "type" | "prints"> & {
-		prints?: P
-	}): ChainEventFilter<"print_event", {
-		type: "print_event"
-	} & Omit<SpecFor<"print_event">, "type" | "prints"> & {
-		prints?: P
-	}>;
-	sbtcDeposit(fields?: Fields<"sbtc_deposit">): ChainEventFilter<"sbtc_deposit">;
-	sbtcWithdrawalCreate(fields?: Fields<"sbtc_withdrawal_create">): ChainEventFilter<"sbtc_withdrawal_create">;
-	sbtcWithdrawalAccept(fields?: Fields<"sbtc_withdrawal_accept">): ChainEventFilter<"sbtc_withdrawal_accept">;
-	sbtcWithdrawalReject(fields?: Fields<"sbtc_withdrawal_reject">): ChainEventFilter<"sbtc_withdrawal_reject">;
-	sbtcWithdrawalSweptConfirmed(fields?: Fields<"sbtc_withdrawal_swept_confirmed">): ChainEventFilter<"sbtc_withdrawal_swept_confirmed">;
-}
-/**
-* `on.*` — one filter vocabulary for every surface.
-*
-* ```ts
-* import { on } from "@secondlayer/stacks/filters";
-*
-* const usdc = on.ftTransfer({ assetIdentifier: USDC, minAmount: 1_000_000n });
-*
-* sl.index.events.list(usdc.toIndexParams({ limit: 100 }));   // pull
-* sl.streams.events.consume({ ...usdc.toStreamsParams(), onBatch });
-* sl.subscriptions.create({ name, url, triggers: [usdc.toChainTrigger()] });
-* defineSubgraph({ sources: { usdc: usdc.toSubgraphSource() }, schema, handlers });
-* ```
-*
-* A surface a member can't reach is a missing method (compile error), and a
-* field a surface can't express throws at projection time — never a silent
-* zero-row or over-wide match.
-*/
-declare const on: OnNamespace;
-/** Account derived from a local private key (mnemonic or raw key). */
-type LocalAccount = {
-	type: "local"
-	address: string
-	/** Compressed public key (hex) */
-	publicKey: string
-	/** Raw ECDSA sign over a hash */
-	sign(hash: Uint8Array): Uint8Array
-	/** Sign a raw UTF-8 / byte message (`sha256(bytes)`). Not SIP-018. */
-	signMessage(message: string | Uint8Array): string
-};
-/** Account with a user-provided signing function (sync or async). */
-type CustomAccount = {
-	type: "custom"
-	address: string
-	publicKey: string
-	sign(hash: Uint8Array): Promise<Uint8Array> | Uint8Array
-};
-/** Browser wallet provider interface (e.g. Leather, Xverse). */
-type StacksProvider = {
-	request(method: string, params?: any): Promise<any>
-};
-/** Account backed by a browser wallet {@link StacksProvider}. */
-type ProviderAccount = {
-	type: "provider"
-	address: string
-	publicKey: string
-	provider: StacksProvider
-};
-type IntCV = {
-	readonly type: "int"
-	readonly value: bigint
-};
-type UIntCV = {
-	readonly type: "uint"
-	readonly value: bigint
-};
-type BooleanCV = TrueCV | FalseCV;
-type TrueCV = {
-	readonly type: "true"
+type BooleanCV = TrueCV | FalseCV;
+type TrueCV = {
+	readonly type: "true"
 };
 type FalseCV = {
 	readonly type: "false"
@@ -1729,159 +1301,638 @@ declare function createMultiSigClient(config: MultiSigClientConfig): MultiSigCli
 type RedisLike = {
 	send(command: string, args: string[]): Promise<unknown>
 };
-type RedisStoreParams = {
-	redis: RedisLike
-	/** Key prefix for stored nonce counters. Default `"stacks:nonce:"`. */
-	prefix?: string
+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 a Secondlayer instance'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. 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 = {
+	/**
+	* 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
+	/** Instance token, sent as `Authorization: Bearer`. */
+	apiKey?: string
+	/** 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: {
+		client: Client
+		address: string
+	}) => Promise<bigint>
+};
+/**
+* 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?: 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`.
+*/
+declare function http(url?: string, config?: TransportConfig): TransportFactory;
+/** Create a transport backed by a user-provided request function. */
+declare function custom(params: {
+	request: RequestFn
+}): TransportFactory;
+/** Create a transport that tries each transport in order until one succeeds. */
+declare function fallback(transports: TransportFactory[]): TransportFactory;
+/** Configuration for the WebSocket transport, extending base {@link TransportConfig}. */
+type WebSocketTransportConfig = TransportConfig & {
+	/** WebSocket URL (resolved from chain if omitted) */
+	url?: string
+	/** Enable auto-reconnect (default: true) */
+	reconnect?: boolean
+	/** Max reconnect attempts (default: 10) */
+	reconnectMaxAttempts?: number
+	/** Base delay in ms for exponential backoff (default: 1000) */
+	reconnectBaseDelay?: number
+};
+/** Transport with WebSocket subscription capabilities and auto-reconnect. */
+type WebSocketTransport = Transport & {
+	type: "webSocket"
+	subscribe: (params: WsSubscribeParams, callback: (data: any) => void) => Promise<Subscription>
+	destroy: () => void
+};
+/**
+* Create a WebSocket transport for real-time Stacks event subscriptions.
+* HTTP requests use the resolved RPC URL; subscriptions use the WS endpoint.
+*/
+declare function webSocket(url?: string, config?: WebSocketTransportConfig): TransportFactory;
+declare const DECODED_EVENT_TYPES: readonly ["stx_transfer", "stx_mint", "stx_burn", "stx_lock", "ft_transfer", "ft_mint", "ft_burn", "nft_transfer", "nft_mint", "nft_burn", "print"];
+type DecodedEventType = (typeof DECODED_EVENT_TYPES)[number];
+/** Opt-in node vm_events, stored names. Parallel to DECODED_EVENT_TYPES — not
+*  the decoded_events / Streams 1.0 vocab. Cursor second component is
+*  ordinal. Inner calls are never `contract_call`. */
+declare const VM_EVENT_TYPES: readonly ["nested_contract_call", "var_set", "map_set", "map_insert", "map_delete"];
+type VmEventType = (typeof VM_EVENT_TYPES)[number];
+/** Every chain-event filter member across all four surfaces: the 10 decoded
+*  token/STX types, the three contract-shaped types (spelled as subgraphs and
+*  triggers spell them — Index/Streams project `print_event` → `print`), and
+*  the five sBTC lifecycle types (Webhooks-only). */
+declare const CHAIN_EVENT_FILTER_TYPES: readonly ["stx_transfer", "stx_mint", "stx_burn", "stx_lock", "ft_transfer", "ft_mint", "ft_burn", "nft_transfer", "nft_mint", "nft_burn", "contract_call", "contract_deploy", "print_event", "nested_contract_call", "var_set", "map_set", "map_insert", "map_delete", "sbtc_deposit", "sbtc_withdrawal_create", "sbtc_withdrawal_accept", "sbtc_withdrawal_reject", "sbtc_withdrawal_swept_confirmed"];
+type ChainEventFilterType = (typeof CHAIN_EVENT_FILTER_TYPES)[number];
+/** C32-encoded address version bytes for single-sig and multi-sig on each network. */
+declare const AddressVersion: {
+	readonly MainnetSingleSig: 22
+	readonly MainnetMultiSig: 20
+	readonly TestnetSingleSig: 26
+	readonly TestnetMultiSig: 21
+};
+type AddressVersion = (typeof AddressVersion)[keyof typeof AddressVersion];
+/** Mainnet burn address (all-zero hash160). */
+declare const ZERO_ADDRESS = "SP000000000000000000002Q6VF78";
+/** Testnet burn address (all-zero hash160). */
+declare const TESTNET_ZERO_ADDRESS = "ST000000000000000000002AMW42H";
+/** Number of microSTX per 1 STX (10^6). */
+declare const MICROSTX_PER_STX = 1000000n;
+/** Alias for validateStacksAddress — matches future.md naming. */
+declare const isValidAddress: (address: string) => boolean;
+/**
+* Compare two Stacks addresses for equality (case-insensitive, version-aware).
+* Throws if either address is invalid.
+*/
+declare function isAddressEqual(a: string, b: string): boolean;
+/**
+* Build a contract address from deployer + contract name.
+* Validates both parts; returns `deployer.contractName`.
+*/
+declare function getContractAddress(deployer: string, contractName: string): string;
+type AbiUInt128 = "uint128";
+type AbiInt128 = "int128";
+type AbiBool = "bool";
+type AbiPrincipal = "principal";
+type AbiTraitReference = "trait_reference";
+type AbiNone = "none";
+type AbiStringAscii<L extends number = number> = {
+	"string-ascii": {
+		length: L
+	}
+};
+type AbiStringUtf8<L extends number = number> = {
+	"string-utf8": {
+		length: L
+	}
+};
+type AbiBuffer<L extends number = number> = {
+	buff: {
+		length: L
+	}
+};
+type AbiPrimitiveType = AbiUInt128 | AbiInt128 | AbiBool | AbiPrincipal | AbiTraitReference | AbiNone | AbiStringAscii | AbiStringUtf8 | AbiBuffer;
+interface AbiListType {
+	list: {
+		type: AbiType
+		length: number
+	};
+}
+interface AbiTupleType {
+	tuple: ReadonlyArray<{
+		name: string
+		type: AbiType
+	}>;
+}
+interface AbiOptionalType {
+	optional: AbiType;
+}
+interface AbiResponseType {
+	response: {
+		ok: AbiType
+		error: AbiType
+	};
+}
+/** Discriminated union of all Clarity value types (primitives, buffers, lists, tuples, optionals, responses). */
+type AbiType = AbiPrimitiveType | AbiListType | AbiTupleType | AbiOptionalType | AbiResponseType;
+type FunctionAccess = "public" | "read-only" | "private";
+interface FunctionArg {
+	name: string;
+	type: AbiType;
+}
+/** A single Clarity function definition with name, access level, arguments, and return type. */
+interface AbiFunction {
+	name: string;
+	access: FunctionAccess;
+	args: ReadonlyArray<FunctionArg>;
+	outputs: AbiType;
+}
+type VariableAccess = "constant" | "variable";
+interface AbiVariable {
+	name: string;
+	type: AbiType;
+	access: VariableAccess;
+}
+interface AbiMap {
+	name: string;
+	key: AbiType;
+	value: AbiType;
+}
+interface AbiFungibleToken {
+	name: string;
+}
+interface AbiNonFungibleToken {
+	name: string;
+	type: AbiType;
+}
+type TraitFunctionAccess = Exclude<FunctionAccess, "private">;
+interface AbiTraitFunction {
+	name: string;
+	access: TraitFunctionAccess;
+	args: ReadonlyArray<FunctionArg>;
+	outputs: AbiType;
+}
+interface AbiTraitDefinition {
+	name: string;
+	functions: ReadonlyArray<AbiTraitFunction>;
+}
+/** Full Clarity contract ABI including functions, maps, variables, and token definitions. */
+interface AbiContract {
+	functions: ReadonlyArray<AbiFunction>;
+	maps?: ReadonlyArray<AbiMap>;
+	variables?: ReadonlyArray<AbiVariable>;
+	fungible_tokens?: ReadonlyArray<AbiFungibleToken>;
+	non_fungible_tokens?: ReadonlyArray<AbiNonFungibleToken>;
+	implemented_traits?: ReadonlyArray<string>;
+	defined_traits?: ReadonlyArray<AbiTraitDefinition>;
+}
+/**
+* `<contract>::<asset-name>` — the shape a fungible/non-fungible asset filter
+* takes, expressed so the compiler can check it.
+*
+* The most common mistake in this API is passing a CONTRACT ID
+* (`SP….sbtc-token`) where an asset identifier (`SP….sbtc-token::sbtc-token`)
+* belongs, and the failure mode is a query that quietly returns zero rows. The
+* two differ structurally by `::`, so a template-literal type catches it at the
+* call site — no brand, no cast, literals just work.
+*
+* A value that is only known at runtime (config, env) is not narrow enough on
+* purpose; run it through {@link assetId} once, which validates and narrows.
+*
+* Wildcard patterns (Webhooks/Subgraphs-only) are admitted by the second arm — they
+* are legitimately not full identifiers (`SPB.*`), and the runtime validator
+* short-circuits on them for the same reason.
+*/
+type AssetIdentifier = `${string}::${string}` | `${string}*${string}`;
+/** Scalar print field types (structural mirror of the subgraphs `ColumnType`). */
+type PrintScalarType = "uint" | "int" | "text" | "principal" | "boolean" | "timestamp" | "jsonb";
+/**
+* One declared print field — structural mirror of `PrintField` in
+* `@secondlayer/subgraphs`. Composite forms exist because real print payloads
+* nest: a vocabulary that could only say `"jsonb"` is what let a flat-field
+* declaration type-check while every event decoded to null.
+*
+* Kept literal through `toSubgraphSource()` so handler narrowing survives.
+*/
+type PrintFieldType = PrintScalarType | {
+	type: PrintFieldType
+	optional: true
+} | {
+	tuple: Record<string, PrintFieldType>
+} | {
+	list: PrintFieldType
+};
+interface StxTransferSpec {
+	type: "stx_transfer";
+	sender?: string;
+	recipient?: string;
+	minAmount?: bigint;
+	maxAmount?: bigint;
+}
+interface StxMintSpec {
+	type: "stx_mint";
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface StxBurnSpec {
+	type: "stx_burn";
+	sender?: string;
+	minAmount?: bigint;
+}
+interface StxLockSpec {
+	type: "stx_lock";
+	lockedAddress?: string;
+	minAmount?: bigint;
+}
+/** Scope to contracts conforming to a trait/standard (e.g. "sip-010") instead
+*  of a fixed contract. Index + Subgraphs + Webhooks; Streams has no
+*  trait resolution — `toStreamsParams()` throws if set. */
+type TraitScope = {
+	trait?: string
+};
+/** Scope to a DYNAMIC address set discovered from another source's events —
+*  a Subgraphs-only concept (`toSubgraphSource()` keeps it; every other
+*  projection throws). Structural mirror of the subgraphs `FactoryScope`:
+*  `stacks` is the dependency-graph leaf and cannot import it. */
+type FactoryScope = {
+	factory?: {
+		/** Source name whose events reveal the addresses. */
+		from: string
+		/** Dotted path to the address on that source's payload (e.g. "data.pool"). */
+		field: string
+	}
+};
+interface FtTransferSpec extends TraitScope {
+	type: "ft_transfer";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtMintSpec extends TraitScope {
+	type: "ft_mint";
+	assetIdentifier?: AssetIdentifier;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtBurnSpec extends TraitScope {
+	type: "ft_burn";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+	minAmount?: bigint;
+}
+interface NftTransferSpec extends TraitScope {
+	type: "nft_transfer";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+	recipient?: string;
+}
+interface NftMintSpec extends TraitScope {
+	type: "nft_mint";
+	assetIdentifier?: AssetIdentifier;
+	recipient?: string;
+}
+interface NftBurnSpec extends TraitScope {
+	type: "nft_burn";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+}
+interface ContractCallSpec extends TraitScope, FactoryScope {
+	type: "contract_call";
+	/** One contract id, or a set of them (max 20). Mirrors the subgraphs
+	*  filter — a router plus its pools is one source, not N. */
+	contractId?: string | readonly string[];
+	functionName?: string;
+	caller?: string;
+	/** Contract ABI (`as const`) — preserved literally so `toSubgraphSource()`
+	*  keeps typing `event.input` in `defineSubgraph`. */
+	abi?: AbiContract;
+}
+interface ContractDeploySpec {
+	type: "contract_deploy";
+	deployer?: string;
+	contractName?: string;
+}
+interface NestedContractCallSpec extends TraitScope, FactoryScope {
+	type: "nested_contract_call";
+	contractId?: string | readonly string[];
+	functionName?: string;
+	caller?: string;
+	sender?: string;
+}
+interface VarSetSpec extends TraitScope, FactoryScope {
+	type: "var_set";
+	contractId?: string | readonly string[];
+	varName?: string;
+}
+interface MapSetSpec extends TraitScope, FactoryScope {
+	type: "map_set";
+	contractId?: string | readonly string[];
+	map?: string;
+}
+interface MapInsertSpec extends TraitScope, FactoryScope {
+	type: "map_insert";
+	contractId?: string | readonly string[];
+	map?: string;
+}
+interface MapDeleteSpec extends TraitScope, FactoryScope {
+	type: "map_delete";
+	contractId?: string | readonly string[];
+	map?: string;
+}
+interface PrintEventSpec extends TraitScope, FactoryScope {
+	type: "print_event";
+	/** One contract id, or a set of them (max 20). */
+	contractId?: string | readonly string[];
+	topic?: string;
+	/** Per-topic field schema — preserved literally so `toSubgraphSource()`
+	*  keeps the discriminated-union narrowing of `event.data`. */
+	prints?: Record<string, Record<string, PrintFieldType>>;
+}
+interface SbtcDepositSpec {
+	type: "sbtc_deposit";
+	sender?: string;
+	minAmount?: bigint;
+	maxAmount?: bigint;
+	bitcoinTxid?: string;
+	requestId?: number;
+}
+interface SbtcWithdrawalCreateSpec {
+	type: "sbtc_withdrawal_create";
+	sender?: string;
+	minAmount?: bigint;
+	maxAmount?: bigint;
+	requestId?: number;
+}
+interface SbtcWithdrawalAcceptSpec {
+	type: "sbtc_withdrawal_accept";
+	requestId?: number;
+	sweepTxid?: string;
+}
+interface SbtcWithdrawalRejectSpec {
+	type: "sbtc_withdrawal_reject";
+	requestId?: number;
+}
+interface SbtcWithdrawalSweptConfirmedSpec {
+	type: "sbtc_withdrawal_swept_confirmed";
+	requestId?: number;
+	sweepTxid?: string;
+}
+type ChainEventFilterSpec = StxTransferSpec | StxMintSpec | StxBurnSpec | StxLockSpec | FtTransferSpec | FtMintSpec | FtBurnSpec | NftTransferSpec | NftMintSpec | NftBurnSpec | ContractCallSpec | ContractDeploySpec | NestedContractCallSpec | VarSetSpec | MapSetSpec | MapInsertSpec | MapDeleteSpec | PrintEventSpec | SbtcDepositSpec | SbtcWithdrawalCreateSpec | SbtcWithdrawalAcceptSpec | SbtcWithdrawalRejectSpec | SbtcWithdrawalSweptConfirmedSpec;
+type SpecFor<T extends ChainEventFilterType> = Extract<ChainEventFilterSpec, {
+	type: T
+}>;
+/** Wire shape of a chain trigger (Webhooks), derived per member from
+*  the spec: same fields, with `bigint` amounts stringified (uint128 exceeds
+*  JS safe integers) and the type-only `abi`/`prints` decorations dropped.
+*  Structurally assignable to the SDK's `ChainTrigger` union. */
+type ChainTriggerOf<S> = { [K in keyof Omit<S, "abi" | "prints" | "factory">] : Exclude<S[K], bigint | readonly string[]> | (bigint extends S[K] ? string : never) };
+/** Params fragment for `index.events.*` (spread into list/walk/consume). */
+type IndexEventsParamsShape = {
+	eventType: DecodedEventType | VmEventType
+	/** A spec's contract set passes through verbatim (the API takes up to 20). */
+	contractId?: string | readonly string[]
+	assetIdentifier?: AssetIdentifier
+	sender?: string
+	recipient?: string
+	functionName?: string
+	caller?: string
+	map?: string
+	varName?: string
+	trait?: string
+};
+/** Params fragment for `index.contractCalls.*`. */
+type ContractCallsParamsShape = {
+	/** A spec's contract set passes through verbatim (the API takes up to 20). */
+	contractId?: string | readonly string[]
+	functionName?: string
+	/** Populated from the spec's `caller` — the endpoint filters by tx sender,
+	*  which is the caller. */
+	sender?: string
+	trait?: 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
+type VmMember = "nested_contract_call" | "var_set" | "map_set" | "map_insert" | "map_delete";
+/** Params fragment for classic `streams.events.*` (Streams 1.0). VM members
+*  project to {@link StreamsVmParamsShape} instead — mixing the vocabularies
+*  here makes `events.consume({ ...on.ftTransfer().toStreamsParams(), onBatch })`
+*  fail type-check. */
+type StreamsParamsShape = {
+	types: readonly DecodedEventType[]
+	contractId?: string | readonly string[]
+	sender?: string
+	recipient?: string
+	assetIdentifier?: AssetIdentifier
+};
+/** VM member projection: `clock` is the `"vm"` literal so SDK overload 1 matches. */
+type StreamsVmParamsShape<T extends VmMember = VmMember> = {
+	types: readonly [T]
+	clock: "vm"
+	contractId?: string | readonly string[]
 };
+type DecodedMember = "stx_transfer" | "stx_mint" | "stx_burn" | "stx_lock" | "ft_transfer" | "ft_mint" | "ft_burn" | "nft_transfer" | "nft_mint" | "nft_burn" | "print_event";
+type ProjectionsFor<
+	T extends ChainEventFilterType,
+	S
+> = {
+	/** Wire trigger for `webhooks.create({ triggers: [...] })`. BigInt
+	*  amounts become strings here — the one sanctioned boundary. */
+	toChainTrigger(): ChainTriggerOf<S>
+} & (T extends DecodedMember | VmMember ? {
+	/** Params for `index.events.list/walk/consume` (merge your own
+	*  `limit`/`fromHeight`/`txContext` etc. on top). */
+	toIndexParams<Extra extends Record<string, unknown>>(extra?: Extra): IndexEventsParamsShape & Extra
+	/** Params for `streams.events.list/consume/stream`. Throws if the
+	*  filter uses `trait` (Streams has no trait resolution) or a
+	*  min/max amount (Streams filters have no amount predicates). */
+	toStreamsParams<Extra extends Record<string, unknown> = Record<string, never>>(extra?: Extra): T extends VmMember ? StreamsVmParamsShape<T> & Extra : StreamsParamsShape & Extra
+} : {}) & (T extends "contract_call" ? {
+	/** Params for `index.contractCalls.list/walk/consume`. */
+	toContractCallsParams<Extra extends Record<string, unknown>>(extra?: Extra): ContractCallsParamsShape & Extra
+} : {}) & (T extends Exclude<ChainEventFilterType, `sbtc_${string}`> ? {
+	/** The `sources` entry for `defineSubgraph` — literal `prints`/`abi`
+	*  types are preserved, so handler narrowing survives. */
+	toSubgraphSource(): S
+} : {});
 /**
-* 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)`.
+* A canonical chain-event filter: the spec fields plus the projections its
+* member supports. Write the filter once; project it to a query
+* (`toIndexParams`), a stream (`toStreamsParams`), a webhook trigger
+* (`toChainTrigger`), or a subgraph source (`toSubgraphSource`).
 */
-declare function postgresStore(params: PostgresStoreParams): NonceStore;
+type ChainEventFilter<
+	T extends ChainEventFilterType = ChainEventFilterType,
+	S extends {
+		type: T
+	} = SpecFor<T>
+> = S & ProjectionsFor<T, S>;
+type Fields<T extends ChainEventFilterType> = Omit<SpecFor<T>, "type">;
+/** The `on.*` namespace, annotated explicitly — bunup's dts emitter needs an
+*  annotation on exported values (an inferred object of generic factories
+*  collapses to `{}` in the emitted declarations). */
+interface OnNamespace {
+	stxTransfer(fields?: Fields<"stx_transfer">): ChainEventFilter<"stx_transfer">;
+	stxMint(fields?: Fields<"stx_mint">): ChainEventFilter<"stx_mint">;
+	stxBurn(fields?: Fields<"stx_burn">): ChainEventFilter<"stx_burn">;
+	stxLock(fields?: Fields<"stx_lock">): ChainEventFilter<"stx_lock">;
+	ftTransfer(fields?: Fields<"ft_transfer">): ChainEventFilter<"ft_transfer">;
+	ftMint(fields?: Fields<"ft_mint">): ChainEventFilter<"ft_mint">;
+	ftBurn(fields?: Fields<"ft_burn">): ChainEventFilter<"ft_burn">;
+	nftTransfer(fields?: Fields<"nft_transfer">): ChainEventFilter<"nft_transfer">;
+	nftMint(fields?: Fields<"nft_mint">): ChainEventFilter<"nft_mint">;
+	nftBurn(fields?: Fields<"nft_burn">): ChainEventFilter<"nft_burn">;
+	/** `abi` literals are preserved (`const A`) so `toSubgraphSource()` keeps
+	*  typing `event.input` inside `defineSubgraph`. */
+	contractCall<const A extends AbiContract | undefined = undefined>(fields?: Omit<SpecFor<"contract_call">, "type" | "abi"> & {
+		abi?: A
+	}): ChainEventFilter<"contract_call", {
+		type: "contract_call"
+	} & Omit<SpecFor<"contract_call">, "type" | "abi"> & {
+		abi?: A
+	}>;
+	contractDeploy(fields?: Fields<"contract_deploy">): ChainEventFilter<"contract_deploy">;
+	/** Canonical member is `print_event` (as Subgraphs and Webhooks spell
+	*  it); `toIndexParams`/`toStreamsParams` project to `print`. `prints`
+	*  literals are preserved (`const P`) for per-topic `event.data` narrowing. */
+	print<const P extends Record<string, Record<string, PrintFieldType>> | undefined = undefined>(fields?: Omit<SpecFor<"print_event">, "type" | "prints"> & {
+		prints?: P
+	}): ChainEventFilter<"print_event", {
+		type: "print_event"
+	} & Omit<SpecFor<"print_event">, "type" | "prints"> & {
+		prints?: P
+	}>;
+	nestedCall(fields?: Fields<"nested_contract_call">): ChainEventFilter<"nested_contract_call">;
+	varSet(fields?: Fields<"var_set">): ChainEventFilter<"var_set">;
+	mapSet(fields?: Fields<"map_set">): ChainEventFilter<"map_set">;
+	mapInsert(fields?: Fields<"map_insert">): ChainEventFilter<"map_insert">;
+	mapDelete(fields?: Fields<"map_delete">): ChainEventFilter<"map_delete">;
+	sbtcDeposit(fields?: Fields<"sbtc_deposit">): ChainEventFilter<"sbtc_deposit">;
+	sbtcWithdrawalCreate(fields?: Fields<"sbtc_withdrawal_create">): ChainEventFilter<"sbtc_withdrawal_create">;
+	sbtcWithdrawalAccept(fields?: Fields<"sbtc_withdrawal_accept">): ChainEventFilter<"sbtc_withdrawal_accept">;
+	sbtcWithdrawalReject(fields?: Fields<"sbtc_withdrawal_reject">): ChainEventFilter<"sbtc_withdrawal_reject">;
+	sbtcWithdrawalSweptConfirmed(fields?: Fields<"sbtc_withdrawal_swept_confirmed">): ChainEventFilter<"sbtc_withdrawal_swept_confirmed">;
+}
 /**
-* Mempool-aware {@link NonceManagerSource}s.
+* `on.*` — one filter vocabulary for every surface.
 *
-* 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:
+* ```ts
+* import { on } from "@secondlayer/stacks/filters";
 *
-*   - {@link mempoolAwareSource} — bring your own `getPending`.
-*   - {@link indexSource}: prebuilt over a Secondlayer instance'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.
+* const usdc = on.ftTransfer({ assetIdentifier: USDC, minAmount: 1_000_000n });
 *
-* 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. 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 = {
-	/**
-	* 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
-	/** Instance token, sent as `Authorization: Bearer`. */
-	apiKey?: string
-	/** 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: {
-		client: Client
-		address: string
-	}) => Promise<bigint>
-};
-/**
-* 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?: 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`.
-*/
-declare function http(url?: string, config?: TransportConfig): TransportFactory;
-/** Create a transport backed by a user-provided request function. */
-declare function custom(params: {
-	request: RequestFn
-}): TransportFactory;
-/** Create a transport that tries each transport in order until one succeeds. */
-declare function fallback(transports: TransportFactory[]): TransportFactory;
-/** Configuration for the WebSocket transport, extending base {@link TransportConfig}. */
-type WebSocketTransportConfig = TransportConfig & {
-	/** WebSocket URL (resolved from chain if omitted) */
-	url?: string
-	/** Enable auto-reconnect (default: true) */
-	reconnect?: boolean
-	/** Max reconnect attempts (default: 10) */
-	reconnectMaxAttempts?: number
-	/** Base delay in ms for exponential backoff (default: 1000) */
-	reconnectBaseDelay?: number
-};
-/** Transport with WebSocket subscription capabilities and auto-reconnect. */
-type WebSocketTransport = Transport & {
-	type: "webSocket"
-	subscribe: (params: WsSubscribeParams, callback: (data: any) => void) => Promise<Subscription>
-	destroy: () => void
-};
-/**
-* Create a WebSocket transport for real-time Stacks event subscriptions.
-* HTTP requests use the resolved RPC URL; subscriptions use the WS endpoint.
+* sl.index.events.list(usdc.toIndexParams({ limit: 100 }));   // pull
+* sl.streams.events.consume({ ...usdc.toStreamsParams(), onBatch });
+* sl.webhooks.create({ name, url, triggers: [usdc.toChainTrigger()] });
+* defineSubgraph({ sources: { usdc: usdc.toSubgraphSource() }, schema, handlers });
+* ```
+*
+* A surface a member can't reach is a missing method (compile error), and a
+* field a surface can't express throws at projection time — never a silent
+* zero-row or over-wide match.
 */
-declare function webSocket(url?: string, config?: WebSocketTransportConfig): TransportFactory;
+declare const on: OnNamespace;
 /** Create a ProviderAccount by querying the wallet for addresses */
 declare function providerToAccount(provider: StacksProvider): Promise<ProviderAccount>;
 /** Stacks mainnet chain definition (Hiro API). */
@@ -1991,4 +2042,4 @@ declare class ReadContractError 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, TimeoutError, TESTNET_ZERO_ADDRESS, Subscription, StartNonceReconcilerParams, StacksProvider, StacksChain, SqlLike, SimulationError, SigningError, SerializationError, RequestOptions, RequestFn, RedisStoreParams, RedisLike, ReconcileNonceResult, ReconcileNonceParams, ReadContractError, 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 };
+export { Account, AddressVersion, BaseError, BroadcastError, ChainEventFilter, ChainEventFilterSpec, ChainEventFilterType, ChainTriggerOf, Client, ClientConfig, CreateNonceManagerParams, CustomAccount, GetTransactionParams, HiroNonceSourceParams, HttpRequestError, IndexSourceConfigError, IndexSourceParams, IndexTxSourceParams, LocalAccount, MICROSTX_PER_STX, MalformedResponseError, MempoolAwareSourceParams, MultiSigActions, MultiSigClient, MultiSigClientConfig, NonceManager, NonceManagerSource, NonceStore, PostgresStoreParams, ProviderAccount, PublicActions, PublicClient, PublicClientConfig, ReadContractError, ReconcileNonceParams, ReconcileNonceResult, RedisLike, RedisStoreParams, RequestFn, RequestOptions, SerializationError, SigningError, SimulationError, SqlLike, StacksChain, StacksProvider, StartNonceReconcilerParams, Subscription, TESTNET_ZERO_ADDRESS, TimeoutError, TransactionAbortedError, TransactionDroppedError, TransactionError, TransactionReceipt, TransactionSnapshot, TransactionStatus, TransactionStatusSource, Transport, TransportConfig, TransportFactory, TxRejectionReason, WaitForTransactionReceiptParams, WaitForTransactionTimeoutError, WalletActions, WalletClient, WalletClientConfig, WebSocketError, WebSocketTransport, WebSocketTransportConfig, ZERO_ADDRESS, broadcastWithNonceReset, createClient, createMultiSigClient, createNonceManager, createPublicClient, createWalletClient, custom, defineChain, devnet, extendedApiSource, fallback, formatStx, getContractAddress, getTransaction2 as getTransaction, hiroNonceSource, http, indexSource, indexTxSource, isAddressEqual, isNonceConflictError, isValidAddress, jsonRpcSource, mainnet, memoryStore, mempoolAwareSource, mocknet, multisigActions, nextFreeNonce, on, parseStx, postgresStore, providerToAccount, publicActions, reconcileNonce, redisStore, resolveNonce, startNonceReconciler, testnet, waitForTransactionReceipt2 as waitForTransactionReceipt, walletActions, webSocket };