@secondlayer/subgraphs 3.21.0 → 3.23.0

package/dist/src/schema/index.d.ts

@@ -1,4 +1,32 @@
-import { AbiContract } from "@secondlayer/stacks/clarity";
+import { AbiContract as AbiContract2 } 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
+};
+/**
+* `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 */
@@ -25,15 +53,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 +105,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";
@@ -106,9 +182,19 @@ interface NftBurnFilter extends TraitScope {
 	sender?: string;
 }
 /** 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;
 	/**
@@ -117,7 +203,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";
@@ -146,9 +232,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
@@ -186,8 +274,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;
@@ -251,9 +352,9 @@ interface GeneratedSQL {
 * each with auto-columns and indexes.
 */
 declare function generateSubgraphSQL(def: SubgraphDefinition, schemaNameOverride?: string): GeneratedSQL;
-import { Database } from "@secondlayer/shared/db";
-import { Kysely } from "kysely";
-type AnyDb = Kysely<Database>;
+import { Database as Database2 } from "@secondlayer/shared/db";
+import { Kysely as Kysely2 } from "kysely";
+type AnyDb = Kysely2<Database2>;
 interface TableDiff {
 	/** Tables added to the schema */
 	addedTables: string[];

package/dist/src/schema/index.js

@@ -86,24 +86,105 @@ var VALID_FILTER_TYPES = [
   "contract_deploy",
   "print_event"
 ];
-var SubgraphFilterSchema = z.object({
-  type: z.enum(VALID_FILTER_TYPES),
-  sender: z.string().optional(),
-  recipient: z.string().optional(),
+var contractIdField = z.union([
+  z.string(),
+  z.array(z.string()).min(1).max(20)
+]);
+var traitScope = { trait: z.string().optional() };
+var factoryScope = {
+  factory: z.object({ from: z.string().min(1), field: z.string().min(1) }).strict().optional()
+};
+var amountRange = {
   minAmount: z.bigint().optional(),
-  maxAmount: z.bigint().optional(),
-  assetIdentifier: z.string().optional(),
-  contractId: z.string().optional(),
-  functionName: z.string().optional(),
-  caller: z.string().optional(),
-  deployer: z.string().optional(),
-  contractName: z.string().optional(),
-  topic: z.string().optional(),
-  lockedAddress: z.string().optional(),
-  abi: AbiContractSchema.optional(),
-  trait: z.string().optional(),
-  prints: z.record(z.string(), z.record(z.string(), PrintFieldSchema)).optional()
-}).strict();
+  maxAmount: z.bigint().optional()
+};
+var SubgraphFilterUnion = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("stx_transfer"),
+    sender: z.string().optional(),
+    recipient: z.string().optional(),
+    ...amountRange
+  }).strict(),
+  z.object({
+    type: z.literal("stx_mint"),
+    recipient: z.string().optional(),
+    minAmount: z.bigint().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("stx_burn"),
+    sender: z.string().optional(),
+    minAmount: z.bigint().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("stx_lock"),
+    lockedAddress: z.string().optional(),
+    minAmount: z.bigint().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("ft_transfer"),
+    assetIdentifier: z.string().optional(),
+    sender: z.string().optional(),
+    recipient: z.string().optional(),
+    minAmount: z.bigint().optional(),
+    ...traitScope
+  }).strict(),
+  z.object({
+    type: z.literal("ft_mint"),
+    assetIdentifier: z.string().optional(),
+    recipient: z.string().optional(),
+    minAmount: z.bigint().optional(),
+    ...traitScope
+  }).strict(),
+  z.object({
+    type: z.literal("ft_burn"),
+    assetIdentifier: z.string().optional(),
+    sender: z.string().optional(),
+    minAmount: z.bigint().optional(),
+    ...traitScope
+  }).strict(),
+  z.object({
+    type: z.literal("nft_transfer"),
+    assetIdentifier: z.string().optional(),
+    sender: z.string().optional(),
+    recipient: z.string().optional(),
+    ...traitScope
+  }).strict(),
+  z.object({
+    type: z.literal("nft_mint"),
+    assetIdentifier: z.string().optional(),
+    recipient: z.string().optional(),
+    ...traitScope
+  }).strict(),
+  z.object({
+    type: z.literal("nft_burn"),
+    assetIdentifier: z.string().optional(),
+    sender: z.string().optional(),
+    ...traitScope
+  }).strict(),
+  z.object({
+    type: z.literal("contract_call"),
+    contractId: contractIdField.optional(),
+    functionName: z.string().optional(),
+    caller: z.string().optional(),
+    abi: AbiContractSchema.optional(),
+    ...traitScope,
+    ...factoryScope
+  }).strict(),
+  z.object({
+    type: z.literal("contract_deploy"),
+    deployer: z.string().optional(),
+    contractName: z.string().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("print_event"),
+    contractId: contractIdField.optional(),
+    topic: z.string().optional(),
+    prints: z.record(z.string(), z.record(z.string(), PrintFieldSchema)).optional(),
+    ...traitScope,
+    ...factoryScope
+  }).strict()
+]);
+var SubgraphFilterSchema = SubgraphFilterUnion;
 var SubgraphDefinitionSchema = z.object({
   name: SubgraphNameSchema,
   version: z.string().optional(),
@@ -117,6 +198,23 @@ var SubgraphDefinitionSchema = z.object({
 function validateSubgraphDefinition(def) {
   return SubgraphDefinitionSchema.parse(def);
 }
+function filterFieldsByType() {
+  const options = SubgraphFilterUnion?._def?.options ?? [];
+  const out = [];
+  for (const option of options) {
+    const shape = option?.shape ?? option?._def?.shape;
+    if (!shape)
+      continue;
+    const literal = shape.type?._def?.values?.[0] ?? shape.type?._def?.value ?? undefined;
+    if (typeof literal !== "string")
+      continue;
+    out.push({
+      type: literal,
+      fields: Object.keys(shape).filter((k) => k !== "type")
+    });
+  }
+  return out;
+}
 
 // src/schema/generator.ts
 import { createHash } from "node:crypto";
@@ -212,6 +310,18 @@ function emitJournalDDL(schemaName) {
     `CREATE INDEX IF NOT EXISTS idx_${schemaName}_journal_height ON ${schemaName}._journal (block_height)`
   ];
 }
+function emitFactoryDDL(schemaName) {
+  return [
+    `CREATE TABLE IF NOT EXISTS ${schemaName}._factory_addresses (
+  source_name TEXT NOT NULL,
+  address TEXT NOT NULL,
+  block_height BIGINT NOT NULL,
+  _created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (source_name, address)
+)`,
+    `CREATE INDEX IF NOT EXISTS idx_${schemaName}_factory_height ON ${schemaName}._factory_addresses (block_height)`
+  ];
+}
 function emitForeignKeyDDL(schemaName, tableName, tableDef) {
   return (tableDef.relations ?? []).map((rel) => {
     const constraintName = `fk_${schemaName}_${tableName}_${rel.name}`;
@@ -230,6 +340,9 @@ function generateSubgraphSQL(def, schemaNameOverride) {
     statements.push(...emitTableDDL(schemaName, tableName, tableDef));
   }
   statements.push(...emitJournalDDL(schemaName));
+  if (Object.values(def.sources ?? {}).some((src) => src.factory !== undefined)) {
+    statements.push(...emitFactoryDDL(schemaName));
+  }
   for (const [tableName, tableDef] of Object.entries(def.schema)) {
     statements.push(...emitForeignKeyDDL(schemaName, tableName, tableDef));
   }
@@ -255,8 +368,8 @@ function diffKeyLists(existing, incoming) {
   const existingSet = new Set((existing ?? []).map(key));
   const incomingSet = new Set((incoming ?? []).map(key));
   return {
-    added: (incoming ?? []).filter((cols) => !existingSet.has(key(cols))),
-    removed: (existing ?? []).filter((cols) => !incomingSet.has(key(cols)))
+    added: (incoming ?? []).filter((cols) => !existingSet.has(key(cols))).map((cols) => [...cols]),
+    removed: (existing ?? []).filter((cols) => !incomingSet.has(key(cols))).map((cols) => [...cols])
   };
 }
 function diffSchema(existing, incoming) {
@@ -605,5 +718,5 @@ export {
   TYPE_MAP
 };
 
-//# debugId=9CD49545FF5B17EC64756E2164756E21
+//# debugId=A19E9CF28F38E66064756E2164756E21
 //# sourceMappingURL=index.js.map