@secondlayer/subgraphs 3.22.0 → 3.23.0

package/dist/src/types.d.ts

@@ -1,4 +1,32 @@
-import { AbiContract } from "@secondlayer/stacks/clarity";
+import { AbiContract as AbiContract2 } 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
+};
+/**
+* `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 */
@@ -216,7 +244,7 @@ interface ContractCallFilter extends TraitScope, FactoryScope {
 	* definition and used at runtime to decode args by name. Omit to keep
 	* `event.args` as a positional `unknown[]`.
 	*/
-	abi?: AbiContract;
+	abi?: AbiContract2;
 }
 interface ContractDeployFilter {
 	type: "contract_deploy";
@@ -287,8 +315,21 @@ interface SubgraphContext {
 		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;

package/dist/src/validate.d.ts

@@ -1,4 +1,32 @@
-import { AbiContract } from "@secondlayer/stacks/clarity";
+import { AbiContract as AbiContract2 } 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
+};
+/**
+* `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 */
@@ -175,7 +203,7 @@ interface ContractCallFilter extends TraitScope, FactoryScope {
 	* definition and used at runtime to decode args by name. Omit to keep
 	* `event.args` as a positional `unknown[]`.
 	*/
-	abi?: AbiContract;
+	abi?: AbiContract2;
 }
 interface ContractDeployFilter {
 	type: "contract_deploy";
@@ -246,8 +274,21 @@ interface SubgraphContext {
 		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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secondlayer/subgraphs",
-	"version": "3.22.0",
+	"version": "3.23.0",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -49,7 +49,9 @@
 			"import": "./dist/src/testing/index.js"
 		}
 	},
-	"files": ["dist"],
+	"files": [
+		"dist"
+	],
 	"scripts": {
 		"build": "bunup",
 		"dev": "bunup --watch",
@@ -59,7 +61,7 @@
 	},
 	"dependencies": {
 		"@secondlayer/shared": "^7.0.3",
-		"@secondlayer/stacks": "^2.21.1",
+		"@secondlayer/stacks": "^2.22.0",
 		"esbuild": "^0.27.4",
 		"kysely": "0.28.17",
 		"zod": "^4.3.6"