@secondlayer/subgraphs 6.3.6 → 6.5.0

package/dist/verification.d.ts

@@ -0,0 +1,441 @@
+import { SubgraphVerification } from "@secondlayer/shared/schemas/subgraphs";
+import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
+import { AssetIdentifier } from "@secondlayer/stacks/filters";
+/**
+* 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;
+};
+/**
+* `ChainReadClient` with the ABI generic erased. Structurally cheap, so the
+* base `SubgraphContext` can carry it; `TypedSubgraphContext` uses the real
+* one and handlers get full inference.
+*/
+interface ErasedChainReadClient {
+	contract(contractId: string, abi: unknown, options?: ChainReadOptions): {
+		read: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>;
+	};
+}
+/** 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;
+}
+/**
+* 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[])[];
+}
+/** Subgraph schema — maps table names to table definitions */
+type SubgraphSchema = Record<string, SubgraphTable>;
+/** STX event filters */
+interface StxTransferFilter {
+	type: "stx_transfer";
+	sender?: string;
+	recipient?: string;
+	minAmount?: bigint;
+	maxAmount?: bigint;
+}
+interface StxMintFilter {
+	type: "stx_mint";
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface StxBurnFilter {
+	type: "stx_burn";
+	sender?: string;
+	minAmount?: bigint;
+}
+interface StxLockFilter {
+	type: "stx_lock";
+	lockedAddress?: string;
+	minAmount?: bigint;
+}
+/**
+* Restrict a source to contracts conforming to a trait/standard (e.g. "sip-010")
+* instead of a fixed contract — resolved from the contract registry at match time,
+* as-of each processed block. Lets a source index "all SIP-010 tokens" etc.
+*/
+type TraitScope = {
+	trait?: string;
+};
+/**
+* Scope a source to a DYNAMIC address set discovered from another source's
+* events, instead of a fixed contract list.
+*
+* The standard shape it unlocks: a router plus pools created after you
+* deploy. `contractId` arrays cover a set you know at authoring time; a
+* factory covers the set that grows. It is deliberately NOT tied to contract
+* deployment — the address can come from any field of any event, so it also
+* covers launchpad-minted tokens, DAO extension allowlists, and registry
+* entries.
+*
+* ```ts
+* sources: {
+*   registry: {
+*     type: "print_event",
+*     contractId: REGISTRY,
+*     topic: "pool-created",
+*     prints: { "pool-created": { pool: "principal" } },
+*   },
+*   swaps: {
+*     type: "print_event",
+*     topic: "swap",
+*     // every pool the registry has ever announced, including new ones
+*     factory: { from: "registry", field: "data.pool" },
+*   },
+* }
+* ```
+*
+* Two guarantees the runtime provides:
+* - **Same-block ordering** — a contract discovered in block N receives its
+*   own block-N events. Discovery runs before matching, within the block.
+* - **Reorg-scoped** — the discovered set is stamped with the block that
+*   revealed it and rolled back with everything else on a fork, so an address
+*   announced on an orphaned chain does not linger forever.
+*/
+interface FactoryScope {
+	factory?: {
+		/** Source name whose events reveal the addresses. */
+		from: string;
+		/** Dotted path to the address on that source's payload
+		*  (e.g. `"data.pool"`, `"contractId"`, `"data.token.id"`). */
+		field: string;
+	};
+}
+/** FT event filters */
+interface FtTransferFilter extends TraitScope {
+	type: "ft_transfer";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtMintFilter extends TraitScope {
+	type: "ft_mint";
+	assetIdentifier?: AssetIdentifier;
+	recipient?: string;
+	minAmount?: bigint;
+}
+interface FtBurnFilter extends TraitScope {
+	type: "ft_burn";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+	minAmount?: bigint;
+}
+/** NFT event filters */
+interface NftTransferFilter extends TraitScope {
+	type: "nft_transfer";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+	recipient?: string;
+}
+interface NftMintFilter extends TraitScope {
+	type: "nft_mint";
+	assetIdentifier?: AssetIdentifier;
+	recipient?: string;
+}
+interface NftBurnFilter extends TraitScope {
+	type: "nft_burn";
+	assetIdentifier?: AssetIdentifier;
+	sender?: string;
+}
+/** Contract event filters */
+interface ContractCallFilter extends TraitScope, FactoryScope {
+	type: "contract_call";
+	/**
+	* One contract id, or a SET of them (max 20) — the standard DeFi shape is
+	* a router plus N pools, which used to cost N near-identical sources and
+	* handlers. Payload types are identical per `type`, so one handler serves
+	* the set and `event.contractId` disambiguates.
+	*
+	* Supports `*` wildcards (e.g. `"SP1ABC….pool-*"`). Mutually exclusive
+	* with `trait`, which resolves its own set per block.
+	*/
+	contractId?: string | readonly string[];
+	functionName?: string;
+	caller?: string;
+	/**
+	* Contract ABI (pass it `as const`) used to type `event.input` — the named,
+	* decoded function arguments. Dev-provided; serialized into the deployed
+	* definition and used at runtime to decode args by name. Omit to keep
+	* `event.args` as a positional `unknown[]`.
+	*
+	* Required whenever `functionName` is set. `secondlayer subgraphs deploy`
+	* fills it in from the deployed contract for a single concrete
+	* `contractId`; pass it yourself for wildcard, multi-contract or trait
+	* sources, or a local deploy (`normalizeAbi()` from
+	* `@secondlayer/stacks/clarity`).
+	*/
+	abi?: AbiContract2;
+}
+interface ContractDeployFilter {
+	type: "contract_deploy";
+	deployer?: string;
+	contractName?: string;
+}
+interface NestedContractCallFilter extends TraitScope, FactoryScope {
+	type: "nested_contract_call";
+	contractId?: string | readonly string[];
+	functionName?: string;
+	caller?: string;
+	sender?: string;
+}
+interface VarSetFilter extends TraitScope, FactoryScope {
+	type: "var_set";
+	contractId?: string | readonly string[];
+	varName?: string;
+}
+interface MapWriteFilter extends TraitScope, FactoryScope {
+	type: "map_set" | "map_insert" | "map_delete";
+	contractId?: string | readonly string[];
+	map?: string;
+}
+/**
+* One declared field of a print payload.
+*
+* A bare {@link ColumnType} is a required scalar (`amount: "uint"`). The
+* composite forms exist because real print payloads are not flat: BNS-V2
+* emits `name` as a NESTED tuple, and a `prints` vocabulary that could only
+* say `"jsonb"` is why a handler reading flat `data.name` type-checked,
+* deployed, and then decoded to null on every event.
+*
+* - `{ type: F, optional: true }` — the KEY becomes optional on `event.data`
+*   (mirrors `always_present: false` in the inferred schema).
+* - `{ tuple: { … } }` — a nested tuple, typed all the way down.
+* - `{ list: F }` — a list of `F`.
+*/
+type PrintField = ColumnType | {
+	type: PrintField;
+	optional: true;
+} | {
+	tuple: Record<string, PrintField>;
+} | {
+	list: PrintField;
+};
+/**
+* Per-topic field schema for a print_event source. When declared, the handler's
+* `event` is a discriminated union keyed by `topic` and `event.data` is typed
+* per topic. Nested tuples, lists, and optional fields — see {@link PrintField}.
+*
+* Also opts the source into RUNTIME validation: a payload that does not match
+* is skipped and logged rather than written as nulls.
+*/
+type PrintEventPrints = Record<string, Record<string, PrintField>>;
+type PrintEventFields = FactoryScope & {
+	type: "print_event";
+	topic?: string;
+};
+/**
+* Pinned to one or more contract ids with no trait — `prints` is required so
+* `event.data` is typed and empty-table handlers cannot typecheck.
+*/
+type PinnedPrintEventFilter = PrintEventFields & {
+	contractId: string | readonly string[];
+	trait?: undefined;
+	prints: PrintEventPrints;
+};
+/**
+* Trait-scoped print source (optionally narrowed by contractId). No single
+* schema — `prints` stays optional.
+*/
+type TraitPrintEventFilter = PrintEventFields & {
+	contractId?: string | readonly string[];
+	trait: string;
+	prints?: PrintEventPrints;
+};
+/**
+* Unpinned / factory-only print source (no contractId). `prints` optional.
+*/
+type UnpinnedPrintEventFilter = PrintEventFields & {
+	contractId?: undefined;
+	trait?: string;
+	prints?: PrintEventPrints;
+};
+/**
+* Print-event filter. Pinned sources (contractId set, no trait) require
+* `prints`; trait and unpinned sources may omit it.
+*/
+type PrintEventFilter = PinnedPrintEventFilter | TraitPrintEventFilter | UnpinnedPrintEventFilter;
+/** All subgraph filter types — discriminated on `type` */
+type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter | NestedContractCallFilter | VarSetFilter | MapWriteFilter;
+/** Transaction metadata available in handlers */
+interface TxMeta {
+	txId: string;
+	sender: string;
+	type: string;
+	status: string;
+	contractId?: string | null;
+	functionName?: string | null;
+}
+/** Context passed to subgraph handlers during event processing */
+interface SubgraphContext {
+	block: {
+		height: number;
+		hash: string;
+		timestamp: number;
+		burnBlockHeight: number;
+		/** Nakamoto StacksBlockId, when the block row carries one. */
+		indexBlockHash?: string | null;
+	};
+	tx: TxMeta;
+	/**
+	* Read-only contract calls pinned to this block. Cached, so the same
+	* (contract, function, args) is fetched once per block rather than once
+	* per event.
+	*
+	* Erased here on purpose: this interface is compared structurally wherever
+	* a subgraph definition is passed around, and carrying an ABI-generic
+	* method pushes those comparisons past TS's instantiation depth. Handlers
+	* receive `TypedSubgraphContext`, which exposes the fully typed version.
+	*/
+	client: ErasedChainReadClient;
+	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. Applies
+	* `col = COALESCE(col, 0) + delta` per column (insert-or-add); deltas may
+	* be negative. Requires a uniqueKeys constraint matching `key`. Prefer
+	* this over read-modify-write handlers for running totals.
+	*/
+	increment(table: string, key: Record<string, unknown>, deltas: Record<string, bigint | number>): void;
+	findOne(table: string, where: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+	findMany(table: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+}
+/** Handler function that processes events and writes to the subgraph */
+type SubgraphHandler = (event: Record<string, unknown>, ctx: SubgraphContext) => Promise<void> | void;
+/** Complete subgraph definition */
+interface SubgraphDefinition {
+	/** Unique subgraph name (lowercase, alphanumeric + hyphens) */
+	name: string;
+	/** Human description */
+	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 */
+	schema: SubgraphSchema;
+	/** Handler functions, one per source, keyed by source name */
+	handlers: Record<string, SubgraphHandler>;
+}
+/** Runtime identity baked into every pin: matcher, decode and flush semantics. */
+declare const SUBGRAPHS_RUNTIME: string;
+/**
+* Globals a handler may not touch, with the reason shown to the developer.
+* The deploy scan reports them; the realm replaces each with a getter that
+* throws `NondeterminismError`.
+*/
+declare const FORBIDDEN_GLOBALS: Readonly<Record<string, string>>;
+/**
+* Globals a handler may use: ECMAScript built-ins whose results are fully
+* specified, plus deterministic host encoders. `Math` is narrowed separately
+* ({@link ALLOWED_MATH}).
+*/
+declare const ALLOWED_GLOBALS: readonly string[];
+/** `Math` members whose results are exact on every engine. The rest
+*  (`sin`, `pow`, `log`, …) are implementation-approximated. */
+declare const ALLOWED_MATH: readonly string[];
+/** Methods whose output depends on the host's locale data. */
+declare const LOCALE_METHODS: readonly string[];
+/**
+* One thing the deploy scan found in a bundled handler.
+*
+* - `nondeterministic`: breaks the determinism contract. Fails the deploy of
+*   a state subgraph; advice for everything else.
+* - `needs-events`: deterministic, but reads something only re-execution proofs cover
+*   (`ctx.client`). Raises the level instead of failing.
+*/
+interface HandlerFinding {
+	kind: "nondeterministic" | "needs-events";
+	/** What was used, e.g. `Date`, `Math.random`, `import()`, `ctx.client`. */
+	name: string;
+	reason: string;
+	/** Original source file when a sourcemap was available, else the bundle. */
+	file: string;
+	/** 1-based. */
+	line: number;
+	/** 1-based. */
+	column: number;
+}
+declare function formatFinding(f: HandlerFinding): string;
+/**
+* Derive how far a subgraph's rows can be checked. Level = the highest any
+* source or handler read needs. `reasons` lists everything standing between
+* the subgraph and checkable rows; a `state` subgraph with any reason is
+* refused at deploy, so every stored `state` row has none. Never configured,
+* never a flag.
+*/
+declare function deriveVerification(def: Pick<SubgraphDefinition, "sources" | "backfillMode">, findings?: readonly HandlerFinding[]): SubgraphVerification;
+/**
+* True when the deploy must be refused: the sources are provable (`state`), so
+* the determinism contract is enforced, and the scan broke it.
+*/
+declare function isDeterminismViolation(v: SubgraphVerification): boolean;
+interface PinInput {
+	/** Existing `schema_hash` (name + schema + sources). */
+	schemaHash: string;
+	/** Bundled ESM exactly as stored in `subgraphs.handler_code`. */
+	handlerCode: string;
+	startBlock?: number | null;
+	network: string;
+	/** Defaults to {@link SUBGRAPHS_RUNTIME}. */
+	runtime?: string;
+}
+/** What a pin commits to, as stored in `pin_preimage`. */
+interface PinFields {
+	/** sha256 of the bundled handler, hex. */
+	handlerHash: string;
+	network: string;
+	runtime: string;
+	schemaHash: string;
+	startBlock: number | null;
+}
+/**
+* The canonical JSON a pin is the sha256 of: fixed key order, primitives
+* only. Stored beside the pin so anyone can recompute it from the served
+* handler code.
+*/
+declare function pinPreimage(input: PinInput): string;
+/**
+* Content hash over everything that shapes a subgraph's rows. Unlike
+* `schema_hash`, it changes with the handler, `startBlock` and runtime, so
+* two deploys with the same pin produce the same rows from the same chain.
+*/
+declare function computePin(input: PinInput): string;
+export { ALLOWED_GLOBALS, ALLOWED_MATH, FORBIDDEN_GLOBALS, HandlerFinding, LOCALE_METHODS, PinFields, PinInput, SUBGRAPHS_RUNTIME, SubgraphVerification, computePin, deriveVerification, formatFinding, isDeterminismViolation, pinPreimage };