@secondlayer/subgraphs 3.21.0 → 3.23.0

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

@@ -1,3 +1,62 @@
+import { UnwrapResponse } from "@secondlayer/stacks/actions";
+import { AbiContract, ExtractFunctionArgs, ExtractFunctionOutput, ExtractReadOnlyFunctions, ToCamelCase } from "@secondlayer/stacks/clarity";
+/**
+* How long a read stays valid.
+*
+* - `per-block` (default): pinned to the block being processed, cached under
+*   its `index_block_hash`. Sound for any read-only function — reindexing the
+*   same block always returns the same value, and a reorg-replaced block has a
+*   different id so it can't inherit the orphaned answer.
+* - `contract-constant`: the caller asserts the value cannot change for this
+*   contract and these args (SIP-010 `get-decimals`/`get-symbol`), so it is
+*   resolved ONCE instead of once per block. This is the mode that makes a
+*   backfill affordable — under `per-block` every block is a distinct key and
+*   therefore a distinct RPC. Declaring it on a value that does change pins the
+*   first answer forever, so it is opt-in and never inferred.
+*/
+type ChainReadCacheMode = "per-block" | "contract-constant";
+type ChainReadOptions = {
+	cache?: ChainReadCacheMode
+};
+/**
+* The chain-read surface, fully typed by an ABI.
+*
+* Shaped like `getContract` from `@secondlayer/stacks` — the same ABI in, the
+* same camelCased read methods out — minus `call`/`buildCall`: a handler
+* indexes the chain, it never writes to it.
+*
+* Reached through {@link readContractAt} rather than off `ctx.client`
+* directly: an ABI-generic method living on the context interface makes every
+* structural comparison of a subgraph definition instantiate it, which exceeds
+* TS's depth budget. At a call site the ABI is already concrete and it costs
+* nothing.
+*/
+interface ChainReadClient {
+	/**
+	* Read-only methods of a contract, evaluated against the exact block being
+	* processed.
+	*
+	* Every call is pinned to the block's `index_block_hash`, so a handler is a
+	* pure function of its block: reindexing a range produces byte-identical
+	* rows. Reading at the node's tip instead would make the same reindex
+	* return different values — that is the corruption this refuses to allow,
+	* so a block whose id was never persisted throws rather than falling back.
+	*
+	* Results are memoized in Postgres, so a value is fetched once per block
+	* rather than once per event (or once per contract with
+	* `cache: "contract-constant"`).
+	*/
+	contract<const C extends AbiContract>(contractId: string, abi: C, options?: ChainReadOptions): {
+		read: ChainReadMethods<C>
+	};
+}
+/**
+* The camelCased read methods of an ABI. Spelled out rather than reused from
+* `ContractInstance<C>["read"]`: that type is a conditional over the codegen
+* brand, and evaluating it wherever a subgraph definition is structurally
+* compared pushes TS past its instantiation depth.
+*/
+type ChainReadMethods<C extends AbiContract> = { [N in ExtractReadOnlyFunctions<C> as ToCamelCase<N>] : (args: ExtractFunctionArgs<C, N>) => Promise<UnwrapResponse<ExtractFunctionOutput<C, N>>> };
 /** Supported column types for subgraph schemas */
 type ColumnType = "text" | "uint" | "int" | "principal" | "boolean" | "timestamp" | "jsonb";
 /** Column definition in a subgraph table */
@@ -24,15 +83,24 @@ interface SubgraphRelation {
 	/** Target column(s) the fields point at (a uniqueKeys entry on the target). */
 	referencedColumns: string[];
 }
-/** Table definition within a subgraph schema */
+/**
+* Table definition within a subgraph schema.
+*
+* The array fields are `readonly` so a schema literal can be hoisted out of
+* the `defineSubgraph()` call with `as const` (or {@link defineSchema}) and
+* still typecheck — `as const` produces `readonly [readonly ["holder"]]`,
+* which a mutable `string[][]` rejects. Without that, extracting a helper
+* that takes `ctx` meant losing the entire typed surface, which is why the
+* shipped starter reached for `ctx: any`.
+*/
 interface SubgraphTable {
 	columns: Record<string, SubgraphColumn>;
 	/** Composite indexes (each entry is an array of column names) */
-	indexes?: string[][];
+	indexes?: readonly (readonly string[])[];
 	/** Unique key constraints (each entry is an array of column names). Required for upsert. */
-	uniqueKeys?: string[][];
+	uniqueKeys?: readonly (readonly string[])[];
 	/** Foreign-key relations to other tables (for typed ORM joins). */
-	relations?: SubgraphRelation[];
+	relations?: readonly SubgraphRelation[];
 }
 /** Subgraph schema — maps table names to table definitions */
 type SubgraphSchema = Record<string, SubgraphTable>;
@@ -40,12 +108,19 @@ type SubgraphSchema = Record<string, SubgraphTable>;
 type RowValue = string | number | bigint | boolean | null | undefined | Record<string, unknown> | unknown[];
 /** Value or computed function that receives existing row */
 type ComputedValue = RowValue | ((existing: Record<string, unknown> | null) => unknown);
