@secondlayer/subgraphs 6.3.6 → 6.5.0

package/dist/schema/index.d.ts

@@ -16,7 +16,7 @@ import { AssetIdentifier } from "@secondlayer/stacks/filters";
 */
 type ChainReadCacheMode = "per-block" | "contract-constant";
 type ChainReadOptions = {
-	cache?: ChainReadCacheMode
+	cache?: ChainReadCacheMode;
 };
 /**
 * `ChainReadClient` with the ABI generic erased. Structurally cheap, so the
@@ -25,7 +25,7 @@ type ChainReadOptions = {
 */
 interface ErasedChainReadClient {
 	contract(contractId: string, abi: unknown, options?: ChainReadOptions): {
-		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>
+		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>;
 	};
 }
 /** Supported column types for subgraph schemas */
@@ -86,7 +86,7 @@ interface StxLockFilter {
 * as-of each processed block. Lets a source index "all SIP-010 tokens" etc.
 */
 type TraitScope = {
-	trait?: string
+	trait?: string;
 };
 /**
 * Scope a source to a DYNAMIC address set discovered from another source's
@@ -126,10 +126,10 @@ type TraitScope = {
 interface FactoryScope {
 	factory?: {
 		/** Source name whose events reveal the addresses. */
-		from: string
+		from: string;
 		/** Dotted path to the address on that source's payload
 		*  (e.g. `"data.pool"`, `"contractId"`, `"data.token.id"`). */
-		field: string
+		field: string;
 	};
 }
 /** FT event filters */
