@secondlayer/subgraphs 3.23.1 → 3.24.0

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

@@ -1,4 +1,5 @@
 import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
+import { AssetIdentifier } from "@secondlayer/stacks/filters";
 /**
 * How long a read stays valid.
 *
@@ -147,38 +148,38 @@ interface FactoryScope {
 /** FT event filters */
 interface FtTransferFilter extends TraitScope {
 	type: "ft_transfer";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 	recipient?: string;
 	minAmount?: bigint;
 }
 interface FtMintFilter extends TraitScope {
 	type: "ft_mint";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	recipient?: string;
 	minAmount?: bigint;
 }
 interface FtBurnFilter extends TraitScope {
 	type: "ft_burn";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 	minAmount?: bigint;
 }
 /** NFT event filters */
 interface NftTransferFilter extends TraitScope {
 	type: "nft_transfer";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 	recipient?: string;
 }
 interface NftMintFilter extends TraitScope {
 	type: "nft_mint";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	recipient?: string;
 }
 interface NftBurnFilter extends TraitScope {
 	type: "nft_burn";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 }
 /** Contract event filters */
@@ -235,7 +236,10 @@ type PrintField = ColumnType | {
 interface PrintEventFilter extends TraitScope, FactoryScope {
 	type: "print_event";
 	/** One contract id, or a set of them (max 20). Supports `*` wildcards.
-	*  Mutually exclusive with `trait`. */
+	*  COMPOSES with `trait` — the matcher ANDs them, so the pair means
+	*  "contracts conforming to this trait, narrowed to these ids". (The Index
+	*  read API refuses the combination, but that is its query planner's
+	*  constraint, not a semantic one.) */
 	contractId?: string | readonly string[];
 	topic?: string;
 	/**
@@ -341,9 +345,58 @@ interface SubgraphDefinition {
 	/** Handler functions — keys must match source names (or "*" for catch-all) */
 	handlers: Record<string, SubgraphHandler>;
 }
-import { Transaction } from "kysely";
+type TxRecord = {
+	tx_id: string
+	type: string
+	sender: string
+	status: string
+	/** Position within the block — the runner sorts dispatch into chain order. */
+	tx_index?: number
+	contract_id?: string | null
+	function_name?: string | null
+	function_args?: unknown | null
+	raw_result?: string | null
+};
+type EventRecord = {
+	id: string
+	tx_id: string
+	type: string
+	event_index: number
+	data: unknown
+};
+import { Database as Database2 } from "@secondlayer/shared/db";
+import { Kysely as Kysely2, Transaction } from "kysely";
 /** Drop a subgraph's cached route — call on redeploy/delete (conn may change). */
 declare function invalidateSubgraphRoute(subgraphName: string): void;
+/**
+* Resolve each distinct trait used by a subgraph's sources to its conforming
+* contract-id set, as of `blockHeight`, from the contract registry. Empty map
+* when no source is trait-scoped (the common case → no DB work).
+*/
+/**
+* Resolve each factory-scoped source's address set for this block.
+*
+* Two parts, and the ORDER is the guarantee:
+* 1. addresses persisted by earlier blocks (`block_height <= blockHeight`,
+*    so a reindex sees exactly what the live walk saw), then
+* 2. addresses revealed by THIS block's events — computed before matching,
+*    so a contract discovered in block N receives its own block-N events.
+*    Without this pass the first event from every discovered contract is
+*    silently lost.
+*/
+/**
+* Exported as a test seam. Both guarantees this function carries — a contract
+* discovered in block N receiving its OWN block-N events, and the persisted set
+* being height-stamped so a reorg can roll it back — were asserted only by
+* comment until now.
+*/
+declare function resolveFactoryContracts(subgraph: SubgraphDefinition, blockHeight: number, schemaName: string, db: Kysely2<Database2>, txs: TxRecord[], evts: EventRecord[]): Promise<{
+	resolved: Map<string, ReadonlySet<string>>
+	discovered: Array<{
+		sourceName: string
+		address: string
+	}>
+}>;
 interface ProcessBlockTiming {
 	totalMs: number;
 	handlerMs: number;
@@ -397,6 +450,19 @@ interface ProcessBlockOptions {
 	} | {
 		operationId: string
 	};
+	/**
+	* Reorg rewind (f069): set exclusively by `reorg.ts`'s fork-block
+	* reprocess. Bypasses the live-path replay guard (a fork block's height
+	* is, by construction, at or below the current cursor — the guard would
+	* otherwise skip it) and writes the checkpoint via
+	* `rewindLiveProgress` (unconditional — a rewind's whole point is
+	* moving the cursor *backward*, which the live path's conditional
+	* advance would refuse). Safe only because the reorg path holds a
+	* transaction-scoped advisory lock across its whole
+	* delete+reprocess+rewind sequence, so nothing else can interleave a
+	* forward write. Never set this outside `reorg.ts`.
+	*/
+	reorgRewind?: true;
 }
 /** Default per-block retry schedule before a failure counts as persistent. */
 declare const BLOCK_RETRY_DELAYS_MS: number[];
@@ -407,4 +473,4 @@ declare const BLOCK_RETRY_DELAYS_MS: number[];
 */
 declare function processBlockWithRetry(subgraph: SubgraphDefinition, subgraphName: string, blockHeight: number, opts?: ProcessBlockOptions, retryDelaysMs?: number[]): Promise<ProcessBlockResult>;
 declare function processBlock(subgraph: SubgraphDefinition, subgraphName: string, blockHeight: number, opts?: ProcessBlockOptions): Promise<ProcessBlockResult>;
-export { processBlockWithRetry, processBlock, invalidateSubgraphRoute, ProcessBlockTiming, ProcessBlockResult, ProcessBlockOptions, PreloadedBlockData, BLOCK_RETRY_DELAYS_MS };
+export { resolveFactoryContracts, processBlockWithRetry, processBlock, invalidateSubgraphRoute, ProcessBlockTiming, ProcessBlockResult, ProcessBlockOptions, PreloadedBlockData, BLOCK_RETRY_DELAYS_MS };

package/dist/src/runtime/block-processor.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/runtime/context.ts
-import { logger } from "@secondlayer/shared/logger";
+import { logger as logger2 } from "@secondlayer/shared/logger";
 import { formatUnits } from "@secondlayer/stacks/utils";
 import { sql } from "kysely";
 
@@ -147,6 +147,7 @@ function generateSubgraphSQL(def, schemaNameOverride) {
 
 // src/runtime/chain-read.ts
 import { getSourceDb } from "@secondlayer/shared/db";
+import { logger } from "@secondlayer/shared/logger";
 import { http, createPublicClient } from "@secondlayer/stacks";
 import {
   ContractResponseError,
@@ -232,6 +233,14 @@ function createChainReadClient(ctx) {
     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 value2 = await readContract(nodeClient(rpcUrl), {
         contract: contractId,
         functionName: fn.name,
@@ -346,7 +355,7 @@ class SubgraphContext {
         data: { ...key, ...row, ...meta, _upsert_keys: keyColumns }
       });
     } else {
-      logger.warn("upsert called without matching uniqueKeys constraint, using fallback", {
+      logger2.warn("upsert called without matching uniqueKeys constraint, using fallback", {
         table,
         keys: keyColumns
       });
@@ -906,7 +915,7 @@ function decodeFunctionArgs(args) {
 
 // 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,
@@ -1257,7 +1266,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
   units.sort((a, b) => (a.tx.tx_index ?? 0) - (b.tx.tx_index ?? 0) || (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
@@ -1266,7 +1275,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
     }
     const handler = subgraph.handlers[sourceName] ?? subgraph.handlers["*"] ?? 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
@@ -1323,7 +1332,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,
@@ -1338,7 +1347,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
     } catch (err) {
       ctx.rollbackTo(checkpoint);
       errors++;
-      logger2.error("Subgraph handler error", {
+      logger3.error("Subgraph handler error", {
         subgraph: subgraph.name,
         sourceName,
         txId: tx.tx_id,
@@ -1618,12 +1627,14 @@ import { resolveTraitContractIds } from "@secondlayer/shared/db/queries/contract
 import { advanceOperationCursor } from "@secondlayer/shared/db/queries/subgraph-operations";
 import {
   isByoSubgraph,
+  recordLiveError,
   recordLiveProgress,
   recordSubgraphProcessed,
   resolveSubgraphDb,
+  rewindLiveProgress,
   updateSubgraphStatus
 } from "@secondlayer/shared/db/queries/subgraphs";
-import { logger as logger5 } from "@secondlayer/shared/logger";
+import { logger as logger6 } from "@secondlayer/shared/logger";
 import { sql as sql3 } from "kysely";
 
 // src/runtime/block-source.ts
@@ -1631,7 +1642,7 @@ import { getSourceDb as getSourceDb2 } from "@secondlayer/shared/db";
 import {
   IndexHttpClient
 } from "@secondlayer/shared/index-http";
-import { logger as logger3 } from "@secondlayer/shared/logger";
+import { logger as logger4 } from "@secondlayer/shared/logger";
 
 // src/runtime/batch-loader.ts
 async function loadBlockRange(db, fromHeight, toHeight) {
@@ -1955,7 +1966,7 @@ class FallbackBlockSource {
     try {
       return await this.primary.getTip();
     } catch (err) {
-      logger3.warn("block source primary getTip failed — using DB tap", {
+      logger4.warn("block source primary getTip failed — using DB tap", {
         error: err instanceof Error ? err.message : String(err)
       });
       return this.fallback.getTip();
@@ -1965,7 +1976,7 @@ class FallbackBlockSource {
     try {
       return await this.primary.loadBlockRange(fromHeight, toHeight);
     } catch (err) {
-      logger3.warn("block source primary loadBlockRange failed — using DB tap", {
+      logger4.warn("block source primary loadBlockRange failed — using DB tap", {
         from: fromHeight,
         to: toHeight,
         error: err instanceof Error ? err.message : String(err)
@@ -1997,7 +2008,7 @@ function resolveBlockSource(subgraph) {
     return new FallbackBlockSource(new PublicApiBlockSource(buildHttpClient(), referencedIndexEventTypes(subgraph), canSparseScan(subgraph) ? sparseProbeTargets(subgraph) : undefined, needsTransactionData(subgraph)), postgresBlockSource);
   }
   if (process.env.SUBGRAPH_SOURCE === "streams-index" && subgraph) {
-    logger3.debug("Subgraph not streams-index eligible, using DB tap", {
+    logger4.debug("Subgraph not streams-index eligible, using DB tap", {
       subgraph: subgraph.name
     });
   }
@@ -2006,7 +2017,7 @@ function resolveBlockSource(subgraph) {
 
 // src/runtime/outbox-emit.ts
 import { createHash as createHash2 } from "node:crypto";
-import { logger as logger4 } from "@secondlayer/shared/logger";
+import { logger as logger5 } from "@secondlayer/shared/logger";
 var loggedKillSwitch = false;
 var OP_VERB = {
   insert: "created",
@@ -2030,7 +2041,7 @@ function stableStringify(obj) {
 async function emitSubscriptionOutbox(tx, subgraphName, manifest, matcher, blockHeight) {
   if (!isEmitOutboxEnabled()) {
     if (!loggedKillSwitch) {
-      logger4.warn("SECONDLAYER_EMIT_OUTBOX=false — outbox emission bypassed");
+      logger5.warn("SECONDLAYER_EMIT_OUTBOX=false — outbox emission bypassed");
       loggedKillSwitch = true;
     }
     return 0;
@@ -2328,10 +2339,20 @@ class CursorRaceLostError extends Error {
     this.name = "CursorRaceLostError";
   }
 }
+
+class LiveCursorRaceLostError extends Error {
+  constructor(subgraphName, height) {
+    super(`live cursor race lost for ${subgraphName} at block ${height}`);
+    this.name = "LiveCursorRaceLostError";
+  }
+}
 function opCursorMode(opts) {
   const ap = opts?.atomicProgress;
   return ap && "operationId" in ap ? ap : undefined;
 }
+function isReorgRewind(opts) {
+  return opts?.reorgRewind === true;
+}
 function statusMode(opts) {
   const ap = opts?.atomicProgress;
   return ap && "status" in ap ? ap : undefined;
@@ -2350,7 +2371,7 @@ async function processBlockWithRetry(subgraph, subgraphName, blockHeight, opts,
       const delay = retryDelaysMs[attempt];
       if (delay === undefined)
         break;
-      logger5.warn("Block processing failed, retrying", {
+      logger6.warn("Block processing failed, retrying", {
         subgraph: subgraphName,
         blockHeight,
         attempt: attempt + 1,
@@ -2382,7 +2403,7 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
   } else {
     const data = (await resolveBlockSource(subgraph).loadBlockRange(blockHeight, blockHeight)).get(blockHeight);
     if (!data) {
-      logger5.debug("Block not found or non-canonical for subgraph processing", {
+      logger6.debug("Block not found or non-canonical for subgraph processing", {
         subgraph: subgraphName,
         blockHeight
       });
@@ -2401,7 +2422,11 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
   result.matched = matched.length;
   if (matched.length === 0) {
     if (!opts?.skipProgressUpdate) {
-      await recordLiveProgress(targetDb, subgraphName, blockHeight);
+      if (isReorgRewind(opts)) {
+        await rewindLiveProgress(targetDb, subgraphName, blockHeight);
+      } else {
+        await recordLiveProgress(targetDb, subgraphName, blockHeight);
+      }
     }
     return result;
   }
@@ -2420,13 +2445,23 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
   };
   let handlerMs = 0;
   let flushMs = 0;
-  const applyProgress = async (tx, rr) => {
+  const applyProgress = async (tx, rr, flushedWrites) => {
     if (opts?.skipProgressUpdate)
       return;
+    const rewind = isReorgRewind(opts);
     if (rr.errors > 0 && rr.processed === 0) {
-      await updateSubgraphStatus(tx, subgraphName, "error", blockHeight);
+      if (rewind) {
+        await updateSubgraphStatus(tx, subgraphName, "error", blockHeight);
+      } else {
+        await recordLiveError(tx, subgraphName, blockHeight);
+      }
+    } else if (rewind) {
+      await rewindLiveProgress(tx, subgraphName, blockHeight);
     } else {
-      await recordLiveProgress(tx, subgraphName, blockHeight);
+      const advanced = await recordLiveProgress(tx, subgraphName, blockHeight);
+      if (!advanced && flushedWrites && !route.byo) {
+        throw new LiveCursorRaceLostError(subgraphName, blockHeight);
+      }
     }
     if (rr.processed > 0 || rr.errors > 0) {
       const lastError = rr.errors > 0 ? `${rr.errors} error(s) at block ${blockHeight}` : undefined;
@@ -2475,13 +2510,15 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
       } else if (byoOm && manifest && manifest.count > 0) {
         await advanceOperationCursor(tx, byoOm.operationId, blockHeight);
       }
-      await applyProgress(tx, runResult);
+      await applyProgress(tx, runResult, manifest ? manifest.count > 0 : false);
     });
   } else {
     try {
       await targetDb.transaction().execute(async (tx) => {
         const opMode = opCursorMode(opts);
-        if (statusMode(opts)) {
+        const sm = statusMode(opts);
+        const rewind = isReorgRewind(opts);
+        if (sm) {
           const row = await tx.selectFrom("subgraphs").select("last_processed_block").where("name", "=", subgraphName).executeTakeFirst();
           if (row && Number(row.last_processed_block) >= blockHeight) {
             result.skipped = true;
@@ -2493,6 +2530,12 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
             result.skipped = true;
             return;
           }
+        } else if (!rewind) {
+          const row = await tx.selectFrom("subgraphs").select("last_processed_block").where("name", "=", subgraphName).executeTakeFirst();
+          if (row && Number(row.last_processed_block) >= blockHeight) {
+            result.skipped = true;
+            return;
+          }
         }
         const ctx = new SubgraphContext(tx, schemaName, subgraph.schema, blockMeta, initialTx, false, journalEnabled(opts));
         const handlerStart = performance.now();
@@ -2510,7 +2553,6 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
           }
           flushMs = performance.now() - flushStart;
         }
-        const sm = statusMode(opts);
         if (sm && flushedWrites) {
           await updateSubgraphStatus(tx, subgraphName, sm.status, blockHeight);
         } else if (opMode && flushedWrites) {
@@ -2519,11 +2561,11 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
             throw new CursorRaceLostError(opMode.operationId, blockHeight);
           }
         }
-        await applyProgress(tx, runResult);
+        await applyProgress(tx, runResult, flushedWrites);
       });
     } catch (err) {
-      if (err instanceof CursorRaceLostError) {
-        logger5.warn("cursor race lost — block already covered", {
+      if (err instanceof CursorRaceLostError || err instanceof LiveCursorRaceLostError) {
+        logger6.warn("cursor race lost — block already covered", {
           subgraph: subgraphName,
           blockHeight,
           error: err.message
@@ -2535,11 +2577,13 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
     }
   }
   const totalMs = performance.now() - blockStart;
-  result.timing = {
-    totalMs: Math.round(totalMs),
-    handlerMs: Math.round(handlerMs),
-    flushMs: Math.round(flushMs)
-  };
+  if (!result.skipped) {
+    result.timing = {
+      totalMs: Math.round(totalMs),
+      handlerMs: Math.round(handlerMs),
+      flushMs: Math.round(flushMs)
+    };
+  }
   if (blockHeight % 1000 === 0) {
     try {
       const tables = Object.keys(subgraph.schema);
@@ -2547,7 +2591,7 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
         const { rows } = await sql3.raw(`SELECT n_live_tup AS count FROM pg_stat_user_tables WHERE schemaname = '${schemaName}' AND relname = '${table}'`).execute(route.dataDb);
         const count = Number(rows[0]?.count ?? 0);
         if (count >= 1e7) {
-          logger5.warn("Subgraph table exceeds 10M rows (estimate)", {
+          logger6.warn("Subgraph table exceeds 10M rows (estimate)", {
             subgraph: subgraphName,
             table,
             count
@@ -2555,7 +2599,7 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
         }
       }
     } catch (err) {
-      logger5.debug("Row count sample failed", {
+      logger6.debug("Row count sample failed", {
         subgraph: subgraphName,
         error: err instanceof Error ? err.message : String(err)
       });
@@ -2567,11 +2611,12 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
   return result;
 }
 export {
+  resolveFactoryContracts,
   processBlockWithRetry,
   processBlock,
   invalidateSubgraphRoute,
   BLOCK_RETRY_DELAYS_MS
 };
 
-//# debugId=0225B7830F6ABAFA64756E2164756E21
+//# debugId=0C53CE27E78CBEED64756E2164756E21
 //# sourceMappingURL=block-processor.js.map