@secondlayer/subgraphs 4.4.1 → 5.0.0

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

@@ -1,15 +0,0 @@
-/**
-* Decode a hex-encoded Clarity value to a JS object.
-* Returns original value on failure.
-*/
-declare function decodeClarityValue(hex: string): unknown;
-/**
-* Recursively decode all hex-encoded Clarity values in an object.
-* Any string starting with "0x" and longer than 10 chars is attempted.
-*/
-declare function decodeEventData(data: unknown): unknown;
-/**
-* Decode function args array (hex-encoded Clarity values).
-*/
-declare function decodeFunctionArgs(args: string[]): unknown[];
-export { decodeFunctionArgs, decodeEventData, decodeClarityValue };

package/dist/src/runtime/clarity.js

@@ -1,41 +0,0 @@
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/runtime/clarity.ts
-import { cvToValue, deserializeCV } from "@secondlayer/stacks/clarity";
-function decodeClarityValue(hex) {
-  try {
-    const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
-    const cv = deserializeCV(cleanHex);
-    return cvToValue(cv);
-  } catch {
-    return hex;
-  }
-}
-function decodeEventData(data) {
-  if (typeof data === "string" && data.startsWith("0x") && data.length > 10) {
-    return decodeClarityValue(data);
-  }
-  if (Array.isArray(data)) {
-    return data.map(decodeEventData);
-  }
-  if (typeof data === "object" && data !== null) {
-    const decoded = {};
-    for (const [key, value] of Object.entries(data)) {
-      decoded[key] = decodeEventData(value);
-    }
-    return decoded;
-  }
-  return data;
-}
-function decodeFunctionArgs(args) {
-  return args.map(decodeClarityValue);
-}
-export {
-  decodeFunctionArgs,
-  decodeEventData,
-  decodeClarityValue
-};
-
-//# debugId=27ED3AEA8666AA8C64756E2164756E21
-//# sourceMappingURL=clarity.js.map

package/dist/src/runtime/clarity.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/runtime/clarity.ts"],
-  "sourcesContent": [
-    "import { cvToValue, deserializeCV } from \"@secondlayer/stacks/clarity\";\n\n/**\n * Decode a hex-encoded Clarity value to a JS object.\n * Returns original value on failure.\n */\nexport function decodeClarityValue(hex: string): unknown {\n\ttry {\n\t\tconst cleanHex = hex.startsWith(\"0x\") ? hex.slice(2) : hex;\n\t\tconst cv = deserializeCV(cleanHex);\n\t\treturn cvToValue(cv);\n\t} catch {\n\t\treturn hex;\n\t}\n}\n\n/**\n * Recursively decode all hex-encoded Clarity values in an object.\n * Any string starting with \"0x\" and longer than 10 chars is attempted.\n */\nexport function decodeEventData(data: unknown): unknown {\n\tif (typeof data === \"string\" && data.startsWith(\"0x\") && data.length > 10) {\n\t\treturn decodeClarityValue(data);\n\t}\n\n\tif (Array.isArray(data)) {\n\t\treturn data.map(decodeEventData);\n\t}\n\n\tif (typeof data === \"object\" && data !== null) {\n\t\tconst decoded: Record<string, unknown> = {};\n\t\tfor (const [key, value] of Object.entries(data)) {\n\t\t\tdecoded[key] = decodeEventData(value);\n\t\t}\n\t\treturn decoded;\n\t}\n\n\treturn data;\n}\n\n/**\n * Decode function args array (hex-encoded Clarity values).\n */\nexport function decodeFunctionArgs(args: string[]): unknown[] {\n\treturn args.map(decodeClarityValue);\n}\n"
-  ],
-  "mappings": ";;;;AAAA;AAMO,SAAS,kBAAkB,CAAC,KAAsB;AAAA,EACxD,IAAI;AAAA,IACH,MAAM,WAAW,IAAI,WAAW,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI;AAAA,IACvD,MAAM,KAAK,cAAc,QAAQ;AAAA,IACjC,OAAO,UAAU,EAAE;AAAA,IAClB,MAAM;AAAA,IACP,OAAO;AAAA;AAAA;AAQF,SAAS,eAAe,CAAC,MAAwB;AAAA,EACvD,IAAI,OAAO,SAAS,YAAY,KAAK,WAAW,IAAI,KAAK,KAAK,SAAS,IAAI;AAAA,IAC1E,OAAO,mBAAmB,IAAI;AAAA,EAC/B;AAAA,EAEA,IAAI,MAAM,QAAQ,IAAI,GAAG;AAAA,IACxB,OAAO,KAAK,IAAI,eAAe;AAAA,EAChC;AAAA,EAEA,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM;AAAA,IAC9C,MAAM,UAAmC,CAAC;AAAA,IAC1C,YAAY,KAAK,UAAU,OAAO,QAAQ,IAAI,GAAG;AAAA,MAChD,QAAQ,OAAO,gBAAgB,KAAK;AAAA,IACrC;AAAA,IACA,OAAO;AAAA,EACR;AAAA,EAEA,OAAO;AAAA;AAMD,SAAS,kBAAkB,CAAC,MAA2B;AAAA,EAC7D,OAAO,KAAK,IAAI,kBAAkB;AAAA;",
-  "debugId": "27ED3AEA8666AA8C64756E2164756E21",
-  "names": []
-}

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

