@secondlayer/subgraphs 3.20.0 → 3.21.0

package/dist/src/runtime/block-processor.d.ts

@@ -124,18 +124,45 @@ interface ContractDeployFilter {
 	deployer?: string;
 	contractName?: string;
 }
+/**
+* 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 {
 	type: "print_event";
 	contractId?: 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/block-processor.js

@@ -758,6 +758,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 +1083,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 +1108,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 +1164,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,7 +1193,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
       });
     }
   }
-  return { processed, errors };
+  return { processed, errors, ...skipped > 0 ? { skipped } : {} };
 }
 
 // src/runtime/source-matcher.ts
@@ -2244,5 +2341,5 @@ export {
   BLOCK_RETRY_DELAYS_MS
 };
 
-//# debugId=787B3926873D0C0764756E2164756E21
+//# debugId=6575DE1AB15AD38164756E2164756E21
 //# sourceMappingURL=block-processor.js.map