@@ -235,12 +235,12 @@ interface MapWriteFilter extends TraitScope, FactoryScope {
 * - `{ list: F }` — a list of `F`.
 */
 type PrintField = ColumnType | {
-	type: PrintField
-	optional: true
+	type: PrintField;
+	optional: true;
 } | {
-	tuple: Record<string, PrintField>
+	tuple: Record<string, PrintField>;
 } | {
-	list: PrintField
+	list: PrintField;
 };
 /**
 * Per-topic field schema for a print_event source. When declared, the handler's
@@ -252,34 +252,34 @@ type PrintField = ColumnType | {
 */
 type PrintEventPrints = Record<string, Record<string, PrintField>>;
 type PrintEventFields = FactoryScope & {
-	type: "print_event"
-	topic?: string
+	type: "print_event";
+	topic?: string;
 };
 /**
 * 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
+	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
+	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
+	contractId?: undefined;
+	trait?: string;
+	prints?: PrintEventPrints;
 };
 /**
 * Print-event filter. Pinned sources (contractId set, no trait) require
@@ -300,12 +300,12 @@ interface TxMeta {
 /** Context passed to subgraph handlers during event processing */
 interface SubgraphContext {
 	block: {
-		height: number
-		hash: string
-		timestamp: number
-		burnBlockHeight: number
+		height: number;
+		hash: string;
+		timestamp: number;
+		burnBlockHeight: number;
 		/** Nakamoto StacksBlockId, when the block row carries one. */
-		indexBlockHash?: string | null
+		indexBlockHash?: string | null;
 	};
 	tx: TxMeta;
 	/**
@@ -366,6 +366,7 @@ interface GeneratedSQL {
 declare function generateSubgraphSQL(def: SubgraphDefinition, schemaNameOverride?: string): GeneratedSQL;
 import { Database as Database2 } from "@secondlayer/shared/db";
 import { Kysely as Kysely2 } from "kysely";
+import { SubgraphVerification } from "@secondlayer/shared/schemas/subgraphs";
 type AnyDb = Kysely2<Database2>;
 interface TableDiff {
 	/** Tables added to the schema */
@@ -422,18 +423,24 @@ interface DeployDiff {
 * - Breaking change → auto-reindex (drop + recreate)
 */
 declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: string, opts?: {
-	forceReindex?: boolean
-	apiKeyId?: string
-	accountId?: string
-	schemaName?: string
-	handlerCode?: string
-	sourceCode?: string
+	forceReindex?: boolean;
+	apiKeyId?: string;
+	accountId?: string;
+	schemaName?: string;
+	handlerCode?: string;
+	sourceCode?: string;
+	/** Derived level to store (see `deriveVerification`). */
+	verification?: SubgraphVerification;
+	/** Network baked into the pin. Defaults to `NETWORK`, then mainnet. */
+	network?: string;
 }): Promise<{
-	action: "created" | "unchanged" | "handler_updated" | "updated" | "reindexed"
-	subgraphId: string
-	version: string
-	diff?: DeployDiff
+	action: "created" | "unchanged" | "handler_updated" | "updated" | "reindexed";
+	subgraphId: string;
+	version: string;
+	/** Present when the deploy carried a bundled handler. */
+	pin?: string;
+	diff?: DeployDiff;
 	/** Non-fatal caveats the caller should surface (e.g. handler grafts at tip). */
-	warnings?: string[]
+	warnings?: string[];
 }>;
 export { ColumnDiff, GeneratedSQL, TYPE_MAP, TableDiff, deploySchema, diffSchema, generateSubgraphSQL };

package/dist/schema/index.js

@@ -461,6 +461,274 @@ function filterFieldsByType() {
   return out;
 }
 
+// src/verification.ts
+import { createHash as createHash2 } from "node:crypto";
+// package.json
+var package_default = {
+  name: "@secondlayer/subgraphs",
+  version: "6.5.0",
+  description: "Describe the Stacks data you want as one TypeScript file; it fills itself and survives reorgs.",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/ryanwaits/secondlayer.git",
+    directory: "packages/subgraphs"
+  },
+  homepage: "https://github.com/ryanwaits/secondlayer/tree/main/packages/subgraphs#readme",
+  type: "module",
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./types": {
+      types: "./dist/types.d.ts",
+      import: "./dist/types.js"
+    },
+    "./schema": {
+      types: "./dist/schema/index.d.ts",
+      import: "./dist/schema/index.js"
+    },
+    "./validate": {
+      types: "./dist/validate.d.ts",
+      import: "./dist/validate.js"
+    },
+    "./verification": {
+      types: "./dist/verification.d.ts",
+      import: "./dist/verification.js"
+    },
+    "./runtime/replay": {
+      types: "./dist/runtime/replay.d.ts",
+      import: "./dist/runtime/replay.js"
+    },
+    "./runtime/emitter": {
+      types: "./dist/runtime/emitter.d.ts",
+      import: "./dist/runtime/emitter.js"
+    },
+    "./testing": {
+      types: "./dist/testing/index.d.ts",
+      import: "./dist/testing/index.js"
+    },
+    "./verify": {
+      types: "./dist/verify/index.d.ts",
+      import: "./dist/verify/index.js"
+    }
+  },
+  files: ["dist"],
+  scripts: {
+    build: "bunup",
+    dev: "bunup --watch",
+    test: "bun test",
+    typecheck: "tsc --noEmit",
+    prepublishOnly: "bun run build"
+  },
+  dependencies: {
+    "@secondlayer/shared": "^11.23.0",
+    "@secondlayer/stacks": "^6.2.0",
+    "@secondlayer/verify": "^0.3.0",
+    esbuild: "^0.28.2",
+    kysely: "0.28.17",
+    zod: "^4.3.6"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    bunup: "0.16.32",
+    typescript: "^5"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/verification.ts
+var SUBGRAPHS_RUNTIME = `@secondlayer/subgraphs@${package_default.version}`;
+var FORBIDDEN_GLOBALS = {
+  Date: "wall-clock time differs per run",
+  performance: "timers differ per run",
+  process: "host environment differs per run",
+  fetch: "network reads are not chain inputs",
+  crypto: "randomness differs per run",
+  setTimeout: "scheduling order differs per run",
+  setInterval: "scheduling order differs per run",
+  setImmediate: "scheduling order differs per run",
+  clearTimeout: "scheduling order differs per run",
+  clearInterval: "scheduling order differs per run",
+  queueMicrotask: "scheduling order differs per run",
+  WeakRef: "garbage collection timing differs per run",
+  FinalizationRegistry: "garbage collection timing differs per run",
+  Atomics: "shared memory is not single-threaded",
+  SharedArrayBuffer: "shared memory is not single-threaded",
+  Intl: "locale and time zone data differ per host",
+  Temporal: "locale and time zone data differ per host",
+  eval: "generated code hides inputs from the scan",
+  WebAssembly: "compiled code hides inputs from the scan",
+  ShadowRealm: "a nested realm escapes the allow-list",
+  require: "imports must be bundled into the handler"
+};
+var ALLOWED_GLOBALS = [
+  "undefined",
+  "NaN",
+  "Infinity",
+  "globalThis",
+  "isNaN",
+  "isFinite",
+  "parseInt",
+  "parseFloat",
+  "decodeURI",
+  "decodeURIComponent",
+  "encodeURI",
+  "encodeURIComponent",
+  "escape",
+  "unescape",
+  "Object",
+  "Function",
+  "Array",
+  "Number",
+  "Boolean",
+  "String",
+  "Symbol",
+  "BigInt",
+  "Math",
+  "JSON",
+  "Reflect",
+  "Proxy",
+  "Promise",
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "RegExp",
+  "Iterator",
+  "DisposableStack",
+  "AsyncDisposableStack",
+  "Error",
+  "AggregateError",
+  "SuppressedError",
+  "EvalError",
+  "RangeError",
+  "ReferenceError",
+  "SyntaxError",
+  "TypeError",
+  "URIError",
+  "ArrayBuffer",
+  "DataView",
+  "Int8Array",
+  "Uint8Array",
+  "Uint8ClampedArray",
+  "Int16Array",
+  "Uint16Array",
+  "Int32Array",
+  "Uint32Array",
+  "Float16Array",
+  "Float32Array",
+  "Float64Array",
+  "BigInt64Array",
+  "BigUint64Array",
+  "TextEncoder",
+  "TextDecoder",
+  "atob",
+  "btoa",
+  "console"
+];
+var ALLOWED_MATH = [
+  "abs",
+  "min",
+  "max",
+  "floor",
+  "ceil",
+  "trunc",
+  "sign",
+  "round",
+  "E",
+  "LN10",
+  "LN2",
+  "LOG10E",
+  "LOG2E",
+  "PI",
+  "SQRT1_2",
+  "SQRT2"
+];
+var LOCALE_METHODS = [
+  "toLocaleString",
+  "toLocaleDateString",
+  "toLocaleTimeString",
+  "toLocaleUpperCase",
+  "toLocaleLowerCase",
+  "localeCompare"
+];
+function formatFinding(f) {
+  return `${f.file}:${f.line}:${f.column} ${f.name}: ${f.reason}`;
+}
+var STATE_SOURCE_TYPES = new Set([
+  "var_set",
+  "map_set",
+  "map_delete"
+]);
+var LEVEL_RANK = { state: 0, events: 1, none: 2 };
+var MAX_LISTED_FINDINGS = 10;
+function deriveVerification(def, findings = []) {
+  let level = "state";
+  const raise = (to) => {
+    if (LEVEL_RANK[to] > LEVEL_RANK[level])
+      level = to;
+  };
+  const reasons = [];
+  for (const [name, source] of Object.entries(def.sources ?? {})) {
+    const filter = source;
+    if (filter.trait) {
+      raise("none");
+      reasons.push(`source "${name}": trait scope needs a proven contract registry`);
+    } else if (filter.type === "map_insert") {
+      raise("events");
+      reasons.push(`map_insert source "${name}": map_insert vs map_set needs event proofs`);
+    } else if (!STATE_SOURCE_TYPES.has(filter.type)) {
+      raise("events");
+      reasons.push(`${filter.type} source "${name}" needs event proofs`);
+    }
+  }
+  if (def.backfillMode === "concurrent") {
+    raise("none");
+    reasons.push("backfillMode concurrent: tip-first order is not chain order");
+  }
+  if (findings.some((f) => f.kind === "needs-events"))
+    raise("events");
+  for (const f of findings.slice(0, MAX_LISTED_FINDINGS)) {
+    reasons.push(f.kind === "needs-events" ? `${formatFinding(f)} (needs event proofs)` : formatFinding(f));
+  }
+  if (findings.length > MAX_LISTED_FINDINGS) {
+    reasons.push(`…and ${findings.length - MAX_LISTED_FINDINGS} more handler findings`);
+  }
+  return {
+    level,
+    reasons,
+    unproven: reasons.length === 0 ? [
+      "tx attribution of writes: event.tx, _tx_id (needs event proofs)",
+      "intermediate writes within a block (needs event proofs)"
+    ] : []
+  };
+}
+function isDeterminismViolation(v) {
+  return v.level === "state" && v.reasons.length > 0;
+}
+function sha256(input) {
+  return createHash2("sha256").update(input).digest("hex");
+}
+function pinPreimage(input) {
+  const fields = {
+    handlerHash: sha256(input.handlerCode),
+    network: input.network,
+    runtime: input.runtime ?? SUBGRAPHS_RUNTIME,
+    schemaHash: input.schemaHash,
+    startBlock: input.startBlock ?? null
+  };
+  return JSON.stringify(fields);
+}
+function computePin(input) {
+  return sha256(pinPreimage(input));
+}
+
 // src/schema/deployer.ts
 function toJsonSafe(obj) {
   return JSON.parse(JSON.stringify(obj, (_key, value) => typeof value === "bigint" ? value.toString() : value));
@@ -558,6 +826,15 @@ function renderDeployPlan(def, schemaName) {
 async function deploySchema(db, def, handlerPath, opts) {
   validateSubgraphDefinition(def);
   const { statements, hash } = generateSubgraphSQL(def, opts?.schemaName);
+  const pinInput = opts?.handlerCode != null ? {
+    schemaHash: hash,
+    handlerCode: opts.handlerCode,
+    startBlock: def.startBlock,
+    network: opts.network ?? process.env.NETWORK ?? "mainnet"
+  } : null;
+  const pin = pinInput ? computePin(pinInput) : null;
+  const preimage = pinInput ? pinPreimage(pinInput) : null;
+  const identity = pin ? { pin } : {};
   const { getSubgraph, registerSubgraph } = await import("@secondlayer/shared/db/queries/subgraphs");
   const ddlDb = db;
   const existing = await getSubgraph(db, def.name, opts?.accountId);
@@ -580,7 +857,10 @@ async function deploySchema(db, def, handlerPath, opts) {
     handlerCode: opts?.handlerCode,
     sourceCode: opts?.sourceCode,
     schemaName,
-    startBlock: def.startBlock
+    startBlock: def.startBlock,
+    pin,
+    pinPreimage: preimage,
+    verification: opts?.verification ?? null
   };
   if (existing) {
     const schemaExists = await sql`
@@ -594,19 +874,28 @@ async function deploySchema(db, def, handlerPath, opts) {
         await sql.raw(stmt).execute(ddlDb);
       }
       const sg = await registerSubgraph(db, regData);
-      return { action: "reindexed", subgraphId: sg.id, version: newVersion };
+      return {
+        action: "reindexed",
+        subgraphId: sg.id,
+        version: newVersion,
+        ...identity
+      };
     }
     if (existing.schema_hash === hash && !opts?.forceReindex) {
       const handlerChanged = opts?.handlerCode != null && opts.handlerCode !== existing.handler_code;
       const { updateSubgraphHandlerPath } = await import("@secondlayer/shared/db/queries/subgraphs");
       await updateSubgraphHandlerPath(db, def.name, handlerPath, {
         handlerCode: opts?.handlerCode,
-        sourceCode: opts?.sourceCode
+        sourceCode: opts?.sourceCode,
+        pin,
+        pinPreimage: preimage,
+        verification: opts?.verification ?? null
       });
       return {
         action: handlerChanged ? "handler_updated" : "unchanged",
         subgraphId: existing.id,
         version: existing.version,
+        ...identity,
         ...handlerChanged ? {
           warnings: [
             "handler changed but schema did not: new logic applies from the current tip only. Rows already indexed were computed by the previous handler. To recompute history, redeploy with --reindex (or backfill a range)."
@@ -620,7 +909,12 @@ async function deploySchema(db, def, handlerPath, opts) {
         await sql.raw(stmt).execute(ddlDb);
       }
       const sg = await registerSubgraph(db, regData);
-      return { action: "reindexed", subgraphId: sg.id, version: newVersion };
+      return {
+        action: "reindexed",
+        subgraphId: sg.id,
+        version: newVersion,
+        ...identity
+      };
     }
     if (existing.definition.schema) {
       const diff = diffSchema(existing.definition.schema, def.schema);
@@ -636,6 +930,7 @@ async function deploySchema(db, def, handlerPath, opts) {
           action: "reindexed",
           subgraphId: sg.id,
           version: newVersion,
+          ...identity,
           diff: deployDiff
         };
       }
@@ -755,6 +1050,7 @@ async function deploySchema(db, def, handlerPath, opts) {
         action: "updated",
         subgraphId: sg.id,
         version: newVersion,
+        ...identity,
         diff: deployDiff
       };
     }
@@ -763,7 +1059,12 @@ async function deploySchema(db, def, handlerPath, opts) {
     await sql.raw(stmt).execute(ddlDb);
   }
   const sg = await registerSubgraph(db, regData);
-  return { action: "created", subgraphId: sg.id, version: newVersion };
+  return {
+    action: "created",
+    subgraphId: sg.id,
+    version: newVersion,
+    ...identity
+  };
 }
 function getDefault(type) {
   switch (type) {
@@ -790,5 +1091,5 @@ export {
   generateSubgraphSQL
 };
 
-//# debugId=054E6A0FD91586DA64756E2164756E21
+//# debugId=858E528FDE59D30764756E2164756E21
 //# sourceMappingURL=index.js.map