-import { Database } from "@secondlayer/shared/db";
-import { Kysely, Transaction } from "kysely";
-type AnyDb = Kysely<Database> | Transaction<Database>;
+import { Database as Database2 } from "@secondlayer/shared/db";
+import { Kysely as Kysely2, Transaction } from "kysely";
+type AnyDb = Kysely2<Database2> | Transaction<Database2>;
 /** Reorg journal entries older than this many blocks are prunable — far past
 *  Stacks finality (observed reorg depth is single digits). */
 declare const JOURNAL_RETENTION_BLOCKS = 300;
+interface WriteOp {
+	kind: "insert" | "update" | "delete" | "increment";
+	table: string;
+	data: Record<string, unknown>;
+	/** For update: SET clause. For increment: column → signed delta. */
+	set?: Record<string, unknown>;
+}
 interface FlushWrite {
 	op: "insert" | "update" | "delete";
 	table: string;
@@ -67,6 +142,13 @@ interface BlockMeta {
 	hash: string;
 	timestamp: number;
 	burnBlockHeight: number;
+	/**
+	* Nakamoto StacksBlockId — the identifier `?tip=` accepts, and the only way
+	* to pin a read-only call to THIS block. Null on rows ingested before it
+	* was persisted; `ctx.client.readOnly` refuses to run rather than silently
+	* reading at the node's tip.
+	*/
+	indexBlockHash?: string | null;
 }
 interface TxMeta2 {
 	txId: string;
@@ -92,7 +174,10 @@ declare class SubgraphContext2 {
 	private readonly db;
 	private readonly pgSchemaName;
 	private readonly subgraphSchema;
-	private readonly ops;
+	/** Pending writes for this block. `protected` so the in-memory test
+	*  context (`@secondlayer/subgraphs/testing`) can materialize them through
+	*  the SAME overlay this class uses — never a second implementation. */
+	protected readonly ops: WriteOp[];
 	/**
 	* BYO data plane: handler writes land in a user-owned DB whose flush can't
 	* share the managed block transaction, so a crash replays the block. When
@@ -108,7 +193,15 @@ declare class SubgraphContext2 {
 	* journal would just be churn the pruner deletes.
 	*/
 	private readonly journal;
+	/** Memoized per block; see the `client` getter. */
+	protected _client?: ChainReadClient;
 	constructor(db: AnyDb, pgSchemaName: string, subgraphSchema: SubgraphSchema, block: BlockMeta, tx: TxMeta2, byo?: boolean, journal?: boolean);
+	/**
+	* Chain reads pinned to THIS block. Lazily built so a handler that never
+	* reads never touches the node config, and so the in-memory test context
+	* can override it without a node.
+	*/
+	get client(): ChainReadClient;
 	get tx(): TxMeta2;
 	/** Update the current transaction context (used by runner between events) */
 	setTx(tx: TxMeta2): void;
@@ -143,6 +236,13 @@ declare class SubgraphContext2 {
 	patchOrInsert(table: string, key: Record<string, unknown>, row: Record<string, ComputedValue>): Promise<void>;
 	/** Format a bigint amount with decimal places */
 	formatUnits(value: bigint, decimals: number): string;
+	/**
+	* Committed rows matching `where`, BEFORE the pending-ops overlay. The one
+	* seam a different backing store replaces (the in-memory test context);
+	* everything above it — validation, overlay, op queueing, flush semantics
+	* — stays here so the two can't diverge.
+	*/
+	protected readRows(table: string, where: Record<string, unknown>, limit?: number): Promise<Record<string, unknown>[]>;
 	findOne(table: string, where: Record<string, unknown>): Promise<Record<string, unknown> | null>;
 	findMany(table: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
 	/**
@@ -152,10 +252,10 @@ declare class SubgraphContext2 {
 	* apply by where-match. Overlaid rows synthesized from pending inserts
 	* lack DB-generated columns (_id, _created_at).
 	*/
-	private overlayOne;
-	private overlayMany;
+	protected overlayOne(table: string, where: Record<string, unknown>, dbRow: Record<string, unknown> | null): Record<string, unknown> | null;
+	protected overlayMany(table: string, where: Record<string, unknown>, dbRows: Record<string, unknown>[]): Record<string, unknown>[];
 	/** Apply one pending op to a candidate row state (null = row absent). */
-	private applyOpToRow;
+	protected applyOpToRow(op: WriteOp, row: Record<string, unknown> | null, where: Record<string, unknown>): Record<string, unknown> | null;
 	count(table: string, where?: Record<string, unknown>): Promise<number>;
 	sum(table: string, column: string, where?: Record<string, unknown>): Promise<bigint>;
 	min(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;

package/dist/src/runtime/context.js

@@ -100,6 +100,18 @@ function emitJournalDDL(schemaName) {
     `CREATE INDEX IF NOT EXISTS idx_${schemaName}_journal_height ON ${schemaName}._journal (block_height)`
   ];
 }
+function emitFactoryDDL(schemaName) {
+  return [
+    `CREATE TABLE IF NOT EXISTS ${schemaName}._factory_addresses (
+  source_name TEXT NOT NULL,
+  address TEXT NOT NULL,
+  block_height BIGINT NOT NULL,
+  _created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (source_name, address)
+)`,
+    `CREATE INDEX IF NOT EXISTS idx_${schemaName}_factory_height ON ${schemaName}._factory_addresses (block_height)`
+  ];
+}
 function emitForeignKeyDDL(schemaName, tableName, tableDef) {
   return (tableDef.relations ?? []).map((rel) => {
     const constraintName = `fk_${schemaName}_${tableName}_${rel.name}`;
@@ -118,6 +130,9 @@ function generateSubgraphSQL(def, schemaNameOverride) {
     statements.push(...emitTableDDL(schemaName, tableName, tableDef));
   }
   statements.push(...emitJournalDDL(schemaName));
+  if (Object.values(def.sources ?? {}).some((src) => src.factory !== undefined)) {
+    statements.push(...emitFactoryDDL(schemaName));
+  }
   for (const [tableName, tableDef] of Object.entries(def.schema)) {
     statements.push(...emitForeignKeyDDL(schemaName, tableName, tableDef));
   }
@@ -130,6 +145,139 @@ function generateSubgraphSQL(def, schemaNameOverride) {
   return { statements, hash };
 }
 
+// src/runtime/chain-read.ts
+import { getSourceDb } from "@secondlayer/shared/db";
+import { http, createPublicClient } from "@secondlayer/stacks";
+import {
+  ContractResponseError,
+  buildFunctionArgs,
+  isResponseOutput,
+  readContract
+} from "@secondlayer/stacks/actions";
+import {
+  clarityValueToJSUntyped,
+  deserializeCV,
+  normalizeAbi,
+  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 })
+  });
+}
+
+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 () => {
+      const value2 = await readContract(nodeClient(rpcUrl), {
+        contract: contractId,
+        functionName: fn.name,
+        args: clarityArgs,
+        tip: ctx.indexBlockHash ?? undefined
+      });
+      return serializeCV(value2);
+    });
+    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 = deserializeCV(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/runtime/context.ts
 var JOURNAL_RETENTION_BLOCKS = 300;
 var journalEnsured = new Set;
@@ -148,6 +296,7 @@ class SubgraphContext {
   ops = [];
   byo;
   journal;
+  _client;
   constructor(db, pgSchemaName2, subgraphSchema, block, tx, byo = false, journal = false) {
     this.db = db;
     this.pgSchemaName = pgSchemaName2;
@@ -157,6 +306,13 @@ class SubgraphContext {
     this.byo = byo;
     this.journal = journal;
   }
+  get client() {
+    this._client ??= createChainReadClient({
+      blockHeight: this.block.height,
+      indexBlockHash: this.block.indexBlockHash
+    });
+    return this._client;
+  }
   get tx() {
     return this._tx;
   }
@@ -262,23 +418,21 @@ class SubgraphContext {
   formatUnits(value, decimals) {
     return formatUnits(value, decimals);
   }
-  async findOne(table, where) {
-    this.validateTable(table);
+  async readRows(table, where, limit) {
     const qualifiedTable = `"${this.pgSchemaName}"."${table}"`;
     const { clause } = buildWhereClause(where);
-    const query = `SELECT * FROM ${qualifiedTable} WHERE ${clause} LIMIT 1`;
+    const query = `SELECT * FROM ${qualifiedTable} WHERE ${clause}${limit !== undefined ? ` LIMIT ${limit}` : ""}`;
     const { rows } = await sql.raw(query).execute(this.db);
-    const row = rows[0] ?? null;
-    return this.overlayOne(table, where, row ? this.coerceRow(table, row) : null);
+    return rows.map((r) => this.coerceRow(table, r));
+  }
+  async findOne(table, where) {
+    this.validateTable(table);
+    const row = (await this.readRows(table, where, 1))[0] ?? null;
+    return this.overlayOne(table, where, row);
   }
   async findMany(table, where) {
     this.validateTable(table);
-    const qualifiedTable = `"${this.pgSchemaName}"."${table}"`;
-    const { clause } = buildWhereClause(where);
-    const query = `SELECT * FROM ${qualifiedTable} WHERE ${clause}`;
-    const { rows } = await sql.raw(query).execute(this.db);
-    const dbRows = rows.map((r) => this.coerceRow(table, r));
-    return this.overlayMany(table, where, dbRows);
+    return this.overlayMany(table, where, await this.readRows(table, where));
   }
   overlayOne(table, where, dbRow) {
     if (this.ops.length === 0)
@@ -723,5 +877,5 @@ export {
   JOURNAL_RETENTION_BLOCKS
 };
 
-//# debugId=E55C45575AA28BA564756E2164756E21
+//# debugId=943E34F234EEBFC564756E2164756E21
 //# sourceMappingURL=context.js.map