@secondlayer/subgraphs 6.4.0 → 6.6.0

package/README.md

@@ -63,6 +63,7 @@ Every source needs a handler of the same name. Handlers write with `ctx.insert`,
 | `./testing` | `runSubgraphTest`, `createTestContext`, `buildEvent`: run handlers against real or built events before deploying |
 | `./runtime/replay` | `replayWebhook({ accountId, webhookId, fromBlock, toBlock })`: re-enqueue historical rows as outbox entries |
 | `./runtime/emitter` | Webhook egress checks used by the API (`checkEgressAllowed`) |
+| `./verify` | `replaySubgraph`, `compareRows`, `checkPin`: recompute a `state` subgraph from blocks proven with `@secondlayer/verify` and compare the served rows (powers `secondlayer verify subgraph --replay`) |
 
 ## Runtime
 

package/dist/index.d.ts

@@ -18,7 +18,7 @@ import { AbiContract, ExtractFunctionArgs, ExtractFunctionOutput, ExtractReadOnl
 */
 type ChainReadCacheMode = "per-block" | "contract-constant";
 type ChainReadOptions = {
-	cache?: ChainReadCacheMode
+	cache?: ChainReadCacheMode;
 };
 /**
 * The chain-read surface, fully typed by an ABI.
@@ -49,7 +49,7 @@ interface ChainReadClient {
 	* `cache: "contract-constant"`).
 	*/
 	contract<const C extends AbiContract>(contractId: string, abi: C, options?: ChainReadOptions): {
-		read: ChainReadMethods<C>
+		read: ChainReadMethods<C>;
 	};
 }
 /**
@@ -78,7 +78,7 @@ type ChainReadMethods<C extends AbiContract> = { [N in ExtractReadOnlyFunctions<
 */
 interface ErasedChainReadClient {
 	contract(contractId: string, abi: unknown, options?: ChainReadOptions): {
-		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>
+		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>;
 	};
 }
 /**
@@ -92,9 +92,9 @@ interface ErasedChainReadClient {
 * ```
 */
 declare function readContractAt<const C extends AbiContract>(ctx: {
-	client: ErasedChainReadClient
+	client: ErasedChainReadClient;
 }, contractId: string, abi: C, options?: ChainReadOptions): {
-	read: ChainReadMethods<C>
+	read: ChainReadMethods<C>;
 };
 declare class ChainReadError extends Error {
 	name: string;
@@ -157,7 +157,7 @@ interface StxLockFilter {
 * as-of each processed block. Lets a source index "all SIP-010 tokens" etc.
 */
 type TraitScope = {
-	trait?: string
+	trait?: string;
 };
 /**
 * Scope a source to a DYNAMIC address set discovered from another source's
@@ -197,10 +197,10 @@ type TraitScope = {
 interface FactoryScope {
 	factory?: {
 		/** Source name whose events reveal the addresses. */
-		from: string
+		from: string;
 		/** Dotted path to the address on that source's payload
 		*  (e.g. `"data.pool"`, `"contractId"`, `"data.token.id"`). */
-		field: string
+		field: string;
 	};
 }
 /** FT event filters */
@@ -273,12 +273,12 @@ interface ContractCallEvent {
 	resultHex: string | null;
 	/** Transaction metadata. */
 	tx: {
-		txId: string
-		sender: string
-		type: string
-		status: string
-		contractId: string | null
-		functionName: string | null
+		txId: string;
+		sender: string;
+		type: string;
+		status: string;
+		contractId: string | null;
+		functionName: string | null;
 	};
 }
 /** Contract event filters */
