@secondlayer/subgraphs 3.21.0 → 3.23.0

package/dist/src/index.d.ts

@@ -1,4 +1,91 @@
-import { AbiContract } from "@secondlayer/stacks/clarity";
+import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
+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>
+	};
+}
+/**
+* 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>] : (args: 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>>
+	};
+}
+/**
+* Typed read methods for one contract, from a handler.
+*
+* ```ts
+* const token = readContractAt(ctx, contractId, SIP010_ABI, {
+*   cache: "contract-constant",
+* });
+* const decimals = await token.read.getDecimals({}); // bigint
+* ```
+*/
+declare function readContractAt<const C extends AbiContract>(ctx: {
+	client: ErasedChainReadClient
+}, contractId: string, abi: C, options?: ChainReadOptions): {
+	read: ChainReadMethods<C>
+};
+declare class ChainReadError extends Error {
+	name: string;
+}
 /** Supported column types for subgraph schemas */
 type ColumnType = "text" | "uint" | "int" | "principal" | "boolean" | "timestamp" | "jsonb";
 /** Column definition in a subgraph table */
@@ -25,15 +112,24 @@ interface SubgraphRelation {
 	/** Target column(s) the fields point at (a uniqueKeys entry on the target). */
 	referencedColumns: string[];
 }
-/** Table definition within a subgraph schema */
+/**
+* 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?: string[][];
+	indexes?: readonly (readonly string[])[];
 	/** Unique key constraints (each entry is an array of column names). Required for upsert. */
-	uniqueKeys?: string[][];
+	uniqueKeys?: readonly (readonly string[])[];
 	/** Foreign-key relations to other tables (for typed ORM joins). */
-	relations?: SubgraphRelation[];
+	relations?: readonly SubgraphRelation[];
 }
 /** Subgraph schema — maps table names to table definitions */
 type SubgraphSchema = Record<string, SubgraphTable>;
@@ -68,6 +164,45 @@ interface StxLockFilter {
 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";
@@ -147,9 +282,19 @@ interface ContractCallEvent {
 	};
 }
 /** Contract event filters */
