@secondlayer/subgraphs 3.0.0 → 3.2.0

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
+import { AbiContract } from "@secondlayer/stacks/clarity";
 /** Supported column types for subgraph schemas */
 type ColumnType = "text" | "uint" | "int" | "principal" | "boolean" | "timestamp" | "jsonb";
 /** Column definition in a subgraph table */
@@ -125,8 +126,13 @@ interface ContractCallFilter {
 	contractId?: string;
 	functionName?: string;
 	caller?: string;
-	/** ABI for typed event.args. If omitted, auto-fetched at deploy time. */
-	abi?: Record<string, unknown>;
+	/**
+	* 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[]`.
+	*/
+	abi?: AbiContract;
 }
 interface ContractDeployFilter {
 	type: "contract_deploy";
@@ -137,6 +143,14 @@ interface PrintEventFilter {
 	type: "print_event";
 	contractId?: string;
 	topic?: string;
+	/**
+	* Optional per-topic field schema. When declared, the handler's `event` is
+	* a discriminated union keyed by `topic` and `event.data` is typed per topic
+	* (e.g. `{ "completed-deposit": { amount: "uint", sender: "principal" } }`).
+	* Uses the same `ColumnType` vocab as `schema`; nested fields use `"jsonb"`.
+	* Type-level only — not validated at runtime.
+	*/
+	prints?: Record<string, Record<string, ColumnType>>;
 }
 /** All subgraph filter types — discriminated on `type` */
 type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter;
@@ -246,114 +260,7 @@ declare function backfillSubgraph(def: SubgraphDefinition, opts: {
 }): Promise<{
 	processed: number
 }>;
-interface FtTransferPayload {
-	sender: string;
-	recipient: string;
-	amount: bigint;
-	assetIdentifier: string;
-	tx: TxMeta;
-}
-interface FtMintPayload {
-	recipient: string;
-	amount: bigint;
-	assetIdentifier: string;
-	tx: TxMeta;
-}
-interface FtBurnPayload {
-	sender: string;
-	amount: bigint;
-	assetIdentifier: string;
-	tx: TxMeta;
-}
-interface NftTransferPayload {
-	sender: string;
-	recipient: string;
-	tokenId: unknown;
-	assetIdentifier: string;
-	tx: TxMeta;
-}
-interface NftMintPayload {
-	recipient: string;
-	tokenId: unknown;
-	assetIdentifier: string;
-	tx: TxMeta;
-}
-interface NftBurnPayload {
-	sender: string;
-	tokenId: unknown;
-	assetIdentifier: string;
-	tx: TxMeta;
-}
-interface StxTransferPayload {
-	sender: string;
-	recipient: string;
-	amount: bigint;
-	/** Memo string, or "" when none was attached. */
-	memo: string;
-	tx: TxMeta;
-}
-interface StxMintPayload {
-	recipient: string;
-	amount: bigint;
-	tx: TxMeta;
-}
-interface StxBurnPayload {
-	sender: string;
-	amount: bigint;
-	tx: TxMeta;
-}
-interface StxLockPayload {
-	lockedAddress: string;
-	lockedAmount: bigint;
-	unlockHeight: bigint;
-	tx: TxMeta;
-}
-interface PrintEventPayload {
-	contractId: string;
-	/** Decoded print topic (the Clarity tuple's `topic` field), or "". */
-	topic: string;
-	/**
-	* Remaining decoded tuple fields, camelCased. Empty object when the print
-	* value isn't a tuple. Narrow per `topic` to access typed fields.
-	*/
-	data: Record<string, unknown>;
-	tx: TxMeta;
-}
-interface ContractDeployPayload {
-	contractId: string;
-	deployer: string;
-	tx: TxMeta;
-}
-/** The event payload a handler receives for a given source filter. */
-type EventForFilter<F extends SubgraphFilter> = F extends {
-	type: "print_event"
-} ? PrintEventPayload : F extends {
-	type: "ft_transfer"
-} ? FtTransferPayload : F extends {
-	type: "ft_mint"
-} ? FtMintPayload : F extends {
-	type: "ft_burn"
-} ? FtBurnPayload : F extends {
-	type: "nft_transfer"
-} ? NftTransferPayload : F extends {
-	type: "nft_mint"
-} ? NftMintPayload : F extends {
-	type: "nft_burn"
-} ? NftBurnPayload : F extends {
-	type: "stx_transfer"
-} ? StxTransferPayload : F extends {
-	type: "stx_mint"
-} ? StxMintPayload : F extends {
-	type: "stx_burn"
-} ? StxBurnPayload : F extends {
-	type: "stx_lock"
-} ? StxLockPayload : F extends {
-	type: "contract_call"
-} ? ContractCallEvent : F extends {
-	type: "contract_deploy"
-} ? ContractDeployPayload : never;
-/** Union of every event payload — the `"*"` catch-all handler receives this. */
-type AnyEvent = FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | PrintEventPayload | ContractCallEvent | ContractDeployPayload;
+import { AbiContract as AbiContract2, ExtractFunctionArgs, ExtractFunctionNames } from "@secondlayer/stacks/clarity";
 /** Maps a ColumnType string literal to its TypeScript equivalent */
 type ColumnToTS<T extends string> = T extends "uint" | "int" ? bigint : T extends "text" | "principal" | "timestamp" ? string : T extends "boolean" ? boolean : T extends "jsonb" ? Record<string, unknown> : unknown;
 /** Infer TS type for a single column definition, respecting nullable */
@@ -461,6 +368,139 @@ interface TypedSubgraphContext<S extends SubgraphSchema> {
 type InferSubgraphClient<T> = T extends {
 	schema: infer S
 } ? { [K in keyof S] : S[K] extends SubgraphTable ? SubgraphTableClient<InferTableRow<S[K]>> : never } : never;
+interface FtTransferPayload {
+	sender: string;
+	recipient: string;
+	amount: bigint;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface FtMintPayload {
+	recipient: string;
+	amount: bigint;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface FtBurnPayload {
+	sender: string;
+	amount: bigint;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface NftTransferPayload {
+	sender: string;
+	recipient: string;
+	tokenId: unknown;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface NftMintPayload {
+	recipient: string;
+	tokenId: unknown;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface NftBurnPayload {
+	sender: string;
+	tokenId: unknown;
+	assetIdentifier: string;
+	tx: TxMeta;
+}
+interface StxTransferPayload {
+	sender: string;
+	recipient: string;
+	amount: bigint;
+	/** Memo string, or "" when none was attached. */
+	memo: string;
+	tx: TxMeta;
+}
+interface StxMintPayload {
+	recipient: string;
+	amount: bigint;
+	tx: TxMeta;
+}
+interface StxBurnPayload {
+	sender: string;
+	amount: bigint;
+	tx: TxMeta;
+}
+interface StxLockPayload {
+	lockedAddress: string;
+	lockedAmount: bigint;
+	unlockHeight: bigint;
+	tx: TxMeta;
+}
+interface PrintEventPayload {
+	contractId: string;
+	/** Decoded print topic (the Clarity tuple's `topic` field), or "". */
+	topic: string;
+	/**
+	* Remaining decoded tuple fields, camelCased. Empty object when the print
+	* value isn't a tuple. Narrow per `topic` to access typed fields.
+	*/
+	data: Record<string, unknown>;
+	tx: TxMeta;
+}
+interface ContractDeployPayload {
+	contractId: string;
+	deployer: string;
+	tx: TxMeta;
+}
+/**
+* Contract-call payload. When the source carries a `const` `abi` and a known
+* `functionName`, `event.input` is the named, typed, decoded arguments
+* (camelCased, via the contract ABI). The positional `event.args` is always
+* present for back-compat. Without an `abi`, the payload is {@link ContractCallEvent}.
+*/
+type ContractCallPayload<F> = F extends {
+	abi: infer A extends AbiContract2
+	functionName: infer N extends string
+} ? N extends ExtractFunctionNames<A> ? ContractCallEvent & {
+	input: ExtractFunctionArgs<A, N>
+} : ContractCallEvent : ContractCallEvent;
+/**
+* Print event typed per topic. When a `print_event` source declares a `prints`
+* map, the payload is a discriminated union keyed by `topic` with `data` typed
+* per topic; otherwise it falls back to the untyped {@link PrintEventPayload}.
+*/
+type PrintEventFor<F> = F extends {
+	prints: infer P extends Record<string, Record<string, ColumnType>>
+} ? { [K in keyof P] : {
+	contractId: string
+	topic: K
+	data: { [Field in keyof P[K]] : ColumnToTS<P[K][Field]> }
+	tx: TxMeta
+} }[keyof P] : PrintEventPayload;
+/** The event payload a handler receives for a given source filter. */
+type EventForFilter<F extends SubgraphFilter> = F extends {
+	type: "print_event"
+} ? PrintEventFor<F> : F extends {
+	type: "ft_transfer"
+} ? FtTransferPayload : F extends {
+	type: "ft_mint"
+} ? FtMintPayload : F extends {
+	type: "ft_burn"
+} ? FtBurnPayload : F extends {
+	type: "nft_transfer"
+} ? NftTransferPayload : F extends {
+	type: "nft_mint"
+} ? NftMintPayload : F extends {
+	type: "nft_burn"
+} ? NftBurnPayload : F extends {
+	type: "stx_transfer"
+} ? StxTransferPayload : F extends {
+	type: "stx_mint"
+} ? StxMintPayload : F extends {
+	type: "stx_burn"
+} ? StxBurnPayload : F extends {
+	type: "stx_lock"
+} ? StxLockPayload : F extends {
+	type: "contract_call"
+} ? ContractCallPayload<F> : F extends {
+	type: "contract_deploy"
+} ? ContractDeployPayload : never;
+/** Union of every event payload — the `"*"` catch-all handler receives this. */
+type AnyEvent = FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | PrintEventPayload | ContractCallEvent | ContractDeployPayload;
 /**
 * Handlers keyed by source name. Each handler's `event` is typed from the
 * matching source's filter `type` (e.g. a `print_event` source → `event.topic`
@@ -567,4 +607,4 @@ declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: s
 	version: string
 	diff?: DeployDiff
 }>;
-export { validateSubgraphDefinition, resumeReindex, reindexSubgraph, pgSchemaName, generateSubgraphSQL, diffSchema, deploySchema, defineSubgraph, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, RowValue, ReindexOptions, PrintEventPayload, PrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, InferTableRow, InferSubgraphClient, InferColumnType, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, EventForFilter, ContractDeployPayload, ContractDeployFilter, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, AnyEvent };
+export { validateSubgraphDefinition, resumeReindex, reindexSubgraph, pgSchemaName, generateSubgraphSQL, diffSchema, deploySchema, defineSubgraph, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, RowValue, ReindexOptions, PrintEventPayload, PrintEventFor, PrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, InferTableRow, InferSubgraphClient, InferColumnType, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, EventForFilter, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, AnyEvent };

package/dist/src/index.js

@@ -421,6 +421,11 @@ function decodeFunctionArgs(args) {
 // src/runtime/runner.ts
 import { getErrorMessage } from "@secondlayer/shared";
 import { logger as logger2 } from "@secondlayer/shared/logger";
+import {
+  clarityValueToJS,
+  deserializeCV as deserializeCV2,
+  toCamelCase
+} from "@secondlayer/stacks/clarity";
 var DEFAULT_ERROR_THRESHOLD = 50;
 function camelCase(str) {
   return str.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
@@ -475,6 +480,37 @@ function safeBigInt(val) {
   }
   return 0n;
 }
+function buildContractCallInput(filter, tx) {
+  const abi = filter.abi;
+  const fnName = tx.function_name;
+  if (!abi || !fnName)
+    return;
+  const fn = abi.functions?.find((f) => f.name === fnName);
+  if (!fn || !Array.isArray(fn.args))
+    return;
+  let rawArgs = tx.function_args;
+  if (typeof rawArgs === "string") {
+    try {
+      rawArgs = JSON.parse(rawArgs);
+    } catch {
+      return;
+    }
+  }
+  if (!Array.isArray(rawArgs))
+    return;
+  const decodeArg = clarityValueToJS;
+  const input = {};
+  fn.args.forEach((arg, i) => {
+    const hex = rawArgs[i];
+    if (typeof hex !== "string")
+      return;
+    try {
+      const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+      input[toCamelCase(arg.name)] = decodeArg(arg.type, deserializeCV2(clean));
+    } catch {}
+  });
+  return input;
+}
 function buildEventPayload(filter, tx, event) {
   const txMeta = {
     txId: tx.tx_id,
@@ -488,17 +524,20 @@ function buildEventPayload(filter, tx, event) {
   const decodedResult = decodeRawResult(tx.raw_result);
   if (!event) {
     switch (filter.type) {
-      case "contract_call":
+      case "contract_call": {
+        const input = buildContractCallInput(filter, tx);
         return {
           type: "contract_call",
           contractId: tx.contract_id ?? "",
           functionName: tx.function_name ?? "",
           sender: tx.sender,
           args: decodedArgs,
+          ...input !== undefined ? { input } : {},
           result: decodedResult,
           resultHex: tx.raw_result ?? null,
           tx: txMeta
         };
+      }
       case "contract_deploy":
         return {
           contractId: tx.contract_id ?? "",
@@ -596,7 +635,8 @@ function buildEventPayload(filter, tx, event) {
         tx: txMeta
       };
     }
-    case "contract_call":
+    case "contract_call": {
+      const input = buildContractCallInput(filter, tx);
       return {
         ...decoded,
         type: "contract_call",
@@ -605,10 +645,12 @@ function buildEventPayload(filter, tx, event) {
         functionName: tx.function_name ?? "",
         sender: tx.sender,
         args: decodedArgs,
+        ...input !== undefined ? { input } : {},
         result: decodedResult,
         resultHex: tx.raw_result ?? null,
         tx: txMeta
       };
+    }
     case "contract_deploy":
       return {
         contractId: tx.contract_id ?? "",
@@ -2176,5 +2218,5 @@ export {
   backfillSubgraph
 };
 
-//# debugId=E831E58EC98F118E64756E2164756E21
+//# debugId=E652DFA8BE73568E64756E2164756E21
 //# sourceMappingURL=index.js.map