@secondlayer/subgraphs 4.4.1 → 5.0.0

package/dist/src/runtime/runner.d.ts

@@ -1,719 +0,0 @@
-import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
-import { AssetIdentifier } from "@secondlayer/stacks/filters";
-import { UnwrapResponse } from "@secondlayer/stacks/actions";
-import { AbiContract, ExtractFunctionArgs, ExtractFunctionOutput, ExtractReadOnlyFunctions, ToCamelCase } 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
-};
-/**
-* The chain-read surface, fully typed by an ABI.
-*
-* Shaped like `getContract` from `@secondlayer/stacks` — the same ABI in, the
-* same camelCased read methods out — minus `call`/`buildCall`: a handler
-* indexes the chain, it never writes to it.
-*
-* Reached through {@link readContractAt} rather than off `ctx.client`
-* directly: an ABI-generic method living on the context interface makes every
-* structural comparison of a subgraph definition instantiate it, which exceeds
-* TS's depth budget. At a call site the ABI is already concrete and it costs
-* nothing.
-*/
-interface ChainReadClient {
-	/**
-	* Read-only methods of a contract, evaluated against the exact block being
-	* processed.
-	*
-	* Every call is pinned to the block's `index_block_hash`, so a handler is a
-	* pure function of its block: reindexing a range produces byte-identical
-	* rows. Reading at the node's tip instead would make the same reindex
-	* return different values — that is the corruption this refuses to allow,
-	* so a block whose id was never persisted throws rather than falling back.
-	*
-	* Results are memoized in Postgres, so a value is fetched once per block
-	* rather than once per event (or once per contract with
-	* `cache: "contract-constant"`).
-	*/
-	contract<const C extends AbiContract>(contractId: string, abi: C, options?: ChainReadOptions): {
-		read: ChainReadMethods<C>
-	};
-}
-/**
-* True for a structural empty mapped type (`{}`) and for codegen's
-* `Record<string, never>`. `keyof Record<string, never>` is `string`, so the
-* first check alone is not enough. Local copy of the `getContract` helper —
-* importing `ContractInstance<C>["read"]` would re-enter the codegen-brand
-* conditional this type exists to avoid.
-*/
-type IsEmptyArgs<A> = [keyof A & string] extends [never] ? true : Record<string, never> extends A ? true : false;
-type ChainReadMethod<
-	A,
-	R
-> = IsEmptyArgs<A> extends true ? (args?: A) => R : (args: A) => R;
-/**
-* The camelCased read methods of an ABI. Spelled out rather than reused from
-* `ContractInstance<C>["read"]`: that type is a conditional over the codegen
-* brand, and evaluating it wherever a subgraph definition is structurally
-* compared pushes TS past its instantiation depth.
-*/
-type ChainReadMethods<C extends AbiContract> = { [N in ExtractReadOnlyFunctions<C> as ToCamelCase<N>] : ChainReadMethod<ExtractFunctionArgs<C, N>, Promise<UnwrapResponse<ExtractFunctionOutput<C, N>>>> };
-/**
-* `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",
-*     prints: { "pool-created": { pool: "principal" } },
-*   },
-*   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?: AssetIdentifier;
-	sender?: string;
-	recipient?: string;
-	minAmount?: bigint;
-}
-interface FtMintFilter extends TraitScope {
-	type: "ft_mint";
-	assetIdentifier?: AssetIdentifier;
-	recipient?: string;
-	minAmount?: bigint;
-}
-interface FtBurnFilter extends TraitScope {
-	type: "ft_burn";
-	assetIdentifier?: AssetIdentifier;
-	sender?: string;
-	minAmount?: bigint;
-}
-/** NFT event filters */
-interface NftTransferFilter extends TraitScope {
-	type: "nft_transfer";
-	assetIdentifier?: AssetIdentifier;
-	sender?: string;
-	recipient?: string;
-}
-interface NftMintFilter extends TraitScope {
-	type: "nft_mint";
-	assetIdentifier?: AssetIdentifier;
-	recipient?: string;
-}
-interface NftBurnFilter extends TraitScope {
-	type: "nft_burn";
-	assetIdentifier?: AssetIdentifier;
-	sender?: string;
-}
-/** 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[]`.
-	*
-	* Deploy validation requires `abi` whenever `functionName` is set
-	* (`normalizeAbi()` from `@secondlayer/stacks/clarity`).
-	*/
-	abi?: AbiContract2;
-}
-interface ContractDeployFilter {
-	type: "contract_deploy";
-	deployer?: string;
-	contractName?: string;
-}
-interface NestedContractCallFilter extends TraitScope, FactoryScope {
-	type: "nested_contract_call";
-	contractId?: string | readonly string[];
-	functionName?: string;
-	caller?: string;
-	sender?: string;
-}
-interface VarSetFilter extends TraitScope, FactoryScope {
-	type: "var_set";
-	contractId?: string | readonly string[];
-	varName?: string;
-}
-interface MapWriteFilter extends TraitScope, FactoryScope {
-	type: "map_set" | "map_insert" | "map_delete";
-	contractId?: string | readonly string[];
-	map?: 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
-};
-/**
-* Per-topic field schema for a print_event source. When declared, the handler's
-* `event` is a discriminated union keyed by `topic` and `event.data` is typed
-* per topic. Nested tuples, lists, and optional fields — see {@link PrintField}.
-*
-* Also opts the source into RUNTIME validation: a payload that does not match
-* is skipped and logged rather than written as nulls.
-*/
-type PrintEventPrints = Record<string, Record<string, PrintField>>;
-/**
-* One column in a static identity map. Literals only — the bundler never
-* executes user code, so `{ from: "tokenX" }` is valid and `from("tokenX")`
-* is not.
-*/
-type MaterializeColumn = {
-	from: string
-} | {
-	fromTx: "sender" | "txId"
-} | {
-	fromBlock: "height" | "hash" | "timestamp"
-};
-/** Static insert from a source event — replaces a 1:1 handler. */
-interface MaterializeSpec {
-	table: string;
-	/** Keys = schema column names (snake). */
-	columns: Record<string, MaterializeColumn>;
-}
-type PrintEventFields = FactoryScope & {
-	type: "print_event"
-	topic?: string
-	/** Identity map: insert without a handler function. XOR with handlers[name]. */
-	materialize?: MaterializeSpec
-};
-/**
-* Pinned to one or more contract ids with no trait — `prints` is required so
-* `event.data` is typed and empty-table handlers cannot typecheck.
-*/
-type PinnedPrintEventFilter = PrintEventFields & {
-	contractId: string | readonly string[]
-	trait?: undefined
-	prints: PrintEventPrints
-};
-/**
-* Trait-scoped print source (optionally narrowed by contractId). No single
-* schema — `prints` stays optional.
-*/
-type TraitPrintEventFilter = PrintEventFields & {
-	contractId?: string | readonly string[]
-	trait: string
-	prints?: PrintEventPrints
-};
-/**
-* Unpinned / factory-only print source (no contractId). `prints` optional.
-*/
-type UnpinnedPrintEventFilter = PrintEventFields & {
-	contractId?: undefined
-	trait?: string
-	prints?: PrintEventPrints
-};
-/**
-* Print-event filter. Pinned sources (contractId set, no trait) require
-* `prints`; trait and unpinned sources may omit it.
-*/
-type PrintEventFilter = PinnedPrintEventFilter | TraitPrintEventFilter | UnpinnedPrintEventFilter;
-/** All subgraph filter types — discriminated on `type` */
-type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter | NestedContractCallFilter | VarSetFilter | MapWriteFilter;
-/** 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);
-/** Context passed to subgraph handlers during event processing */
-interface SubgraphContext {
-	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. Cached, so the same
-	* (contract, function, args) is fetched once per block rather than once
-	* per event.
-	*
-	* Erased here on purpose: this interface is compared structurally wherever
-	* a subgraph definition is passed around, and carrying an ABI-generic
-	* method pushes those comparisons past TS's instantiation depth. Handlers
-	* receive `TypedSubgraphContext`, which exposes the fully typed version.
-	*/
-	client: ErasedChainReadClient;
-	insert(table: string, row: Record<string, unknown>): void;
-	update(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
-	upsert(table: string, key: Record<string, unknown>, row: Record<string, unknown>): void;
-	delete(table: string, where: Record<string, unknown>): void;
-	/**
-	* Atomic counter update — the blessed accumulator primitive. Applies
-	* `col = COALESCE(col, 0) + delta` per column (insert-or-add); deltas may
-	* be negative. Requires a uniqueKeys constraint matching `key`. Prefer
-	* this over patchOrInsert with functional updaters for running totals.
-	*/
-	increment(table: string, key: Record<string, unknown>, deltas: Record<string, bigint | number>): void;
-	/** Partial update — sets only specified fields, preserves others */
-	patch(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
-	/** Find-then-merge-or-insert. Values can be functions: (existing) => newValue */
-	patchOrInsert(table: string, key: Record<string, unknown>, row: Record<string, ComputedValue>): Promise<void>;
-	findOne(table: string, where: Record<string, unknown>): Promise<Record<string, unknown> | null>;
-	findMany(table: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
-	/** Format a bigint amount with decimal places */
-	formatUnits(value: bigint, decimals: number): string;
-	/** Count rows matching filter */
-	count(table: string, where?: Record<string, unknown>): Promise<number>;
-	/** Sum a numeric column */
-	sum(table: string, column: string, where?: Record<string, unknown>): Promise<bigint>;
-	/** Min of a numeric column */
-	min(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;
-	/** Max of a numeric column */
-	max(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;
-	/** Count distinct values in a column */
-	countDistinct(table: string, column: string, where?: Record<string, unknown>): Promise<number>;
-}
-/** Handler function that processes events and writes to the subgraph */
-type SubgraphHandler = (event: Record<string, unknown>, ctx: SubgraphContext) => Promise<void> | void;
-/** Complete subgraph definition */
-interface SubgraphDefinition {
-	/** Unique subgraph name (lowercase, alphanumeric + hyphens) */
-	name: string;
-	/** Semantic version */
-	version?: string;
-	/** Human description */
-	description?: string;
-	/** Block height to start indexing from (default: 1) */
-	startBlock?: number;
-	/** 'concurrent' = tip-first: live at tip now, history backfills behind.
-	*  Requires order-tolerant handlers. Default 'blocking'. */
-	backfillMode?: "blocking" | "concurrent";
-	/** Named source filters — keys become handler keys */
-	sources: Record<string, SubgraphFilter>;
-	/** Tables in this subgraph */
-	schema: SubgraphSchema;
-	/** Handler functions — keys must match source names (or "*" for catch-all) */
-	handlers: Record<string, SubgraphHandler>;
-}
-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
-	/** Classic `event_index`, or `ordinal` when `clock === "vm"`. */
-	event_index: number
-	data: unknown
-	/** Set on opt-in `vm_events` rows. Two clocks never sort or dedupe together. */
-	clock?: "vm"
-};
-import { Database as Database2 } from "@secondlayer/shared/db";
-import { Kysely as Kysely2, Transaction } from "kysely";
-type AnyDb = Kysely2<Database2> | Transaction<Database2>;
-interface WriteOp {
-	kind: "insert" | "update" | "delete" | "increment";
-	table: string;
-	data: Record<string, unknown>;
-	/** For update: SET clause. For increment: column → signed delta. */
-	set?: Record<string, unknown>;
-}
-interface FlushWrite {
-	op: "insert" | "update" | "delete";
-	table: string;
-	/** Full row data (for inserts) or where+set merged (for updates). Bigints stringified. */
-	row: Record<string, unknown>;
-	/** Stable identifier for dedup — `{blockHeight, txId, rowIndex}` */
-	pk: {
-		blockHeight: number
-		txId: string
-		rowIndex: number
-	};
-}
-interface FlushManifest {
-	count: number;
-	writes: FlushWrite[];
-}
-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;
-}
-/**
-* Runtime context passed to subgraph handlers.
-* Batches writes and flushes them atomically at the end of a block.
-*
-* Row reads (findOne/findMany) are read-your-writes: they overlay the pending
-* ops queue on the DB state, so a handler observes every write queued earlier
-* in the same block. Without this, accumulator patterns (balance = f(existing))
-* silently lose all but the last same-block delta per row (fix-f040 B1).
-* Aggregate reads (count/sum/min/max) remain pre-flush DB state.
-*/
-declare class SubgraphContext2 {
-	readonly block: BlockMeta;
-	private _tx;
-	private readonly db;
-	private readonly pgSchemaName;
-	private readonly subgraphSchema;
-	/** Pending writes for this block. `protected` so the in-memory test
-	*  context (`@secondlayer/subgraphs/testing`) can materialize them through
-	*  the SAME overlay this class uses — never a second implementation. */
-	protected readonly ops: WriteOp[];
-	/**
-	* Record pre-images of keyed mutations into the schema's `_journal` so a
-	* reorg can restore prior row states (fix-f040 B2). Enabled on the live
-	* path only — deep reindex/backfill heights are past finality, and the
-	* journal would just be churn the pruner deletes.
-	*/
-	private readonly journal;
-	/** Memoized per block; see the `client` getter. */
-	protected _client?: ChainReadClient;
-	constructor(db: AnyDb, pgSchemaName: string, subgraphSchema: SubgraphSchema, block: BlockMeta, tx: TxMeta2, journal?: boolean);
-	/**
-	* Chain reads pinned to THIS block. Lazily built so a handler that never
-	* reads never touches the node config, and so the in-memory test context
-	* can override it without a node.
-	*/
-	get client(): ChainReadClient;
-	get tx(): TxMeta2;
-	/** Update the current transaction context (used by runner between events) */
-	setTx(tx: TxMeta2): void;
-	insert(table: string, row: Record<string, unknown>): void;
-	update(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
-	upsert(table: string, key: Record<string, unknown>, row: Record<string, unknown>): void;
-	delete(table: string, where: Record<string, unknown>): void;
-	/**
-	* Atomic counter update — the blessed accumulator primitive. Compiles to
-	* `INSERT ... ON CONFLICT (key) DO UPDATE SET col = COALESCE(t.col,0) + delta`,
-	* so deltas commute: same-block, replayed-in-order, and concurrent updates
-	* all land correctly without read-modify-write. Missing row inserts the
-	* delta as the initial value. Requires a uniqueKeys constraint matching
-	* `key`; deltas may be negative.
-	*/
-	increment(table: string, key: Record<string, unknown>, deltas: Record<string, bigint | number>): void;
-	/** Current length of the pending-ops queue. Pair with {@link rollbackTo}. */
-	opsCheckpoint(): number;
-	/**
-	* Discard ops queued after a checkpoint. The runner wraps each handler
-	* invocation so a thrown handler contributes nothing — without this, a
-	* transfer handler that debited then threw flushes a one-sided debit
-	* (fix-f040 B6).
-	*/
-	rollbackTo(checkpoint: number): void;
-	/** Partial update — sets only specified fields, preserves everything else */
-	patch(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
-	/**
-	* Find-then-merge-or-insert. Values can be functions: (existing) => newValue.
-	* Async because it reads existing row first.
-	*/
-	patchOrInsert(table: string, key: Record<string, unknown>, row: Record<string, ComputedValue>): Promise<void>;
-	/** Format a bigint amount with decimal places */
-	formatUnits(value: bigint, decimals: number): string;
-	/**
-	* Committed rows matching `where`, BEFORE the pending-ops overlay. The one
-	* seam a different backing store replaces (the in-memory test context);
-	* everything above it — validation, overlay, op queueing, flush semantics
-	* — stays here so the two can't diverge.
-	*/
-	protected readRows(table: string, where: Record<string, unknown>, limit?: number): Promise<Record<string, unknown>[]>;
-	findOne(table: string, where: Record<string, unknown>): Promise<Record<string, unknown> | null>;
-	findMany(table: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
-	/**
-	* Replay pending ops for `table` over a single DB-read result so reads
-	* observe earlier same-block writes. Mirrors flush semantics: upserts
-	* merge non-key/non-meta columns, increments add deltas, updates/deletes
-	* apply by where-match. Overlaid rows synthesized from pending inserts
-	* lack DB-generated columns (_id, _created_at).
-	*/
-	protected overlayOne(table: string, where: Record<string, unknown>, dbRow: Record<string, unknown> | null): Record<string, unknown> | null;
-	protected overlayMany(table: string, where: Record<string, unknown>, dbRows: Record<string, unknown>[]): Record<string, unknown>[];
-	/** Apply one pending op to a candidate row state (null = row absent). */
-	protected applyOpToRow(op: WriteOp, row: Record<string, unknown> | null, where: Record<string, unknown>): Record<string, unknown> | null;
-	count(table: string, where?: Record<string, unknown>): Promise<number>;
-	sum(table: string, column: string, where?: Record<string, unknown>): Promise<bigint>;
-	min(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;
-	max(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;
-	countDistinct(table: string, column: string, where?: Record<string, unknown>): Promise<number>;
-	/** Coerce string values from Postgres back to BigInt for uint/int columns */
-	private coerceRow;
-	/** Number of pending write operations */
-	get pendingOps(): number;
-	/**
-	* Execute all batched writes in a single transaction.
-	* Auto-populates _block_height, _tx_id, _created_at on inserts.
-	*
-	* Returns a {@link FlushManifest} describing every write so downstream
-	* consumers (webhook emitter) can fan out outbox rows atomically
-	* with the flush itself.
-	*/
-	flush(): Promise<FlushManifest>;
-	/**
-	* Run a built statement list on an open transaction.
-	*
-	* Plain statements run in order. An increment runs UPDATE-first and then,
-	* ONLY if that matched nothing, the guarded INSERT — and if the INSERT also
-	* wrote nothing, the UPDATE again.
-	*
-	* That last step is the whole point. Under READ COMMITTED, two block
-	* transactions flushing the same key while the row is absent both see
-	* `UPDATE → 0 rows`; the first commits its INSERT, and the second's
-	* `WHERE NOT EXISTS` then sees that committed row and inserts nothing. No
-	* error, no constraint violation — the second delta was simply dropped.
-	* Re-running the UPDATE takes a fresh snapshot that DOES see the winner's
-	* row and applies the delta onto it.
-	*
-	* It cannot double-apply: the retry is reached only when the first UPDATE
-	* matched no row AND the INSERT wrote no row, so the delta has not been
-	* applied by either.
-	*/
-	private execStatements;
-	/** Prepare a single insert row, returning its data, columns, upsert key for batching. */
-	private prepareInsert;
-	/**
-	* Lazily create `_journal` for schemas deployed before it existed. Cached
-	* per process only once CONFIRMED present (to_regclass) — a CREATE issued
-	* inside a block tx could roll back with it, so self-created tables are
-	* re-verified on the next flush instead of trusted.
-	*/
-	private ensureJournalTable;
-	/** SQL type of a user column (for casting journal key VALUES), if known. */
-	private columnSqlType;
-	/**
-	* Journal pre-images for a keyed batch: one `_journal` row per key with the
-	* row's current state (`prev_row`), or NULL when the key doesn't exist yet
-	* (the mutation will create it — a revert deletes it). Emitted BEFORE the
-	* mutation statement, same transaction.
-	*/
-	private journalCaptureSQL;
-	/** Journal pre-images of rows a where-clause mutation will touch, keyed by `_id`. */
-	private journalCaptureByWhereSQL;
-	/** Build SQL statements from write ops, batching compatible INSERTs. */
-	private buildStatements;
-	private validateTable;
-}
-interface RunResult {
-	processed: number;
-	errors: number;
-	/** Print events skipped because their decoded payload did not match the
-	*  source's declared `prints` schema. Never an error: skipping keeps the
-	*  block committable, which the checkpoint model requires. */
-	skipped?: number;
-}
-/**
-* Build the named, ABI-decoded `event.input` for a contract_call source that
-* declares an `abi`. Each function arg is decoded via `clarityValueToJS` so the
-* values match the types `ExtractFunctionArgs` promises (Uint8Array buffers,
-* camelCase tuple keys, wrapped responses). Returns undefined when no abi /
-* function match, leaving handlers with the positional `args` only.
-*/
-declare function buildContractCallInput(filter: ContractCallFilter, tx: MatchedTx["tx"]): Record<string, unknown> | undefined;
-/**
-* 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>;
-/**\\n* Run a subgraph's keyed handlers against all matched transactions/events.\\n*\\n* Each MatchedTx carries a sourceName from the matcher. The runner looks up\\n* the corresponding handler in subgraph.handlers, falling back to "*".\\n*\\n* Does NOT flush — caller is responsible for flushing ctx after run.\\n*/
-declare function runHandlers(subgraph: SubgraphDefinition, matched: MatchedTx[], ctx: SubgraphContext2, opts?: {
-	errorThreshold?: number
-}): Promise<RunResult>;
-export { runHandlers, buildEventPayload, buildContractCallInput, RunResult };