@@ -1,325 +0,0 @@
-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>
-	};
-}
-/**
-* True for a structural empty mapped type (`{}`) and for codegen's
-* `Record<string, never>`. `keyof Record<string, never>` is `string`, so the
-* first check alone is not enough. Local copy of the `getContract` helper —
-* importing `ContractInstance<C>["read"]` would re-enter the codegen-brand
-* conditional this type exists to avoid.
-*/
-type IsEmptyArgs<A> = [keyof A & string] extends [never] ? true : Record<string, never> extends A ? true : false;
-type ChainReadMethod<
-	A,
-	R
-> = IsEmptyArgs<A> extends true ? (args?: A) => R : (args: A) => R;
-/**
-* 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>] : ChainReadMethod<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 */
-interface SubgraphColumn {
-	type: ColumnType;
-	nullable?: boolean;
-	indexed?: boolean;
-	search?: boolean;
-	default?: string | number | boolean;
-}
-/**
-* A foreign-key relation to another table in the same subgraph. Drives DDL FK
-* constraints and ORM codegen (`@relation` in Prisma, `relations()` in Drizzle)
-* so generated clients get typed joins. The referenced columns must form a
-* `uniqueKeys` entry on the target table.
-*/
-interface SubgraphRelation {
-	/** Relation field name on this table's generated model (e.g. "pool"). */
-	name: string;
-	/** Target table name in this subgraph. */
-	references: string;
-	/** Local column(s) holding the foreign key. */
-	fields: string[];
-	/** Target column(s) the fields point at (a uniqueKeys entry on the target). */
-	referencedColumns: string[];
-}
-/**
-* 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?: readonly (readonly string[])[];
-	/** Unique key constraints (each entry is an array of column names). Required for upsert. */
-	uniqueKeys?: readonly (readonly string[])[];
-	/** Foreign-key relations to other tables (for typed ORM joins). */
-	relations?: readonly SubgraphRelation[];
-}
-/** Subgraph schema — maps table names to table definitions */
-type SubgraphSchema = Record<string, SubgraphTable>;
-/** Scalar types that can appear as row values */
-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 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;
-	/** Full row data (for inserts) or where+set merged (for updates). Bigints stringified. */
-	row: Record<string, unknown>;
-	/** Stable identifier for dedup — `{blockHeight, txId, rowIndex}` */
-	pk: {
-		blockHeight: number
-		txId: string
-		rowIndex: number
-	};
-}
-interface FlushManifest {
-	count: number;
-	writes: FlushWrite[];
-}
-interface BlockMeta {
-	height: number;
-	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;
-	sender: string;
-	type: string;
-	status: string;
-	contractId?: string | null;
-	functionName?: string | null;
-}
-/**
-* Runtime context passed to subgraph handlers.
-* Batches writes and flushes them atomically at the end of a block.
-*
-* Row reads (findOne/findMany) are read-your-writes: they overlay the pending
-* ops queue on the DB state, so a handler observes every write queued earlier
-* in the same block. Without this, accumulator patterns (balance = f(existing))
-* silently lose all but the last same-block delta per row (fix-f040 B1).
-* Aggregate reads (count/sum/min/max) remain pre-flush DB state.
-*/
-declare class SubgraphContext2 {
-	readonly block: BlockMeta;
-	private _tx;
-	private readonly db;
-	private readonly pgSchemaName;
-	private readonly subgraphSchema;
-	/** 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[];
-	/**
-	* Record pre-images of keyed mutations into the schema's `_journal` so a
-	* reorg can restore prior row states (fix-f040 B2). Enabled on the live
-	* path only — deep reindex/backfill heights are past finality, and the
-	* 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, 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;
-	insert(table: string, row: Record<string, unknown>): void;
-	update(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
-	upsert(table: string, key: Record<string, unknown>, row: Record<string, unknown>): void;
-	delete(table: string, where: Record<string, unknown>): void;
-	/**
-	* Atomic counter update — the blessed accumulator primitive. Compiles to
-	* `INSERT ... ON CONFLICT (key) DO UPDATE SET col = COALESCE(t.col,0) + delta`,
-	* so deltas commute: same-block, replayed-in-order, and concurrent updates
-	* all land correctly without read-modify-write. Missing row inserts the
-	* delta as the initial value. Requires a uniqueKeys constraint matching
-	* `key`; deltas may be negative.
-	*/
-	increment(table: string, key: Record<string, unknown>, deltas: Record<string, bigint | number>): void;
-	/** Current length of the pending-ops queue. Pair with {@link rollbackTo}. */
-	opsCheckpoint(): number;
-	/**
-	* Discard ops queued after a checkpoint. The runner wraps each handler
-	* invocation so a thrown handler contributes nothing — without this, a
-	* transfer handler that debited then threw flushes a one-sided debit
-	* (fix-f040 B6).
-	*/
-	rollbackTo(checkpoint: number): void;
-	/** Partial update — sets only specified fields, preserves everything else */
-	patch(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
-	/**
-	* Find-then-merge-or-insert. Values can be functions: (existing) => newValue.
-	* Async because it reads existing row first.
-	*/
-	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>[]>;
-	/**
-	* Replay pending ops for `table` over a single DB-read result so reads
-	* observe earlier same-block writes. Mirrors flush semantics: upserts
-	* merge non-key/non-meta columns, increments add deltas, updates/deletes
-	* apply by where-match. Overlaid rows synthesized from pending inserts
-	* lack DB-generated columns (_id, _created_at).
-	*/
-	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). */
-	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>;
-	max(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;
-	countDistinct(table: string, column: string, where?: Record<string, unknown>): Promise<number>;
-	/** Coerce string values from Postgres back to BigInt for uint/int columns */
-	private coerceRow;
-	/** Number of pending write operations */
-	get pendingOps(): number;
-	/**
-	* Execute all batched writes in a single transaction.
-	* Auto-populates _block_height, _tx_id, _created_at on inserts.
-	*
-	* Returns a {@link FlushManifest} describing every write so downstream
-	* consumers (webhook emitter) can fan out outbox rows atomically
-	* with the flush itself.
-	*/
-	flush(): Promise<FlushManifest>;
-	/**
-	* Run a built statement list on an open transaction.
-	*
-	* Plain statements run in order. An increment runs UPDATE-first and then,
-	* ONLY if that matched nothing, the guarded INSERT — and if the INSERT also
-	* wrote nothing, the UPDATE again.
-	*
-	* That last step is the whole point. Under READ COMMITTED, two block
-	* transactions flushing the same key while the row is absent both see
-	* `UPDATE → 0 rows`; the first commits its INSERT, and the second's
-	* `WHERE NOT EXISTS` then sees that committed row and inserts nothing. No
-	* error, no constraint violation — the second delta was simply dropped.
-	* Re-running the UPDATE takes a fresh snapshot that DOES see the winner's
-	* row and applies the delta onto it.
-	*
-	* It cannot double-apply: the retry is reached only when the first UPDATE
-	* matched no row AND the INSERT wrote no row, so the delta has not been
-	* applied by either.
-	*/
-	private execStatements;
-	/** Prepare a single insert row, returning its data, columns, upsert key for batching. */
-	private prepareInsert;
-	/**
-	* Lazily create `_journal` for schemas deployed before it existed. Cached
-	* per process only once CONFIRMED present (to_regclass) — a CREATE issued
-	* inside a block tx could roll back with it, so self-created tables are
-	* re-verified on the next flush instead of trusted.
-	*/
-	private ensureJournalTable;
-	/** SQL type of a user column (for casting journal key VALUES), if known. */
-	private columnSqlType;
-	/**
-	* Journal pre-images for a keyed batch: one `_journal` row per key with the
-	* row's current state (`prev_row`), or NULL when the key doesn't exist yet
-	* (the mutation will create it — a revert deletes it). Emitted BEFORE the
-	* mutation statement, same transaction.
-	*/
-	private journalCaptureSQL;
-	/** Journal pre-images of rows a where-clause mutation will touch, keyed by `_id`. */
-	private journalCaptureByWhereSQL;
-	/** Build SQL statements from write ops, batching compatible INSERTs. */
-	private buildStatements;
-	private validateTable;
-}
-export { TxMeta2 as TxMeta, SubgraphContext2 as SubgraphContext, JOURNAL_RETENTION_BLOCKS, FlushWrite, FlushManifest, BlockMeta };