@@ -347,12 +347,12 @@ interface MapWriteFilter extends TraitScope, FactoryScope {
 * - `{ list: F }` — a list of `F`.
 */
 type PrintField = ColumnType | {
-	type: PrintField
-	optional: true
+	type: PrintField;
+	optional: true;
 } | {
-	tuple: Record<string, PrintField>
+	tuple: Record<string, PrintField>;
 } | {
-	list: PrintField
+	list: PrintField;
 };
 /**
 * Per-topic field schema for a print_event source. When declared, the handler's
@@ -364,34 +364,34 @@ type PrintField = ColumnType | {
 */
 type PrintEventPrints = Record<string, Record<string, PrintField>>;
 type PrintEventFields = FactoryScope & {
-	type: "print_event"
-	topic?: string
+	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
+	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
+	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
+	contractId?: undefined;
+	trait?: string;
+	prints?: PrintEventPrints;
 };
 /**
 * Print-event filter. Pinned sources (contractId set, no trait) require
@@ -414,12 +414,12 @@ type RowValue = string | number | bigint | boolean | null | undefined | Record<s
 /** Context passed to subgraph handlers during event processing */
 interface SubgraphContext {
 	block: {
-		height: number
-		hash: string
-		timestamp: number
-		burnBlockHeight: number
+		height: number;
+		hash: string;
+		timestamp: number;
+		burnBlockHeight: number;
 		/** Nakamoto StacksBlockId, when the block row carries one. */
-		indexBlockHash?: string | null
+		indexBlockHash?: string | null;
 	};
 	tx: TxMeta;
 	/**
@@ -483,18 +483,18 @@ interface SystemRow {
 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
+	eq?: T;
+	neq?: T;
+	gt?: T;
+	gte?: T;
+	lt?: T;
+	lte?: T;
 	/** Match any value in the set. */
-	in?: T[]
+	in?: T[];
 	/** Match none of the values in the set. */
-	notIn?: T[]
+	notIn?: T[];
 	/** SQL ILIKE pattern (case-insensitive); `%`/`_` wildcards. Strings only. */
-	like?: string
+	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]> };
@@ -503,16 +503,16 @@ type WhereInput<TRow> = { [K in keyof TRow]? : TRow[K] | ComparisonFilter<TRow[K
 * Both `_blockHeight` and `blockHeight` are valid — serializer handles mapping.
 */
 type SystemWhereAliases = {
-	blockHeight?: bigint | ComparisonFilter<bigint>
-	txId?: string | ComparisonFilter<string>
-	createdAt?: string | ComparisonFilter<string>
-	id?: string | ComparisonFilter<string>
+	blockHeight?: bigint | ComparisonFilter<bigint>;
+	txId?: string | ComparisonFilter<string>;
+	createdAt?: string | ComparisonFilter<string>;
+	id?: string | ComparisonFilter<string>;
 };
 type SystemOrderByAliases = {
-	blockHeight?: "asc" | "desc"
-	txId?: "asc" | "desc"
-	createdAt?: "asc" | "desc"
-	id?: "asc" | "desc"
+	blockHeight?: "asc" | "desc";
+	txId?: "asc" | "desc";
+	createdAt?: "asc" | "desc";
+	id?: "asc" | "desc";
 };
 interface FindManyOptions<TRow> {
 	where?: WhereInput<TRow> & SystemWhereAliases;
@@ -582,15 +582,15 @@ type AggregateResult<
 	TRow,
 	A extends AggregateSpec<TRow>
 > = (A["count"] extends true ? {
-	count: number
+	count: number;
 } : unknown) & (A["countDistinct"] extends readonly string[] ? {
-	countDistinct: Record<ColsOf<A, "countDistinct">, number>
+	countDistinct: Record<ColsOf<A, "countDistinct">, number>;
 } : unknown) & (A["sum"] extends readonly string[] ? {
-	sum: Record<ColsOf<A, "sum">, string>
+	sum: Record<ColsOf<A, "sum">, string>;
 } : unknown) & (A["min"] extends readonly string[] ? {
-	min: Record<ColsOf<A, "min">, string | null>
+	min: Record<ColsOf<A, "min">, string | null>;
 } : unknown) & (A["max"] extends readonly string[] ? {
-	max: Record<ColsOf<A, "max">, string | null>
+	max: Record<ColsOf<A, "max">, string | null>;
 } : unknown);
 interface SubgraphTableClient<TRow> {
 	/**
@@ -601,7 +601,7 @@ interface SubgraphTableClient<TRow> {
 	* names without `as const` at the call site (same pattern as `aggregate`).
 	*/
 	findMany<const F extends readonly (keyof TRow & string)[] = readonly (keyof TRow & string)[]>(options?: Omit<FindManyOptions<TRow>, "fields"> & {
-		fields?: F
+		fields?: F;
 	}): Promise<FindManyPage<Pick<TRow, F[number]>>>;
 	count(where?: WhereInput<TRow> & SystemWhereAliases): Promise<number>;
 	/**
@@ -620,9 +620,9 @@ interface SubgraphTableClient<TRow> {
 }
 /** A column is optional on insert when it's nullable or has a SQL default. */
 type IsOptionalColumn<C> = C extends {
-	nullable: true
+	nullable: true;
 } ? true : C extends {
-	default: string | number | boolean
+	default: string | number | boolean;
 } ? true : false;
 /**
 * Like `InferColumnType` but for WRITE inputs: numeric (`uint`/`int`) columns
@@ -653,12 +653,12 @@ type RowWhere<
 */
 interface TypedSubgraphContext<S extends SubgraphSchema> {
 	block: {
-		height: number
-		hash: string
-		timestamp: number
-		burnBlockHeight: number
+		height: number;
+		hash: string;
+		timestamp: number;
+		burnBlockHeight: number;
 		/** Nakamoto StacksBlockId, when the block row carries one. */
-		indexBlockHash?: string | null
+		indexBlockHash?: string | null;
 	};
 	tx: TxMeta;
 	/**
@@ -687,7 +687,7 @@ interface TypedSubgraphContext<S extends SubgraphSchema> {
 }
 /** Infer a typed client object from a subgraph definition shape */
 type InferSubgraphClient<T> = T extends {
-	schema: infer S
+	schema: infer S;
 } ? { [K in keyof S] : S[K] extends SubgraphTable ? SubgraphTableClient<InferTableRow<S[K]>> : never } : never;
 interface FtTransferPayload {
 	sender: string;
@@ -774,10 +774,10 @@ interface ContractDeployPayload {
 * 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
+	abi: infer A extends AbiContract3;
+	functionName: infer N extends string;
 } ? N extends ExtractFunctionNames<A> ? ContractCallEvent & {
-	input: ExtractFunctionArgs2<A, N>
+	input: ExtractFunctionArgs2<A, N>;
 } : ContractCallEvent : ContractCallEvent;
 interface NestedContractCallPayload {
 	contractId: string;
@@ -821,24 +821,24 @@ interface MapDeletePayload {
 * 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>>
+	prints: infer P extends Record<string, Record<string, PrintField>>;
 } ? { [K in keyof P] : {
-	contractId: string
-	topic: K
-	data: PrintDataOf<P[K]>
-	tx: TxMeta
+	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
+	type: infer Inner;
+	optional: true;
 } ? PrintFieldToTS<Inner> : F extends {
-	tuple: infer T extends Record<string, PrintField>
+	tuple: infer T extends Record<string, PrintField>;
 } ? PrintDataOf<T> : F extends {
-	list: infer Item
+	list: infer Item;
 } ? PrintFieldToTS<Item>[] : unknown;
 type OptionalFieldKeys<T> = { [K in keyof T] : T[K] extends {
-	optional: true
+	optional: true;
 } ? K : never }[keyof T];
 /** Collapse an intersection into one object literal, so hovering `event.data`
 *  shows the fields rather than `A & B`. */
@@ -851,37 +851,37 @@ type Flatten<T> = { [K in keyof T] : T[K] } & {};
 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"
+	type: "print_event";
 } ? PrintEventFor<F> : F extends {
-	type: "ft_transfer"
+	type: "ft_transfer";
 } ? FtTransferPayload : F extends {
-	type: "ft_mint"
+	type: "ft_mint";
 } ? FtMintPayload : F extends {
-	type: "ft_burn"
+	type: "ft_burn";
 } ? FtBurnPayload : F extends {
-	type: "nft_transfer"
+	type: "nft_transfer";
 } ? NftTransferPayload : F extends {
-	type: "nft_mint"
+	type: "nft_mint";
 } ? NftMintPayload : F extends {
-	type: "nft_burn"
+	type: "nft_burn";
 } ? NftBurnPayload : F extends {
-	type: "stx_transfer"
+	type: "stx_transfer";
 } ? StxTransferPayload : F extends {
-	type: "stx_mint"
+	type: "stx_mint";
 } ? StxMintPayload : F extends {
-	type: "stx_burn"
+	type: "stx_burn";
 } ? StxBurnPayload : F extends {
-	type: "stx_lock"
+	type: "stx_lock";
 } ? StxLockPayload : F extends {
-	type: "contract_call"
+	type: "contract_call";
 } ? ContractCallPayload<F> : F extends {
-	type: "contract_deploy"
+	type: "contract_deploy";
 } ? ContractDeployPayload : F extends {
-	type: "nested_contract_call"
+	type: "nested_contract_call";
 } ? NestedContractCallPayload : F extends {
-	type: "var_set"
+	type: "var_set";
 } ? VarSetPayload : F extends {
-	type: infer T extends "map_set" | "map_insert" | "map_delete"
+	type: infer T extends "map_set" | "map_insert" | "map_delete";
 } ? T extends "map_delete" ? MapDeletePayload : MapWritePayload : never;
 /** Union of every event payload. */
 type AnyEvent = FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | PrintEventPayload | ContractCallEvent | ContractDeployPayload | NestedContractCallPayload | VarSetPayload | MapWritePayload | MapDeletePayload;
@@ -905,9 +905,9 @@ type TypedSubgraphDefinition<
 	Sources extends Record<string, SubgraphFilter>,
 	S extends SubgraphSchema
 > = Omit<SubgraphDefinition, "sources" | "schema" | "handlers"> & {
-	sources: Sources
-	schema: S
-	handlers: TypedHandlers<Sources, S>
+	sources: Sources;
+	schema: S;
+	handlers: TypedHandlers<Sources, S>;
 };
 /**
 * Identity function that preserves `sources` and `schema` literal types so
@@ -972,7 +972,7 @@ declare function defineSchema<const S extends SubgraphSchema>(schema: S): S;
 * this is the form for when only the definition is in scope.
 */
 type InferContext<D> = D extends {
-	schema: infer S extends SubgraphSchema
+	schema: infer S extends SubgraphSchema;
 } ? TypedSubgraphContext<S> : never;
 /**
 * Validates a subgraph definition, returning the parsed result or throwing on failure.
@@ -985,14 +985,14 @@ declare function validateSubgraphDefinition(def: unknown): SubgraphDefinition;
 * means adding a field to a filter can never leave the documentation behind.
 */
 declare function filterFieldsByType(): Array<{
-	type: string
-	fields: string[]
+	type: string;
+	fields: string[];
 }>;
 type PrintValidationResult = {
-	ok: true
+	ok: true;
 } | {
-	ok: false
-	reason: string
+	ok: false;
+	reason: string;
 };
 /**
 * Empirical print-payload schema inference. Callers (the index print-schema
@@ -1214,8 +1214,8 @@ declare function diffSchema(existing: SubgraphSchema, incoming: SubgraphSchema):
 * Index-flag and composite-index changes are never breaking.
 */
 declare function hasBreakingChanges(diff: TableDiff): {
-	breaking: boolean
-	reasons: string[]
+	breaking: boolean;
+	reasons: string[];
 };
 interface DeployDiff {
 	addedTables: string[];
@@ -1247,32 +1247,32 @@ declare function renderDeployPlan(def: SubgraphDefinition, schemaName?: string):
 * - Breaking change → auto-reindex (drop + recreate)
 */
 declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: string, opts?: {
-	forceReindex?: boolean
-	apiKeyId?: string
-	accountId?: string
-	schemaName?: string
-	handlerCode?: string
-	sourceCode?: string
+	forceReindex?: boolean;
+	apiKeyId?: string;
+	accountId?: string;
+	schemaName?: string;
+	handlerCode?: string;
+	sourceCode?: string;
 	/** Derived level to store (see `deriveVerification`). */
-	verification?: SubgraphVerification
+	verification?: SubgraphVerification;
 	/** Network baked into the pin. Defaults to `NETWORK`, then mainnet. */
-	network?: string
+	network?: string;
 }): Promise<{
-	action: "created" | "unchanged" | "handler_updated" | "updated" | "reindexed"
-	subgraphId: string
-	version: string
+	action: "created" | "unchanged" | "handler_updated" | "updated" | "reindexed";
+	subgraphId: string;
+	version: string;
 	/** Present when the deploy carried a bundled handler. */
-	pin?: string
-	diff?: DeployDiff
+	pin?: string;
+	diff?: DeployDiff;
 	/** Non-fatal caveats the caller should surface (e.g. handler grafts at tip). */
-	warnings?: string[]
+	warnings?: string[];
 }>;
 /** A (decoded event type, optional contract scope) pair the sparse probe
 *  checks. Contract scoping is what makes token-subgraph reindexes leap over
 *  everything that isn't their token. */
 type SparseProbeTarget = {
-	eventType: string
-	contractId?: string
+	eventType: string;
+	contractId?: string;
 };
 /** Sparse scanning is sound only when EVERY source is an event-type filter —
 *  a contract_call/contract_deploy source matches transactions, which the