@secondlayer/subgraphs 7.3.0 → 7.5.0

package/dist/verification.js

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 // package.json
 var package_default = {
   name: "@secondlayer/subgraphs",
-  version: "7.3.0",
+  version: "7.5.0",
   description: "Describe the Stacks data you want as one TypeScript file; it fills itself and survives reorgs.",
   license: "MIT",
   repository: {
@@ -63,7 +63,7 @@ var package_default = {
     prepublishOnly: "bun run build"
   },
   dependencies: {
-    "@secondlayer/shared": "^13.2.0",
+    "@secondlayer/shared": "^13.4.0",
     "@secondlayer/stacks": "^6.4.0",
     "@secondlayer/verify": "^0.6.0",
     esbuild: "^0.28.2",
@@ -279,5 +279,5 @@ export {
   pinPreimage
 };
 
-//# debugId=B00215F36B8986F364756E2164756E21
+//# debugId=77C06EADF44962D564756E2164756E21
 //# sourceMappingURL=verification.js.map

package/dist/verification.js.map

@@ -5,6 +5,6 @@
     "/**\n * Verifiable subgraphs: the determinism contract, the derived level and the\n * pin. Pure (node:crypto only) so the bundler's deploy scan, the API and the\n * runtime realm all read the same rules.\n *\n * A subgraph is never configured as verifiable. Its level is derived from\n * its sources plus a scan of the bundled handler, and only a subgraph whose\n * every input is provable today (`state`: named state writes) has the contract\n * enforced. Everything else gets the same findings as advice.\n */\nimport { createHash } from \"node:crypto\";\nimport type { SubgraphVerification } from \"@secondlayer/shared/schemas/subgraphs\";\nimport pkg from \"../package.json\" with { type: \"json\" };\nimport type { SubgraphDefinition, SubgraphFilter } from \"./types.ts\";\n\nexport type { SubgraphVerification };\n\n/** Runtime identity baked into every pin: matcher, decode and flush semantics. */\nexport const SUBGRAPHS_RUNTIME: string = `@secondlayer/subgraphs@${pkg.version}`;\n\n// ── Determinism contract ────────────────────────────────────────────────\n\n/**\n * Globals a handler may not touch, with the reason shown to the developer.\n * The deploy scan reports them; the realm replaces each with a getter that\n * throws `NondeterminismError`.\n */\nexport const FORBIDDEN_GLOBALS: Readonly<Record<string, string>> = {\n\tDate: \"wall-clock time differs per run\",\n\tperformance: \"timers differ per run\",\n\tprocess: \"host environment differs per run\",\n\tfetch: \"network reads are not chain inputs\",\n\tcrypto: \"randomness differs per run\",\n\tsetTimeout: \"scheduling order differs per run\",\n\tsetInterval: \"scheduling order differs per run\",\n\tsetImmediate: \"scheduling order differs per run\",\n\tclearTimeout: \"scheduling order differs per run\",\n\tclearInterval: \"scheduling order differs per run\",\n\tqueueMicrotask: \"scheduling order differs per run\",\n\tWeakRef: \"garbage collection timing differs per run\",\n\tFinalizationRegistry: \"garbage collection timing differs per run\",\n\tAtomics: \"shared memory is not single-threaded\",\n\tSharedArrayBuffer: \"shared memory is not single-threaded\",\n\tIntl: \"locale and time zone data differ per host\",\n\tTemporal: \"locale and time zone data differ per host\",\n\teval: \"generated code hides inputs from the scan\",\n\tWebAssembly: \"compiled code hides inputs from the scan\",\n\tShadowRealm: \"a nested realm escapes the allow-list\",\n\trequire: \"imports must be bundled into the handler\",\n};\n\n/**\n * Globals a handler may use: ECMAScript built-ins whose results are fully\n * specified, plus deterministic host encoders. `Math` is narrowed separately\n * ({@link ALLOWED_MATH}).\n */\nexport const ALLOWED_GLOBALS: readonly string[] = [\n\t\"undefined\",\n\t\"NaN\",\n\t\"Infinity\",\n\t\"globalThis\",\n\t\"isNaN\",\n\t\"isFinite\",\n\t\"parseInt\",\n\t\"parseFloat\",\n\t\"decodeURI\",\n\t\"decodeURIComponent\",\n\t\"encodeURI\",\n\t\"encodeURIComponent\",\n\t\"escape\",\n\t\"unescape\",\n\t\"Object\",\n\t\"Function\",\n\t\"Array\",\n\t\"Number\",\n\t\"Boolean\",\n\t\"String\",\n\t\"Symbol\",\n\t\"BigInt\",\n\t\"Math\",\n\t\"JSON\",\n\t\"Reflect\",\n\t\"Proxy\",\n\t\"Promise\",\n\t\"Map\",\n\t\"Set\",\n\t\"WeakMap\",\n\t\"WeakSet\",\n\t\"RegExp\",\n\t\"Iterator\",\n\t\"DisposableStack\",\n\t\"AsyncDisposableStack\",\n\t\"Error\",\n\t\"AggregateError\",\n\t\"SuppressedError\",\n\t\"EvalError\",\n\t\"RangeError\",\n\t\"ReferenceError\",\n\t\"SyntaxError\",\n\t\"TypeError\",\n\t\"URIError\",\n\t\"ArrayBuffer\",\n\t\"DataView\",\n\t\"Int8Array\",\n\t\"Uint8Array\",\n\t\"Uint8ClampedArray\",\n\t\"Int16Array\",\n\t\"Uint16Array\",\n\t\"Int32Array\",\n\t\"Uint32Array\",\n\t\"Float16Array\",\n\t\"Float32Array\",\n\t\"Float64Array\",\n\t\"BigInt64Array\",\n\t\"BigUint64Array\",\n\t\"TextEncoder\",\n\t\"TextDecoder\",\n\t\"atob\",\n\t\"btoa\",\n\t\"console\",\n];\n\n/** `Math` members whose results are exact on every engine. The rest\n *  (`sin`, `pow`, `log`, …) are implementation-approximated. */\nexport const ALLOWED_MATH: readonly string[] = [\n\t\"abs\",\n\t\"min\",\n\t\"max\",\n\t\"floor\",\n\t\"ceil\",\n\t\"trunc\",\n\t\"sign\",\n\t\"round\",\n\t\"E\",\n\t\"LN10\",\n\t\"LN2\",\n\t\"LOG10E\",\n\t\"LOG2E\",\n\t\"PI\",\n\t\"SQRT1_2\",\n\t\"SQRT2\",\n];\n\n/** Methods whose output depends on the host's locale data. */\nexport const LOCALE_METHODS: readonly string[] = [\n\t\"toLocaleString\",\n\t\"toLocaleDateString\",\n\t\"toLocaleTimeString\",\n\t\"toLocaleUpperCase\",\n\t\"toLocaleLowerCase\",\n\t\"localeCompare\",\n];\n\n/**\n * One thing the deploy scan found in a bundled handler.\n *\n * - `nondeterministic`: breaks the determinism contract. Fails the deploy of\n *   a state subgraph; advice for everything else.\n * - `needs-events`: deterministic, but reads something only re-execution proofs cover\n *   (`ctx.client`). Raises the level instead of failing.\n */\nexport interface HandlerFinding {\n\tkind: \"nondeterministic\" | \"needs-events\";\n\t/** What was used, e.g. `Date`, `Math.random`, `import()`, `ctx.client`. */\n\tname: string;\n\treason: string;\n\t/** Original source file when a sourcemap was available, else the bundle. */\n\tfile: string;\n\t/** 1-based. */\n\tline: number;\n\t/** 1-based. */\n\tcolumn: number;\n}\n\n/** Formats a handler finding as `file:line:column name: reason`. */\nexport function formatFinding(f: HandlerFinding): string {\n\treturn `${f.file}:${f.line}:${f.column} ${f.name}: ${f.reason}`;\n}\n\n// ── Derived level ───────────────────────────────────────────────────────\n\n/**\n * Sources whose every field is a named state write: provable per block from\n * the header-backed witness plus `state_writes`. Not `map_insert`: storage\n * holds `(some v)` for an insert and a set alike, so telling them apart takes\n * re-execution (event proofs).\n */\nconst STATE_SOURCE_TYPES: ReadonlySet<string> = new Set([\n\t\"var_set\",\n\t\"map_set\",\n\t\"map_delete\",\n]);\n\nconst LEVEL_RANK = { state: 0, events: 1, none: 2 } as const;\n\n/** Handler findings listed in `reasons`; the rest are counted. */\nconst MAX_LISTED_FINDINGS = 10;\n\n/**\n * Derive how far a subgraph's rows can be checked. Level = the highest any\n * source or handler read needs. `reasons` lists everything standing between\n * the subgraph and checkable rows; a `state` subgraph with any reason is\n * refused at deploy, so every stored `state` row has none. Never configured,\n * never a flag.\n */\nexport function deriveVerification(\n\tdef: Pick<SubgraphDefinition, \"sources\" | \"backfillMode\">,\n\tfindings: readonly HandlerFinding[] = [],\n): SubgraphVerification {\n\tlet level: keyof typeof LEVEL_RANK = \"state\";\n\tconst raise = (to: keyof typeof LEVEL_RANK) => {\n\t\tif (LEVEL_RANK[to] > LEVEL_RANK[level]) level = to;\n\t};\n\tconst reasons: string[] = [];\n\n\tfor (const [name, source] of Object.entries(def.sources ?? {})) {\n\t\tconst filter = source as SubgraphFilter & { trait?: string };\n\t\tif (filter.trait) {\n\t\t\traise(\"none\");\n\t\t\treasons.push(\n\t\t\t\t`source \"${name}\": trait scope needs a proven contract registry`,\n\t\t\t);\n\t\t} else if (filter.type === \"map_insert\") {\n\t\t\traise(\"events\");\n\t\t\treasons.push(\n\t\t\t\t`map_insert source \"${name}\": map_insert vs map_set needs event proofs`,\n\t\t\t);\n\t\t} else if (!STATE_SOURCE_TYPES.has(filter.type)) {\n\t\t\traise(\"events\");\n\t\t\treasons.push(`${filter.type} source \"${name}\" needs event proofs`);\n\t\t}\n\t}\n\tif (def.backfillMode === \"concurrent\") {\n\t\traise(\"none\");\n\t\treasons.push(\"backfillMode concurrent: tip-first order is not chain order\");\n\t}\n\tif (findings.some((f) => f.kind === \"needs-events\")) raise(\"events\");\n\t// A large bundled library can trip dozens of findings; list a few.\n\tfor (const f of findings.slice(0, MAX_LISTED_FINDINGS)) {\n\t\treasons.push(\n\t\t\tf.kind === \"needs-events\"\n\t\t\t\t? `${formatFinding(f)} (needs event proofs)`\n\t\t\t\t: formatFinding(f),\n\t\t);\n\t}\n\tif (findings.length > MAX_LISTED_FINDINGS) {\n\t\treasons.push(\n\t\t\t`…and ${findings.length - MAX_LISTED_FINDINGS} more handler findings`,\n\t\t);\n\t}\n\n\treturn {\n\t\tlevel,\n\t\treasons,\n\t\tunproven:\n\t\t\treasons.length === 0\n\t\t\t\t? [\n\t\t\t\t\t\t\"tx attribution of writes: event.tx, _tx_id (needs event proofs)\",\n\t\t\t\t\t\t\"intermediate writes within a block (needs event proofs)\",\n\t\t\t\t\t]\n\t\t\t\t: [],\n\t};\n}\n\n/**\n * Tells whether a deploy must be refused for breaking determinism.\n *\n * It is refused when the sources are provable (`state`), so the determinism\n * contract is enforced, and the scan broke it.\n */\nexport function isDeterminismViolation(v: SubgraphVerification): boolean {\n\treturn v.level === \"state\" && v.reasons.length > 0;\n}\n\n// ── Pin ─────────────────────────────────────────────────────────────────\n\n/** What a pin is computed from: schema hash, handler code, network. */\nexport interface PinInput {\n\t/** Existing `schema_hash` (name + schema + sources). */\n\tschemaHash: string;\n\t/** Bundled ESM exactly as stored in `subgraphs.handler_code`. */\n\thandlerCode: string;\n\tstartBlock?: number | null;\n\tnetwork: string;\n\t/** Defaults to {@link SUBGRAPHS_RUNTIME}. */\n\truntime?: string;\n}\n\nfunction sha256(input: string): string {\n\treturn createHash(\"sha256\").update(input).digest(\"hex\");\n}\n\n/** What a pin commits to, as stored in `pin_preimage`. */\nexport interface PinFields {\n\t/** sha256 of the bundled handler, hex. */\n\thandlerHash: string;\n\tnetwork: string;\n\truntime: string;\n\tschemaHash: string;\n\tstartBlock: number | null;\n}\n\n/**\n * The canonical JSON a pin is the sha256 of: fixed key order, primitives\n * only. Stored beside the pin so anyone can recompute it from the served\n * handler code.\n */\nexport function pinPreimage(input: PinInput): string {\n\tconst fields: PinFields = {\n\t\thandlerHash: sha256(input.handlerCode),\n\t\tnetwork: input.network,\n\t\truntime: input.runtime ?? SUBGRAPHS_RUNTIME,\n\t\tschemaHash: input.schemaHash,\n\t\tstartBlock: input.startBlock ?? null,\n\t};\n\treturn JSON.stringify(fields);\n}\n\n/**\n * Content hash over everything that shapes a subgraph's rows. Unlike\n * `schema_hash`, it changes with the handler, `startBlock` and runtime, so\n * two deploys with the same pin produce the same rows from the same chain.\n */\nexport function computePin(input: PinInput): string {\n\treturn sha256(pinPreimage(input));\n}\n"
   ],
   "mappings": "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",
-  "debugId": "B00215F36B8986F364756E2164756E21",
+  "debugId": "77C06EADF44962D564756E2164756E21",
   "names": []
 }

package/dist/verify/index.js

@@ -1,5 +1,5 @@
 // src/verify/replay.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 import { decodeRawTx } from "@secondlayer/shared/node/tx-summary";
 import {
   BlockVerifier,
@@ -9,7 +9,7 @@ import {
 
 // src/runtime/runner.ts
 import { getErrorMessage } from "@secondlayer/shared";
-import { logger as logger2 } from "@secondlayer/shared/logger";
+import { logger as logger3 } from "@secondlayer/shared/logger";
 import {
   clarityValueToJS,
   deserializeCV as deserializeCV3,
@@ -388,6 +388,158 @@ function decodeEventData(data) {
   return data;
 }
 
+// src/runtime/error-groups.ts
+import { createHash } from "node:crypto";
+import { getTargetDb } from "@secondlayer/shared/db";
+import { logger } from "@secondlayer/shared/logger";
+import { sql } from "kysely";
+var ERROR_GROUPS_CAP_PER_SUBGRAPH = 50;
+var MESSAGE_MAX_CHARS = 500;
+function normalizeMessage(message) {
+  return message.replace(/0x[0-9a-f]+/gi, "<hex>").replace(/(["'`])(?:(?!\1).)*\1/g, "<str>").replace(/\d+/g, "<n>");
+}
+function errorFingerprint(input) {
+  return createHash("sha1").update([
+    input.sourceName,
+    input.eventType ?? "",
+    normalizeMessage(input.message),
+    input.frame ?? ""
+  ].join("|")).digest("hex");
+}
+function topFrame(err) {
+  if (!(err instanceof Error) || !err.stack)
+    return null;
+  for (const line of err.stack.split(`
+`).slice(1)) {
+    const match = /([^/\\\s()]+):(\d+):\d+\)?\s*$/.exec(line);
+    if (match)
+      return `${match[1]}:${match[2]}`;
+  }
+  return null;
+}
+var FLUSH_INTERVAL_MS = 5000;
+var MAX_PENDING_KEYS = 1000;
+var pending = new Map;
+var droppedKeys = 0;
+var flushTimer = null;
+function startFlusher() {
+  if (flushTimer)
+    return;
+  flushTimer = setInterval(() => {
+    flushHandlerErrors();
+  }, FLUSH_INTERVAL_MS);
+  flushTimer.unref();
+}
+async function flushHandlerErrors() {
+  if (pending.size === 0 && droppedKeys === 0)
+    return;
+  const batch = pending;
+  const dropped = droppedKeys;
+  pending = new Map;
+  droppedKeys = 0;
+  if (dropped > 0) {
+    logger.warn("Handler error groups dropped: too many distinct errors", {
+      dropped,
+      cap: MAX_PENDING_KEYS
+    });
+  }
+  if (batch.size === 0)
+    return;
+  try {
+    const db = getTargetDb();
+    const subgraphs = new Set;
+    for (const group of batch.values()) {
+      subgraphs.add(group.subgraphName);
+      await db.insertInto("subgraph_error_groups").values({
+        subgraph_name: group.subgraphName,
+        fingerprint: group.fingerprint,
+        source_name: group.sourceName,
+        event_type: group.eventType,
+        message: group.message,
+        frame: group.frame,
+        count: group.count,
+        sample_tx_id: group.sampleTxId,
+        sample_block_height: group.sampleBlockHeight,
+        first_seen: group.firstSeenAt,
+        last_seen: group.lastSeenAt
+      }).onConflict((oc) => oc.columns(["subgraph_name", "fingerprint"]).doUpdateSet({
+        count: sql`subgraph_error_groups.count + ${group.count}`,
+        last_seen: group.lastSeenAt,
+        sample_tx_id: group.sampleTxId,
+        sample_block_height: group.sampleBlockHeight
+      })).execute();
+    }
+    for (const subgraphName of subgraphs) {
+      await sql`
+				DELETE FROM subgraph_error_groups
+				WHERE id IN (
+					SELECT id FROM subgraph_error_groups
+					WHERE subgraph_name = ${subgraphName}
+					ORDER BY last_seen DESC, id
+					OFFSET ${ERROR_GROUPS_CAP_PER_SUBGRAPH}
+				)
+			`.execute(db);
+    }
+  } catch (err) {
+    logger.warn("Failed to flush handler error groups", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+var recorderOverride = null;
+function recordHandlerError(input) {
+  try {
+    if (recorderOverride) {
+      recorderOverride(input).catch((err) => {
+        logger.warn("Failed to record handler error group", {
+          subgraph: input.subgraphName,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      });
+      return;
+    }
+    const message = (input.err instanceof Error ? input.err.message : String(input.err)).slice(0, MESSAGE_MAX_CHARS);
+    const frame = topFrame(input.err);
+    const fingerprint = errorFingerprint({
+      sourceName: input.sourceName,
+      eventType: input.eventType,
+      message,
+      frame
+    });
+    const key = `${input.subgraphName}|${fingerprint}`;
+    const now = new Date;
+    const existing = pending.get(key);
+    if (existing) {
+      existing.count++;
+      existing.sampleTxId = input.txId;
+      existing.sampleBlockHeight = input.blockHeight;
+      existing.lastSeenAt = now;
+    } else if (pending.size >= MAX_PENDING_KEYS) {
+      droppedKeys++;
+    } else {
+      pending.set(key, {
+        subgraphName: input.subgraphName,
+        fingerprint,
+        sourceName: input.sourceName,
+        eventType: input.eventType,
+        message,
+        frame,
+        count: 1,
+        sampleTxId: input.txId,
+        sampleBlockHeight: input.blockHeight,
+        firstSeenAt: now,
+        lastSeenAt: now
+      });
+    }
+    startFlusher();
+  } catch (err) {
+    logger.warn("Failed to record handler error group", {
+      subgraph: input.subgraphName,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+
 // src/runtime/print-validate.ts
 var COLUMN_TYPES = new Set([
   "text",
@@ -471,11 +623,11 @@ function validatePrintPayload(prints, topic, data) {
 import vm from "node:vm";
 
 // src/verification.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 // package.json
 var package_default = {
   name: "@secondlayer/subgraphs",
-  version: "7.3.0",
+  version: "7.5.0",
   description: "Describe the Stacks data you want as one TypeScript file; it fills itself and survives reorgs.",
   license: "MIT",
   repository: {
@@ -535,7 +687,7 @@ var package_default = {
     prepublishOnly: "bun run build"
   },
   dependencies: {
-    "@secondlayer/shared": "^13.2.0",
+    "@secondlayer/shared": "^13.4.0",
     "@secondlayer/stacks": "^6.4.0",
     "@secondlayer/verify": "^0.6.0",
     esbuild: "^0.28.2",
@@ -723,7 +875,7 @@ function isDeterminismViolation(v) {
   return v.level === "state" && v.reasons.length > 0;
 }
 function sha256(input) {
-  return createHash("sha256").update(input).digest("hex");
+  return createHash2("sha256").update(input).digest("hex");
 }
 function pinPreimage(input) {
   const fields = {
@@ -1307,9 +1459,9 @@ function matchSources(sources, transactions, events, traitContracts = new Map, f
 }
 
 // src/runtime/violations.ts
-import { getTargetDb } from "@secondlayer/shared/db";
-import { logger } from "@secondlayer/shared/logger";
-import { sql } from "kysely";
+import { getTargetDb as getTargetDb2 } from "@secondlayer/shared/db";
+import { logger as logger2 } from "@secondlayer/shared/logger";
+import { sql as sql2 } from "kysely";
 var VIOLATIONS_CAP_PER_SUBGRAPH = 100;
 function jsonSafe(value) {
   if (typeof value === "bigint")
@@ -1329,7 +1481,7 @@ function jsonSafe(value) {
 }
 async function defaultRecordPrintViolation(input) {
   try {
-    const db = getTargetDb();
+    const db = getTargetDb2();
     const sample = jsonSafe(input.samplePayload);
     await db.insertInto("subgraph_violations").values({
       subgraph_name: input.subgraphName,
@@ -1339,7 +1491,7 @@ async function defaultRecordPrintViolation(input) {
       reason: input.reason,
       sample_payload: sample
     }).execute();
-    await sql`
+    await sql2`
 			DELETE FROM subgraph_violations
 			WHERE id IN (
 				SELECT id FROM subgraph_violations
@@ -1349,7 +1501,7 @@ async function defaultRecordPrintViolation(input) {
 			)
 		`.execute(db);
   } catch (err) {
-    logger.warn("Failed to record print violation", {
+    logger2.warn("Failed to record print violation", {
       subgraph: input.subgraphName,
       error: err instanceof Error ? err.message : String(err)
     });
@@ -1691,7 +1843,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
   units.sort((a, b) => (a.tx.tx_index ?? 0) - (b.tx.tx_index ?? 0) || clockRank(a.event) - clockRank(b.event) || (a.event?.event_index ?? -1) - (b.event?.event_index ?? -1));
   for (const { tx, event, sourceName } of units) {
     if (errors >= threshold) {
-      logger2.error("Subgraph error threshold reached, skipping remaining events", {
+      logger3.error("Subgraph error threshold reached, skipping remaining events", {
         subgraph: subgraph.name,
         errors,
         threshold
@@ -1706,7 +1858,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
     const filter = filterLookup.get(sourceName);
     const handler = subgraph.handlers[sourceName] ?? null;
     if (!handler) {
-      logger2.warn("No handler found for source", {
+      logger3.warn("No handler found for source", {
         subgraph: subgraph.name,
         sourceName,
         txId: tx.tx_id
@@ -1763,7 +1915,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
         const verdict = validatePrintPayload(filter.prints, printPayload.topic ?? "", printPayload.data ?? {});
         if (!verdict.ok) {
           skipped++;
-          logger2.warn("Print payload does not match declared prints schema", {
+          logger3.warn("Print payload does not match declared prints schema", {
             subgraph: subgraph.name,
             sourceName,
             topic: printPayload.topic,
@@ -1791,7 +1943,15 @@ async function runHandlers(subgraph, matched, ctx, opts) {
         throw err;
       ctx.rollbackTo(checkpoint);
       errors++;
-      logger2.error("Subgraph handler error", {
+      recordHandlerError({
+        subgraphName: subgraph.name,
+        sourceName,
+        eventType: event?.type ?? null,
+        txId: tx.tx_id,
+        blockHeight: ctx.block.height,
+        err
+      });
+      logger3.error("Subgraph handler error", {
         subgraph: subgraph.name,
         sourceName,
         txId: tx.tx_id,
@@ -1819,11 +1979,11 @@ async function applyBlock(def, data, ctx, scopes = {}) {
 import { normalizeAbi as normalizeAbi2, toCamelCase as toCamelCase3 } from "@secondlayer/stacks/clarity";
 
 // src/runtime/context.ts
-import { logger as logger4 } from "@secondlayer/shared/logger";
-import { sql as sql2 } from "kysely";
+import { logger as logger5 } from "@secondlayer/shared/logger";
+import { sql as sql3 } from "kysely";
 
 // src/schema/generator.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 
 // src/schema/utils.ts
 import { pgSchemaName } from "@secondlayer/shared/db/queries/subgraphs";
@@ -1854,7 +2014,7 @@ var MAX_IDENT_BYTES = 63;
 function safeIndexName(name) {
   if (name.length <= MAX_IDENT_BYTES)
     return name;
-  const hash = createHash2("sha256").update(name).digest("hex").slice(0, 8);
+  const hash = createHash3("sha256").update(name).digest("hex").slice(0, 8);
   return `${name.slice(0, MAX_IDENT_BYTES - hash.length - 1)}_${hash}`;
 }
 function emitIndexedColumnIndexDDL(schemaName, tableName, colName, opts) {
@@ -1985,7 +2145,7 @@ function generateSubgraphSQL(def, schemaNameOverride) {
     schema: def.schema,
     sources: def.sources
   }, (_key, value) => typeof value === "bigint" ? value.toString() : value);
-  const hash = createHash2("sha256").update(hashInput).digest("hex");
+  const hash = createHash3("sha256").update(hashInput).digest("hex");
   return { statements, hash };
 }
 
@@ -1994,7 +2154,7 @@ import { getErrorMessage as getErrorMessage2 } from "@secondlayer/shared";
 import { chainReadArgsHash } from "@secondlayer/shared/chain-read";
 import { getSourceDb } from "@secondlayer/shared/db";
 import { hasNoLocalChain } from "@secondlayer/shared/db/queries/instance";
-import { logger as logger3 } from "@secondlayer/shared/logger";
+import { logger as logger4 } from "@secondlayer/shared/logger";
 import {
   http,
   HttpRequestError,
@@ -2130,7 +2290,7 @@ function createChainReadClient(ctx) {
           throw new HandlerReadError(`Block ${ctx.blockHeight} has no index_block_hash, so a hosted contract read cannot be pinned to it. Reindex the subgraph from this block once the block is re-ingested.`);
         }
         if (!ctx.indexBlockHash) {
-          logger3.warn("Chain read is not pinned to a block (no index_block_hash)", {
+          logger4.warn("Chain read is not pinned to a block (no index_block_hash)", {
             contractId,
             functionName: fn.name,
             blockHeight: ctx.blockHeight,
@@ -2258,7 +2418,7 @@ class SubgraphContext {
         data: { ...key, ...row, ...meta, _upsert_keys: keyColumns }
       });
     } else {
-      logger4.warn("upsert called without matching uniqueKeys constraint, using fallback", {
+      logger5.warn("upsert called without matching uniqueKeys constraint, using fallback", {
         table,
         keys: keyColumns
       });
@@ -2320,7 +2480,7 @@ class SubgraphContext {
     const qualifiedTable = `"${this.pgSchemaName}"."${table}"`;
     const { clause } = buildWhereClause(where);
     const query = `SELECT * FROM ${qualifiedTable} WHERE ${clause} ORDER BY "_id"${limit !== undefined ? ` LIMIT ${limit}` : ""}`;
-    const { rows } = await sql2.raw(query).execute(this.db);
+    const { rows } = await sql3.raw(query).execute(this.db);
     return rows.map((r) => this.coerceRow(table, r));
   }
   async findOne(table, where) {
@@ -2466,16 +2626,16 @@ class SubgraphContext {
     const affected = (r) => r.numAffectedRows ?? 0n;
     for (const stmt of statements) {
       if (typeof stmt === "string") {
-        await sql2.raw(stmt).execute(executor);
+        await sql3.raw(stmt).execute(executor);
         continue;
       }
-      const updated = await sql2.raw(stmt.update).execute(executor);
+      const updated = await sql3.raw(stmt.update).execute(executor);
       if (affected(updated) > 0n)
         continue;
-      const inserted = await sql2.raw(stmt.insert).execute(executor);
+      const inserted = await sql3.raw(stmt.insert).execute(executor);
       if (affected(inserted) > 0n)
         continue;
-      const retried = await sql2.raw(stmt.update).execute(executor);
+      const retried = await sql3.raw(stmt.update).execute(executor);
       if (affected(retried) === 0n) {
         throw new Error(`increment could not be applied to ${this.pgSchemaName}.${stmt.table} where ${stmt.keyPred}: row neither updated nor inserted`);
       }
@@ -2501,13 +2661,13 @@ class SubgraphContext {
   async ensureJournalTable() {
     if (!this.journal || journalEnsured.has(this.pgSchemaName))
       return;
-    const { rows } = await sql2.raw(`SELECT to_regclass('"${this.pgSchemaName}"."_journal"') AS r`).execute(this.db);
+    const { rows } = await sql3.raw(`SELECT to_regclass('"${this.pgSchemaName}"."_journal"') AS r`).execute(this.db);
     if (rows[0]?.r) {
       journalEnsured.add(this.pgSchemaName);
       return;
     }
     for (const stmt of emitJournalDDL(this.pgSchemaName)) {
-      await sql2.raw(stmt).execute(this.db);
+      await sql3.raw(stmt).execute(this.db);
     }
   }
   columnSqlType(table, col) {
@@ -2863,7 +3023,7 @@ function sameValue(a, b) {
 }
 
 // src/runtime/batch-loader.ts
-import { sql as sql3 } from "kysely";
+import { sql as sql4 } from "kysely";
 function stateWriteBlocks(writesByHeight, txsByHeight) {
   const out = new Map;
   for (const [height, writes] of writesByHeight) {
@@ -2945,8 +3105,8 @@ async function loadBlockRange(db, fromHeight, toHeight, opts = {}) {
   return result;
 }
 async function loadStateWrites(db, fromHeight, toHeight, feed) {
-  const scope = feed.contracts ? sql3`AND (${sql3.join(feed.contracts.map((c) => sql3`starts_with(key, ${`vm::${c}::`})`), sql3` OR `)})` : sql3``;
-  const { rows } = await sql3`
+  const scope = feed.contracts ? sql4`AND (${sql4.join(feed.contracts.map((c) => sql4`starts_with(key, ${`vm::${c}::`})`), sql4` OR `)})` : sql4``;
+  const { rows } = await sql4`
 		SELECT block_height, ordinal, tx_index, key, value_hex
 		FROM state_writes
 		WHERE block_height >= ${fromHeight} AND block_height <= ${toHeight} ${scope}
@@ -3087,7 +3247,7 @@ function replayContracts(def) {
   }
   return [...out];
 }
-var sha2562 = (s) => createHash3("sha256").update(s).digest("hex");
+var sha2562 = (s) => createHash4("sha256").update(s).digest("hex");
 function checkPin(served, def) {
   if (!served.pin || !served.pinPreimage)
     return { status: "unchecked", notes: [] };
@@ -3329,7 +3489,7 @@ async function replaySubgraph(opts) {
   }, { ...opts, bitcoinCheckpoint: checkpoint.bitcoin.height });
 }
 // src/verify/compare.ts
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash5 } from "node:crypto";
 function canonicalJson(value) {
   if (typeof value === "bigint")
     return value.toString();
@@ -3372,7 +3532,7 @@ function canonicalRow(def, row, columns = Object.keys(def.columns).sort()) {
 }
 var line = (r) => JSON.stringify(r);
 function digest(lines) {
-  return createHash4("sha256").update([...lines].sort().join(`
+  return createHash5("sha256").update([...lines].sort().join(`
 `)).digest("hex");
 }
 var heightOf = (row) => Number(row._block_height);
@@ -3465,5 +3625,5 @@ export {
   replaySubgraph
 };
 
-//# debugId=4966C31FE93CC61864756E2164756E21
+//# debugId=D8DAF87FB8AF0A3A64756E2164756E21
 //# sourceMappingURL=index.js.map