@secondlayer/subgraphs 6.3.6 → 6.4.0

package/dist/index.d.ts

@@ -1038,6 +1038,81 @@ declare function camelizeKeys(obj: unknown): unknown;
 * contribute nothing to typing.
 */
 declare function inferPrintTopics(samples: PrintSample[]): InferredTopicSchema[];
+import { SubgraphVerification } from "@secondlayer/shared/schemas/subgraphs";
+/** Runtime identity baked into every pin: matcher, decode and flush semantics. */
+declare const SUBGRAPHS_RUNTIME: 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;
+}
+/**
+* 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;
+/**
+* A handler broke the determinism contract at runtime. Infra-class: the
+* block aborts (rollback + retry) instead of skipping the event, because a
+* skip would commit output that depends on the run.
+*/
+declare class NondeterminismError extends Error {
+	name: string;
+}
+/**
+* A ctx read (DB, chain) failed under a verifiable subgraph. Infra-class like
+* {@link NondeterminismError}: skipping the event would make its rows depend
+* on whether the database was reachable.
+*/
+declare class HandlerReadError extends Error {
+	name: string;
+}
+/**
+* Evaluate a bundled handler (ESM, as stored in `handler_code`) inside a
+* fresh deterministic realm and return its definition with every handler
+* wrapped to receive the {@link deterministicContext} facade.
+*/
+declare function loadDeterministicDefinition(handlerCode: string): Promise<SubgraphDefinition>;
 interface GeneratedSQL {
 	statements: string[];
 	hash: string;
@@ -1178,10 +1253,16 @@ declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: s
 	schemaName?: string
 	handlerCode?: string
 	sourceCode?: string
+	/** Derived level to store (see `deriveVerification`). */
+	verification?: SubgraphVerification
+	/** Network baked into the pin. Defaults to `NETWORK`, then mainnet. */
+	network?: string
 }): Promise<{
 	action: "created" | "unchanged" | "handler_updated" | "updated" | "reindexed"
 	subgraphId: string
 	version: string
+	/** Present when the deploy carried a bundled handler. */
+	pin?: string
 	diff?: DeployDiff
 	/** Non-fatal caveats the caller should surface (e.g. handler grafts at tip). */
 	warnings?: string[]
@@ -1229,4 +1310,4 @@ interface ReindexOptions {
 	operationId?: string;
 	signal?: AbortSignal;
 }
-export { AggregateResult, AggregateSpec, AnyEvent, ChainReadCacheMode, ChainReadClient, ChainReadError, ChainReadMethods, ChainReadOptions, ColumnDiff, ColumnToTS, ColumnType, ComparisonFilter, ContractCallEvent, ContractCallFilter, ContractCallPayload, ContractDeployFilter, ContractDeployPayload, DeployDiff, DeployPlan, DrizzleGenOptions, ErasedChainReadClient, EventForFilter, FactoryScope, FindManyOptions, FindManyPage, FtBurnFilter, FtBurnPayload, FtMintFilter, FtMintPayload, FtTransferFilter, FtTransferPayload, GeneratedSQL, IndexCodegenOptions, IndexCodegenTarget, InferColumnType, InferContext, InferSubgraphClient, InferTableRow, InferredPrintField, InferredTopicSchema, KyselyGenOptions, MapDeletePayload, MapWritePayload, NestedContractCallPayload, NftBurnFilter, NftBurnPayload, NftMintFilter, NftMintPayload, NftTransferFilter, NftTransferPayload, PinnedPrintEventFilter, PrintDataOf, PrintEventFilter, PrintEventFor, PrintEventPayload, PrintEventPrints, PrintField, PrintFieldToTS, PrintSample, PrintValidationResult, PrismaGenOptions, ReindexOptions, RowValue, SparseProbeTarget, StxBurnFilter, StxBurnPayload, StxLockFilter, StxLockPayload, StxMintFilter, StxMintPayload, StxTransferFilter, StxTransferPayload, SubgraphColumn, SubgraphContext, SubgraphDefinition, SubgraphFilter, SubgraphHandler, SubgraphSchema, SubgraphTable, SubgraphTableClient, SubgraphTip, SubscribeOptions, SystemRow, TableDiff, TraitPrintEventFilter, TxMeta, TypedHandlers, TypedSubgraphContext, TypedSubgraphDefinition, UnpinnedPrintEventFilter, VarSetPayload, WhereInput, WriteRow, camelizeKeys, canSparseScan, defineSchema, defineSubgraph, deploySchema, diffSchema, filterFieldsByType, generateDrizzleSchema, generateIndexSchema, generateKyselySchema, generatePrismaSchema, generateSubgraphSQL, hasBreakingChanges, inferPrintTopics, isStreamsIndexEligible, pgSchemaName, readContractAt, renderDeployPlan, sparseProbeTargets, validateSubgraphDefinition };
+export { AggregateResult, AggregateSpec, AnyEvent, ChainReadCacheMode, ChainReadClient, ChainReadError, ChainReadMethods, ChainReadOptions, ColumnDiff, ColumnToTS, ColumnType, ComparisonFilter, ContractCallEvent, ContractCallFilter, ContractCallPayload, ContractDeployFilter, ContractDeployPayload, DeployDiff, DeployPlan, DrizzleGenOptions, ErasedChainReadClient, EventForFilter, FactoryScope, FindManyOptions, FindManyPage, FtBurnFilter, FtBurnPayload, FtMintFilter, FtMintPayload, FtTransferFilter, FtTransferPayload, GeneratedSQL, HandlerFinding, HandlerReadError, IndexCodegenOptions, IndexCodegenTarget, InferColumnType, InferContext, InferSubgraphClient, InferTableRow, InferredPrintField, InferredTopicSchema, KyselyGenOptions, MapDeletePayload, MapWritePayload, NestedContractCallPayload, NftBurnFilter, NftBurnPayload, NftMintFilter, NftMintPayload, NftTransferFilter, NftTransferPayload, NondeterminismError, PinInput, PinnedPrintEventFilter, PrintDataOf, PrintEventFilter, PrintEventFor, PrintEventPayload, PrintEventPrints, PrintField, PrintFieldToTS, PrintSample, PrintValidationResult, PrismaGenOptions, ReindexOptions, RowValue, SUBGRAPHS_RUNTIME, SparseProbeTarget, StxBurnFilter, StxBurnPayload, StxLockFilter, StxLockPayload, StxMintFilter, StxMintPayload, StxTransferFilter, StxTransferPayload, SubgraphColumn, SubgraphContext, SubgraphDefinition, SubgraphFilter, SubgraphHandler, SubgraphSchema, SubgraphTable, SubgraphTableClient, SubgraphTip, SubgraphVerification, SubscribeOptions, SystemRow, TableDiff, TraitPrintEventFilter, TxMeta, TypedHandlers, TypedSubgraphContext, TypedSubgraphDefinition, UnpinnedPrintEventFilter, VarSetPayload, WhereInput, WriteRow, camelizeKeys, canSparseScan, computePin, defineSchema, defineSubgraph, deploySchema, deriveVerification, diffSchema, filterFieldsByType, formatFinding, generateDrizzleSchema, generateIndexSchema, generateKyselySchema, generatePrismaSchema, generateSubgraphSQL, hasBreakingChanges, inferPrintTopics, isDeterminismViolation, isStreamsIndexEligible, loadDeterministicDefinition, pgSchemaName, readContractAt, renderDeployPlan, sparseProbeTargets, validateSubgraphDefinition };