@secondlayer/subgraphs 6.3.6 → 6.4.0

package/dist/index.js

@@ -782,8 +782,476 @@ function createChainReadClient(ctx) {
     }
   };
 }
-// src/schema/generator.ts
+// src/verification.ts
 import { createHash } from "node:crypto";
+// package.json
+var package_default = {
+  name: "@secondlayer/subgraphs",
+  version: "6.4.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"
+    }
+  },
+  files: ["dist"],
+  scripts: {
+    build: "bunup",
+    dev: "bunup --watch",
+    test: "bun test",
+    typecheck: "tsc --noEmit",
+    prepublishOnly: "bun run build"
+  },
+  dependencies: {
+    "@secondlayer/shared": "^11.22.0",
+    "@secondlayer/stacks": "^6.1.0",
+    esbuild: "^0.28.2",
+    kysely: "0.28.17",
+    zod: "^4.3.6"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    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_insert",
+  "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 (!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`);
+  }
+  const writesMapInsert = Object.values(def.sources ?? {}).some((s) => s.type === "map_insert");
+  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)",
+      ...writesMapInsert ? ["map_insert vs map_set (needs event proofs)"] : []
+    ] : []
+  };
+}
+function isDeterminismViolation(v) {
+  return v.level === "state" && v.reasons.length > 0;
+}
+function sha256(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+function computePin(input) {
+  const canonical = JSON.stringify({
+    handlerHash: sha256(input.handlerCode),
+    network: input.network,
+    runtime: input.runtime ?? SUBGRAPHS_RUNTIME,
+    schemaHash: input.schemaHash,
+    startBlock: input.startBlock ?? null
+  });
+  return sha256(canonical);
+}
+// src/runtime/realm.ts
+import vm from "node:vm";
+class NondeterminismError extends Error {
+  name = "NondeterminismError";
+}
+
+class HandlerReadError extends Error {
+  name = "HandlerReadError";
+}
+var HOST_GLOBALS = [
+  "ArrayBuffer",
+  "DataView",
+  "Int8Array",
+  "Uint8Array",
+  "Uint8ClampedArray",
+  "Int16Array",
+  "Uint16Array",
+  "Int32Array",
+  "Uint32Array",
+  "Float16Array",
+  "Float32Array",
+  "Float64Array",
+  "BigInt64Array",
+  "BigUint64Array",
+  "TextEncoder",
+  "TextDecoder",
+  "atob",
+  "btoa"
+];
+function forbid(name, reason) {
+  return () => {
+    throw new NondeterminismError(`${name}: ${reason}`);
+  };
+}
+function createRealm() {
+  const host = globalThis;
+  const sandbox = Object.create(null);
+  for (const name of HOST_GLOBALS) {
+    if (host[name] !== undefined)
+      sandbox[name] = host[name];
+  }
+  const context = vm.createContext(sandbox, {
+    name: "subgraph-handler",
+    codeGeneration: { strings: false, wasm: false }
+  });
+  const g = vm.runInContext("globalThis", context);
+  const allowed = new Set(ALLOWED_GLOBALS);
+  for (const name of Object.getOwnPropertyNames(g)) {
+    if (!allowed.has(name))
+      delete g[name];
+  }
+  for (const [name, reason] of Object.entries(FORBIDDEN_GLOBALS)) {
+    Object.defineProperty(g, name, { get: forbid(name, reason) });
+  }
+  const realmMath = g.Math;
+  const safeMath = {};
+  const allowedMath = new Set(ALLOWED_MATH);
+  for (const key of Object.getOwnPropertyNames(realmMath)) {
+    if (allowedMath.has(key))
+      safeMath[key] = realmMath[key];
+    else
+      Object.defineProperty(safeMath, key, {
+        get: forbid(`Math.${key}`, key === "random" ? "randomness differs per run" : "result is engine-approximated")
+      });
+  }
+  Object.defineProperty(g, "Math", { value: Object.freeze(safeMath) });
+  for (const ctor of ["String", "Number", "BigInt", "Array", "Object"]) {
+    const proto = g[ctor].prototype;
+    for (const method of LOCALE_METHODS) {
+      if (Object.prototype.hasOwnProperty.call(proto, method)) {
+        Object.defineProperty(proto, method, {
+          value: forbid(method, "output depends on the host's locale data")
+        });
+      }
+    }
+  }
+  Object.preventExtensions(g);
+  return context;
+}
+function checkRowValues(where, values) {
+  for (const [col, value] of Object.entries(values)) {
+    checkValue(value, `${where}.${col}`);
+  }
+}
+function checkValue(value, path) {
+  switch (typeof value) {
+    case "number":
+      if (!Number.isSafeInteger(value)) {
+        throw new TypeError(`${path}: ${value} is not a safe integer; verifiable subgraphs store bigint or integers only`);
+      }
+      return;
+    case "function":
+    case "symbol":
+      throw new TypeError(`${path}: a ${typeof value} is not a row value`);
+    case "object":
+      if (value === null || ArrayBuffer.isView(value))
+        return;
+      if (Array.isArray(value)) {
+        value.forEach((v, i) => checkValue(v, `${path}[${i}]`));
+        return;
+      }
+      for (const [k, v] of Object.entries(value))
+        checkValue(v, `${path}.${k}`);
+      return;
+    default:
+      return;
+  }
+}
+function deterministicContext(ctx, schema) {
+  let pendingReads = 0;
+  const knownTable = (table) => {
+    if (!Object.prototype.hasOwnProperty.call(schema, table)) {
+      throw new Error(`Table "${table}" not found in subgraph schema`);
+    }
+  };
+  const guard = (op) => {
+    if (pendingReads > 0) {
+      throw new NondeterminismError(`ctx.${op} while a ctx read is pending: concurrent ctx calls order writes by database latency; await each read before the next call`);
+    }
+  };
+  const read = async (op, run) => {
+    guard(op);
+    pendingReads++;
+    try {
+      return await run();
+    } catch (err) {
+      if (err instanceof NondeterminismError)
+        throw err;
+      throw new HandlerReadError(`ctx.${op} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    } finally {
+      pendingReads--;
+    }
+  };
+  return {
+    get block() {
+      return ctx.block;
+    },
+    get tx() {
+      return ctx.tx;
+    },
+    get client() {
+      throw new NondeterminismError("ctx.client: contract reads need re-execution proofs");
+    },
+    insert(table, row) {
+      guard("insert");
+      checkRowValues(`insert ${table}`, row);
+      ctx.insert(table, row);
+    },
+    update(table, where, set) {
+      guard("update");
+      checkRowValues(`update ${table}`, where);
+      checkRowValues(`update ${table}`, set);
+      ctx.update(table, where, set);
+    },
+    upsert(table, key, row) {
+      guard("upsert");
+      checkRowValues(`upsert ${table}`, key);
+      checkRowValues(`upsert ${table}`, row);
+      ctx.upsert(table, key, row);
+    },
+    delete(table, where) {
+      guard("delete");
+      ctx.delete(table, where);
+    },
+    increment(table, key, deltas) {
+      guard("increment");
+      checkRowValues(`increment ${table}`, key);
+      checkRowValues(`increment ${table}`, deltas);
+      ctx.increment(table, key, deltas);
+    },
+    findOne: (table, where) => {
+      knownTable(table);
+      return read("findOne", () => ctx.findOne(table, where));
+    },
+    findMany: (table, ...rest) => {
+      knownTable(table);
+      return read("findMany", () => ctx.findMany(table, ...rest));
+    }
+  };
+}
+async function loadDeterministicDefinition(handlerCode) {
+  const { transform } = await import("esbuild");
+  const { code } = await transform(handlerCode, {
+    format: "cjs",
+    loader: "js",
+    logLevel: "silent"
+  });
+  const context = createRealm();
+  const evaluate = vm.runInContext(`(function (module, exports) {
+${code}
+})`, context, { filename: "handler.js" });
+  const mod = { exports: {} };
+  evaluate(mod, mod.exports);
+  const def = mod.exports.default ?? mod.exports;
+  const sources = structuredClone(def.sources);
+  const schema = structuredClone(def.schema);
+  const facades = new WeakMap;
+  const handlers = {};
+  for (const [name, handler] of Object.entries(def.handlers ?? {})) {
+    handlers[name] = (event, ctx) => {
+      let facade = facades.get(ctx);
+      if (!facade) {
+        facade = deterministicContext(ctx, schema);
+        facades.set(ctx, facade);
+      }
+      return handler(event, facade);
+    };
+  }
+  return { ...def, sources, schema, handlers };
+}
+// src/schema/generator.ts
+import { createHash as createHash2 } from "node:crypto";
 
 // src/schema/utils.ts
 import { pgSchemaName } from "@secondlayer/shared/db/queries/subgraphs";
@@ -814,7 +1282,7 @@ var MAX_IDENT_BYTES = 63;
 function safeIndexName(name) {
   if (name.length <= MAX_IDENT_BYTES)
     return name;
-  const hash = createHash("sha256").update(name).digest("hex").slice(0, 8);
+  const hash = createHash2("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) {
@@ -945,7 +1413,7 @@ function generateSubgraphSQL(def, schemaNameOverride) {
     schema: def.schema,
     sources: def.sources
   }, (_key, value) => typeof value === "bigint" ? value.toString() : value);
-  const hash = createHash("sha256").update(hashInput).digest("hex");
+  const hash = createHash2("sha256").update(hashInput).digest("hex");
   return { statements, hash };
 }
 // src/schema/prisma.ts
@@ -1532,6 +2000,13 @@ function renderDeployPlan(def, schemaName) {
 async function deploySchema(db, def, handlerPath, opts) {
   validateSubgraphDefinition(def);
   const { statements, hash } = generateSubgraphSQL(def, opts?.schemaName);
+  const pin = opts?.handlerCode != null ? computePin({
+    schemaHash: hash,
+    handlerCode: opts.handlerCode,
+    startBlock: def.startBlock,
+    network: opts.network ?? process.env.NETWORK ?? "mainnet"
+  }) : 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);
@@ -1554,7 +2029,9 @@ async function deploySchema(db, def, handlerPath, opts) {
     handlerCode: opts?.handlerCode,
     sourceCode: opts?.sourceCode,
     schemaName,
-    startBlock: def.startBlock
+    startBlock: def.startBlock,
+    pin,
+    verification: opts?.verification ?? null
   };
   if (existing) {
     const schemaExists = await sql`
@@ -1568,19 +2045,27 @@ 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,
+        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)."
@@ -1594,7 +2079,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);
@@ -1610,6 +2100,7 @@ async function deploySchema(db, def, handlerPath, opts) {
           action: "reindexed",
           subgraphId: sg.id,
           version: newVersion,
+          ...identity,
           diff: deployDiff
         };
       }
@@ -1729,6 +2220,7 @@ async function deploySchema(db, def, handlerPath, opts) {
         action: "updated",
         subgraphId: sg.id,
         version: newVersion,
+        ...identity,
         diff: deployDiff
       };
     }
@@ -1737,7 +2229,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) {
@@ -2186,13 +2683,19 @@ function buildHttpClient() {
 }
 export {
   ChainReadError,
+  HandlerReadError,
+  NondeterminismError,
+  SUBGRAPHS_RUNTIME,
   camelizeKeys,
   canSparseScan,
+  computePin,
   defineSchema,
   defineSubgraph,
   deploySchema,
+  deriveVerification,
   diffSchema,
   filterFieldsByType,
+  formatFinding,
   generateDrizzleSchema,
   generateIndexSchema,
   generateKyselySchema,
@@ -2200,7 +2703,9 @@ export {
   generateSubgraphSQL,
   hasBreakingChanges,
   inferPrintTopics,
+  isDeterminismViolation,
   isStreamsIndexEligible,
+  loadDeterministicDefinition,
   pgSchemaName,
   readContractAt,
   renderDeployPlan,
@@ -2208,5 +2713,5 @@ export {
   validateSubgraphDefinition
 };
 
-//# debugId=94E9A1B5DDFFF67E64756E2164756E21
+//# debugId=BDCC478FBE9DE96064756E2164756E21
 //# sourceMappingURL=index.js.map