@secondlayer/subgraphs 3.20.0 → 3.22.0

package/dist/src/index.js

@@ -14,6 +14,44 @@ var ColumnTypeSchema = z.enum([
   "timestamp",
   "jsonb"
 ]);
+var PrintFieldSchema = z.lazy(() => z.union([
+  ColumnTypeSchema,
+  z.object({ type: PrintFieldSchema, optional: z.literal(true) }),
+  z.object({ tuple: z.record(z.string(), PrintFieldSchema) }),
+  z.object({ list: PrintFieldSchema })
+]));
+var AbiTypeSchema = z.lazy(() => z.union([
+  z.string(),
+  z.object({ buff: z.object({ length: z.number() }) }),
+  z.object({ "string-ascii": z.object({ length: z.number() }) }),
+  z.object({ "string-utf8": z.object({ length: z.number() }) }),
+  z.object({ optional: AbiTypeSchema }),
+  z.object({
+    list: z.object({ type: AbiTypeSchema, length: z.number() })
+  }),
+  z.object({
+    tuple: z.array(z.object({ name: z.string(), type: AbiTypeSchema }))
+  }),
+  z.object({
+    response: z.object({ ok: AbiTypeSchema, error: AbiTypeSchema })
+  })
+]));
+var AbiContractSchema = z.object({
+  functions: z.array(z.object({
+    name: z.string(),
+    access: z.enum(["public", "read-only", "private"], {
+      message: "ABI access must be public | read-only | private — a raw Hiro/Clarinet ABI uses `read_only`. Normalize it first: normalizeAbi() from @secondlayer/stacks/clarity."
+    }),
+    args: z.array(z.object({ name: z.string(), type: AbiTypeSchema })),
+    outputs: AbiTypeSchema
+  })),
+  maps: z.array(z.unknown()).optional(),
+  variables: z.array(z.unknown()).optional(),
+  fungible_tokens: z.array(z.unknown()).optional(),
+  non_fungible_tokens: z.array(z.unknown()).optional(),
+  implemented_traits: z.array(z.unknown()).optional(),
+  defined_traits: z.array(z.unknown()).optional()
+});
 var SubgraphColumnSchema = z.object({
   type: ColumnTypeSchema,
   nullable: z.boolean().optional(),
@@ -48,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: z.record(z.string(), z.any()).optional(),
-  trait: z.string().optional(),
-  prints: z.record(z.string(), z.record(z.string(), ColumnTypeSchema)).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(),
@@ -79,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/runtime/context.ts
 import { logger } from "@secondlayer/shared/logger";
@@ -179,6 +315,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}`;
@@ -197,6 +345,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));
   }
@@ -341,23 +492,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)
@@ -837,6 +986,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());
@@ -1081,6 +1311,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)) {
@@ -1105,7 +1336,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) {
@@ -1161,6 +1392,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) {
@@ -1175,11 +1421,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;
@@ -1192,6 +1441,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)
@@ -1203,7 +1468,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":
@@ -1330,9 +1595,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;
@@ -1379,11 +1646,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) {
@@ -1395,7 +1664,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) ?? [];
@@ -1405,7 +1674,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)) {
@@ -2060,6 +2329,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)) {
@@ -2146,8 +2466,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) {
@@ -2155,8 +2478,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,
@@ -2214,6 +2535,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);
@@ -2933,6 +3255,9 @@ async function backfillSubgraph(def, opts) {
 function defineSubgraph(def) {
   return def;
 }
+function defineSchema(schema) {
+  return schema;
+}
 // src/print-schema.ts
 import {
   deserializeCV as deserializeCV3
@@ -3852,8 +4177,8 @@ function diffKeyLists(existing, incoming) {
   const existingSet = new Set((existing ?? []).map(key2));
   const incomingSet = new Set((incoming ?? []).map(key2));
   return {
-    added: (incoming ?? []).filter((cols) => !existingSet.has(key2(cols))),
-    removed: (existing ?? []).filter((cols) => !incomingSet.has(key2(cols)))
+    added: (incoming ?? []).filter((cols) => !existingSet.has(key2(cols))).map((cols) => [...cols]),
+    removed: (existing ?? []).filter((cols) => !incomingSet.has(key2(cols))).map((cols) => [...cols])
   };
 }
 function diffSchema(existing, incoming) {
@@ -4197,6 +4522,7 @@ function getDefault(type) {
 }
 export {
   validateSubgraphDefinition,
+  validatePrintPayload,
   sparseProbeTargets,
   resumeReindex,
   renderDeployPlan,
@@ -4209,9 +4535,11 @@ export {
   generateKyselySchema,
   generateIndexSchema,
   generateDrizzleSchema,
+  filterFieldsByType,
   diffSchema,
   deploySchema,
   defineSubgraph,
+  defineSchema,
   canSparseScan,
   camelizeDataKey,
   backfillSubgraph,
@@ -4219,5 +4547,5 @@ export {
   ByoBreakingChangeError
 };
 
-//# debugId=E040C325764492FC64756E2164756E21
+//# debugId=8BECEC189376FB2B64756E2164756E21
 //# sourceMappingURL=index.js.map