@secondlayer/subgraphs 7.7.4 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secondlayer/subgraphs",
-	"version": "7.7.4",
+	"version": "8.0.0",
 	"description": "Describe the Stacks data you want as one TypeScript file; it fills itself and survives reorgs.",
 	"license": "MIT",
 	"repository": {
@@ -17,10 +17,6 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js"
 		},
-		"./types": {
-			"types": "./dist/types.d.ts",
-			"import": "./dist/types.js"
-		},
 		"./schema": {
 			"types": "./dist/schema/index.d.ts",
 			"import": "./dist/schema/index.js"

package/dist/types.d.ts

@@ -1,424 +0,0 @@
-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";
-/** Options for a contract read, such as cache mode. */
-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 {
-	/**
-	* Reads a contract's read-only functions at the block being processed.
-	*
-	* Results are untyped here. Call it through `readContractAt` to get typed
-	* results from the contract's ABI.
-	*/
-	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[])[];
-}
-/** 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;
-}
-/**
-* Event shape passed to contract_call handlers.
-*
-* `args` is a **positional array** of decoded Clarity values matching the
-* contract function's parameter list in declaration order. Use the ABI
-* (or Clarity contract source) to map positions to names:
-*
-* ```ts
-* // pox-4 stack-stx args: (amount-ustx uint) (pox-addr tuple) (start-burn-ht uint) (lock-period uint)
-* const [amountUstx, , , lockPeriod] = event.args;
-* ```
-*
-* Bigints come out as `bigint`. Buffers as `Uint8Array`. Principals as
-* strings (`"SP..."`). Tuples as `Record<string, unknown>`.
-*
-* Historical transactions indexed before the function_args column was added
-* will have `args = []` — always guard with `args.length > 0` when reading
-* args from pre-Nakamoto history.
-*/
-interface ContractCallEvent {
-	type: "contract_call";
-	/** Transaction sender (the principal who signed the tx). Always non-null. */
-	sender: string;
-	contractId: string;
-	functionName: string;
-	/** Positional decoded Clarity values — order matches the ABI parameter list. */
-	args: unknown[];
-	/** Decoded return value from the contract function, or null. */
-	result: unknown;
-	/** Raw hex-encoded result value. */
-	resultHex: string | null;
-	/** Transaction metadata. */
-	tx: {
-		txId: string;
-		sender: string;
-		type: string;
-		status: string;
-		contractId: string | null;
-		functionName: string | null;
-	};
-}
-/** 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;
-	/**
-	* Contract ABI. With a `varName` the abi defines, `event.value` is typed
-	* and decoded from the variable's type. Pass it yourself
-	* (`normalizeAbi()` from `@secondlayer/stacks/clarity`).
-	*/
-	abi?: AbiContract2;
-}
-interface MapWriteFilter extends TraitScope, FactoryScope {
-	type: "map_set" | "map_insert" | "map_delete";
-	contractId?: string | readonly string[];
-	map?: string;
-	/**
-	* Contract ABI. With a `map` the abi defines, `event.key` and
-	* `event.value` are typed and decoded from the map's types. Pass it
-	* yourself (`normalizeAbi()` from `@secondlayer/stacks/clarity`).
-	*/
-	abi?: AbiContract2;
-}
-/**
-* 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;
-	/** Equality on top-level keys of the decoded print tuple, spelled as the
-	*  contract prints them (`signer-manager`). A value matches the field's
-	*  JSON form: principals `SP…`, uints as decimal strings, bools
-	*  `"true"`/`"false"`, buffers `0x…`. An array is any-of; keys AND.
-	*  Nested tuples and lists never match. */
-	where?: Record<string, string | readonly 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;
-/** A subgraph filter, 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;
-}
-/** Scalar types that can appear as row values */
-type RowValue = string | number | bigint | boolean | null | undefined | Record<string, unknown> | unknown[];
-/** 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>;
-}
-export { ColumnType, ContractCallEvent, ContractCallFilter, ContractDeployFilter, FactoryScope, FtBurnFilter, FtMintFilter, FtTransferFilter, MapWriteFilter, NestedContractCallFilter, NftBurnFilter, NftMintFilter, NftTransferFilter, PinnedPrintEventFilter, PrintEventFilter, PrintEventPrints, PrintField, RowValue, StxBurnFilter, StxLockFilter, StxMintFilter, StxTransferFilter, SubgraphColumn, SubgraphContext, SubgraphDefinition, SubgraphFilter, SubgraphHandler, SubgraphSchema, SubgraphTable, TraitPrintEventFilter, TxMeta, UnpinnedPrintEventFilter, VarSetFilter };

package/dist/types.js

@@ -1,3 +0,0 @@
-
-//# debugId=9FCB033A2878230664756E2164756E21
-//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1,9 +0,0 @@
-{
-  "version": 3,
-  "sources": [],
-  "sourcesContent": [
-  ],
-  "mappings": "",
-  "debugId": "9FCB033A2878230664756E2164756E21",
-  "names": []
-}