@secondlayer/subgraphs 6.3.6 → 6.5.0

package/dist/verify/index.d.ts

@@ -0,0 +1,475 @@
+import { BlockVerification, ProofSource, VerifyCheckpoint } from "@secondlayer/verify";
+import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
+import { AssetIdentifier } from "@secondlayer/stacks/filters";
+/**
+* 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;
+}
+/**
+* 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[])[];
+}
+/** 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. 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[]`.
+	*
+	* Required whenever `functionName` is set. `secondlayer subgraphs deploy`
+	* fills it in from the deployed contract for a single concrete
+	* `contractId`; pass it yourself for wildcard, multi-contract or trait
+	* sources, or a local deploy (`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>>;
+type PrintEventFields = FactoryScope & {
+	type: "print_event";
+	topic?: string;
+};
+/**
+* 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;
+}
+/** 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 read-modify-write handlers for running totals.
+	*/
+	increment(table: string, key: Record<string, unknown>, deltas: Record<string, bigint | number>): void;
+	findOne(table: string, where: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+	findMany(table: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+}
+/** 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;
+	/** 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, one per source, keyed by source name */
+	handlers: Record<string, SubgraphHandler>;
+}
+type ReplayStep = "pin" | "blocks" | "txs" | "inputs" | "handlers" | "rows";
+interface ReplayFailure {
+	step: ReplayStep;
+	message: string;
+	height?: number;
+	table?: string;
+	key?: Record<string, unknown>;
+	/** The source could not serve the input: unchecked, not disproven. */
+	unavailable?: boolean;
+}
+interface ReplayResult {
+	ok: boolean;
+	/** Set when the range starts after startBlock and a handler read or merged earlier rows. */
+	inconclusive?: string;
+	from: number;
+	to: number;
+	blocks: number;
+	txs: number;
+	/** Named writes to the subgraph's contracts. */
+	writes: number;
+	/** Events offered to a handler. */
+	events: number;
+	handlerErrors: number;
+	/** MARF proofs the walk took (one per window top below the checkpoint). */
+	marfProofs: number;
+	/** The memory store at `to`. */
+	tables: Map<string, Record<string, unknown>[]>;
+	notes: string[];
+	/** The first entry is the first broken link. */
+	failures: ReplayFailure[];
+}
+interface ReplayOptions {
+	/** Needs `getStateWrites`: the names are what feed the handlers. */
+	source: ProofSource;
+	/** The bundled ESM as stored in `handler_code`. */
+	handlerCode: string;
+	from: number;
+	to: number;
+	/** Defaults to `MAINNET_CHECKPOINT`. */
+	checkpoint?: VerifyCheckpoint;
+	/** Defaults to the definition's `startBlock`. */
+	startBlock?: number;
+	onProgress?: (height: number) => void;
+}
+/** Verify blocks 512 at a time: the top by one MARF jump, the rest by parent links. */
+declare const REPLAY_WINDOW = 512;
+/**
+* The contracts a state subgraph's writes come from, or an error when a
+* source does not fix one: completeness would need every contract's writes.
+*/
+declare function replayContracts(def: Pick<SubgraphDefinition, "sources">): string[] | {
+	error: string;
+};
+type PinCheck = {
+	status: "ok";
+	notes: string[];
+} | {
+	status: "unchecked";
+	notes: string[];
+} | {
+	status: "failed";
+	failure: ReplayFailure;
+	notes: string[];
+};
+/**
+* The served pin against the served bundle: the preimage must hash to the
+* pin, and name this handler code, this schema and this startBlock. A runtime
+* other than this package's is a note: rows can still match.
+*/
+declare function checkPin(served: {
+	pin: string | null;
+	pinPreimage: string | null;
+	handlerCode: string;
+}, def: SubgraphDefinition): PinCheck;
+/** Seams for tests: the block verifier and the burn height hint. */
+interface ReplayDeps {
+	verify(height: number): Promise<BlockVerification>;
+	/** The source's (unproven) burn height for a consensus hash. */
+	burnHeightHint(consensusHash: string): Promise<number>;
+}
+/** The replay loop over an injected verifier. */
+declare function replayBlocks(deps: ReplayDeps, opts: Omit<ReplayOptions, "source" | "checkpoint"> & {
+	bitcoinCheckpoint?: number;
+}): Promise<ReplayResult>;
+/** Verify every block in `[from, to]` from the checkpoint and recompute the subgraph's tables. */
+declare function replaySubgraph(opts: ReplayOptions): Promise<ReplayResult>;
+/**
+* Evaluate a bundled handler (ESM, as stored in `handler_code`) inside a
+* fresh deterministic realm and return its definition with every handler
+* wrapped to receive the {@link deterministicContext} facade.
+*/
+declare function loadDeterministicDefinition(handlerCode: string): Promise<SubgraphDefinition>;
+type Row = Record<string, unknown>;
+interface TableComparison {
+	table: string;
+	/** Replayed rows the served table holds identically. */
+	equal: number;
+	/** Replayed keys the served table re-created after `to`: not checked. */
+	superseded: number;
+	/** sha256 over the sorted canonical replayed rows in the window, hex. */
+	digest: string;
+	/** The same digest over the served rows in the window. */
+	servedDigest: string;
+}
+interface RowComparison {
+	failures: ReplayFailure[];
+	tables: TableComparison[];
+}
+/**
+* Compare the replayed tables with the served ones over `[from, to]` on
+* `_block_height`. Keyed tables (first `uniqueKeys` tuple) compare row by
+* row; unkeyed tables as multisets.
+*/
+declare function compareRows(schema: SubgraphSchema, replayed: {
+	from: number;
+	to: number;
+	tables: Map<string, Row[]>;
+}, served: Map<string, Row[]>): RowComparison;
+export { PinCheck, REPLAY_WINDOW, ReplayDeps, ReplayFailure, ReplayOptions, ReplayResult, ReplayStep, RowComparison, TableComparison, checkPin, compareRows, loadDeterministicDefinition, replayBlocks, replayContracts, replaySubgraph };