@secondlayer/subgraphs 4.1.5 → 4.2.0

package/dist/src/runtime/runner.d.ts

@@ -172,7 +172,12 @@ type TraitScope = {
 *
 * ```ts
 * sources: {
-*   registry: { type: "print_event", contractId: REGISTRY, topic: "pool-created" },
+*   registry: {
+*     type: "print_event",
+*     contractId: REGISTRY,
+*     topic: "pool-created",
+*     prints: { "pool-created": { pool: "principal" } },
+*   },
 *   swaps: {
 *     type: "print_event",
 *     topic: "swap",
@@ -256,6 +261,9 @@ interface ContractCallFilter extends TraitScope, FactoryScope {
 	* decoded function arguments. Dev-provided; serialized into the deployed
 	* definition and used at runtime to decode args by name. Omit to keep
 	* `event.args` as a positional `unknown[]`.
+	*
+	* Deploy validation requires `abi` whenever `functionName` is set
+	* (`normalizeAbi()` from `@secondlayer/stacks/clarity`).
 	*/
 	abi?: AbiContract2;
 }
@@ -286,29 +294,70 @@ type PrintField = ColumnType | {
 } | {
 	list: PrintField
 };
-interface PrintEventFilter extends TraitScope, FactoryScope {
-	type: "print_event";
-	/** One contract id, or a set of them (max 20). Supports `*` wildcards.
-	*  COMPOSES with `trait` — the matcher ANDs them, so the pair means
-	*  "contracts conforming to this trait, narrowed to these ids". (The Index
-	*  read API refuses the combination, but that is its query planner's
-	*  constraint, not a semantic one.) */
-	contractId?: string | readonly string[];
-	topic?: string;
-	/**
-	* 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" } }`).
-	* 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, PrintField>>;
+/**
+* Per-topic field schema for a print_event source. When declared, the handler's
+* `event` is a discriminated union keyed by `topic` and `event.data` is typed
+* per topic. Nested tuples, lists, and optional fields — see {@link PrintField}.
+*
+* Also opts the source into RUNTIME validation: a payload that does not match
+* is skipped and logged rather than written as nulls.
+*/
+type PrintEventPrints = Record<string, Record<string, PrintField>>;
+/**
+* One column in a static identity map. Literals only — the bundler never
+* executes user code, so `{ from: "tokenX" }` is valid and `from("tokenX")`
+* is not.
+*/
+type MaterializeColumn = {
+	from: string
+} | {
+	fromTx: "sender" | "txId"
+} | {
+	fromBlock: "height" | "hash" | "timestamp"
+};
+/** Static insert from a source event — replaces a 1:1 handler. */
+interface MaterializeSpec {
+	table: string;
+	/** Keys = schema column names (snake). */
+	columns: Record<string, MaterializeColumn>;
 }
+type PrintEventFields = FactoryScope & {
+	type: "print_event"
+	topic?: string
+	/** Identity map: insert without a handler function. XOR with handlers[name]. */
+	materialize?: MaterializeSpec
+};
+/**
+* Pinned to one or more contract ids with no trait — `prints` is required so
+* `event.data` is typed and empty-table handlers cannot typecheck.
+*/
+type PinnedPrintEventFilter = PrintEventFields & {
+	contractId: string | readonly string[]
+	trait?: undefined
+	prints: PrintEventPrints
+};
+/**
+* Trait-scoped print source (optionally narrowed by contractId). No single
+* schema — `prints` stays optional.
+*/
+type TraitPrintEventFilter = PrintEventFields & {
+	contractId?: string | readonly string[]
+	trait: string
+	prints?: PrintEventPrints
+};
+/**
+* Unpinned / factory-only print source (no contractId). `prints` optional.
+*/
+type UnpinnedPrintEventFilter = PrintEventFields & {
+	contractId?: undefined
+	trait?: string
+	prints?: PrintEventPrints
+};
+/**
+* Print-event filter. Pinned sources (contractId set, no trait) require
+* `prints`; trait and unpinned sources may omit it.
+*/
+type PrintEventFilter = PinnedPrintEventFilter | TraitPrintEventFilter | UnpinnedPrintEventFilter;
 /** All subgraph filter types — discriminated on `type` */
 type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter;
 /** Transaction metadata available in handlers */

package/dist/src/runtime/runner.js

