@secondlayer/subgraphs 3.11.0 → 3.12.0

package/dist/src/index.d.ts

@@ -237,6 +237,9 @@ interface SubgraphDefinition {
 	description?: string;
 	/** Block height to start indexing from (default: 1) */
 	startBlock?: number;
+	/** 'concurrent' = tip-first: live at tip now, history backfills behind.
+	*  Requires order-tolerant handlers. Default 'blocking'. */
+	backfillMode?: "blocking" | "concurrent";
 	/** Named source filters — keys become handler keys */
 	sources: Record<string, SubgraphFilter>;
 	/** Tables in this subgraph */
@@ -252,6 +255,8 @@ interface ReindexOptions {
 	fromBlock?: number;
 	toBlock?: number;
 	schemaName?: string;
+	/** Op row to receive processed_events on each progress flush. */
+	operationId?: string;
 	signal?: AbortSignal;
 }
 /**
@@ -269,6 +274,7 @@ declare function reindexSubgraph(def: SubgraphDefinition, opts?: ReindexOptions)
 */
 declare function resumeReindex(def: SubgraphDefinition, opts: {
 	schemaName: string
+	operationId?: string
 	signal?: AbortSignal
 }): Promise<{
 	processed: number
@@ -282,6 +288,7 @@ declare function backfillSubgraph(def: SubgraphDefinition, opts: {
 	fromBlock: number
 	toBlock: number
 	schemaName?: string
+	operationId?: string
 	signal?: AbortSignal
 }): Promise<{
 	processed: number
@@ -727,6 +734,14 @@ interface ColumnDiff {
 * Compare two multi-table subgraph schemas and return differences.
 */
 declare function diffSchema(existing: SubgraphSchema, incoming: SubgraphSchema): TableDiff;
+/**
+* Returns true if the diff contains any breaking changes
+* (removed tables, removed columns, or changed column types).
+*/
+declare function hasBreakingChanges(diff: TableDiff): {
+	breaking: boolean
+	reasons: string[]
+};
 interface DeployDiff {
 	addedTables: string[];
 	removedTables: string[];
@@ -794,4 +809,17 @@ declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: s
 	version: string
 	diff?: DeployDiff
 }>;
-export { validateSubgraphDefinition, resumeReindex, renderDeployPlan, reindexSubgraph, pgSchemaName, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, diffSchema, deploySchema, defineSubgraph, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, RowValue, ReindexOptions, PrismaGenOptions, PrintEventPayload, PrintEventFor, PrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferTableRow, InferSubgraphClient, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, EventForFilter, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ByoMigrationPlan, ByoBreakingChangeError, AnyEvent, AggregateSpec, AggregateResult };
+/** A (decoded event type, optional contract scope) pair the sparse probe
+*  checks. Contract scoping is what makes token-subgraph reindexes leap over
+*  everything that isn't their token. */
+type SparseProbeTarget = {
+	eventType: string
+	contractId?: string
+};
+/** Sparse scanning is sound only when EVERY source is an event-type filter —
+*  a contract_call/contract_deploy source matches transactions, which the
+*  event probe can't see. */
+declare function canSparseScan(subgraph: SubgraphDefinition): boolean;
+/** Probe targets for a subgraph's filters: decoded type + contract scope when\\n*  the filter pins one (assetIdentifier "SP….contract::asset" or contractId). */
+declare function sparseProbeTargets(subgraph: SubgraphDefinition): SparseProbeTarget[];
+export { validateSubgraphDefinition, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, pgSchemaName, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, diffSchema, deploySchema, defineSubgraph, canSparseScan, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintEventPayload, PrintEventFor, PrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferTableRow, InferSubgraphClient, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, EventForFilter, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ByoMigrationPlan, ByoBreakingChangeError, AnyEvent, AggregateSpec, AggregateResult };

package/dist/src/index.js

@@ -69,6 +69,7 @@ var SubgraphDefinitionSchema = z.object({
   version: z.string().optional(),
   description: z.string().optional(),
   startBlock: z.number().int().nonnegative().optional(),
+  backfillMode: z.enum(["blocking", "concurrent"]).optional(),
   sources: z.record(z.string(), SubgraphFilterSchema).refine((s) => Object.keys(s).length > 0, "Must have at least one source"),
   schema: SubgraphSchemaSchema,
   handlers: z.record(z.string(), z.any())
@@ -1858,6 +1859,7 @@ import {
   recordGapBatch,
   resolveGaps
 } from "@secondlayer/shared/db/queries/subgraph-gaps";
+import { updateOperationProcessedEvents } from "@secondlayer/shared/db/queries/subgraph-operations";
 import {
   recordSubgraphProcessed as recordSubgraphProcessed2,
   updateSubgraphStatus as updateSubgraphStatus2
@@ -2124,6 +2126,9 @@ async function processBlockRange(def, opts) {
       const shouldFlushProgress = blocksProcessed % 100 === 0 || now - lastProgressFlushAt >= PROGRESS_FLUSH_INTERVAL_MS;
       if (shouldFlushProgress) {
         await updateSubgraphStatus2(targetDb, subgraphName, status, height);
+        if (opts.operationId) {
+          await updateOperationProcessedEvents(targetDb, opts.operationId, totalEventsProcessed).catch(() => {});
+        }
         lastProgressFlushAt = now;
       }
       if (blocksProcessed % LOG_INTERVAL === 0) {
@@ -2241,6 +2246,7 @@ async function reindexSubgraph(def, opts) {
       isCatchup: false,
       apiKeyId: null,
       subgraphId: subgraphRow?.id,
+      operationId: opts?.operationId,
       signal: opts?.signal
     });
     if (result.aborted) {
@@ -2316,6 +2322,7 @@ async function resumeReindex(def, opts) {
       isCatchup: false,
       apiKeyId: null,
       subgraphId: row.id,
+      operationId: opts.operationId,
       signal: opts.signal
     });
     if (result.aborted) {
@@ -2364,6 +2371,7 @@ async function backfillSubgraph(def, opts) {
       isCatchup: false,
       apiKeyId: null,
       subgraphId: subgraphRow?.id,
+      operationId: opts.operationId,
       signal: opts.signal
     });
     if (result.aborted) {
@@ -3238,10 +3246,12 @@ function getDefault(type) {
 }
 export {
   validateSubgraphDefinition,
+  sparseProbeTargets,
   resumeReindex,
   renderDeployPlan,
   reindexSubgraph,
   pgSchemaName,
+  hasBreakingChanges,
   generateSubgraphSQL,
   generatePrismaSchema,
   generateKyselySchema,
@@ -3250,10 +3260,11 @@ export {
   diffSchema,
   deploySchema,
   defineSubgraph,
+  canSparseScan,
   backfillSubgraph,
   INDEX_CODEGEN_TABLES,
   ByoBreakingChangeError
 };
 
-//# debugId=9A94DC6E9FCF6CD964756E2164756E21
+//# debugId=415665ECDA2A436C64756E2164756E21
 //# sourceMappingURL=index.js.map