@secondlayer/subgraphs 3.21.0 → 3.23.0

package/dist/src/testing/index.d.ts

@@ -0,0 +1,667 @@
+import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
+/**
+* How long a read stays valid.
+*
+* - `per-block` (default): pinned to the block being processed, cached under
+*   its `index_block_hash`. Sound for any read-only function — reindexing the
+*   same block always returns the same value, and a reorg-replaced block has a
+*   different id so it can't inherit the orphaned answer.
+* - `contract-constant`: the caller asserts the value cannot change for this
+*   contract and these args (SIP-010 `get-decimals`/`get-symbol`), so it is
+*   resolved ONCE instead of once per block. This is the mode that makes a
+*   backfill affordable — under `per-block` every block is a distinct key and
+*   therefore a distinct RPC. Declaring it on a value that does change pins the
+*   first answer forever, so it is opt-in and never inferred.
+*/
+type ChainReadCacheMode = "per-block" | "contract-constant";
+type ChainReadOptions = {
+	cache?: ChainReadCacheMode
+};
+/**
+* `ChainReadClient` with the ABI generic erased. Structurally cheap, so the
+* base `SubgraphContext` can carry it; `TypedSubgraphContext` uses the real
+* one and handlers get full inference.
+*/
+interface ErasedChainReadClient {
+	contract(contractId: string, abi: unknown, options?: ChainReadOptions): {
+		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>
+	};
+}
+/** Supported column types for subgraph schemas */
+type ColumnType = "text" | "uint" | "int" | "principal" | "boolean" | "timestamp" | "jsonb";
+/** Column definition in a subgraph table */
+interface SubgraphColumn {
+	type: ColumnType;
+	nullable?: boolean;
+	indexed?: boolean;
+	search?: boolean;
+	default?: string | number | boolean;
+}
+/**
+* A foreign-key relation to another table in the same subgraph. Drives DDL FK
+* constraints and ORM codegen (`@relation` in Prisma, `relations()` in Drizzle)
+* so generated clients get typed joins. The referenced columns must form a
+* `uniqueKeys` entry on the target table.
+*/
+interface SubgraphRelation {
+	/** Relation field name on this table's generated model (e.g. "pool"). */
+	name: string;
+	/** Target table name in this subgraph. */
+	references: string;
+	/** Local column(s) holding the foreign key. */
+	fields: string[];
+	/** Target column(s) the fields point at (a uniqueKeys entry on the target). */
+	referencedColumns: string[];
+}
+/**
+* Table definition within a subgraph schema.
+*
+* The array fields are `readonly` so a schema literal can be hoisted out of
+* the `defineSubgraph()` call with `as const` (or {@link defineSchema}) and
+* still typecheck — `as const` produces `readonly [readonly ["holder"]]`,
+* which a mutable `string[][]` rejects. Without that, extracting a helper
+* that takes `ctx` meant losing the entire typed surface, which is why the
+* shipped starter reached for `ctx: any`.
+*/
+interface SubgraphTable {
+	columns: Record<string, SubgraphColumn>;
+	/** Composite indexes (each entry is an array of column names) */
+	indexes?: readonly (readonly string[])[];
+	/** Unique key constraints (each entry is an array of column names). Required for upsert. */
+	uniqueKeys?: readonly (readonly string[])[];
+	/** Foreign-key relations to other tables (for typed ORM joins). */
+	relations?: readonly SubgraphRelation[];
+}
+/** Subgraph schema — maps table names to table definitions */
+type SubgraphSchema = Record<string, SubgraphTable>;
+/** STX event filters */
+interface StxTransferFilter {
+	type: "stx_transfer";
+	sender?: string;
+	recipient?: string;
+	minAmount?: bigint;
+	maxAmount?: bigint;
+}
+interface StxMintFilter {
+	type: "stx_mint";
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface StxBurnFilter {
+	type: "stx_burn";
+	sender?: string;
+	minAmount?: bigint;
+}
+interface StxLockFilter {
+	type: "stx_lock";
+	lockedAddress?: string;
+	minAmount?: bigint;
+}
+/**
+* Restrict a source to contracts conforming to a trait/standard (e.g. "sip-010")
+* instead of a fixed contract — resolved from the contract registry at match time,
+* as-of each processed block. Lets a source index "all SIP-010 tokens" etc.
+*/
+type TraitScope = {
+	trait?: string
+};
+/**
+* Scope a source to a DYNAMIC address set discovered from another source's
+* events, instead of a fixed contract list.
+*
+* The standard shape it unlocks: a router plus pools created after you
+* deploy. `contractId` arrays cover a set you know at authoring time; a
+* factory covers the set that grows. It is deliberately NOT tied to contract
+* deployment — the address can come from any field of any event, so it also
+* covers launchpad-minted tokens, DAO extension allowlists, and registry
+* entries.
+*
+* ```ts
+* sources: {
+*   registry: { type: "print_event", contractId: REGISTRY, topic: "pool-created" },
+*   swaps: {
+*     type: "print_event",
+*     topic: "swap",
+*     // every pool the registry has ever announced, including new ones
+*     factory: { from: "registry", field: "data.pool" },
+*   },
+* }
+* ```
+*
+* Two guarantees the runtime provides:
+* - **Same-block ordering** — a contract discovered in block N receives its
+*   own block-N events. Discovery runs before matching, within the block.
+* - **Reorg-scoped** — the discovered set is stamped with the block that
+*   revealed it and rolled back with everything else on a fork, so an address
+*   announced on an orphaned chain does not linger forever.
+*/
+interface 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"`, `"contractId"`, `"data.token.id"`). */
+		field: string
+	};
+}
+/** FT event filters */
+interface FtTransferFilter extends TraitScope {
+	type: "ft_transfer";
+	assetIdentifier?: string;
+	sender?: string;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtMintFilter extends TraitScope {
+	type: "ft_mint";
+	assetIdentifier?: string;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtBurnFilter extends TraitScope {
+	type: "ft_burn";
+	assetIdentifier?: string;
+	sender?: string;
+	minAmount?: bigint;
+}
+/** NFT event filters */
+interface NftTransferFilter extends TraitScope {
+	type: "nft_transfer";
+	assetIdentifier?: string;
+	sender?: string;
+	recipient?: string;
+}
+interface NftMintFilter extends TraitScope {
+	type: "nft_mint";
+	assetIdentifier?: string;
+	recipient?: string;
+}
+interface NftBurnFilter extends TraitScope {
+	type: "nft_burn";
+	assetIdentifier?: string;
+	sender?: string;
+}
+/**
+* Event shape passed to contract_call handlers.
+*
+* `args` is a **positional array** of decoded Clarity values matching the
+* contract function's parameter list in declaration order. Use the ABI
+* (or Clarity contract source) to map positions to names:
+*
+* ```ts
+* // pox-4 stack-stx args: (amount-ustx uint) (pox-addr tuple) (start-burn-ht uint) (lock-period uint)
+* const [amountUstx, , , lockPeriod] = event.args;
+* ```
+*
+* Bigints come out as `bigint`. Buffers as `Uint8Array`. Principals as
+* strings (`"SP..."`). Tuples as `Record<string, unknown>`.
+*
+* Historical transactions indexed before the function_args column was added
+* will have `args = []` — always guard with `args.length > 0` when reading
+* args from pre-Nakamoto history.
+*/
+interface ContractCallEvent {
+	type: "contract_call";
+	/** Transaction sender (the principal who signed the tx). Always non-null. */
+	sender: string;
+	contractId: string;
+	functionName: string;
+	/** Positional decoded Clarity values — order matches the ABI parameter list. */
+	args: unknown[];
+	/** Decoded return value from the contract function, or null. */
+	result: unknown;
+	/** Raw hex-encoded result value. */
+	resultHex: string | null;
+	/** Transaction metadata. */
+	tx: {
+		txId: string
+		sender: string
+		type: string
+		status: string
+		contractId: string | null
+		functionName: string | null
+	};
+}
+/** Contract event filters */
+interface ContractCallFilter extends TraitScope, FactoryScope {
+	type: "contract_call";
+	/**
+	* One contract id, or a SET of them (max 20) — the standard DeFi shape is
+	* a router plus N pools, which used to cost N near-identical sources and
+	* handlers, or the `"*"` catch-all that erases per-source typing. Payload
+	* types are identical per `type`, so one handler serves the set and
+	* `event.contractId` disambiguates.
+	*
+	* Supports `*` wildcards (e.g. `"SP1ABC….pool-*"`). Mutually exclusive
+	* with `trait`, which resolves its own set per block.
+	*/
+	contractId?: string | readonly string[];
+	functionName?: string;
+	caller?: string;
+	/**
+	* Contract ABI (pass it `as const`) used to type `event.input` — the named,
+	* decoded function arguments. Dev-provided; serialized into the deployed
+	* definition and used at runtime to decode args by name. Omit to keep
+	* `event.args` as a positional `unknown[]`.
+	*/
+	abi?: AbiContract2;
+}
+interface ContractDeployFilter {
+	type: "contract_deploy";
+	deployer?: string;
+	contractName?: string;
+}
+/**
+* One declared field of a print payload.
+*
+* A bare {@link ColumnType} is a required scalar (`amount: "uint"`). The
+* composite forms exist because real print payloads are not flat: BNS-V2
+* emits `name` as a NESTED tuple, and a `prints` vocabulary that could only
+* say `"jsonb"` is why a handler reading flat `data.name` type-checked,
+* deployed, and then decoded to null on every event.
+*
+* - `{ type: F, optional: true }` — the KEY becomes optional on `event.data`
+*   (mirrors `always_present: false` in the inferred schema).
+* - `{ tuple: { … } }` — a nested tuple, typed all the way down.
+* - `{ list: F }` — a list of `F`.
+*/
+type PrintField = ColumnType | {
+	type: PrintField
+	optional: true
+} | {
+	tuple: Record<string, PrintField>
+} | {
+	list: PrintField
+};
+interface PrintEventFilter extends TraitScope, FactoryScope {
+	type: "print_event";
+	/** One contract id, or a set of them (max 20). Supports `*` wildcards.
+	*  Mutually exclusive with `trait`. */
+	contractId?: string | readonly string[];
+	topic?: string;
+	/**
+	* Per-topic field schema. When declared, the handler's `event` is a
+	* discriminated union keyed by `topic` and `event.data` is typed per topic
+	* (e.g. `{ "completed-deposit": { amount: "uint", sender: "principal" } }`).
+	* Nested tuples, lists, and optional fields are expressible — see
+	* {@link PrintField}.
+	*
+	* Declaring `prints` also opts the source into RUNTIME validation: an
+	* event whose decoded payload does not match is skipped and logged rather
+	* than written as nulls (and the deploy-time field lint is promoted from
+	* a warning to an error).
+	*/
+	prints?: Record<string, Record<string, PrintField>>;
+}
+/** All subgraph filter types — discriminated on `type` */
+type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter;
+/** Transaction metadata available in handlers */
+interface TxMeta {
+	txId: string;
+	sender: string;
+	type: string;
+	status: string;
+	contractId?: string | null;
+	functionName?: string | null;
+}
+/** Scalar types that can appear as row values */
+type RowValue = string | number | bigint | boolean | null | undefined | Record<string, unknown> | unknown[];
+/** Value or computed function that receives existing row */
+type ComputedValue = RowValue | ((existing: Record<string, unknown> | null) => unknown);
+interface BlockMeta {
+	height: number;
+	hash: string;
+	timestamp: number;
+	burnBlockHeight: number;
+	/**
+	* Nakamoto StacksBlockId — the identifier `?tip=` accepts, and the only way
+	* to pin a read-only call to THIS block. Null on rows ingested before it
+	* was persisted; `ctx.client.readOnly` refuses to run rather than silently
+	* reading at the node's tip.
+	*/
+	indexBlockHash?: string | null;
+}
+interface TxMeta2 {
+	txId: string;
+	sender: string;
+	type: string;
+	status: string;
+	contractId?: string | null;
+	functionName?: string | null;
+}
+interface MatchedTx {
+	tx: TxRecord;
+	events: EventRecord[];
+	/** Source object key — used for handler dispatch */
+	sourceName: string;
+}
+type TxRecord = {
+	tx_id: string
+	type: string
+	sender: string
+	status: string
+	/** Position within the block — the runner sorts dispatch into chain order. */
+	tx_index?: number
+	contract_id?: string | null
+	function_name?: string | null
+	function_args?: unknown | null
+	raw_result?: string | null
+};
+type EventRecord = {
+	id: string
+	tx_id: string
+	type: string
+	event_index: number
+	data: unknown
+};
+/**
+* Build a typed event payload based on the source filter type.
+* Returns the payload the handler will receive.
+*/
+declare function buildEventPayload(filter: SubgraphFilter, tx: MatchedTx["tx"], event: MatchedTx["events"][0] | null): Record<string, unknown>;
+import { AbiContract as AbiContract3, ExtractFunctionArgs as ExtractFunctionArgs2, ExtractFunctionNames } from "@secondlayer/stacks/clarity";
+/** Maps a ColumnType string literal to its TypeScript equivalent */
+type ColumnToTS<T extends string> = T extends "uint" | "int" ? bigint : T extends "text" | "principal" | "timestamp" ? string : T extends "boolean" ? boolean : T extends "jsonb" ? Record<string, unknown> : unknown;
+/** Infer TS type for a single column definition, respecting nullable */
+type InferColumnType<C extends SubgraphColumn> = C["type"] extends ColumnType ? C["nullable"] extends true ? ColumnToTS<C["type"]> | null : ColumnToTS<C["type"]> : unknown;
+/** Shape of system columns on every returned row (camelCase, underscore-prefixed) */
+interface SystemRow {
+	_id: string;
+	_blockHeight: bigint;
+	_txId: string;
+	_createdAt: string;
+}
+/** Infer the row shape for a single table definition */
+type InferTableRow<T extends SubgraphTable> = SystemRow & { [K in keyof T["columns"]] : InferColumnType<T["columns"][K]> };
+/** Comparison operators for a scalar value */
+type ComparisonFilter<T> = {
+	eq?: T
+	neq?: T
+	gt?: T
+	gte?: T
+	lt?: T
+	lte?: T
+	/** Match any value in the set. */
+	in?: T[]
+	/** Match none of the values in the set. */
+	notIn?: T[]
+	/** SQL ILIKE pattern (case-insensitive); `%`/`_` wildcards. Strings only. */
+	like?: string
+};
+/** Where clause — each column accepts a scalar (eq) or comparison object */
+type WhereInput<TRow> = { [K in keyof TRow]? : TRow[K] | ComparisonFilter<TRow[K]> };
+/** A column is optional on insert when it's nullable or has a SQL default. */
+type IsOptionalColumn<C> = C extends {
+	nullable: true
+} ? true : C extends {
+	default: string | number | boolean
+} ? true : false;
+/**
+* Like `InferColumnType` but for WRITE inputs: numeric (`uint`/`int`) columns
+* also accept a plain `number` (the runtime coerces to bigint). Reads stay
+* strict `bigint` via `InferColumnType`, so handlers still get exact types back.
+*/
+type WriteColumnType<C extends SubgraphColumn> = C["type"] extends "uint" | "int" ? C["nullable"] extends true ? bigint | number | null : bigint | number : InferColumnType<C>;
+/**
+* Row shape accepted by `ctx.insert`. System columns (`_id`, `_blockHeight`,
+* `_txId`, `_createdAt`) are omitted — the runtime adds them. Nullable and
+* defaulted columns are optional; all others required.
+*/
+type WriteRow<T extends SubgraphTable> = { [K in keyof T["columns"] as IsOptionalColumn<T["columns"][K]> extends true ? never : K] : WriteColumnType<T["columns"][K]> } & { [K in keyof T["columns"] as IsOptionalColumn<T["columns"][K]> extends true ? K : never]? : WriteColumnType<T["columns"][K]> };
+/** Computed-or-value row for `patchOrInsert` — each field may be a function of the existing row. */
+type PatchRow<T extends SubgraphTable> = { [K in keyof WriteRow<T>]? : WriteRow<T>[K] | ((existing: InferTableRow<T> | null) => unknown) };
+type TableName<S extends SubgraphSchema> = keyof S & string;
+type ColumnName<
+	S extends SubgraphSchema,
+	T extends TableName<S>
+> = keyof S[T]["columns"] & string;
+type RowWhere<
+	S extends SubgraphSchema,
+	T extends TableName<S>
+> = WhereInput<InferTableRow<S[T]>>;
+/**
+* Schema-typed handler context. Mirrors the runtime `SubgraphContext` but
+* checks table names against `S` and row/where shapes against each table's
+* columns. The runtime passes the concrete (untyped) context — this facade is
+* type-level only.
+*/
+interface TypedSubgraphContext<S extends SubgraphSchema> {
+	block: {
+		height: number
+		hash: string
+		timestamp: number
+		burnBlockHeight: number
+		/** Nakamoto StacksBlockId, when the block row carries one. */
+		indexBlockHash?: string | null
+	};
+	tx: TxMeta;
+	/**
+	* Read-only contract calls pinned to this block. Erased here for the same
+	* reason as on `SubgraphContext`: an ABI-generic method on a structurally
+	* compared interface exceeds TS's instantiation budget. Wrap it with
+	* `readContractAt(ctx, id, abi)` for full ABI typing at the call site.
+	*/
+	client: ErasedChainReadClient;
+	insert<T extends TableName<S>>(table: T, row: WriteRow<S[T]>): void;
+	update<T extends TableName<S>>(table: T, where: RowWhere<S, T>, set: Partial<WriteRow<S[T]>>): void;
+	upsert<
+		T extends TableName<S>,
+		K extends Partial<WriteRow<S[T]>>
+	>(table: T, key: K, row: Omit<WriteRow<S[T]>, keyof K> & Partial<WriteRow<S[T]>>): void;
+	delete<T extends TableName<S>>(table: T, where: RowWhere<S, T>): void;
+	patch<T extends TableName<S>>(table: T, where: RowWhere<S, T>, set: Partial<WriteRow<S[T]>>): void;
+	patchOrInsert<T extends TableName<S>>(table: T, key: Partial<WriteRow<S[T]>>, row: PatchRow<S[T]> & Record<string, ComputedValue>): Promise<void>;
+	/**
+	* Atomic accumulator — `INSERT … ON CONFLICT (key) DO UPDATE SET col =
+	* COALESCE(col,0) + delta`. Deltas commute, so it's the reorg-safe primitive
+	* for running totals (per-cycle aggregates, balances). Requires a `uniqueKeys`
+	* constraint matching `key`; deltas may be `number` or `bigint`.
+	*/
+	increment<T extends TableName<S>>(table: T, key: Partial<WriteRow<S[T]>>, deltas: Partial<Record<ColumnName<S, T>, bigint | number>>): void;
+	findOne<T extends TableName<S>>(table: T, where: RowWhere<S, T>): Promise<InferTableRow<S[T]> | null>;
+	findMany<T extends TableName<S>>(table: T, where: RowWhere<S, T>): Promise<InferTableRow<S[T]>[]>;
+	formatUnits(value: bigint, decimals: number): string;
+	count<T extends TableName<S>>(table: T, where?: RowWhere<S, T>): Promise<number>;
+	sum<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<bigint>;
+	min<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<bigint | null>;
+	max<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<bigint | null>;
+	countDistinct<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<number>;
+}
+interface FtTransferPayload {
+	sender: string;
+	recipient: string;
+	amount: bigint;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface FtMintPayload {
+	recipient: string;
+	amount: bigint;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface FtBurnPayload {
+	sender: string;
+	amount: bigint;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface NftTransferPayload {
+	sender: string;
+	recipient: string;
+	tokenId: unknown;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface NftMintPayload {
+	recipient: string;
+	tokenId: unknown;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface NftBurnPayload {
+	sender: string;
+	tokenId: unknown;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface StxTransferPayload {
+	sender: string;
+	recipient: string;
+	amount: bigint;
+	/** Memo string, or "" when none was attached. */
+	memo: string;
+	tx: TxMeta;
+}
+interface StxMintPayload {
+	recipient: string;
+	amount: bigint;
+	tx: TxMeta;
+}
+interface StxBurnPayload {
+	sender: string;
+	amount: bigint;
+	tx: TxMeta;
+}
+interface StxLockPayload {
+	lockedAddress: string;
+	lockedAmount: bigint;
+	unlockHeight: bigint;
+	tx: TxMeta;
+}
+interface PrintEventPayload {
+	contractId: string;
+	/** Decoded print topic (the Clarity tuple's `topic` field), or "". */
+	topic: string;
+	/**
+	* Remaining decoded tuple fields, camelCased. Empty object when the print
+	* value isn't a tuple. Narrow per `topic` to access typed fields.
+	*/
+	data: Record<string, unknown>;
+	tx: TxMeta;
+}
+interface ContractDeployPayload {
+	contractId: string;
+	deployer: string;
+	tx: TxMeta;
+}
+/**
+* Contract-call payload. When the source carries a `const` `abi` and a known
+* `functionName`, `event.input` is the named, typed, decoded arguments
+* (camelCased, via the contract ABI). The positional `event.args` is always
+* present for back-compat. Without an `abi`, the payload is {@link ContractCallEvent}.
+*/
+type ContractCallPayload<F> = F extends {
+	abi: infer A extends AbiContract3
+	functionName: infer N extends string
+} ? N extends ExtractFunctionNames<A> ? ContractCallEvent & {
+	input: ExtractFunctionArgs2<A, N>
+} : ContractCallEvent : ContractCallEvent;
+/**
+* Print event typed per topic. When a `print_event` source declares a `prints`
+* map, the payload is a discriminated union keyed by `topic` with `data` typed
+* per topic; otherwise it falls back to the untyped {@link PrintEventPayload}.
+*/
+type PrintEventFor<F> = F extends {
+	prints: infer P extends Record<string, Record<string, PrintField>>
+} ? { [K in keyof P] : {
+	contractId: string
+	topic: K
+	data: PrintDataOf<P[K]>
+	tx: TxMeta
+} }[keyof P] : PrintEventPayload;
+/** TS type of one declared print field (nested tuples and lists included). */
+type PrintFieldToTS<F> = F extends ColumnType ? ColumnToTS<F> : F extends {
+	type: infer Inner
+	optional: true
+} ? PrintFieldToTS<Inner> : F extends {
+	tuple: infer T extends Record<string, PrintField>
+} ? PrintDataOf<T> : F extends {
+	list: infer Item
+} ? PrintFieldToTS<Item>[] : unknown;
+type OptionalFieldKeys<T> = { [K in keyof T] : T[K] extends {
+	optional: true
+} ? K : never }[keyof T];
+/** Collapse an intersection into one object literal, so hovering `event.data`
+*  shows the fields rather than `A & B`. */
+type Flatten<T> = { [K in keyof T] : T[K] } & {};
+/**
+* `event.data` for one topic: declared fields typed, with
+* `{ optional: true }` fields made optional KEYS (a field observed on only
+* some events must not be typed as always present).
+*/
+type PrintDataOf<T extends Record<string, PrintField>> = Flatten<{ [K in Exclude<keyof T, OptionalFieldKeys<T>>] : PrintFieldToTS<T[K]> } & { [K in OptionalFieldKeys<T>]? : PrintFieldToTS<T[K]> }>;
+/** The event payload a handler receives for a given source filter. */
+type EventForFilter<F extends SubgraphFilter> = F extends {
+	type: "print_event"
+} ? PrintEventFor<F> : F extends {
+	type: "ft_transfer"
+} ? FtTransferPayload : F extends {
+	type: "ft_mint"
+} ? FtMintPayload : F extends {
+	type: "ft_burn"
+} ? FtBurnPayload : F extends {
+	type: "nft_transfer"
+} ? NftTransferPayload : F extends {
+	type: "nft_mint"
+} ? NftMintPayload : F extends {
+	type: "nft_burn"
+} ? NftBurnPayload : F extends {
+	type: "stx_transfer"
+} ? StxTransferPayload : F extends {
+	type: "stx_mint"
+} ? StxMintPayload : F extends {
+	type: "stx_burn"
+} ? StxBurnPayload : F extends {
+	type: "stx_lock"
+} ? StxLockPayload : F extends {
+	type: "contract_call"
+} ? ContractCallPayload<F> : F extends {
+	type: "contract_deploy"
+} ? ContractDeployPayload : never;
+/** An in-memory subgraph context for tests. */
+interface TestSubgraphContext<S extends SubgraphSchema> extends Omit<TypedSubgraphContext<S>, never> {
+	/**
+	* Current rows of `table`, INCLUDING writes queued by the handler you just
+	* ran (the same read-your-writes overlay the runtime uses). Drop straight
+	* into `toMatchInlineSnapshot()`.
+	*/
+	rows(table: keyof S & string): Promise<Record<string, unknown>[]>;
+	/** Commit pending writes into the in-memory store, as an end-of-block flush
+	*  would — call between blocks when a test spans several. */
+	commit(): Promise<void>;
+	/** Swap the transaction metadata handlers see (`ctx.tx`). */
+	setTx(tx: Partial<TxMeta2>): void;
+}
+/**
+* Build an in-memory context for a subgraph's schema.
+*
+* ```ts
+* const ctx = createTestContext(bns.schema, { block: { height: 167_484 } });
+* await bns.handlers.bns!(buildEvent(bns.sources.bns, { … }), ctx);
+* expect(await ctx.rows("names")).toMatchInlineSnapshot();
+* ```
+*/
+declare function createTestContext<const S extends SubgraphSchema>(schema: S, options?: {
+	block?: Partial<BlockMeta>
+	tx?: Partial<TxMeta2>
+	/** Stubbed `ctx.client.readOnly` results, keyed
+	*  `"<contractId>.<function-name>"`. */
+	reads?: Record<string, unknown>
+}): TestSubgraphContext<S>;
+/**
+* Build a handler-shaped event payload for a source, typed by that source's
+* filter. `data` supplies the decoded, camelCased fields the runtime would
+* have produced; block/tx metadata is filled in.
+*
+* ```ts
+* buildEvent(bns.sources.bns, {
+*   topic: "name-register",
+*   data: { name: { name: "0x616c696365", namespace: "0x627463" } },
+* })
+* ```
+*/
+declare function buildEvent<const F extends SubgraphFilter>(source: F, payload: Record<string, unknown>, options?: {
+	tx?: Partial<TxMeta2>
+}): EventForFilter<F>;
+export { createTestContext, buildEventPayload, buildEvent, TxMeta2 as TxMeta, TestSubgraphContext, BlockMeta };