@@ -302,7 +302,7 @@ function matchSources(sources, transactions, events, traitContracts = new Map, f
 
 // src/runtime/runner.ts
 import { getErrorMessage } from "@secondlayer/shared";
-import { logger } from "@secondlayer/shared/logger";
+import { logger as logger2 } from "@secondlayer/shared/logger";
 import {
   clarityValueToJS,
   deserializeCV as deserializeCV3,
@@ -316,6 +316,19 @@ import {
 function camelizeDataKey(str) {
   return str.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
 }
+function camelizeKeys(obj) {
+  if (obj === null || obj === undefined)
+    return obj;
+  if (typeof obj !== "object")
+    return obj;
+  if (Array.isArray(obj))
+    return obj.map(camelizeKeys);
+  const result = {};
+  for (const [k, v] of Object.entries(obj)) {
+    result[camelizeDataKey(k)] = camelizeKeys(v);
+  }
+  return result;
+}
 function cvToTree(cv) {
   switch (cv.type) {
     case "uint":
@@ -640,6 +653,58 @@ function inferPrintTopics(samples) {
   return out.sort((a, b) => b.count - a.count);
 }
 
+// src/runtime/materialize.ts
+function resolveColumn(col, event, tx, block) {
+  if ("fromTx" in col) {
+    return { ok: true, value: tx[col.fromTx] };
+  }
+  if ("fromBlock" in col) {
+    return { ok: true, value: block[col.fromBlock] };
+  }
+  const data = event.data;
+  const dataObj = data !== null && typeof data === "object" && !Array.isArray(data) ? data : undefined;
+  if (dataObj && Object.prototype.hasOwnProperty.call(dataObj, col.from)) {
+    return { ok: true, value: dataObj[col.from] };
+  }
+  if (col.from === "topic" && "topic" in event) {
+    return { ok: true, value: event.topic };
+  }
+  if (Object.prototype.hasOwnProperty.call(event, col.from)) {
+    return { ok: true, value: event[col.from] };
+  }
+  return { ok: false, missing: col.from };
+}
+function buildMaterializeRow(spec, event, ctx, tableColumns) {
+  const row = {};
+  for (const [colName, mapping] of Object.entries(spec.columns)) {
+    const resolved = resolveColumn(mapping, event, ctx.tx, ctx.block);
+    if (!resolved.ok) {
+      const colDef = tableColumns[colName];
+      if (colDef?.nullable) {
+        row[colName] = null;
+        continue;
+      }
+      return {
+        ok: false,
+        reason: `required materialize field "${resolved.missing}" missing for column "${colName}"`
+      };
+    }
+    row[colName] = resolved.value ?? null;
+  }
+  return { ok: true, row };
+}
+function applyMaterializeInsert(spec, event, ctx, schema) {
+  const table = schema[spec.table];
+  if (!table) {
+    return { ok: false, reason: `materialize table "${spec.table}" missing` };
+  }
+  const built = buildMaterializeRow(spec, event, ctx, table.columns);
+  if (!built.ok)
+    return built;
+  ctx.insert(spec.table, built.row);
+  return { ok: true };
+}
+
 // src/runtime/print-validate.ts
 var COLUMN_TYPES = new Set([
   "text",
@@ -719,21 +784,62 @@ function validatePrintPayload(prints, topic, data) {
   return matchesTopic(declared, data);
 }
 
-// src/runtime/runner.ts
-var DEFAULT_ERROR_THRESHOLD = 50;
-function camelizeKeys(obj) {
-  if (obj === null || obj === undefined)
-    return obj;
-  if (typeof obj !== "object")
-    return obj;
-  if (Array.isArray(obj))
-    return obj.map(camelizeKeys);
-  const result = {};
-  for (const [k, v] of Object.entries(obj)) {
-    result[camelizeDataKey(k)] = camelizeKeys(v);
+// src/runtime/violations.ts
+import { getTargetDb } from "@secondlayer/shared/db";
+import { logger } from "@secondlayer/shared/logger";
+import { sql } from "kysely";
+var VIOLATIONS_CAP_PER_SUBGRAPH = 100;
+function jsonSafe(value) {
+  if (typeof value === "bigint")
+    return value.toString();
+  if (value === null || value === undefined)
+    return value;
+  if (Array.isArray(value))
+    return value.map(jsonSafe);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = jsonSafe(v);
+    }
+    return out;
   }
-  return result;
+  return value;
+}
+async function defaultRecordPrintViolation(input) {
+  try {
+    const db = getTargetDb();
+    const sample = jsonSafe(input.samplePayload);
+    await db.insertInto("subgraph_violations").values({
+      subgraph_name: input.subgraphName,
+      source_name: input.sourceName,
+      block_height: input.blockHeight,
+      tx_id: input.txId,
+      reason: input.reason,
+      sample_payload: sample
+    }).execute();
+    await sql`
+			DELETE FROM subgraph_violations
+			WHERE id IN (
+				SELECT id FROM subgraph_violations
+				WHERE subgraph_name = ${input.subgraphName}
+				ORDER BY seen_at DESC
+				OFFSET ${VIOLATIONS_CAP_PER_SUBGRAPH}
+			)
+		`.execute(db);
+  } catch (err) {
+    logger.warn("Failed to record print violation", {
+      subgraph: input.subgraphName,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+var recorder = defaultRecordPrintViolation;
+async function recordPrintViolation(input) {
+  await recorder(input);
 }
+
+// src/runtime/runner.ts
+var DEFAULT_ERROR_THRESHOLD = 50;
 function decodeFunctionArgs2(args) {
   let parsed = args;
   if (typeof parsed === "string") {
@@ -981,16 +1087,18 @@ async function runHandlers(subgraph, matched, ctx, opts) {
   units.sort((a, b) => (a.tx.tx_index ?? 0) - (b.tx.tx_index ?? 0) || (a.event?.event_index ?? -1) - (b.event?.event_index ?? -1));
   for (const { tx, event, sourceName } of units) {
     if (errors >= threshold) {
-      logger.error("Subgraph error threshold reached, skipping remaining events", {
+      logger2.error("Subgraph error threshold reached, skipping remaining events", {
         subgraph: subgraph.name,
         errors,
         threshold
       });
       return { processed, errors, ...skipped > 0 ? { skipped } : {} };
     }
+    const filter = filterLookup.get(sourceName);
+    const materialize = filter && "materialize" in filter && filter.materialize !== undefined ? filter.materialize : undefined;
     const handler = subgraph.handlers[sourceName] ?? subgraph.handlers["*"] ?? null;
-    if (!handler) {
-      logger.warn("No handler found for source", {
+    if (!handler && !materialize) {
+      logger2.warn("No handler found for source", {
         subgraph: subgraph.name,
         sourceName,
         txId: tx.tx_id
@@ -1005,7 +1113,6 @@ async function runHandlers(subgraph, matched, ctx, opts) {
       contractId: tx.contract_id ?? null,
       functionName: tx.function_name ?? null
     });
-    const filter = filterLookup.get(sourceName);
     const checkpoint = ctx.opsCheckpoint();
     try {
       let payload;
@@ -1047,22 +1154,48 @@ async function runHandlers(subgraph, matched, ctx, opts) {
         const verdict = validatePrintPayload(filter.prints, printPayload.topic ?? "", printPayload.data ?? {});
         if (!verdict.ok) {
           skipped++;
-          logger.warn("Print payload does not match declared prints schema", {
+          logger2.warn("Print payload does not match declared prints schema", {
             subgraph: subgraph.name,
             sourceName,
             topic: printPayload.topic,
             txId: tx.tx_id,
             reason: verdict.reason
           });
+          recordPrintViolation({
+            subgraphName: subgraph.name,
+            sourceName,
+            blockHeight: ctx.block.height,
+            txId: tx.tx_id,
+            reason: verdict.reason,
+            samplePayload: {
+              topic: printPayload.topic ?? "",
+              data: printPayload.data ?? {}
+            }
+          });
+          continue;
+        }
+      }
+      if (materialize) {
+        const result = applyMaterializeInsert(materialize, payload, ctx, subgraph.schema);
+        if (!result.ok) {
+          skipped++;
+          logger2.warn("Materialize skipped: required field missing", {
+            subgraph: subgraph.name,
+            sourceName,
+            txId: tx.tx_id,
+            reason: result.reason
+          });
           continue;
         }
+        processed++;
+      } else if (handler) {
+        await handler(payload, ctx);
+        processed++;
       }
-      await handler(payload, ctx);
-      processed++;
     } catch (err) {
       ctx.rollbackTo(checkpoint);
       errors++;
-      logger.error("Subgraph handler error", {
+      logger2.error("Subgraph handler error", {
         subgraph: subgraph.name,
         sourceName,
         txId: tx.tx_id,
@@ -1079,5 +1212,5 @@ export {
   buildContractCallInput
 };
 
-//# debugId=88617EDFE963086E64756E2164756E21
+//# debugId=B6BA5F58B8903CEC64756E2164756E21
 //# sourceMappingURL=runner.js.map