@secondlayer/subgraphs 3.25.1 → 3.26.1

package/dist/src/runtime/reindex.d.ts

@@ -345,6 +345,29 @@ interface SubgraphDefinition {
 	/** Handler functions — keys must match source names (or "*" for catch-all) */
 	handlers: Record<string, SubgraphHandler>;
 }
+import { Block, Event, Transaction } from "@secondlayer/shared/db";
+interface BlockData {
+	block: Block;
+	txs: Transaction[];
+	events: Event[];
+}
+/**
+* Where the subgraph runtime reads canonical chain data. Today it taps the
+* indexer Postgres directly (`PostgresBlockSource`); the re-point adds a
+* `PublicApiBlockSource` that consumes the Streams clock + Index data over
+* HTTP. `matchSources` / handlers / flush / outbox are unchanged — only the
+* loader + tip swap behind this seam.
+*/
+interface BlockSource {
+	/** Highest canonical block height available to process. */
+	getTip(): Promise<number>;
+	/** Canonical block data for [fromHeight, toHeight], keyed by height. */
+	loadBlockRange(fromHeight: number, toHeight: number): Promise<Map<number, BlockData>>;
+	/** Sparse-scan probe: lowest height in (afterHeight, untilHeight] holding
+	*  an event this source's subgraph could match, or null when the rest of
+	*  the range is empty. Optional — only event-scoped sources support it. */
+	nextDataHeight?(afterHeight: number, untilHeight: number): Promise<number | null>;
+}
 type ReindexBatchConfig = {
 	defaultBatchSize: number
 	minBatchSize: number
@@ -364,16 +387,49 @@ declare function initialReindexProgressBlock(fromBlock: number): number;
 declare function resolveReindexResumeBlock(row: ReindexResumeRow): number | null;
 declare function resolveReindexBatchConfig(env?: ReindexBatchEnv): ReindexBatchConfig;
 interface ReindexOptions {
-	fromBlock?: number;
-	toBlock?: number;
+	/**
+	* Policy floor on the walk's first block — NOT a caller-supplied range.
+	* Free-tier accounts may not reindex below their registered `start_block`
+	* (see `resolveGenesisPolicy` on the API side); this raises the walk start
+	* and can never lower it. There is deliberately no `toBlock` counterpart:
+	* a reindex always runs to chain tip. See {@link resolveBlockRange}.
+	*/
+	startBlockFloor?: number;
 	schemaName?: string;
 	/** Op row to receive processed_events on each progress flush. */
 	operationId?: string;
 	signal?: AbortSignal;
 }
 /**
+* Resolve the reindex walk range. Always the whole subgraph:
+* `[def.startBlock, chain tip]`. Chain tip reads from `index_progress` —
+* lives in the source DB.
+*
+* Reindex drops the schema unconditionally, so the walk range is also the
+* ONLY data that survives. A narrower walk therefore does not "reindex a
+* range" — it silently destroys every row outside it while leaving the
+* subgraph reporting `active` at chain tip (f079: a single-block
+* `--from-block N --to-block N` emptied sbtc-flows, and the first recovery
+* attempt rebuilt only 21% of its history). Ranged, additive work is
+* `backfillSubgraph`'s job.
+*
+* `startBlockFloor` is a plan-policy floor, not a range: it can only raise
+* the start block, never lower it, and never bounds the end.
+*/
+declare function resolveBlockRange(source: BlockSource, def: SubgraphDefinition, opts?: ReindexOptions): Promise<{
+	fromBlock: number
+	toBlock: number
+}>;
+/**
 * Reindex a subgraph by dropping its tables, recreating them, and reprocessing
 * all historical blocks through the handler pipeline.
+*
+* Always whole-subgraph: `[start_block, chain tip]`. There is no ranged
+* reindex — the drop cannot be scoped to a range without re-running delta
+* handlers (`ctx.increment` / `ctx.update` / `ctx.patchOrInsert`) over rows
+* that were never removed, which is the exact double-count hazard `backfill`
+* already refuses. Use `backfillSubgraph` for ranged, additive work.
+*
 * Supports cancellation via AbortSignal — on shutdown abort, status stays
 * "reindexing" for auto-resume; on user cancel, status resets to "active".
 */
@@ -405,4 +461,4 @@ declare function backfillSubgraph(def: SubgraphDefinition, opts: {
 }): Promise<{
 	processed: number
 }>;
-export { resumeReindex, resolveReindexResumeBlock, resolveReindexBatchConfig, reindexSubgraph, initialReindexProgressBlock, backfillSubgraph, ReindexOptions };
+export { resumeReindex, resolveReindexResumeBlock, resolveReindexBatchConfig, resolveBlockRange, reindexSubgraph, initialReindexProgressBlock, backfillSubgraph, ReindexOptions };

package/dist/src/runtime/reindex.js

@@ -605,14 +605,10 @@ class SubgraphContext {
     this.ops.length = 0;
     const statements = this.buildStatements(opsToFlush);
     if ("isTransaction" in this.db) {
-      for (const stmt of statements) {
-        await sql.raw(stmt).execute(this.db);
-      }
+      await this.execStatements(this.db, statements);
     } else {
       await this.db.transaction().execute(async (tx) => {
-        for (const stmt of statements) {
-          await sql.raw(stmt).execute(tx);
-        }
+        await this.execStatements(tx, statements);
       });
     }
     const writes = opsToFlush.map((op, rowIndex) => {
@@ -631,6 +627,25 @@ class SubgraphContext {
     });
     return { count: opsToFlush.length, writes };
   }
+  async execStatements(executor, statements) {
+    const affected = (r) => r.numAffectedRows ?? 0n;
+    for (const stmt of statements) {
+      if (typeof stmt === "string") {
+        await sql.raw(stmt).execute(executor);
+        continue;
+      }
+      const updated = await sql.raw(stmt.update).execute(executor);
+      if (affected(updated) > 0n)
+        continue;
+      const inserted = await sql.raw(stmt.insert).execute(executor);
+      if (affected(inserted) > 0n)
+        continue;
+      const retried = await sql.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`);
+      }
+    }
+  }
   prepareInsert(op) {
     const upsertKeys = op.data._upsert_keys;
     const data = { ...op.data };
@@ -710,7 +725,6 @@ class SubgraphContext {
       for (const r of batch.rows.values()) {
         const keyPred = batch.keyCols.map((k) => `"${k}" = ${escapeLiteral(r.keys[k])}`).join(" AND ");
         const updSet = batch.deltaCols.map((c) => `"${c}" = COALESCE("${c}", 0) + (${String(r.deltas[c] ?? 0n)})`).join(", ");
-        statements.push(`UPDATE ${qualifiedTable} SET ${updSet} WHERE ${keyPred}`);
         const insertVals = [
           ...batch.keyCols.map((k) => escapeLiteral(r.keys[k])),
           ...batch.deltaCols.map((c) => String(r.deltas[c] ?? 0n)),
@@ -718,7 +732,13 @@ class SubgraphContext {
           escapeLiteral(r.meta.txId),
           "NOW()"
         ];
-        statements.push(`INSERT INTO ${qualifiedTable} (${cols.map((c) => `"${c}"`).join(", ")}) ` + `SELECT ${insertVals.join(", ")} ` + `WHERE NOT EXISTS (SELECT 1 FROM ${qualifiedTable} WHERE ${keyPred})`);
+        statements.push({
+          kind: "increment",
+          table: batch.table,
+          keyPred,
+          update: `UPDATE ${qualifiedTable} SET ${updSet} WHERE ${keyPred}`,
+          insert: `INSERT INTO ${qualifiedTable} (${cols.map((c) => `"${c}"`).join(", ")}) ` + `SELECT ${insertVals.join(", ")} ` + `WHERE NOT EXISTS (SELECT 1 FROM ${qualifiedTable} WHERE ${keyPred})`
+        });
       }
       incBatch = null;
       incBatchKey = "";
@@ -3353,9 +3373,9 @@ async function processBlockRange(def, opts) {
   return { blocksProcessed, totalEventsProcessed, totalErrors, aborted };
 }
 async function resolveBlockRange(source, def, opts) {
-  const fromBlock = opts?.fromBlock ?? def.startBlock ?? 1;
-  const toBlock = opts?.toBlock != null ? opts.toBlock : await source.getTip();
-  return { fromBlock, toBlock };
+  const definitionStart = def.startBlock ?? 1;
+  const fromBlock = opts?.startBlockFloor != null ? Math.max(definitionStart, opts.startBlockFloor) : definitionStart;
+  return { fromBlock, toBlock: await source.getTip() };
 }
 async function clearReindexMetadata(db, subgraphName) {
   await db.updateTable("subgraphs").set({ reindex_from_block: null, reindex_to_block: null }).where("name", "=", subgraphName).execute();
@@ -3576,10 +3596,11 @@ export {
   resumeReindex,
   resolveReindexResumeBlock,
   resolveReindexBatchConfig,
+  resolveBlockRange,
   reindexSubgraph,
   initialReindexProgressBlock,
   backfillSubgraph
 };
 
-//# debugId=9F4CFC4A2A15675F64756E2164756E21
+//# debugId=E95B0AF0DF971D5864756E2164756E21
 //# sourceMappingURL=reindex.js.map