@secondlayer/subgraphs 3.13.0 → 3.14.1

package/dist/src/index.d.ts

@@ -664,6 +664,52 @@ declare function defineSubgraph<
 	const Sources extends Record<string, SubgraphFilter>,
 	const S extends SubgraphSchema
 >(def: TypedSubgraphDefinition<Sources, S>): TypedSubgraphDefinition<Sources, S>;
+/**
+* Empirical print-payload schema inference. Callers (the index print-schema
+* endpoint) extract topic + raw Clarity hex per row; this module deserializes
+* a bounded sample per topic, unifies the observed value shapes into a single
+* structural tree, and renders Clarity/TS/ColumnType views of each field.
+*/
+interface PrintSample {
+	blockHeight: number;
+	topic: string;
+	rawHex: string | null;
+}
+interface InferredPrintField {
+	/** Original kebab-case tuple key (the `topic` discriminant is excluded) */
+	name: string;
+	/** What handlers see on `e.data` — exact runner camelization */
+	camel_name: string;
+	/** Rendered Clarity type; buff/string lengths are the max observed */
+	clarity_type: string;
+	/** Decoded handler value type (uint→bigint, buffer→string, …) */
+	ts_type: string;
+	column_type: ColumnType;
+	/** Present in 100% of this topic's decoded samples */
+	always_present: boolean;
+	/** Only when optional observed: share of present samples that were some */
+	optional_some_rate?: number;
+}
+interface InferredTopicSchema {
+	topic: string;
+	count: number;
+	first_height: number;
+	last_height: number;
+	non_tuple: boolean;
+	fields: InferredPrintField[];
+}
+/**
+* Kebab-case → camelCase using the exact runner regex, so `camel_name`
+* matches what handlers see on `e.data` (runner.ts camelizeKeys).
+*/
+declare function camelizeDataKey(str: string): string;
+/**
+* Infers per-topic field schemas from sampled print events. Counts and
+* height bounds cover ALL rows of a topic (cheap); only a bounded subset is
+* deserialized for typing. Rows with missing/undecodable hex still count but
+* contribute nothing to typing.
+*/
+declare function inferPrintTopics(samples: PrintSample[]): InferredTopicSchema[];
 interface GeneratedSQL {
 	statements: string[];
 	hash: string;
@@ -829,4 +875,4 @@ type SparseProbeTarget = {
 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 };
+export { validateSubgraphDefinition, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, diffSchema, deploySchema, defineSubgraph, canSparseScan, camelizeDataKey, 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, PrintSample, PrintEventPayload, PrintEventFor, PrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferredTopicSchema, InferredPrintField, 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

@@ -62,7 +62,8 @@ var SubgraphFilterSchema = z.object({
   topic: z.string().optional(),
   lockedAddress: z.string().optional(),
   abi: z.record(z.string(), z.any()).optional(),
-  trait: z.string().optional()
+  trait: z.string().optional(),
+  prints: z.record(z.string(), z.record(z.string(), ColumnTypeSchema)).optional()
 }).strict();
 var SubgraphDefinitionSchema = z.object({
   name: SubgraphNameSchema,
@@ -1409,6 +1410,7 @@ function matchSources(sources, transactions, events, traitContracts = new Map) {
 // src/runtime/block-processor.ts
 import { getTargetDb } from "@secondlayer/shared/db";
 import { resolveTraitContractIds } from "@secondlayer/shared/db/queries/contracts";
+import { advanceOperationCursor } from "@secondlayer/shared/db/queries/subgraph-operations";
 import {
   isByoSubgraph,
   recordSubgraphProcessed,
@@ -2028,6 +2030,21 @@ async function resolveTraitContracts(subgraph, blockHeight, db) {
   }
   return resolved;
 }
+
+class CursorRaceLostError extends Error {
+  constructor(operationId, height) {
+    super(`op ${operationId} lost cursor race at block ${height}`);
+    this.name = "CursorRaceLostError";
+  }
+}
+function opCursorMode(opts) {
+  const ap = opts?.atomicProgress;
+  return ap && "operationId" in ap ? ap : undefined;
+}
+function statusMode(opts) {
+  const ap = opts?.atomicProgress;
+  return ap && "status" in ap ? ap : undefined;
+}
 var BLOCK_RETRY_DELAYS_MS = [500, 2000, 5000];
 function journalEnabled(opts) {
   return !opts?.skipProgressUpdate;
@@ -2121,12 +2138,19 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
     }
   };
   if (route.byo) {
-    if (opts?.atomicProgress) {
+    if (statusMode(opts)) {
       const row = await targetDb.selectFrom("subgraphs").select("last_processed_block").where("name", "=", subgraphName).executeTakeFirst();
       if (row && Number(row.last_processed_block) >= blockHeight) {
         result.skipped = true;
         return result;
       }
+    } else if (opCursorMode(opts)) {
+      const om = opCursorMode(opts);
+      const row = await targetDb.selectFrom("subgraph_operations").select("cursor_block").where("id", "=", om.operationId).executeTakeFirst();
+      if (row?.cursor_block != null && Number(row.cursor_block) >= blockHeight) {
+        result.skipped = true;
+        return result;
+      }
     }
     let runResult = { processed: 0, errors: 0 };
     let manifest;
@@ -2147,41 +2171,71 @@ async function processBlock(subgraph, subgraphName, blockHeight, opts) {
       if (manifest && manifest.count > 0) {
         await emitSubscriptionOutbox(tx, subgraphName, manifest, matcher, block.height);
       }
-      if (opts?.atomicProgress && manifest && manifest.count > 0) {
-        await updateSubgraphStatus(tx, subgraphName, opts.atomicProgress.status, blockHeight);
+      const byoSm = statusMode(opts);
+      const byoOm = opCursorMode(opts);
+      if (byoSm && manifest && manifest.count > 0) {
+        await updateSubgraphStatus(tx, subgraphName, byoSm.status, blockHeight);
+      } else if (byoOm && manifest && manifest.count > 0) {
+        await advanceOperationCursor(tx, byoOm.operationId, blockHeight);
       }
       await applyProgress(tx, runResult);
     });
   } else {
-    await targetDb.transaction().execute(async (tx) => {
-      if (opts?.atomicProgress) {
-        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;
+    try {
+      await targetDb.transaction().execute(async (tx) => {
+        const opMode = opCursorMode(opts);
+        if (statusMode(opts)) {
+          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;
+          }
+        } else if (opMode) {
+          const row = await tx.selectFrom("subgraph_operations").select("cursor_block").where("id", "=", opMode.operationId).executeTakeFirst();
+          if (row?.cursor_block != null && Number(row.cursor_block) >= blockHeight) {
+            result.skipped = true;
+            return;
+          }
         }
-      }
-      const ctx = new SubgraphContext(tx, schemaName, subgraph.schema, blockMeta, initialTx, false, journalEnabled(opts));
-      const handlerStart = performance.now();
-      const runResult = await runHandlers(subgraph, matched, ctx);
-      handlerMs = performance.now() - handlerStart;
-      result.processed = runResult.processed;
-      result.errors = runResult.errors;
-      let flushedWrites = false;
-      if (ctx.pendingOps > 0) {
-        const flushStart = performance.now();
-        const manifest = await ctx.flush();
-        flushedWrites = manifest.count > 0;
-        if (manifest.count > 0) {
-          await emitSubscriptionOutbox(tx, subgraphName, manifest, matcher, block.height);
+        const ctx = new SubgraphContext(tx, schemaName, subgraph.schema, blockMeta, initialTx, false, journalEnabled(opts));
+        const handlerStart = performance.now();
+        const runResult = await runHandlers(subgraph, matched, ctx);
+        handlerMs = performance.now() - handlerStart;
+        result.processed = runResult.processed;
+        result.errors = runResult.errors;
+        let flushedWrites = false;
+        if (ctx.pendingOps > 0) {
+          const flushStart = performance.now();
+          const manifest = await ctx.flush();
+          flushedWrites = manifest.count > 0;
+          if (manifest.count > 0) {
+            await emitSubscriptionOutbox(tx, subgraphName, manifest, matcher, block.height);
+          }
+          flushMs = performance.now() - flushStart;
         }
-        flushMs = performance.now() - flushStart;
-      }
-      if (opts?.atomicProgress && flushedWrites) {
-        await updateSubgraphStatus(tx, subgraphName, opts.atomicProgress.status, blockHeight);
+        const sm = statusMode(opts);
+        if (sm && flushedWrites) {
+          await updateSubgraphStatus(tx, subgraphName, sm.status, blockHeight);
+        } else if (opMode && flushedWrites) {
+          const advanced = await advanceOperationCursor(tx, opMode.operationId, blockHeight);
+          if (!advanced) {
+            throw new CursorRaceLostError(opMode.operationId, blockHeight);
+          }
+        }
+        await applyProgress(tx, runResult);
+      });
+    } catch (err) {
+      if (err instanceof CursorRaceLostError) {
+        logger5.warn("cursor race lost — block already covered", {
+          subgraph: subgraphName,
+          blockHeight,
+          error: err.message
+        });
+        result.skipped = true;
+        return result;
       }
-      await applyProgress(tx, runResult);
-    });
+      throw err;
+    }
   }
   const totalMs = performance.now() - blockStart;
   result.timing = {
@@ -2286,7 +2340,10 @@ import {
   recordGapBatch,
   resolveGaps
 } from "@secondlayer/shared/db/queries/subgraph-gaps";
-import { updateOperationProcessedEvents } from "@secondlayer/shared/db/queries/subgraph-operations";
+import {
+  advanceOperationCursor as advanceOperationCursor2,
+  updateOperationProcessedEvents
+} from "@secondlayer/shared/db/queries/subgraph-operations";
 import {
   recordSubgraphProcessed as recordSubgraphProcessed2,
   updateSubgraphStatus as updateSubgraphStatus2
@@ -2359,6 +2416,7 @@ async function processBlockRange(def, opts) {
   const totalBlocks = toBlock - fromBlock + 1;
   const stats = new StatsAccumulator(subgraphName, opts.isCatchup);
   let blocksProcessed = 0;
+  let blocksSkippedByCursor = 0;
   let totalEventsProcessed = 0;
   let totalErrors = 0;
   let pendingEventsProcessed = 0;
@@ -2419,7 +2477,8 @@ async function processBlockRange(def, opts) {
     }
     const batchFailedBlocks = [];
     let batchMatched = 0;
-    const atomicProgress = status === "reindexing" ? { status } : undefined;
+    const opCursor = status === "active" && opts.operationId ? { operationId: opts.operationId } : undefined;
+    const atomicProgress = status === "reindexing" ? { status } : opCursor;
     for (let height = currentHeight;height <= batchEnd; height++) {
       let blockData = batch.get(height);
       if (!blockData) {
@@ -2459,6 +2518,8 @@ async function processBlockRange(def, opts) {
         continue;
       }
       blocksProcessed++;
+      if (result.skipped)
+        blocksSkippedByCursor++;
       batchMatched += result.matched;
       totalEventsProcessed += result.processed;
       totalErrors += result.errors;
@@ -2476,7 +2537,11 @@ async function processBlockRange(def, opts) {
       const now = Date.now();
       const shouldFlushProgress = blocksProcessed % 100 === 0 || now - lastProgressFlushAt >= PROGRESS_FLUSH_INTERVAL_MS;
       if (shouldFlushProgress) {
-        await updateSubgraphStatus2(targetDb, subgraphName, status, height);
+        if (opCursor) {
+          await advanceOperationCursor2(targetDb, opCursor.operationId, height);
+        } else {
+          await updateSubgraphStatus2(targetDb, subgraphName, status, height);
+        }
         if (opts.operationId) {
           await updateOperationProcessedEvents(targetDb, opts.operationId, totalEventsProcessed).catch(() => {});
         }
@@ -2488,7 +2553,8 @@ async function processBlockRange(def, opts) {
           processed: blocksProcessed,
           total: totalBlocks,
           currentBlock: height,
-          pct: Math.round(blocksProcessed / totalBlocks * 100)
+          pct: Math.round(blocksProcessed / totalBlocks * 100),
+          ...blocksSkippedByCursor > 0 ? { skippedByCursor: blocksSkippedByCursor } : {}
         });
       }
     }
@@ -2514,7 +2580,11 @@ async function processBlockRange(def, opts) {
       if (jumpTo > batchEnd + 1) {
         const skipped = Math.min(jumpTo, toBlock + 1) - (batchEnd + 1);
         blocksProcessed += skipped;
-        await updateSubgraphStatus2(targetDb, subgraphName, status, jumpTo - 1);
+        if (opCursor) {
+          await advanceOperationCursor2(targetDb, opCursor.operationId, jumpTo - 1);
+        } else {
+          await updateSubgraphStatus2(targetDb, subgraphName, status, jumpTo - 1);
+        }
         logger6.info("Sparse skip", {
           subgraph: subgraphName,
           from: batchEnd + 1,
@@ -2572,7 +2642,11 @@ async function reindexSubgraph(def, opts) {
     for (const stmt of statements) {
       await client.unsafe(stmt);
     }
-    logger6.info("Schema recreated for reindex", { subgraph: subgraphName });
+    await updateSubgraphStatus2(targetDb, subgraphName, "reindexing", Math.max(0, fromBlock - 1));
+    logger6.info("Schema recreated for reindex", {
+      subgraph: subgraphName,
+      cursorResetTo: Math.max(0, fromBlock - 1)
+    });
     await targetDb.updateTable("subgraphs").set({
       last_processed_block: initialReindexProgressBlock(fromBlock),
       reindex_from_block: fromBlock,
@@ -2756,6 +2830,336 @@ async function backfillSubgraph(def, opts) {
 function defineSubgraph(def) {
   return def;
 }
+// src/print-schema.ts
+import {
+  deserializeCV as deserializeCV3
+} from "@secondlayer/stacks/clarity";
+function camelizeDataKey(str) {
+  return str.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function cvToTree(cv) {
+  switch (cv.type) {
+    case "uint":
+    case "int":
+      return { kind: cv.type };
+    case "true":
+    case "false":
+      return { kind: "bool" };
+    case "address":
+    case "contract":
+      return { kind: "principal" };
+    case "buffer":
+      return { kind: "buffer", len: cv.value.length / 2 };
+    case "ascii":
+      return { kind: "ascii", len: cv.value.length };
+    case "utf8":
+      return { kind: "utf8", len: new TextEncoder().encode(cv.value).length };
+    case "none":
+      return { kind: "optional", inner: null };
+    case "some":
+      return { kind: "optional", inner: cvToTree(cv.value) };
+    case "ok":
+      return { kind: "response", ok: cvToTree(cv.value), err: null };
+    case "err":
+      return { kind: "response", ok: null, err: cvToTree(cv.value) };
+    case "list": {
+      let inner = null;
+      for (const el of cv.value) {
+        const t = cvToTree(el);
+        inner = inner ? unify(inner, t) : t;
+      }
+      return { kind: "list", inner };
+    }
+    case "tuple": {
+      const entries = new Map;
+      for (const [k, v] of Object.entries(cv.value)) {
+        entries.set(k, { tree: cvToTree(v), present: 1 });
+      }
+      return { kind: "tuple", count: 1, entries };
+    }
+  }
+}
+function unifyNullable(a, b) {
+  if (!a)
+    return b;
+  if (!b)
+    return a;
+  return unify(a, b);
+}
+var UNION_KIND_ORDER = {
+  uint: 0,
+  int: 1,
+  bool: 2,
+  principal: 3,
+  buffer: 4,
+  ascii: 5,
+  utf8: 6,
+  list: 7,
+  tuple: 8,
+  response: 9
+};
+function makeUnion(members) {
+  const sorted = [...members].sort((a, b) => (UNION_KIND_ORDER[a.kind] ?? 99) - (UNION_KIND_ORDER[b.kind] ?? 99));
+  return { kind: "union", members: sorted };
+}
+function unify(a, b) {
+  if (a.kind === "optional" || b.kind === "optional") {
+    const ai = a.kind === "optional" ? a.inner : a;
+    const bi = b.kind === "optional" ? b.inner : b;
+    return { kind: "optional", inner: unifyNullable(ai, bi) };
+  }
+  if (a.kind === "union")
+    return unionAdd(a.members, b);
+  if (b.kind === "union")
+    return unionAdd(b.members, a);
+  if (a.kind !== b.kind)
+    return makeUnion([a, b]);
+  switch (a.kind) {
+    case "uint":
+    case "int":
+    case "bool":
+    case "principal":
+      return a;
+    case "buffer":
+    case "ascii":
+    case "utf8":
+      return { kind: a.kind, len: Math.max(a.len, b.len) };
+    case "list":
+      return {
+        kind: "list",
+        inner: unifyNullable(a.inner, b.inner)
+      };
+    case "response": {
+      const rb = b;
+      return {
+        kind: "response",
+        ok: unifyNullable(a.ok, rb.ok),
+        err: unifyNullable(a.err, rb.err)
+      };
+    }
+    case "tuple": {
+      const tb = b;
+      const entries = new Map([...a.entries].map(([k, e]) => [k, { ...e }]));
+      for (const [k, e] of tb.entries) {
+        const existing = entries.get(k);
+        entries.set(k, existing ? {
+          tree: unify(existing.tree, e.tree),
+          present: existing.present + e.present
+        } : { ...e });
+      }
+      return { kind: "tuple", count: a.count + tb.count, entries };
+    }
+  }
+}
+function unionAdd(members, t) {
+  if (t.kind === "union") {
+    let acc = { kind: "union", members };
+    for (const m of t.members)
+      acc = unify(acc, m);
+    return acc;
+  }
+  const next = [...members];
+  for (let i = 0;i < next.length; i++) {
+    const member = next[i];
+    if (!member)
+      continue;
+    const merged = unify(member, t);
+    if (merged.kind !== "union") {
+      next[i] = merged;
+      return makeUnion(next);
+    }
+  }
+  next.push(t);
+  return makeUnion(next);
+}
+function wrapOptional(t) {
+  return t.kind === "optional" ? t : { kind: "optional", inner: t };
+}
+function renderClarity(t) {
+  if (!t)
+    return "?";
+  switch (t.kind) {
+    case "uint":
+    case "int":
+    case "bool":
+    case "principal":
+      return t.kind;
+    case "buffer":
+      return `(buff ${t.len})`;
+    case "ascii":
+      return `(string-ascii ${t.len})`;
+    case "utf8":
+      return `(string-utf8 ${t.len})`;
+    case "optional":
+      return `(optional ${renderClarity(t.inner)})`;
+    case "list":
+      return `(list ${renderClarity(t.inner)})`;
+    case "response":
+      return `(response ${renderClarity(t.ok)} ${renderClarity(t.err)})`;
+    case "tuple": {
+      const parts = [...t.entries].map(([k, e]) => {
+        const tree = e.present < t.count ? wrapOptional(e.tree) : e.tree;
+        return `(${k} ${renderClarity(tree)})`;
+      });
+      return `(tuple ${parts.join(" ")})`;
+    }
+    case "union":
+      return t.members.map(renderClarity).join(" | ");
+  }
+}
+function renderTs(t) {
+  if (!t)
+    return "unknown";
+  switch (t.kind) {
+    case "uint":
+    case "int":
+      return "bigint";
+    case "bool":
+      return "boolean";
+    case "principal":
+    case "buffer":
+    case "ascii":
+    case "utf8":
+      return "string";
+    case "optional":
+      return t.inner ? `${renderTs(t.inner)} | null` : "unknown | null";
+    case "list": {
+      const inner = renderTs(t.inner);
+      return inner.includes(" | ") ? `(${inner})[]` : `${inner}[]`;
+    }
+    case "response": {
+      const sides = [...new Set([renderTs(t.ok), renderTs(t.err)])];
+      return sides.join(" | ");
+    }
+    case "tuple": {
+      const parts = [...t.entries].map(([k, e]) => {
+        const opt = e.present < t.count ? "?" : "";
+        return `${camelizeDataKey(k)}${opt}: ${renderTs(e.tree)}`;
+      });
+      return `{ ${parts.join("; ")} }`;
+    }
+    case "union":
+      return [...new Set(t.members.map((m) => renderTs(m)))].join(" | ");
+  }
+}
+function toColumnType(t) {
+  if (!t)
+    return "jsonb";
+  switch (t.kind) {
+    case "uint":
+      return "uint";
+    case "int":
+      return "int";
+    case "bool":
+      return "boolean";
+    case "principal":
+      return "principal";
+    case "buffer":
+    case "ascii":
+    case "utf8":
+      return "text";
+    case "list":
+    case "tuple":
+      return "jsonb";
+    case "optional":
+      return toColumnType(t.inner);
+    case "response":
+      return t.ok ? toColumnType(t.ok) : "jsonb";
+    case "union":
+      return "jsonb";
+  }
+}
+var MAX_DECODED_PER_TOPIC_NEWEST = 75;
+var MAX_DECODED_PER_TOPIC_OLDEST = 25;
+function inferPrintTopics(samples) {
+  const groups = new Map;
+  for (const s of samples) {
+    const group = groups.get(s.topic);
+    if (group)
+      group.push(s);
+    else
+      groups.set(s.topic, [s]);
+  }
+  const out = [];
+  for (const [topic, rows] of groups) {
+    let first = Number.POSITIVE_INFINITY;
+    let last = Number.NEGATIVE_INFINITY;
+    for (const r of rows) {
+      if (r.blockHeight < first)
+        first = r.blockHeight;
+      if (r.blockHeight > last)
+        last = r.blockHeight;
+    }
+    const withHex = [...rows].filter((r) => r.rawHex !== null).sort((a, b) => b.blockHeight - a.blockHeight);
+    const budget = MAX_DECODED_PER_TOPIC_NEWEST + MAX_DECODED_PER_TOPIC_OLDEST;
+    const picked = withHex.length <= budget ? withHex : [
+      ...withHex.slice(0, MAX_DECODED_PER_TOPIC_NEWEST),
+      ...withHex.slice(-MAX_DECODED_PER_TOPIC_OLDEST)
+    ];
+    const tuples = [];
+    let decoded = 0;
+    for (const p of picked) {
+      try {
+        const cv = deserializeCV3(p.rawHex);
+        decoded++;
+        if (cv.type === "tuple")
+          tuples.push(cv);
+      } catch {}
+    }
+    const nonTuple = decoded > 0 && tuples.length === 0;
+    const fields = [];
+    if (!nonTuple) {
+      const stats = new Map;
+      for (const t of tuples) {
+        for (const [key2, value] of Object.entries(t.value)) {
+          if (key2 === "topic")
+            continue;
+          const tree = cvToTree(value);
+          const existing = stats.get(key2);
+          if (existing) {
+            existing.present++;
+            existing.tree = unify(existing.tree, tree);
+            if (value.type === "none")
+              existing.noneCount++;
+            if (value.type === "none" || value.type === "some") {
+              existing.optionalSeen = true;
+            }
+          } else {
+            stats.set(key2, {
+              tree,
+              present: 1,
+              noneCount: value.type === "none" ? 1 : 0,
+              optionalSeen: value.type === "none" || value.type === "some"
+            });
+          }
+        }
+      }
+      for (const [name, st] of [...stats].sort(([a], [b]) => a.localeCompare(b))) {
+        const field = {
+          name,
+          camel_name: camelizeDataKey(name),
+          clarity_type: renderClarity(st.tree),
+          ts_type: renderTs(st.tree),
+          column_type: toColumnType(st.tree),
+          always_present: st.present === tuples.length
+        };
+        if (st.optionalSeen) {
+          field.optional_some_rate = (st.present - st.noneCount) / st.present;
+        }
+        fields.push(field);
+      }
+    }
+    out.push({
+      topic,
+      count: rows.length,
+      first_height: first,
+      last_height: last,
+      non_tuple: nonTuple,
+      fields
+    });
+  }
+  return out.sort((a, b) => b.count - a.count);
+}
 // src/schema/prisma.ts
 var PRISMA_TYPE = {
   uint: { type: "Decimal", db: "@db.Numeric" },
@@ -3602,6 +4006,7 @@ export {
   renderDeployPlan,
   reindexSubgraph,
   pgSchemaName,
+  inferPrintTopics,
   hasBreakingChanges,
   generateSubgraphSQL,
   generatePrismaSchema,
@@ -3612,10 +4017,11 @@ export {
   deploySchema,
   defineSubgraph,
   canSparseScan,
+  camelizeDataKey,
   backfillSubgraph,
   INDEX_CODEGEN_TABLES,
   ByoBreakingChangeError
 };
 
-//# debugId=A7DC4F802366B29864756E2164756E21
+//# debugId=9ABB4400810C6A0464756E2164756E21
 //# sourceMappingURL=index.js.map