-interface ContractCallFilter extends TraitScope {
+interface ContractCallFilter extends TraitScope, FactoryScope {
 	type: "contract_call";
-	contractId?: string;
+	/**
+	* 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;
 	/**
@@ -158,7 +303,7 @@ interface ContractCallFilter extends TraitScope {
 	* definition and used at runtime to decode args by name. Omit to keep
 	* `event.args` as a positional `unknown[]`.
 	*/
-	abi?: AbiContract;
+	abi?: AbiContract2;
 }
 interface ContractDeployFilter {
 	type: "contract_deploy";
@@ -187,9 +332,11 @@ type PrintField = ColumnType | {
 } | {
 	list: PrintField
 };
-interface PrintEventFilter extends TraitScope {
+interface PrintEventFilter extends TraitScope, FactoryScope {
 	type: "print_event";
-	contractId?: string;
+	/** 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
@@ -227,8 +374,21 @@ interface SubgraphContext {
 		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;
@@ -285,6 +445,16 @@ interface SubgraphDefinition {
 * Validates a subgraph definition, returning the parsed result or throwing on failure.
 */
 declare function validateSubgraphDefinition(def: unknown): SubgraphDefinition;
+/**
+* Per-source-type field vocabulary, DERIVED from
+* {@link SubgraphFilterSchema}. Agent-facing surfaces (the MCP filters
+* reference) used to hand-maintain a parallel copy of this list; deriving it
+* means adding a field to a filter can never leave the documentation behind.
+*/
+declare function filterFieldsByType(): Array<{
+	type: string
+	fields: string[]
+}>;
 interface ReindexOptions {
 	fromBlock?: number;
 	toBlock?: number;
@@ -327,7 +497,7 @@ declare function backfillSubgraph(def: SubgraphDefinition, opts: {
 }): Promise<{
 	processed: number
 }>;
-import { AbiContract as AbiContract2, ExtractFunctionArgs, ExtractFunctionNames } from "@secondlayer/stacks/clarity";
+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 */
@@ -504,8 +674,17 @@ interface TypedSubgraphContext<S extends SubgraphSchema> {
 		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<
@@ -620,10 +799,10 @@ interface ContractDeployPayload {
 * present for back-compat. Without an `abi`, the payload is {@link ContractCallEvent}.
 */
 type ContractCallPayload<F> = F extends {
-	abi: infer A extends AbiContract2
+	abi: infer A extends AbiContract3
 	functionName: infer N extends string
 } ? N extends ExtractFunctionNames<A> ? ContractCallEvent & {
-	input: ExtractFunctionArgs<A, N>
+	input: ExtractFunctionArgs2<A, N>
 } : ContractCallEvent : ContractCallEvent;
 /**
 * Print event typed per topic. When a `print_event` source declares a `prints`
@@ -737,6 +916,48 @@ declare function defineSubgraph<
 	const Sources extends Record<string, SubgraphFilter>,
 	const S extends SubgraphSchema
 >(def: TypedSubgraphDefinition<Sources, S>): TypedSubgraphDefinition<Sources, S>;
+/**
+* Identity helper that preserves a schema literal's exact types so it can be
+* HOISTED out of the `defineSubgraph()` call and reused:
+*
+* ```ts
+* const schema = defineSchema({
+*   balances: {
+*     columns: { holder: { type: "principal" }, amount: { type: "uint" } },
+*     uniqueKeys: [["holder"]],
+*   },
+* });
+*
+* // An extracted helper keeps the full typed surface — table names and row
+* // columns are still checked:
+* function credit(ctx: TypedSubgraphContext<typeof schema>, holder: string) {
+*   ctx.increment("balances", { holder }, { amount: 1n });
+* }
+*
+* defineSubgraph({ name: "balances", schema, sources, handlers });
+* ```
+*
+* `as const` alone does not work here (it produces `readonly` arrays that a
+* mutable `uniqueKeys` rejected) and a bare literal widens `type` to `string`.
+* That gap is why the shipped starter typed its helper `ctx: any` — and in
+* doing so modelled a non-commutative read-modify-write the docs warn against.
+*/
+declare function defineSchema<const S extends SubgraphSchema>(schema: S): S;
+/**
+* The typed handler context for a subgraph definition — for annotating
+* helpers extracted out of a handler:
+*
+* ```ts
+* const def = defineSubgraph({ … });
+* function credit(ctx: InferContext<typeof def>) { … }
+* ```
+*
+* Prefer `TypedSubgraphContext<typeof schema>` when the schema is hoisted;
+* this is the form for when only the definition is in scope.
+*/
+type InferContext<D> = D extends {
+	schema: infer S extends SubgraphSchema
+} ? TypedSubgraphContext<S> : never;
 type PrintValidationResult = {
 	ok: true
 } | {
@@ -851,10 +1072,10 @@ declare function generateIndexSchema(target: IndexCodegenTarget, opts?: IndexCod
 /** Index tables available to codegen, for help text and validation. */
 declare const INDEX_CODEGEN_TABLES: readonly string[];
 import { pgSchemaName } from "@secondlayer/shared/db/queries/subgraphs";
-import { Database } from "@secondlayer/shared/db";
+import { Database as Database2 } from "@secondlayer/shared/db";
 import { ByoBreakingChangeDetails } from "@secondlayer/shared/errors";
-import { Kysely } from "kysely";
-type AnyDb = Kysely<Database>;
+import { Kysely as Kysely2 } from "kysely";
+type AnyDb = Kysely2<Database2>;
 interface TableDiff {
 	/** Tables added to the schema */
 	addedTables: string[];
@@ -988,4 +1209,4 @@ type SparseProbeTarget = {
 declare function canSparseScan(subgraph: SubgraphDefinition): boolean;
 /** Probe targets for a subgraph's filters: decoded type + contract scope when\\n*  the filter pins one (assetIdentifier "SP….contract::asset" or contractId). */
 declare function sparseProbeTargets(subgraph: SubgraphDefinition): SparseProbeTarget[];
-export { validateSubgraphDefinition, validatePrintPayload, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, diffSchema, deploySchema, defineSubgraph, canSparseScan, camelizeDataKey, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintValidationResult, PrintSample, PrintFieldToTS, PrintField, PrintEventPayload, PrintEventFor, PrintEventFilter, PrintDataOf, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferredTopicSchema, InferredPrintField, InferTableRow, InferSubgraphClient, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, EventForFilter, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ByoMigrationPlan, ByoBreakingChangeError, AnyEvent, AggregateSpec, AggregateResult };
+export { validateSubgraphDefinition, validatePrintPayload, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, readContractAt, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, filterFieldsByType, diffSchema, deploySchema, defineSubgraph, defineSchema, canSparseScan, camelizeDataKey, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintValidationResult, PrintSample, PrintFieldToTS, PrintField, PrintEventPayload, PrintEventFor, PrintEventFilter, PrintDataOf, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferredTopicSchema, InferredPrintField, InferTableRow, InferSubgraphClient, InferContext, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, FactoryScope, EventForFilter, ErasedChainReadClient, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ChainReadOptions, ChainReadMethods, ChainReadError, ChainReadClient, ChainReadCacheMode, ByoMigrationPlan, ByoBreakingChangeError, AnyEvent, AggregateSpec, AggregateResult };