@secondlayer/stacks 2.19.1 → 2.20.0

package/dist/src/filters/index.d.cts

@@ -0,0 +1,389 @@
+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];
+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>;
+}
+/** Print field-schema vocabulary (structural mirror of the subgraphs
+*  `ColumnType`; kept literal so `toSubgraphSource()` preserves narrowing). */
+type PrintFieldType = "uint" | "int" | "text" | "principal" | "boolean" | "timestamp" | "jsonb";
+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 + Subscriptions; Streams has no
+*  trait resolution — `toStreamsParams()` throws if set. */
+type TraitScope = {
+	trait?: string
+};
+interface FtTransferSpec extends TraitScope {
+	type: "ft_transfer";
+	assetIdentifier?: string;
+	sender?: string;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtMintSpec extends TraitScope {
+	type: "ft_mint";
+	assetIdentifier?: string;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtBurnSpec extends TraitScope {
+	type: "ft_burn";
+	assetIdentifier?: string;
+	sender?: string;
+	minAmount?: bigint;
+}
+interface NftTransferSpec extends TraitScope {
+	type: "nft_transfer";
+	assetIdentifier?: string;
+	sender?: string;
+	recipient?: string;
+}
+interface NftMintSpec extends TraitScope {
+	type: "nft_mint";
+	assetIdentifier?: string;
+	recipient?: string;
+}
+interface NftBurnSpec extends TraitScope {
+	type: "nft_burn";
+	assetIdentifier?: string;
+	sender?: string;
+}
+interface ContractCallSpec extends TraitScope {
+	type: "contract_call";
+	contractId?: 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 {
+	type: "print_event";
+	contractId?: 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 (Subscriptions), 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">] : S[K] extends bigint | undefined ? Exclude<S[K], bigint> | string : S[K] };
+/** Loose trigger shape (any member). */
+type ChainTriggerShape = ChainTriggerOf<ChainEventFilterSpec>;
+/** Params fragment for `index.events.*` (spread into list/walk/consume). */
+type IndexEventsParamsShape = {
+	eventType: DecodedEventType
+	contractId?: string
+	assetIdentifier?: string
+	sender?: string
+	recipient?: string
+	trait?: string
+};
+/** Params fragment for `index.contractCalls.*`. */
+type ContractCallsParamsShape = {
+	contractId?: string
+	functionName?: string
+	sender?: string
+	trait?: string
+};
+/** Params fragment for `streams.events.*`. */
+type StreamsParamsShape = {
+	types: readonly DecodedEventType[]
+	contractId?: string
+	sender?: string
+	recipient?: string
+	assetIdentifier?: 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 `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>;
+/** Build a canonical filter: validated spec + the projections its member
+*  supports (methods are attached per member at runtime, matching the
+*  type-level gating exactly). `const F` preserves field literals — a
+*  `prints`/`abi` declaration keeps its exact type through
+*  `toSubgraphSource()`, which is what feeds `defineSubgraph` narrowing. */
+declare function makeChainEventFilter<
+	T extends ChainEventFilterType,
+	const F extends Omit<SpecFor<T>, "type">
+>(type: T, fields: F): ChainEventFilter<T, {
+	type: T
+} & F>;
+/**
+* Rehydrate a canonical filter from a subgraph-source-shaped object (the
+* inverse of `toSubgraphSource`). Powers migration and the round-trip
+* property gate: `toSubgraphSource(fromSubgraphSource(f))` must deep-equal
+* `f` for every production subgraph source.
+*/
+declare function fromSubgraphSource(source: ChainEventFilterSpec): ChainEventFilter;
+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;
+/** A validated Stacks principal (standard or contract). Branded so downstream
+*  code can require "already validated" without re-checking. */
+type Principal = string & {
+	readonly __principal: unique symbol
+};
+/** `true` for a standard (`SP…`/`ST…`) or contract (`SP….name`) principal. */
+declare function isPrincipal(value: string): value is Principal;
+/** Subscriptions match `*` wildcards in principal/identifier patterns; every
+*  other surface treats the value literally. */
+declare function hasWildcard(value: string): boolean;
+/** Throw unless `value` is a principal or a wildcard pattern. The factories
+*  call this so a swapped argument (asset id where a sender belongs, typo'd
+*  address) fails at construction — not as a silent zero-row query. */
+declare function assertPrincipalish(field: string, value: string): void;
+/** Throw unless `value` looks like `SP….contract::asset` (or a wildcard). */
+declare function assertAssetIdentifier(field: string, value: string): void;
+/** Throw unless `value` is a contract id `SP….name` (or a wildcard). */
+declare function assertContractId(field: string, value: string): void;
+export { on, makeChainEventFilter, isPrincipal, hasWildcard, fromSubgraphSource, assertPrincipalish, assertContractId, assertAssetIdentifier, StxTransferSpec, StxMintSpec, StxLockSpec, StxBurnSpec, StreamsParamsShape, SpecFor, SbtcWithdrawalSweptConfirmedSpec, SbtcWithdrawalRejectSpec, SbtcWithdrawalCreateSpec, SbtcWithdrawalAcceptSpec, SbtcDepositSpec, PrintFieldType, PrintEventSpec, Principal, NftTransferSpec, NftMintSpec, NftBurnSpec, IndexEventsParamsShape, FtTransferSpec, FtMintSpec, FtBurnSpec, DecodedEventType, DECODED_EVENT_TYPES, ContractDeploySpec, ContractCallsParamsShape, ContractCallSpec, ChainTriggerShape, ChainTriggerOf, ChainEventFilterType, ChainEventFilterSpec, ChainEventFilter, CHAIN_EVENT_FILTER_TYPES };