@secondlayer/subgraphs 3.20.0 → 3.22.0

package/dist/src/runtime/reorg.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";
@@ -106,9 +154,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;
 	/**
@@ -124,18 +182,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;

package/dist/src/runtime/reorg.js

@@ -100,6 +100,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}`;
@@ -118,6 +130,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));
   }
@@ -262,23 +277,21 @@ class SubgraphContext {
   formatUnits(value, decimals) {
     return formatUnits(value, decimals);
   }
-  async findOne(table, where) {
-    this.validateTable(table);
+  async readRows(table, where, limit) {
     const qualifiedTable = `"${this.pgSchemaName}"."${table}"`;
     const { clause } = buildWhereClause(where);
-    const query = `SELECT * FROM ${qualifiedTable} WHERE ${clause} LIMIT 1`;
+    const query = `SELECT * FROM ${qualifiedTable} WHERE ${clause}${limit !== undefined ? ` LIMIT ${limit}` : ""}`;
     const { rows } = await sql.raw(query).execute(this.db);
-    const row = rows[0] ?? null;
-    return this.overlayOne(table, where, row ? this.coerceRow(table, row) : null);
+    return rows.map((r) => this.coerceRow(table, r));
+  }
+  async findOne(table, where) {
+    this.validateTable(table);
+    const row = (await this.readRows(table, where, 1))[0] ?? null;
+    return this.overlayOne(table, where, row);
   }
   async findMany(table, where) {
     this.validateTable(table);
-    const qualifiedTable = `"${this.pgSchemaName}"."${table}"`;
-    const { clause } = buildWhereClause(where);
-    const query = `SELECT * FROM ${qualifiedTable} WHERE ${clause}`;
-    const { rows } = await sql.raw(query).execute(this.db);
-    const dbRows = rows.map((r) => this.coerceRow(table, r));
-    return this.overlayMany(table, where, dbRows);
+    return this.overlayMany(table, where, await this.readRows(table, where));
   }
   overlayOne(table, where, dbRow) {
     if (this.ops.length === 0)
@@ -758,6 +771,87 @@ import {
   deserializeCV as deserializeCV2,
   toCamelCase
 } from "@secondlayer/stacks/clarity";
+
+// src/runtime/print-validate.ts
+var COLUMN_TYPES = new Set([
+  "text",
+  "uint",
+  "int",
+  "principal",
+  "boolean",
+  "timestamp",
+  "jsonb"
+]);
+function isColumnType(field) {
+  return typeof field === "string" && COLUMN_TYPES.has(field);
+}
+function matchesField(field, value) {
+  if (isColumnType(field)) {
+    switch (field) {
+      case "uint":
+      case "int":
+        return typeof value === "bigint" || typeof value === "number";
+      case "boolean":
+        return typeof value === "boolean";
+      case "text":
+      case "principal":
+      case "timestamp":
+        return typeof value === "string" || typeof value === "number" || typeof value === "bigint";
+      case "jsonb":
+        return value !== undefined;
+    }
+  }
+  if (typeof field !== "object" || field === null)
+    return false;
+  if ("optional" in field) {
+    return value === undefined || value === null || matchesField(field.type, value);
+  }
+  if ("tuple" in field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return false;
+    }
+    return matchesTopic(field.tuple, value).ok;
+  }
+  if ("list" in field) {
+    return Array.isArray(value) && value.every((item) => matchesField(field.list, item));
+  }
+  return false;
+}
+function matchesTopic(declared, data) {
+  for (const [name, field] of Object.entries(declared)) {
+    const present = name in data;
+    const optional = typeof field === "object" && field !== null && "optional" in field;
+    if (!present) {
+      if (optional)
+        continue;
+      return { ok: false, reason: `missing declared field "${name}"` };
+    }
+    if (!matchesField(field, data[name])) {
+      return {
+        ok: false,
+        reason: `field "${name}" does not match its declared type (got ${describe(data[name])})`
+      };
+    }
+  }
+  return { ok: true };
+}
+function describe(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+}
+function validatePrintPayload(prints, topic, data) {
+  if (!prints)
+    return { ok: true };
+  const declared = prints[topic];
+  if (!declared)
+    return { ok: true };
+  return matchesTopic(declared, data);
+}
+
+// src/runtime/runner.ts
 var DEFAULT_ERROR_THRESHOLD = 50;
 function camelCase(str) {
   return str.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
@@ -1002,6 +1096,7 @@ function buildEventPayload(filter, tx, event) {
 async function runHandlers(subgraph, matched, ctx, opts) {
   let processed = 0;
   let errors = 0;
+  let skipped = 0;
   const threshold = opts?.errorThreshold ?? DEFAULT_ERROR_THRESHOLD;
   const filterLookup = new Map;
   if (!Array.isArray(subgraph.sources)) {
@@ -1026,7 +1121,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
         errors,
         threshold
       });
-      return { processed, errors };
+      return { processed, errors, ...skipped > 0 ? { skipped } : {} };
     }
     const handler = subgraph.handlers[sourceName] ?? subgraph.handlers["*"] ?? null;
     if (!handler) {
@@ -1082,6 +1177,21 @@ async function runHandlers(subgraph, matched, ctx, opts) {
       if (event !== null && filter?.type === "print_event" && filter.topic && payload.topic !== filter.topic) {
         continue;
       }
+      if (event !== null && filter?.type === "print_event" && filter.prints) {
+        const printPayload = payload;
+        const verdict = validatePrintPayload(filter.prints, printPayload.topic ?? "", printPayload.data ?? {});
+        if (!verdict.ok) {
+          skipped++;
+          logger2.warn("Print payload does not match declared prints schema", {
+            subgraph: subgraph.name,
+            sourceName,
+            topic: printPayload.topic,
+            txId: tx.tx_id,
+            reason: verdict.reason
+          });
+          continue;
+        }
+      }
       await handler(payload, ctx);
       processed++;
     } catch (err) {
@@ -1096,11 +1206,14 @@ async function runHandlers(subgraph, matched, ctx, opts) {
       });
     }
   }
-  return { processed, errors };
+  return { processed, errors, ...skipped > 0 ? { skipped } : {} };
 }
 
 // src/runtime/source-matcher.ts
 var patternCache = new Map;
+function matchAny(value, pattern) {
+  return Array.isArray(pattern) ? pattern.some((p) => matchPattern(value, p)) : matchPattern(value, pattern);
+}
 function matchPattern(value, pattern) {
   if (!pattern.includes("*"))
     return value === pattern;
@@ -1113,6 +1226,22 @@ function matchPattern(value, pattern) {
   return re.test(value);
 }
 var EMPTY_SET = new Set;
+function factoryAllows(filter, contractId, factoryContracts) {
+  if (!filter.factory)
+    return true;
+  if (!contractId)
+    return false;
+  return (factoryContracts.get(filter.factory.from) ?? EMPTY_SET).has(contractId);
+}
+function readPath(payload, path) {
+  let cur = payload;
+  for (const key of path.split(".")) {
+    if (cur === null || typeof cur !== "object")
+      return;
+    cur = cur[key];
+  }
+  return cur;
+}
 function traitAllows(filter, contractId, traitContracts) {
   const trait = filter.trait;
   if (!trait)
@@ -1124,7 +1253,7 @@ function traitAllows(filter, contractId, traitContracts) {
 function assetContract(assetId) {
   return assetId?.split("::")[0];
 }
-function matchFilter(filter, transactions, eventsByTx, traitContracts) {
+function matchFilter(filter, transactions, eventsByTx, traitContracts, factoryContracts = new Map) {
   const results = [];
   switch (filter.type) {
     case "stx_transfer":
@@ -1251,9 +1380,11 @@ function matchFilter(filter, transactions, eventsByTx, traitContracts) {
         if (tx.type !== "contract_call")
           continue;
         if (filter.contractId) {
-          if (!tx.contract_id || !matchPattern(tx.contract_id, filter.contractId))
+          if (!tx.contract_id || !matchAny(tx.contract_id, filter.contractId))
             continue;
         }
+        if (!factoryAllows(filter, tx.contract_id, factoryContracts))
+          continue;
         if (filter.functionName) {
           if (!tx.function_name || !matchPattern(tx.function_name, filter.functionName))
             continue;
@@ -1300,11 +1431,13 @@ function matchFilter(filter, transactions, eventsByTx, traitContracts) {
             return false;
           const printContractId = data.contract_identifier ?? data.contract_id;
           if (filter.contractId) {
-            if (!printContractId || !matchPattern(printContractId, filter.contractId))
+            if (!printContractId || !matchAny(printContractId, filter.contractId))
               return false;
           }
           if (!traitAllows(filter, printContractId, traitContracts))
             return false;
+          if (!factoryAllows(filter, printContractId, factoryContracts))
+            return false;
           return true;
         });
         if (matched.length > 0) {
@@ -1316,7 +1449,7 @@ function matchFilter(filter, transactions, eventsByTx, traitContracts) {
   }
   return results;
 }
-function matchSources(sources, transactions, events, traitContracts = new Map) {
+function matchSources(sources, transactions, events, traitContracts = new Map, factoryContracts = new Map) {
   const eventsByTx = new Map;
   for (const event of events) {
     const list = eventsByTx.get(event.tx_id) ?? [];
@@ -1326,7 +1459,7 @@ function matchSources(sources, transactions, events, traitContracts = new Map) {
   const seen = new Set;
   const results = [];
   for (const [sourceName, filter] of Object.entries(sources)) {
-    const matches = matchFilter(filter, transactions, eventsByTx, traitContracts);
+    const matches = matchFilter(filter, transactions, eventsByTx, traitContracts, factoryContracts);
     for (const match of matches) {
       const dedupeKey = `${match.tx.tx_id}:${sourceName}`;
       if (!seen.has(dedupeKey)) {
@@ -1981,6 +2114,57 @@ async function resolveRoute(subgraphName, targetDb) {
 function invalidateSubgraphRoute(subgraphName) {
   routeCache.delete(subgraphName);
 }
+async function resolveFactoryContracts(subgraph, blockHeight, schemaName, db, txs, evts) {
+  const factories = new Map;
+  for (const source of Object.values(subgraph.sources)) {
+    const factory = source.factory;
+    if (factory)
+      factories.set(factory.from, factory);
+  }
+  const resolved = new Map;
+  const discovered = [];
+  if (factories.size === 0)
+    return { resolved, discovered };
+  for (const [discoveringSource, factory] of factories) {
+    const known = new Set;
+    try {
+      const rows = await sql3`
+				SELECT address FROM ${sql3.raw(`"${schemaName}"."_factory_addresses"`)}
+				WHERE source_name = ${discoveringSource} AND block_height <= ${blockHeight}
+			`.execute(db);
+      for (const row of rows.rows)
+        known.add(row.address);
+    } catch {}
+    const discovering = subgraph.sources[factory.from];
+    if (discovering) {
+      const matches = matchSources({ [factory.from]: discovering }, txs, evts, new Map, new Map);
+      for (const match of matches) {
+        for (const event of match.events ?? []) {
+          const payload = buildEventPayload(discovering, match.tx, event);
+          const value = readPath(payload, factory.field);
+          if (typeof value === "string" && value.length > 0 && !known.has(value)) {
+            known.add(value);
+            discovered.push({ sourceName: discoveringSource, address: value });
+          }
+        }
+      }
+    }
+    resolved.set(discoveringSource, known);
+  }
+  return { resolved, discovered };
+}
+async function persistFactoryDiscoveries(schemaName, db, blockHeight, discovered) {
+  if (discovered.length === 0)
+    return;
+  for (const { sourceName, address } of discovered) {
+    await sql3`
+			INSERT INTO ${sql3.raw(`"${schemaName}"."_factory_addresses"`)}
+				(source_name, address, block_height)
+			VALUES (${sourceName}, ${address}, ${blockHeight})
+			ON CONFLICT (source_name, address) DO NOTHING
+		`.execute(db);
+  }
+}
 async function resolveTraitContracts(subgraph, blockHeight, db) {
   const traits = new Set;
   for (const source of Object.values(subgraph.sources)) {
@@ -2067,8 +2251,11 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
     txs = data.txs;
     evts = data.events;
   }
+  const route = await resolveRoute(subgraphName, targetDb);
+  const schemaName = route.schemaName;
   const traitContracts = await resolveTraitContracts(subgraph, blockHeight, targetDb);
-  const matched = matchSources(subgraph.sources, txs, evts, traitContracts);
+  const { resolved: factoryContracts, discovered } = await resolveFactoryContracts(subgraph, blockHeight, schemaName, targetDb, txs, evts);
+  const matched = matchSources(subgraph.sources, txs, evts, traitContracts, factoryContracts);
   result.matched = matched.length;
   if (matched.length === 0) {
     if (!opts?.skipProgressUpdate) {
@@ -2076,8 +2263,6 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
     }
     return result;
   }
-  const route = await resolveRoute(subgraphName, targetDb);
-  const schemaName = route.schemaName;
   const blockMeta = {
     height: block.height,
     hash: block.hash,
@@ -2135,6 +2320,7 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
     });
     result.processed = runResult.processed;
     result.errors = runResult.errors;
+    await persistFactoryDiscoveries(schemaName, route.dataDb, blockHeight, discovered);
     await targetDb.transaction().execute(async (tx) => {
       if (manifest && manifest.count > 0) {
         await emitSubscriptionOutbox(tx, subgraphName, manifest, matcher, block.height);
@@ -2584,6 +2770,11 @@ async function handleSubgraphReorg(blockHeight, loadSubgraphDef) {
             await client.unsafe(`DELETE FROM "${schemaName}"."${tableName}" WHERE "_block_height" >= $1`, [blockHeight]);
           }
         }
+        await client.unsafe(`DO $$ BEGIN
+						IF to_regclass('"${schemaName}"."_factory_addresses"') IS NOT NULL THEN
+							DELETE FROM "${schemaName}"."_factory_addresses" WHERE block_height >= ${Number(blockHeight)};
+						END IF;
+					END $$`);
         for (const [tableName, rows] of Object.entries(revertedByTable)) {
           if (rows.length === 0)
             continue;
@@ -2651,5 +2842,5 @@ export {
   handleSubgraphReorg
 };
 
-//# debugId=283CF7962DBBE8DC64756E2164756E21
+//# debugId=7F2499A1E1B069B564756E2164756E21
 //# sourceMappingURL=reorg.js.map