@secondlayer/subgraphs 3.20.0 → 3.22.0

package/dist/src/index.d.ts

@@ -25,15 +25,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 +77,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 +195,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;
 	/**
@@ -165,18 +223,47 @@ interface ContractDeployFilter {
 	deployer?: string;
 	contractName?: string;
 }
-interface PrintEventFilter extends TraitScope {
+/**
+* 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";
-	contractId?: string;
+	/** One contract id, or a set of them (max 20). Supports `*` wildcards.
+	*  Mutually exclusive with `trait`. */
+	contractId?: string | readonly string[];
 	topic?: string;
 	/**
-	* Optional per-topic field schema. When declared, the handler's `event` is
-	* a discriminated union keyed by `topic` and `event.data` is typed per topic
+	* 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" } }`).
-	* Uses the same `ColumnType` vocab as `schema`; nested fields use `"jsonb"`.
-	* Type-level only — not validated at runtime.
+	* 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, ColumnType>>;
+	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;
@@ -258,6 +345,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;
@@ -604,13 +701,34 @@ type ContractCallPayload<F> = F extends {
 * per topic; otherwise it falls back to the untyped {@link PrintEventPayload}.
 */
 type PrintEventFor<F> = F extends {
-	prints: infer P extends Record<string, Record<string, ColumnType>>
+	prints: infer P extends Record<string, Record<string, PrintField>>
 } ? { [K in keyof P] : {
 	contractId: string
 	topic: K
-	data: { [Field in keyof P[K]] : ColumnToTS<P[K][Field]> }
+	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"
@@ -690,6 +808,60 @@ declare function defineSubgraph<
 	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
+} | {
+	ok: false
+	reason: string
+};
+/**
+* Validate one decoded print event against a source's `prints` declaration.
+* Returns `{ ok: true }` when no declaration covers this topic (undeclared
+* topics are not the developer's stated contract, so they pass through).
+*/
+declare function validatePrintPayload(prints: Record<string, Record<string, PrintField>> | undefined, topic: string, data: Record<string, unknown>): PrintValidationResult;
+/**
 * Empirical print-payload schema inference. Callers (the index print-schema
 * endpoint) extract topic + raw Clarity hex per row; this module deserializes
 * a bounded sample per topic, unifies the observed value shapes into a single
@@ -928,4 +1100,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, 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, PrintSample, PrintEventPayload, PrintEventFor, PrintEventFilter, 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, 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, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ByoMigrationPlan, ByoBreakingChangeError, AnyEvent, AggregateSpec, AggregateResult };