@secondlayer/subgraphs 7.1.0 → 7.3.0

package/dist/index.d.ts

@@ -108,6 +108,12 @@ declare function readContractAt<const C extends AbiContract>(ctx: {
 }, contractId: string, abi: C, options?: ChainReadOptions): {
 	read: ChainReadMethods<C>;
 };
+/**
+* A handler asked for something no node can answer: a function missing from
+* the ABI, or one that isn't read-only. Deterministic, so it fails only the
+* event. A read the processor couldn't complete (no node, node down, cache
+* error) throws {@link HandlerReadError} instead and aborts the block.
+*/
 declare class ChainReadError extends Error {
 	name: string;
 }
@@ -390,6 +396,12 @@ type PrintEventPrints = Record<string, Record<string, PrintField>>;
 type PrintEventFields = FactoryScope & {
 	type: "print_event";
 	topic?: string;
+	/** Equality on top-level keys of the decoded print tuple, spelled as the
+	*  contract prints them (`signer-manager`). A value matches the field's
+	*  JSON form: principals `SP…`, uints as decimal strings, bools
+	*  `"true"`/`"false"`, buffers `0x…`. An array is any-of; keys AND.
+	*  Nested tuples and lists never match. */
+	where?: Record<string, string | readonly string[]>;
 };
 /**
 * Pinned to one or more contract ids with no trait — `prints` is required so
@@ -1200,9 +1212,11 @@ declare class NondeterminismError extends Error {
 	name: string;
 }
 /**
-* A ctx read (DB, chain) failed under a verifiable subgraph. Infra-class like
+* A ctx read failed for a reason outside the handler: the database under a
+* verifiable subgraph, or a chain read (`ctx.client`) on any subgraph that
+* had no node, a node that didn't answer, or a cache error. Infra-class like
 * {@link NondeterminismError}: skipping the event would make its rows depend
-* on whether the database was reachable.
+* on whether the database or node was reachable.
 */
 declare class HandlerReadError extends Error {
 	name: string;

package/dist/index.js

@@ -6,6 +6,7 @@ function defineSchema(schema) {
   return schema;
 }
 // src/validate.ts
+import { PrintWhereSchema } from "@secondlayer/shared/schemas/webhooks";
 import { z } from "zod";
 var SubgraphNameSchema = z.string().min(1).max(63).regex(/^[a-z][a-z0-9-]*$/, "Must start with lowercase letter, contain only lowercase alphanumeric and hyphens");
 var SqlIdentifierSchema = z.string().min(1).max(63).regex(/^[a-z_][a-z0-9_]*$/i, "Must be a valid SQL identifier: start with a letter or underscore, then letters/digits/underscores only");
@@ -182,6 +183,7 @@ var SubgraphFilterUnion = z.discriminatedUnion("type", [
     type: z.literal("print_event"),
     contractId: contractIdField.optional(),
     topic: z.string().optional(),
+    where: PrintWhereSchema.optional(),
     prints: z.record(z.string(), z.record(z.string(), PrintFieldSchema)).optional(),
     ...traitScope,
     ...factoryScope
@@ -646,9 +648,17 @@ function inferPrintTopics(samples) {
   return out.sort((a, b) => b.count - a.count);
 }
 // src/runtime/chain-read.ts
+import { getErrorMessage } 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 } from "@secondlayer/shared/logger";
-import { http, createPublicClient } from "@secondlayer/stacks";
+import {
+  http,
+  HttpRequestError,
+  ReadContractError,
+  createPublicClient
+} from "@secondlayer/stacks";
 import {
   ContractResponseError,
   buildFunctionArgs,
@@ -662,136 +672,16 @@ import {
   serializeCV,
   toCamelCase
 } from "@secondlayer/stacks/clarity";
-function readContractAt(ctx, contractId, abi, options) {
-  return ctx.client.contract(contractId, abi, options);
-}
 
-class ChainReadError extends Error {
-  name = "ChainReadError";
-}
-function nodeClient(rpcUrl) {
-  return createPublicClient({
-    transport: http(rpcUrl, { retryCount: 0, timeout: 1e4 })
-  });
-}
+// src/runtime/realm.ts
+import vm from "node:vm";
 
-class ConcurrencyGate {
-  limit;
-  active = 0;
-  queue = [];
-  constructor(limit) {
-    this.limit = limit;
-  }
-  async run(fn) {
-    if (this.active >= this.limit) {
-      await new Promise((resolve) => this.queue.push(resolve));
-    }
-    this.active++;
-    try {
-      return await fn();
-    } finally {
-      this.active--;
-      this.queue.shift()?.();
-    }
-  }
-}
-var DEFAULT_MAX_CONCURRENT_READS = 4;
-function maxConcurrentReads() {
-  const raw = process.env.SUBGRAPH_CHAIN_READ_CONCURRENCY;
-  const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CONCURRENT_READS;
-}
-var gate = new ConcurrencyGate(maxConcurrentReads());
-function hashArgs(args) {
-  const serialized = args.map((arg) => serializeCV(arg)).join(",");
-  return Bun.hash(serialized).toString(16);
-}
-function findFunction(abi, name) {
-  const fn = abi.functions.find((f) => f.name === name);
-  if (!fn) {
-    throw new ChainReadError(`No function "${name}" in the supplied ABI.`);
-  }
-  if (fn.access !== "read-only") {
-    throw new ChainReadError(`"${name}" is ${fn.access}, not read-only — a handler cannot call it.`);
-  }
-  return fn;
-}
-function createChainReadClient(ctx) {
-  const readValue = async (contractId, abi, functionName, args, options) => {
-    const rpcUrl = ctx.rpcUrl ?? process.env.STACKS_NODE_RPC_URL;
-    if (!rpcUrl) {
-      throw new ChainReadError("ctx.client needs a Stacks node: set STACKS_NODE_RPC_URL on the subgraph processor.");
-    }
-    const constant = options.cache === "contract-constant";
-    if (!constant && !ctx.indexBlockHash) {
-      throw new ChainReadError(`Block ${ctx.blockHeight} has no index_block_hash, so a read cannot be pinned to it. Reading at the node's tip would make this handler non-deterministic (the same reindex would produce different rows). Re-ingest the block, or pass cache: "contract-constant" if the value genuinely cannot change.`);
-    }
-    const fn = findFunction(abi, functionName);
-    const clarityArgs = buildFunctionArgs(fn, args);
-    const db = ctx.db ?? getSourceDb();
-    const argsHash = hashArgs(clarityArgs);
-    const pinnedTo = constant ? null : ctx.indexBlockHash;
-    const cached = await db.selectFrom("chain_read_cache").select("result_hex").where("contract_id", "=", contractId).where("function_name", "=", fn.name).where("args_hash", "=", argsHash).where((eb) => pinnedTo === null ? eb("index_block_hash", "is", null) : eb("index_block_hash", "=", pinnedTo)).executeTakeFirst();
-    const resultHex = cached?.result_hex ?? await gate.run(async () => {
-      if (!ctx.indexBlockHash) {
-        logger.warn("Chain read is not pinned to a block (no index_block_hash)", {
-          contractId,
-          functionName: fn.name,
-          blockHeight: ctx.blockHeight,
-          note: 'cache: "contract-constant" asserts this value cannot change; the node answered at its own tip'
-        });
-      }
-      const value = await readContract(nodeClient(rpcUrl), {
-        contract: contractId,
-        functionName: fn.name,
-        args: clarityArgs,
-        tip: ctx.indexBlockHash ?? undefined
-      });
-      return serializeCV(value);
-    });
-    if (!cached) {
-      await db.insertInto("chain_read_cache").values({
-        contract_id: contractId,
-        function_name: fn.name,
-        args_hash: argsHash,
-        index_block_hash: pinnedTo,
-        block_height: constant ? null : ctx.blockHeight,
-        result_hex: resultHex
-      }).onConflict((oc) => oc.doNothing()).execute();
-    }
-    const value = deserializeCV2(resultHex);
-    const js = clarityValueToJSUntyped(fn.outputs, value);
-    if (isResponseOutput(fn.outputs)) {
-      const response = js;
-      if ("ok" in response)
-        return response.ok;
-      throw new ContractResponseError(`${contractId}::${fn.name} returned an err response.`, response.err);
-    }
-    return js;
-  };
-  return {
-    contract(contractId, rawAbi, options = {}) {
-      const abi = normalizeAbi(rawAbi);
-      const camelToKebab = new Map;
-      for (const fn of abi.functions) {
-        camelToKebab.set(toCamelCase(fn.name), fn.name);
-      }
-      const read = new Proxy({}, {
-        get(_target, prop) {
-          const fnName = camelToKebab.get(prop) ?? prop;
-          return (args = {}) => readValue(contractId, abi, fnName, args, options);
-        }
-      });
-      return { read };
-    }
-  };
-}
 // src/verification.ts
 import { createHash } from "node:crypto";
 // package.json
 var package_default = {
   name: "@secondlayer/subgraphs",
-  version: "7.1.0",
+  version: "7.3.0",
   description: "Describe the Stacks data you want as one TypeScript file; it fills itself and survives reorgs.",
   license: "MIT",
   repository: {
@@ -851,8 +741,8 @@ var package_default = {
     prepublishOnly: "bun run build"
   },
   dependencies: {
-    "@secondlayer/shared": "^13.0.0",
-    "@secondlayer/stacks": "^6.3.0",
+    "@secondlayer/shared": "^13.2.0",
+    "@secondlayer/stacks": "^6.4.0",
     "@secondlayer/verify": "^0.6.0",
     esbuild: "^0.28.2",
     kysely: "0.28.17",
@@ -1054,8 +944,8 @@ function pinPreimage(input) {
 function computePin(input) {
   return sha256(pinPreimage(input));
 }
+
 // src/runtime/realm.ts
-import vm from "node:vm";
 class NondeterminismError extends Error {
   name = "NondeterminismError";
 }
@@ -1270,6 +1160,186 @@ ${code}
   realmDefinitions.add(loaded);
   return loaded;
 }
+
+// src/runtime/chain-read.ts
+function readContractAt(ctx, contractId, abi, options) {
+  return ctx.client.contract(contractId, abi, options);
+}
+
+class ChainReadError extends Error {
+  name = "ChainReadError";
+}
+var NO_NODE_MESSAGE = "ctx.client needs a Stacks node: set STACKS_NODE_RPC_URL on the subgraph processor.";
+async function resolveReadTarget(rpcUrl, db) {
+  if (rpcUrl)
+    return { kind: "node", rpcUrl };
+  const apiUrl = process.env.SUBGRAPH_INDEX_API_URL;
+  if (!apiUrl || !await hasNoLocalChain(db)) {
+    throw new HandlerReadError(NO_NODE_MESSAGE);
+  }
+  const apiKey = process.env.INDEX_INTERNAL_API_KEY?.trim();
+  if (!apiKey) {
+    throw new HandlerReadError("Hosted contract reads need the processor's key (INDEX_INTERNAL_API_KEY), and none is set. Set STACKS_NODE_RPC_URL to read a node directly instead.");
+  }
+  return { kind: "hosted", apiUrl, apiKey };
+}
+function hostedReadError(err, label) {
+  if (!(err instanceof HttpRequestError))
+    return;
+  if (err.status === 400) {
+    return new ChainReadError(`${label} was refused as invalid: ${err.details ?? err.message}`);
+  }
+  if (err.status === 403) {
+    return new HandlerReadError(`${label}: hosted contract reads serve hosted subgraphs only. ${NO_NODE_MESSAGE}`, { cause: err });
+  }
+  return;
+}
+function isChainAnswer(err) {
+  return err instanceof ContractResponseError || err instanceof ReadContractError;
+}
+function readClient(target) {
+  if (target.kind === "node") {
+    return createPublicClient({
+      transport: http(target.rpcUrl, { retryCount: 0, timeout: 1e4 })
+    });
+  }
+  return createPublicClient({
+    transport: http(`${target.apiUrl.replace(/\/+$/, "")}/v1/chain-read`, {
+      retryCount: 3,
+      timeout: 1e4,
+      fetchOptions: {
+        headers: { authorization: `Bearer ${target.apiKey}` }
+      }
+    })
+  });
+}
+
+class ConcurrencyGate {
+  limit;
+  active = 0;
+  queue = [];
+  constructor(limit) {
+    this.limit = limit;
+  }
+  async run(fn) {
+    if (this.active >= this.limit) {
+      await new Promise((resolve) => this.queue.push(resolve));
+    }
+    this.active++;
+    try {
+      return await fn();
+    } finally {
+      this.active--;
+      this.queue.shift()?.();
+    }
+  }
+}
+var DEFAULT_MAX_CONCURRENT_READS = 4;
+function maxConcurrentReads() {
+  const raw = process.env.SUBGRAPH_CHAIN_READ_CONCURRENCY;
+  const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CONCURRENT_READS;
+}
+var gate = new ConcurrencyGate(maxConcurrentReads());
+function hashArgs(args) {
+  return chainReadArgsHash(args.map((arg) => serializeCV(arg)));
+}
+function findFunction(abi, name) {
+  const fn = abi.functions.find((f) => f.name === name);
+  if (!fn) {
+    throw new ChainReadError(`No function "${name}" in the supplied ABI.`);
+  }
+  if (fn.access !== "read-only") {
+    throw new ChainReadError(`"${name}" is ${fn.access}, not read-only — a handler cannot call it.`);
+  }
+  return fn;
+}
+function createChainReadClient(ctx) {
+  const readValue = async (contractId, abi, functionName, args, options) => {
+    const db = ctx.db ?? getSourceDb();
+    const rpcUrl = ctx.rpcUrl || process.env.STACKS_NODE_RPC_URL || undefined;
+    if (!rpcUrl && !process.env.SUBGRAPH_INDEX_API_URL) {
+      throw new HandlerReadError(NO_NODE_MESSAGE);
+    }
+    const constant = options.cache === "contract-constant";
+    if (!constant && !ctx.indexBlockHash) {
+      throw new HandlerReadError(`Block ${ctx.blockHeight} has no index_block_hash, so a read cannot be pinned to it. Reading at the node's tip would make this handler non-deterministic (the same reindex would produce different rows). Re-ingest the block, or pass cache: "contract-constant" if the value genuinely cannot change.`);
+    }
+    const fn = findFunction(abi, functionName);
+    const clarityArgs = buildFunctionArgs(fn, args);
+    const argsHash = hashArgs(clarityArgs);
+    const pinnedTo = constant ? null : ctx.indexBlockHash;
+    let resultHex;
+    try {
+      const cached = await db.selectFrom("chain_read_cache").select("result_hex").where("contract_id", "=", contractId).where("function_name", "=", fn.name).where("args_hash", "=", argsHash).where((eb) => pinnedTo === null ? eb("index_block_hash", "is", null) : eb("index_block_hash", "=", pinnedTo)).executeTakeFirst();
+      resultHex = cached?.result_hex ?? await gate.run(async () => {
+        const target = await resolveReadTarget(rpcUrl, db);
+        if (!ctx.indexBlockHash && target.kind === "hosted") {
+          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) {
+          logger.warn("Chain read is not pinned to a block (no index_block_hash)", {
+            contractId,
+            functionName: fn.name,
+            blockHeight: ctx.blockHeight,
+            note: 'cache: "contract-constant" asserts this value cannot change; the node answered at its own tip'
+          });
+        }
+        try {
+          const value = await readContract(readClient(target), {
+            contract: contractId,
+            functionName: fn.name,
+            args: clarityArgs,
+            tip: ctx.indexBlockHash ?? undefined
+          });
+          return serializeCV(value);
+        } catch (err) {
+          throw target.kind === "hosted" && hostedReadError(err, `Chain read ${contractId}::${fn.name}`) || err;
+        }
+      });
+      if (!cached) {
+        await db.insertInto("chain_read_cache").values({
+          contract_id: contractId,
+          function_name: fn.name,
+          args_hash: argsHash,
+          index_block_hash: pinnedTo,
+          block_height: constant ? null : ctx.blockHeight,
+          result_hex: resultHex
+        }).onConflict((oc) => oc.doNothing()).execute();
+      }
+    } catch (err) {
+      if (isChainAnswer(err) || err instanceof ChainReadError || err instanceof HandlerReadError) {
+        throw err;
+      }
+      throw new HandlerReadError(`Chain read ${contractId}::${fn.name} at block ${ctx.blockHeight} failed: ${getErrorMessage(err)}`, { cause: err });
+    }
+    const value = deserializeCV2(resultHex);
+    const js = clarityValueToJSUntyped(fn.outputs, value);
+    if (isResponseOutput(fn.outputs)) {
+      const response = js;
+      if ("ok" in response)
+        return response.ok;
+      throw new ContractResponseError(`${contractId}::${fn.name} returned an err response.`, response.err);
+    }
+    return js;
+  };
+  return {
+    contract(contractId, rawAbi, options = {}) {
+      const abi = normalizeAbi(rawAbi);
+      const camelToKebab = new Map;
+      for (const fn of abi.functions) {
+        camelToKebab.set(toCamelCase(fn.name), fn.name);
+      }
+      const read = new Proxy({}, {
+        get(_target, prop) {
+          const fnName = camelToKebab.get(prop) ?? prop;
+          return (args = {}) => readValue(contractId, abi, fnName, args, options);
+        }
+      });
+      return { read };
+    }
+  };
+}
 // src/schema/generator.ts
 import { createHash as createHash2 } from "node:crypto";
 
@@ -2953,5 +3023,5 @@ export {
   validateSubgraphDefinition
 };
 
-//# debugId=DC950AFB0608338264756E2164756E21
+//# debugId=B682843D48E7715C64756E2164756E21
 //# sourceMappingURL=index.js.map