@secondlayer/stacks 3.0.0 → 3.1.0

package/dist/shared/{stacks-tqrws7kd.js → stacks-0j16z8ev.js}

@@ -37,6 +37,10 @@ var CHAIN_EVENT_FILTER_TYPES = [
   "sbtc_withdrawal_swept_confirmed"
 ];
 // src/filters/validate.ts
+function assetId(value) {
+  assertAssetIdentifier("assetIdentifier", value);
+  return value;
+}
 function isPrincipal(value) {
   const parts = value.split(".");
   if (parts.length > 2)
@@ -108,11 +112,21 @@ function unsupported(surface, field, hint) {
 }
 function assertNoWildcards(surface, spec) {
   for (const [key, value] of specEntries(spec)) {
-    if (typeof value === "string" && hasWildcard(value)) {
-      unsupported(surface, `${key} wildcard "${value}"`, "wildcard patterns are Subscriptions-only");
+    const candidates = Array.isArray(value) ? value : [value];
+    for (const candidate of candidates) {
+      if (typeof candidate === "string" && hasWildcard(candidate)) {
+        unsupported(surface, `${key} wildcard "${candidate}"`, "wildcard patterns are Subscriptions/Subgraphs-only");
+      }
     }
   }
 }
+function assertNotTraitAndContract(surface, spec) {
+  const trait = "trait" in spec ? spec.trait : undefined;
+  const contract = "contractId" in spec ? spec.contractId : undefined;
+  if (trait !== undefined && contract !== undefined) {
+    unsupported(surface, "trait with contractId", "the Index treats them as mutually exclusive — drop one, or use a subgraph source, which ANDs the pair");
+  }
+}
 function toChainTrigger(spec) {
   const out = {};
   for (const [key, value] of specEntries(spec)) {
@@ -127,6 +141,7 @@ function toChainTrigger(spec) {
 }
 function toIndexParams(spec, extra = {}) {
   assertNoWildcards("Index events", spec);
+  assertNotTraitAndContract("Index events", spec);
   const out = {
     eventType: spec.type === "print_event" ? "print" : spec.type
   };
@@ -140,7 +155,8 @@ function toIndexParams(spec, extra = {}) {
       unsupported("Index events", "topic", "per-topic reads are Subgraphs/Subscriptions-only (or read the contract's print feed and switch on topic)");
     }
     if (key === "lockedAddress") {
-      unsupported("Index events", "lockedAddress", "stx_lock address filtering is Subscriptions/Subgraphs-only");
+      out.sender = value;
+      continue;
     }
     if (key === "caller") {
       unsupported("Index events", "caller", "contract-call fields live on index.contractCalls");
@@ -175,12 +191,14 @@ function toStreamsParams(spec, extra = {}) {
 }
 function toContractCallsParams(spec, extra = {}) {
   assertNoWildcards("Index contract-calls", spec);
+  assertNotTraitAndContract("Index contract-calls", spec);
   const out = {};
   for (const [key, value] of specEntries(spec)) {
     if (DECORATIVE_FIELDS.has(key))
       continue;
     if (key === "caller") {
-      unsupported("Index contract-calls", "caller", "caller filtering is Subscriptions/Subgraphs-only (the endpoint filters by tx sender)");
+      out.sender = value;
+      continue;
     }
     out[key] = value;
   }
@@ -246,7 +264,7 @@ var on = {
   sbtcWithdrawalReject: (fields = {}) => makeChainEventFilter("sbtc_withdrawal_reject", fields),
   sbtcWithdrawalSweptConfirmed: (fields = {}) => makeChainEventFilter("sbtc_withdrawal_swept_confirmed", fields)
 };
-export { DECODED_EVENT_TYPES, CHAIN_EVENT_FILTER_TYPES, isPrincipal, hasWildcard, assertPrincipalish, assertAssetIdentifier, assertContractId, makeChainEventFilter, fromSubgraphSource, on };
+export { DECODED_EVENT_TYPES, CHAIN_EVENT_FILTER_TYPES, assetId, isPrincipal, hasWildcard, assertPrincipalish, assertAssetIdentifier, assertContractId, makeChainEventFilter, fromSubgraphSource, on };
 
-//# debugId=422B5FA8F2B0610E64756E2164756E21
-//# sourceMappingURL=stacks-tqrws7kd.js.map
+//# debugId=EBF984B8438B171C64756E2164756E21
+//# sourceMappingURL=stacks-0j16z8ev.js.map

package/dist/shared/stacks-0j16z8ev.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/filters/event-types.ts", "../src/filters/validate.ts", "../src/filters/factories.ts"],
+  "sourcesContent": [
+    "// The decoded event-type vocabulary — canonical home. Index (decoded layer)\n// and Streams (canonical firehose) expose the SAME set. This lives in\n// @secondlayer/stacks because it is the leaf of the dependency graph\n// (shared → stacks), so no package can drift a private copy upward:\n// @secondlayer/shared re-exports it for back-compat.\nexport const DECODED_EVENT_TYPES = [\n\t\"stx_transfer\",\n\t\"stx_mint\",\n\t\"stx_burn\",\n\t\"stx_lock\",\n\t\"ft_transfer\",\n\t\"ft_mint\",\n\t\"ft_burn\",\n\t\"nft_transfer\",\n\t\"nft_mint\",\n\t\"nft_burn\",\n\t\"print\",\n] as const;\n\nexport type DecodedEventType = (typeof DECODED_EVENT_TYPES)[number];\n\n/** Every chain-event filter member across all four surfaces: the 10 decoded\n *  token/STX types, the three contract-shaped types (spelled as subgraphs and\n *  triggers spell them — Index/Streams project `print_event` → `print`), and\n *  the five sBTC lifecycle types (Subscriptions-only). */\nexport const CHAIN_EVENT_FILTER_TYPES = [\n\t\"stx_transfer\",\n\t\"stx_mint\",\n\t\"stx_burn\",\n\t\"stx_lock\",\n\t\"ft_transfer\",\n\t\"ft_mint\",\n\t\"ft_burn\",\n\t\"nft_transfer\",\n\t\"nft_mint\",\n\t\"nft_burn\",\n\t\"contract_call\",\n\t\"contract_deploy\",\n\t\"print_event\",\n\t\"sbtc_deposit\",\n\t\"sbtc_withdrawal_create\",\n\t\"sbtc_withdrawal_accept\",\n\t\"sbtc_withdrawal_reject\",\n\t\"sbtc_withdrawal_swept_confirmed\",\n] as const;\n\nexport type ChainEventFilterType = (typeof CHAIN_EVENT_FILTER_TYPES)[number];\n",
+    "import { isValidAddress } from \"../utils/address.ts\";\n\n/** A validated Stacks principal (standard or contract). Branded so downstream\n *  code can require \"already validated\" without re-checking. */\nexport type Principal = string & { readonly __principal: unique symbol };\n\n/**\n * `<contract>::<asset-name>` — the shape a fungible/non-fungible asset filter\n * takes, expressed so the compiler can check it.\n *\n * The most common mistake in this API is passing a CONTRACT ID\n * (`SP….sbtc-token`) where an asset identifier (`SP….sbtc-token::sbtc-token`)\n * belongs, and the failure mode is a query that quietly returns zero rows. The\n * two differ structurally by `::`, so a template-literal type catches it at the\n * call site — no brand, no cast, literals just work.\n *\n * A value that is only known at runtime (config, env) is not narrow enough on\n * purpose; run it through {@link assetId} once, which validates and narrows.\n *\n * Wildcard patterns (Subscriptions/Subgraphs-only) are admitted by the second arm — they\n * are legitimately not full identifiers (`SPB.*`), and the runtime validator\n * short-circuits on them for the same reason.\n */\nexport type AssetIdentifier = `${string}::${string}` | `${string}*${string}`;\n\n/**\n * Narrow a runtime string to an {@link AssetIdentifier}, validating it.\n *\n * The escape hatch for config-driven values: `assetId(process.env.ASSET!)`\n * throws on a contract id instead of letting it through to a zero-row query.\n */\nexport function assetId(value: string): AssetIdentifier {\n\tassertAssetIdentifier(\"assetIdentifier\", value);\n\treturn value as AssetIdentifier;\n}\n\n/** `true` for a standard (`SP…`/`ST…`) or contract (`SP….name`) principal. */\nexport function isPrincipal(value: string): value is Principal {\n\tconst parts = value.split(\".\");\n\tif (parts.length > 2) return false;\n\tconst [addr, contractName] = parts;\n\tif (!addr || !isValidAddress(addr)) return false;\n\tif (parts.length === 2 && !contractName) return false;\n\treturn true;\n}\n\n/** Subscriptions and Subgraph sources match `*` wildcards in\n *  principal/identifier patterns; every\n *  other surface treats the value literally. */\nexport function hasWildcard(value: string): boolean {\n\treturn value.includes(\"*\");\n}\n\n/** Throw unless `value` is a principal or a wildcard pattern. The factories\n *  call this so a swapped argument (asset id where a sender belongs, typo'd\n *  address) fails at construction — not as a silent zero-row query. */\nexport function assertPrincipalish(field: string, value: string): void {\n\tif (hasWildcard(value)) return;\n\tif (!isPrincipal(value)) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is not a valid Stacks principal (SP…/ST…, optionally .contract-name).`,\n\t\t);\n\t}\n}\n\n/** Throw unless `value` looks like `SP….contract::asset` (or a wildcard). */\nexport function assertAssetIdentifier(field: string, value: string): void {\n\tif (hasWildcard(value)) return;\n\tconst [contractId, assetName, ...rest] = value.split(\"::\");\n\tif (\n\t\t!contractId ||\n\t\t!assetName ||\n\t\trest.length > 0 ||\n\t\t!contractId.includes(\".\") ||\n\t\t!isPrincipal(contractId)\n\t) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is not a valid asset identifier (SP….contract-name::asset-name). Passing a bare contract id here matches zero rows — use contractId for that.`,\n\t\t);\n\t}\n}\n\n/** Throw unless `value` is a contract id `SP….name` (or a wildcard). */\nexport function assertContractId(field: string, value: string): void {\n\tif (hasWildcard(value)) return;\n\tif (value.includes(\"::\")) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is an asset identifier, not a contract id — use assetIdentifier for that.`,\n\t\t);\n\t}\n\tif (!value.includes(\".\") || !isPrincipal(value)) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is not a valid contract id (SP….contract-name).`,\n\t\t);\n\t}\n}\n",
+    "import type { AbiContract } from \"../clarity/abi/contract.ts\";\nimport type { ChainEventFilterType } from \"./event-types.ts\";\nimport type { SubgraphMemberType, SubgraphSourceSpec } from \"./types.ts\";\nimport type {\n\tChainEventFilter,\n\tChainEventFilterSpec,\n\tChainTriggerShape,\n\tContractCallsParamsShape,\n\tIndexEventsParamsShape,\n\tPrintFieldType,\n\tSpecFor,\n\tStreamsParamsShape,\n} from \"./types.ts\";\nimport {\n\tassertAssetIdentifier,\n\tassertContractId,\n\tassertPrincipalish,\n\thasWildcard,\n} from \"./validate.ts\";\n\n// ── Field metadata driving validation and projections ────────────────────\n\nconst PRINCIPAL_FIELDS = new Set([\n\t\"sender\",\n\t\"recipient\",\n\t\"caller\",\n\t\"deployer\",\n\t\"lockedAddress\",\n]);\nconst AMOUNT_FIELDS = new Set([\"minAmount\", \"maxAmount\"]);\n/** Fields with no filtering semantics — safe to drop in a projection. */\nconst DECORATIVE_FIELDS = new Set([\"abi\", \"prints\"]);\n\nfunction specEntries(spec: ChainEventFilterSpec): Array<[string, unknown]> {\n\treturn Object.entries(spec).filter(\n\t\t([key, value]) => key !== \"type\" && value !== undefined,\n\t);\n}\n\nfunction validateSpec(spec: ChainEventFilterSpec): void {\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (PRINCIPAL_FIELDS.has(key)) {\n\t\t\tassertPrincipalish(key, value as string);\n\t\t} else if (key === \"assetIdentifier\") {\n\t\t\tassertAssetIdentifier(key, value as string);\n\t\t} else if (key === \"contractId\") {\n\t\t\t// A contract SET validates member-wise — one bad id in a router+pools\n\t\t\t// list must fail as loudly as a bad single id.\n\t\t\tfor (const id of Array.isArray(value) ? value : [value]) {\n\t\t\t\tassertContractId(key, id as string);\n\t\t\t}\n\t\t}\n\t}\n}\n\n/** Throw for a field the target surface cannot express — dropping it would\n *  silently widen the match, which is the exact bug this module exists to\n *  kill. Names the surface that CAN express it. */\nfunction unsupported(surface: string, field: string, hint: string): never {\n\tthrow new Error(\n\t\t`${field} cannot be expressed on ${surface} — ${hint}. Drop the field from the filter or use the surface that supports it.`,\n\t);\n}\n\nfunction assertNoWildcards(surface: string, spec: ChainEventFilterSpec): void {\n\tfor (const [key, value] of specEntries(spec)) {\n\t\t// Arrays too: a wildcard inside a contractId set would otherwise reach\n\t\t// the wire as a literal `IN ('SP….pool-*')` — the silent zero-row match\n\t\t// this module exists to kill.\n\t\tconst candidates = Array.isArray(value) ? value : [value];\n\t\tfor (const candidate of candidates) {\n\t\t\tif (typeof candidate === \"string\" && hasWildcard(candidate)) {\n\t\t\t\tunsupported(\n\t\t\t\t\tsurface,\n\t\t\t\t\t`${key} wildcard \"${candidate}\"`,\n\t\t\t\t\t\"wildcard patterns are Subscriptions/Subgraphs-only\",\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n}\n\n/** The Index API treats `trait` and `contractId` as mutually exclusive (a\n *  trait already resolves to a contract set). Throw here, naming the fix,\n *  instead of letting the pair reach the server as a 400. Subgraphs AND them\n *  — that surface accepts both. */\nfunction assertNotTraitAndContract(\n\tsurface: string,\n\tspec: ChainEventFilterSpec,\n): void {\n\tconst trait = \"trait\" in spec ? spec.trait : undefined;\n\tconst contract = \"contractId\" in spec ? spec.contractId : undefined;\n\tif (trait !== undefined && contract !== undefined) {\n\t\tunsupported(\n\t\t\tsurface,\n\t\t\t\"trait with contractId\",\n\t\t\t\"the Index treats them as mutually exclusive — drop one, or use a subgraph source, which ANDs the pair\",\n\t\t);\n\t}\n}\n\n// ── Projections ──────────────────────────────────────────────────────────\n\nfunction toChainTrigger(spec: ChainEventFilterSpec): ChainTriggerShape {\n\tconst out: Record<string, string | number> = {};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (Array.isArray(value)) {\n\t\t\t// One trigger, one contract: silently taking the first would watch\n\t\t\t// a fraction of what the filter says. Create one subscription per\n\t\t\t// contract instead.\n\t\t\tunsupported(\n\t\t\t\t\"Subscriptions\",\n\t\t\t\t`${key} set`,\n\t\t\t\t\"a chain trigger targets ONE contract — create one subscription per contract, or use Index/Subgraphs which accept the set\",\n\t\t\t);\n\t\t}\n\t\t// The one sanctioned bigint→string boundary.\n\t\tout[key] =\n\t\t\ttypeof value === \"bigint\" ? value.toString() : (value as string | number);\n\t}\n\treturn { type: spec.type, ...out };\n}\n\nfunction toIndexParams(\n\tspec: ChainEventFilterSpec,\n\textra: Record<string, unknown> = {},\n): IndexEventsParamsShape {\n\tassertNoWildcards(\"Index events\", spec);\n\tassertNotTraitAndContract(\"Index events\", spec);\n\tconst out: Record<string, unknown> = {\n\t\teventType: spec.type === \"print_event\" ? \"print\" : spec.type,\n\t};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (AMOUNT_FIELDS.has(key)) {\n\t\t\tunsupported(\n\t\t\t\t\"Index events\",\n\t\t\t\tkey,\n\t\t\t\t\"amount predicates are Subscriptions/Subgraphs-only; filter client-side on the decoded rows\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"topic\") {\n\t\t\tunsupported(\n\t\t\t\t\"Index events\",\n\t\t\t\t\"topic\",\n\t\t\t\t\"per-topic reads are Subgraphs/Subscriptions-only (or read the contract's print feed and switch on topic)\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"lockedAddress\") {\n\t\t\t// Index normalizes stx_lock's locked_address INTO the `sender` column\n\t\t\t// (the row's sender IS the locked address) — a rename, not a gap.\n\t\t\tout.sender = value;\n\t\t\tcontinue;\n\t\t}\n\t\tif (key === \"caller\") {\n\t\t\tunsupported(\n\t\t\t\t\"Index events\",\n\t\t\t\t\"caller\",\n\t\t\t\t\"contract-call fields live on index.contractCalls\",\n\t\t\t);\n\t\t}\n\t\tout[key] = value;\n\t}\n\treturn { ...out, ...extra } as IndexEventsParamsShape;\n}\n\nfunction toStreamsParams(\n\tspec: ChainEventFilterSpec,\n\textra: Record<string, unknown> = {},\n): StreamsParamsShape {\n\tassertNoWildcards(\"Streams\", spec);\n\tconst out: Record<string, unknown> = {\n\t\ttypes: [spec.type === \"print_event\" ? \"print\" : spec.type],\n\t};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (AMOUNT_FIELDS.has(key)) {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\tkey,\n\t\t\t\t\"amount predicates are Subscriptions/Subgraphs-only\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"trait\") {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\t\"trait\",\n\t\t\t\t\"Streams has no trait resolution — Index and Subgraphs do\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"topic\") {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\t\"topic\",\n\t\t\t\t\"per-topic filtering is Subgraphs/Subscriptions-only\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"lockedAddress\") {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\t\"lockedAddress\",\n\t\t\t\t\"stx_lock address filtering is Subscriptions/Subgraphs-only\",\n\t\t\t);\n\t\t}\n\t\tout[key] = value;\n\t}\n\treturn { ...out, ...extra } as StreamsParamsShape;\n}\n\nfunction toContractCallsParams(\n\tspec: ChainEventFilterSpec,\n\textra: Record<string, unknown> = {},\n): ContractCallsParamsShape {\n\tassertNoWildcards(\"Index contract-calls\", spec);\n\tassertNotTraitAndContract(\"Index contract-calls\", spec);\n\tconst out: Record<string, unknown> = {};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (key === \"caller\") {\n\t\t\t// The endpoint filters by tx sender, which IS the caller — a rename,\n\t\t\t// not a gap.\n\t\t\tout.sender = value;\n\t\t\tcontinue;\n\t\t}\n\t\tout[key] = value;\n\t}\n\treturn { ...out, ...extra } as ContractCallsParamsShape;\n}\n\nfunction toSubgraphSource(spec: ChainEventFilterSpec): ChainEventFilterSpec {\n\t// The spec IS the subgraph source shape (camelCase, bigint amounts,\n\t// literal prints/abi preserved). Strip the projection methods by copying\n\t// data fields only.\n\treturn Object.fromEntries([\n\t\t[\"type\", spec.type],\n\t\t...specEntries(spec),\n\t]) as unknown as ChainEventFilterSpec;\n}\n\n// ── Factory ──────────────────────────────────────────────────────────────\n\nconst DECODED_MEMBERS = new Set<ChainEventFilterType>([\n\t\"stx_transfer\",\n\t\"stx_mint\",\n\t\"stx_burn\",\n\t\"stx_lock\",\n\t\"ft_transfer\",\n\t\"ft_mint\",\n\t\"ft_burn\",\n\t\"nft_transfer\",\n\t\"nft_mint\",\n\t\"nft_burn\",\n\t\"print_event\",\n]);\n\n/** Build a canonical filter: validated spec + the projections its member\n *  supports (methods are attached per member at runtime, matching the\n *  type-level gating exactly). `const F` preserves field literals — a\n *  `prints`/`abi` declaration keeps its exact type through\n *  `toSubgraphSource()`, which is what feeds `defineSubgraph` narrowing. */\nexport function makeChainEventFilter<\n\tT extends ChainEventFilterType,\n\tconst F extends Omit<SpecFor<T>, \"type\">,\n>(type: T, fields: F): ChainEventFilter<T, { type: T } & F> {\n\tconst spec = { type, ...fields } as unknown as SpecFor<T>;\n\tvalidateSpec(spec);\n\n\tconst filter = { ...spec } as unknown as Record<string, unknown>;\n\tfilter.toChainTrigger = () => toChainTrigger(spec);\n\tif (DECODED_MEMBERS.has(type)) {\n\t\tfilter.toIndexParams = (extra?: Record<string, unknown>) =>\n\t\t\ttoIndexParams(spec, extra);\n\t\tfilter.toStreamsParams = (extra?: Record<string, unknown>) =>\n\t\t\ttoStreamsParams(spec, extra);\n\t}\n\tif (type === \"contract_call\") {\n\t\tfilter.toContractCallsParams = (extra?: Record<string, unknown>) =>\n\t\t\ttoContractCallsParams(spec, extra);\n\t}\n\tif (!type.startsWith(\"sbtc_\")) {\n\t\tfilter.toSubgraphSource = () => toSubgraphSource(spec);\n\t}\n\treturn filter as unknown as ChainEventFilter<T, { type: T } & F>;\n}\n\n/**\n * Rehydrate a canonical filter from a subgraph-source-shaped object (the\n * inverse of `toSubgraphSource`). Powers migration and the round-trip\n * property gate: `toSubgraphSource(fromSubgraphSource(f))` must deep-equal\n * `f` for every production subgraph source.\n */\nexport function fromSubgraphSource(\n\tsource: SubgraphSourceSpec,\n): ChainEventFilter<SubgraphMemberType> {\n\tconst { type, ...fields } = source;\n\treturn makeChainEventFilter(\n\t\ttype,\n\t\tfields as Omit<SpecFor<typeof type>, \"type\">,\n\t) as unknown as ChainEventFilter<SubgraphMemberType>;\n}\n\ntype Fields<T extends ChainEventFilterType> = Omit<SpecFor<T>, \"type\">;\n\n/** The `on.*` namespace, annotated explicitly — bunup's dts emitter needs an\n *  annotation on exported values (an inferred object of generic factories\n *  collapses to `{}` in the emitted declarations). */\nexport interface OnNamespace {\n\tstxTransfer(\n\t\tfields?: Fields<\"stx_transfer\">,\n\t): ChainEventFilter<\"stx_transfer\">;\n\tstxMint(fields?: Fields<\"stx_mint\">): ChainEventFilter<\"stx_mint\">;\n\tstxBurn(fields?: Fields<\"stx_burn\">): ChainEventFilter<\"stx_burn\">;\n\tstxLock(fields?: Fields<\"stx_lock\">): ChainEventFilter<\"stx_lock\">;\n\tftTransfer(fields?: Fields<\"ft_transfer\">): ChainEventFilter<\"ft_transfer\">;\n\tftMint(fields?: Fields<\"ft_mint\">): ChainEventFilter<\"ft_mint\">;\n\tftBurn(fields?: Fields<\"ft_burn\">): ChainEventFilter<\"ft_burn\">;\n\tnftTransfer(\n\t\tfields?: Fields<\"nft_transfer\">,\n\t): ChainEventFilter<\"nft_transfer\">;\n\tnftMint(fields?: Fields<\"nft_mint\">): ChainEventFilter<\"nft_mint\">;\n\tnftBurn(fields?: Fields<\"nft_burn\">): ChainEventFilter<\"nft_burn\">;\n\t/** `abi` literals are preserved (`const A`) so `toSubgraphSource()` keeps\n\t *  typing `event.input` inside `defineSubgraph`. */\n\tcontractCall<const A extends AbiContract | undefined = undefined>(\n\t\tfields?: Omit<SpecFor<\"contract_call\">, \"type\" | \"abi\"> & { abi?: A },\n\t): ChainEventFilter<\n\t\t\"contract_call\",\n\t\t{ type: \"contract_call\" } & Omit<\n\t\t\tSpecFor<\"contract_call\">,\n\t\t\t\"type\" | \"abi\"\n\t\t> & {\n\t\t\t\tabi?: A;\n\t\t\t}\n\t>;\n\tcontractDeploy(\n\t\tfields?: Fields<\"contract_deploy\">,\n\t): ChainEventFilter<\"contract_deploy\">;\n\t/** Canonical member is `print_event` (as Subgraphs and Subscriptions spell\n\t *  it); `toIndexParams`/`toStreamsParams` project to `print`. `prints`\n\t *  literals are preserved (`const P`) for per-topic `event.data` narrowing. */\n\tprint<\n\t\tconst P extends\n\t\t\t| Record<string, Record<string, PrintFieldType>>\n\t\t\t| undefined = undefined,\n\t>(\n\t\tfields?: Omit<SpecFor<\"print_event\">, \"type\" | \"prints\"> & { prints?: P },\n\t): ChainEventFilter<\n\t\t\"print_event\",\n\t\t{ type: \"print_event\" } & Omit<\n\t\t\tSpecFor<\"print_event\">,\n\t\t\t\"type\" | \"prints\"\n\t\t> & {\n\t\t\t\tprints?: P;\n\t\t\t}\n\t>;\n\tsbtcDeposit(\n\t\tfields?: Fields<\"sbtc_deposit\">,\n\t): ChainEventFilter<\"sbtc_deposit\">;\n\tsbtcWithdrawalCreate(\n\t\tfields?: Fields<\"sbtc_withdrawal_create\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_create\">;\n\tsbtcWithdrawalAccept(\n\t\tfields?: Fields<\"sbtc_withdrawal_accept\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_accept\">;\n\tsbtcWithdrawalReject(\n\t\tfields?: Fields<\"sbtc_withdrawal_reject\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_reject\">;\n\tsbtcWithdrawalSweptConfirmed(\n\t\tfields?: Fields<\"sbtc_withdrawal_swept_confirmed\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_swept_confirmed\">;\n}\n\n/**\n * `on.*` — one filter vocabulary for every surface.\n *\n * ```ts\n * import { on } from \"@secondlayer/stacks/filters\";\n *\n * const usdc = on.ftTransfer({ assetIdentifier: USDC, minAmount: 1_000_000n });\n *\n * sl.index.events.list(usdc.toIndexParams({ limit: 100 }));   // pull\n * sl.streams.events.consume({ ...usdc.toStreamsParams(), onBatch });\n * sl.subscriptions.create({ name, url, triggers: [usdc.toChainTrigger()] });\n * defineSubgraph({ sources: { usdc: usdc.toSubgraphSource() }, schema, handlers });\n * ```\n *\n * A surface a member can't reach is a missing method (compile error), and a\n * field a surface can't express throws at projection time — never a silent\n * zero-row or over-wide match.\n */\nexport const on: OnNamespace = {\n\tstxTransfer: (fields: Fields<\"stx_transfer\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_transfer\", fields),\n\tstxMint: (fields: Fields<\"stx_mint\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_mint\", fields),\n\tstxBurn: (fields: Fields<\"stx_burn\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_burn\", fields),\n\tstxLock: (fields: Fields<\"stx_lock\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_lock\", fields),\n\tftTransfer: (fields: Fields<\"ft_transfer\"> = {}) =>\n\t\tmakeChainEventFilter(\"ft_transfer\", fields),\n\tftMint: (fields: Fields<\"ft_mint\"> = {}) =>\n\t\tmakeChainEventFilter(\"ft_mint\", fields),\n\tftBurn: (fields: Fields<\"ft_burn\"> = {}) =>\n\t\tmakeChainEventFilter(\"ft_burn\", fields),\n\tnftTransfer: (fields: Fields<\"nft_transfer\"> = {}) =>\n\t\tmakeChainEventFilter(\"nft_transfer\", fields),\n\tnftMint: (fields: Fields<\"nft_mint\"> = {}) =>\n\t\tmakeChainEventFilter(\"nft_mint\", fields),\n\tnftBurn: (fields: Fields<\"nft_burn\"> = {}) =>\n\t\tmakeChainEventFilter(\"nft_burn\", fields),\n\tcontractCall: <const A extends AbiContract | undefined = undefined>(\n\t\tfields: Omit<SpecFor<\"contract_call\">, \"type\" | \"abi\"> & { abi?: A } = {},\n\t) => makeChainEventFilter(\"contract_call\", fields),\n\tcontractDeploy: (fields: Fields<\"contract_deploy\"> = {}) =>\n\t\tmakeChainEventFilter(\"contract_deploy\", fields),\n\t/** Canonical member is `print_event` (as Subgraphs and Subscriptions spell\n\t *  it); `toIndexParams`/`toStreamsParams` project to `print`. */\n\tprint: <\n\t\tconst P extends\n\t\t\t| Record<string, Record<string, PrintFieldType>>\n\t\t\t| undefined = undefined,\n\t>(\n\t\tfields: Omit<SpecFor<\"print_event\">, \"type\" | \"prints\"> & {\n\t\t\tprints?: P;\n\t\t} = {},\n\t) => makeChainEventFilter(\"print_event\", fields),\n\tsbtcDeposit: (fields: Fields<\"sbtc_deposit\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_deposit\", fields),\n\tsbtcWithdrawalCreate: (fields: Fields<\"sbtc_withdrawal_create\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_withdrawal_create\", fields),\n\tsbtcWithdrawalAccept: (fields: Fields<\"sbtc_withdrawal_accept\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_withdrawal_accept\", fields),\n\tsbtcWithdrawalReject: (fields: Fields<\"sbtc_withdrawal_reject\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_withdrawal_reject\", fields),\n\tsbtcWithdrawalSweptConfirmed: (\n\t\tfields: Fields<\"sbtc_withdrawal_swept_confirmed\"> = {},\n\t) => makeChainEventFilter(\"sbtc_withdrawal_swept_confirmed\", fields),\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "EBF984B8438B171C64756E2164756E21",
+  "names": []
+}

package/dist/shared/{stacks-2p9cazp7.cjs → stacks-xh87kdz8.cjs}

@@ -6,6 +6,7 @@ __export(exports_filters, {
   isPrincipal: () => isPrincipal,
   hasWildcard: () => hasWildcard,
   fromSubgraphSource: () => fromSubgraphSource,
+  assetId: () => assetId,
   assertPrincipalish: () => assertPrincipalish,
   assertContractId: () => assertContractId,
   assertAssetIdentifier: () => assertAssetIdentifier,
@@ -49,6 +50,10 @@ var CHAIN_EVENT_FILTER_TYPES = [
   "sbtc_withdrawal_swept_confirmed"
 ];
 // src/filters/validate.ts
+function assetId(value) {
+  assertAssetIdentifier("assetIdentifier", value);
+  return value;
+}
 function isPrincipal(value) {
   const parts = value.split(".");
   if (parts.length > 2)
@@ -120,11 +125,21 @@ function unsupported(surface, field, hint) {
 }
 function assertNoWildcards(surface, spec) {
   for (const [key, value] of specEntries(spec)) {
-    if (typeof value === "string" && hasWildcard(value)) {
-      unsupported(surface, `${key} wildcard "${value}"`, "wildcard patterns are Subscriptions-only");
+    const candidates = Array.isArray(value) ? value : [value];
+    for (const candidate of candidates) {
+      if (typeof candidate === "string" && hasWildcard(candidate)) {
+        unsupported(surface, `${key} wildcard "${candidate}"`, "wildcard patterns are Subscriptions/Subgraphs-only");
+      }
     }
   }
 }
+function assertNotTraitAndContract(surface, spec) {
+  const trait = "trait" in spec ? spec.trait : undefined;
+  const contract = "contractId" in spec ? spec.contractId : undefined;
+  if (trait !== undefined && contract !== undefined) {
+    unsupported(surface, "trait with contractId", "the Index treats them as mutually exclusive — drop one, or use a subgraph source, which ANDs the pair");
+  }
+}
 function toChainTrigger(spec) {
   const out = {};
   for (const [key, value] of specEntries(spec)) {
@@ -139,6 +154,7 @@ function toChainTrigger(spec) {
 }
 function toIndexParams(spec, extra = {}) {
   assertNoWildcards("Index events", spec);
+  assertNotTraitAndContract("Index events", spec);
   const out = {
     eventType: spec.type === "print_event" ? "print" : spec.type
   };
@@ -152,7 +168,8 @@ function toIndexParams(spec, extra = {}) {
       unsupported("Index events", "topic", "per-topic reads are Subgraphs/Subscriptions-only (or read the contract's print feed and switch on topic)");
     }
     if (key === "lockedAddress") {
-      unsupported("Index events", "lockedAddress", "stx_lock address filtering is Subscriptions/Subgraphs-only");
+      out.sender = value;
+      continue;
     }
     if (key === "caller") {
       unsupported("Index events", "caller", "contract-call fields live on index.contractCalls");
@@ -187,12 +204,14 @@ function toStreamsParams(spec, extra = {}) {
 }
 function toContractCallsParams(spec, extra = {}) {
   assertNoWildcards("Index contract-calls", spec);
+  assertNotTraitAndContract("Index contract-calls", spec);
   const out = {};
   for (const [key, value] of specEntries(spec)) {
     if (DECORATIVE_FIELDS.has(key))
       continue;
     if (key === "caller") {
-      unsupported("Index contract-calls", "caller", "caller filtering is Subscriptions/Subgraphs-only (the endpoint filters by tx sender)");
+      out.sender = value;
+      continue;
     }
     out[key] = value;
   }
@@ -259,5 +278,5 @@ var on = {
   sbtcWithdrawalSweptConfirmed: (fields = {}) => makeChainEventFilter("sbtc_withdrawal_swept_confirmed", fields)
 };
 
-//# debugId=8303CB4112ECC69D64756E2164756E21
-//# sourceMappingURL=stacks-2p9cazp7.cjs.map
+//# debugId=287B8CB0793CF87664756E2164756E21
+//# sourceMappingURL=stacks-xh87kdz8.cjs.map

package/dist/shared/stacks-xh87kdz8.cjs.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/filters/event-types.ts", "../src/filters/validate.ts", "../src/filters/factories.ts"],
+  "sourcesContent": [
+    "// The decoded event-type vocabulary — canonical home. Index (decoded layer)\n// and Streams (canonical firehose) expose the SAME set. This lives in\n// @secondlayer/stacks because it is the leaf of the dependency graph\n// (shared → stacks), so no package can drift a private copy upward:\n// @secondlayer/shared re-exports it for back-compat.\nexport const DECODED_EVENT_TYPES = [\n\t\"stx_transfer\",\n\t\"stx_mint\",\n\t\"stx_burn\",\n\t\"stx_lock\",\n\t\"ft_transfer\",\n\t\"ft_mint\",\n\t\"ft_burn\",\n\t\"nft_transfer\",\n\t\"nft_mint\",\n\t\"nft_burn\",\n\t\"print\",\n] as const;\n\nexport type DecodedEventType = (typeof DECODED_EVENT_TYPES)[number];\n\n/** Every chain-event filter member across all four surfaces: the 10 decoded\n *  token/STX types, the three contract-shaped types (spelled as subgraphs and\n *  triggers spell them — Index/Streams project `print_event` → `print`), and\n *  the five sBTC lifecycle types (Subscriptions-only). */\nexport const CHAIN_EVENT_FILTER_TYPES = [\n\t\"stx_transfer\",\n\t\"stx_mint\",\n\t\"stx_burn\",\n\t\"stx_lock\",\n\t\"ft_transfer\",\n\t\"ft_mint\",\n\t\"ft_burn\",\n\t\"nft_transfer\",\n\t\"nft_mint\",\n\t\"nft_burn\",\n\t\"contract_call\",\n\t\"contract_deploy\",\n\t\"print_event\",\n\t\"sbtc_deposit\",\n\t\"sbtc_withdrawal_create\",\n\t\"sbtc_withdrawal_accept\",\n\t\"sbtc_withdrawal_reject\",\n\t\"sbtc_withdrawal_swept_confirmed\",\n] as const;\n\nexport type ChainEventFilterType = (typeof CHAIN_EVENT_FILTER_TYPES)[number];\n",
+    "import { isValidAddress } from \"../utils/address.ts\";\n\n/** A validated Stacks principal (standard or contract). Branded so downstream\n *  code can require \"already validated\" without re-checking. */\nexport type Principal = string & { readonly __principal: unique symbol };\n\n/**\n * `<contract>::<asset-name>` — the shape a fungible/non-fungible asset filter\n * takes, expressed so the compiler can check it.\n *\n * The most common mistake in this API is passing a CONTRACT ID\n * (`SP….sbtc-token`) where an asset identifier (`SP….sbtc-token::sbtc-token`)\n * belongs, and the failure mode is a query that quietly returns zero rows. The\n * two differ structurally by `::`, so a template-literal type catches it at the\n * call site — no brand, no cast, literals just work.\n *\n * A value that is only known at runtime (config, env) is not narrow enough on\n * purpose; run it through {@link assetId} once, which validates and narrows.\n *\n * Wildcard patterns (Subscriptions/Subgraphs-only) are admitted by the second arm — they\n * are legitimately not full identifiers (`SPB.*`), and the runtime validator\n * short-circuits on them for the same reason.\n */\nexport type AssetIdentifier = `${string}::${string}` | `${string}*${string}`;\n\n/**\n * Narrow a runtime string to an {@link AssetIdentifier}, validating it.\n *\n * The escape hatch for config-driven values: `assetId(process.env.ASSET!)`\n * throws on a contract id instead of letting it through to a zero-row query.\n */\nexport function assetId(value: string): AssetIdentifier {\n\tassertAssetIdentifier(\"assetIdentifier\", value);\n\treturn value as AssetIdentifier;\n}\n\n/** `true` for a standard (`SP…`/`ST…`) or contract (`SP….name`) principal. */\nexport function isPrincipal(value: string): value is Principal {\n\tconst parts = value.split(\".\");\n\tif (parts.length > 2) return false;\n\tconst [addr, contractName] = parts;\n\tif (!addr || !isValidAddress(addr)) return false;\n\tif (parts.length === 2 && !contractName) return false;\n\treturn true;\n}\n\n/** Subscriptions and Subgraph sources match `*` wildcards in\n *  principal/identifier patterns; every\n *  other surface treats the value literally. */\nexport function hasWildcard(value: string): boolean {\n\treturn value.includes(\"*\");\n}\n\n/** Throw unless `value` is a principal or a wildcard pattern. The factories\n *  call this so a swapped argument (asset id where a sender belongs, typo'd\n *  address) fails at construction — not as a silent zero-row query. */\nexport function assertPrincipalish(field: string, value: string): void {\n\tif (hasWildcard(value)) return;\n\tif (!isPrincipal(value)) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is not a valid Stacks principal (SP…/ST…, optionally .contract-name).`,\n\t\t);\n\t}\n}\n\n/** Throw unless `value` looks like `SP….contract::asset` (or a wildcard). */\nexport function assertAssetIdentifier(field: string, value: string): void {\n\tif (hasWildcard(value)) return;\n\tconst [contractId, assetName, ...rest] = value.split(\"::\");\n\tif (\n\t\t!contractId ||\n\t\t!assetName ||\n\t\trest.length > 0 ||\n\t\t!contractId.includes(\".\") ||\n\t\t!isPrincipal(contractId)\n\t) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is not a valid asset identifier (SP….contract-name::asset-name). Passing a bare contract id here matches zero rows — use contractId for that.`,\n\t\t);\n\t}\n}\n\n/** Throw unless `value` is a contract id `SP….name` (or a wildcard). */\nexport function assertContractId(field: string, value: string): void {\n\tif (hasWildcard(value)) return;\n\tif (value.includes(\"::\")) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is an asset identifier, not a contract id — use assetIdentifier for that.`,\n\t\t);\n\t}\n\tif (!value.includes(\".\") || !isPrincipal(value)) {\n\t\tthrow new Error(\n\t\t\t`${field} \"${value}\" is not a valid contract id (SP….contract-name).`,\n\t\t);\n\t}\n}\n",
+    "import type { AbiContract } from \"../clarity/abi/contract.ts\";\nimport type { ChainEventFilterType } from \"./event-types.ts\";\nimport type { SubgraphMemberType, SubgraphSourceSpec } from \"./types.ts\";\nimport type {\n\tChainEventFilter,\n\tChainEventFilterSpec,\n\tChainTriggerShape,\n\tContractCallsParamsShape,\n\tIndexEventsParamsShape,\n\tPrintFieldType,\n\tSpecFor,\n\tStreamsParamsShape,\n} from \"./types.ts\";\nimport {\n\tassertAssetIdentifier,\n\tassertContractId,\n\tassertPrincipalish,\n\thasWildcard,\n} from \"./validate.ts\";\n\n// ── Field metadata driving validation and projections ────────────────────\n\nconst PRINCIPAL_FIELDS = new Set([\n\t\"sender\",\n\t\"recipient\",\n\t\"caller\",\n\t\"deployer\",\n\t\"lockedAddress\",\n]);\nconst AMOUNT_FIELDS = new Set([\"minAmount\", \"maxAmount\"]);\n/** Fields with no filtering semantics — safe to drop in a projection. */\nconst DECORATIVE_FIELDS = new Set([\"abi\", \"prints\"]);\n\nfunction specEntries(spec: ChainEventFilterSpec): Array<[string, unknown]> {\n\treturn Object.entries(spec).filter(\n\t\t([key, value]) => key !== \"type\" && value !== undefined,\n\t);\n}\n\nfunction validateSpec(spec: ChainEventFilterSpec): void {\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (PRINCIPAL_FIELDS.has(key)) {\n\t\t\tassertPrincipalish(key, value as string);\n\t\t} else if (key === \"assetIdentifier\") {\n\t\t\tassertAssetIdentifier(key, value as string);\n\t\t} else if (key === \"contractId\") {\n\t\t\t// A contract SET validates member-wise — one bad id in a router+pools\n\t\t\t// list must fail as loudly as a bad single id.\n\t\t\tfor (const id of Array.isArray(value) ? value : [value]) {\n\t\t\t\tassertContractId(key, id as string);\n\t\t\t}\n\t\t}\n\t}\n}\n\n/** Throw for a field the target surface cannot express — dropping it would\n *  silently widen the match, which is the exact bug this module exists to\n *  kill. Names the surface that CAN express it. */\nfunction unsupported(surface: string, field: string, hint: string): never {\n\tthrow new Error(\n\t\t`${field} cannot be expressed on ${surface} — ${hint}. Drop the field from the filter or use the surface that supports it.`,\n\t);\n}\n\nfunction assertNoWildcards(surface: string, spec: ChainEventFilterSpec): void {\n\tfor (const [key, value] of specEntries(spec)) {\n\t\t// Arrays too: a wildcard inside a contractId set would otherwise reach\n\t\t// the wire as a literal `IN ('SP….pool-*')` — the silent zero-row match\n\t\t// this module exists to kill.\n\t\tconst candidates = Array.isArray(value) ? value : [value];\n\t\tfor (const candidate of candidates) {\n\t\t\tif (typeof candidate === \"string\" && hasWildcard(candidate)) {\n\t\t\t\tunsupported(\n\t\t\t\t\tsurface,\n\t\t\t\t\t`${key} wildcard \"${candidate}\"`,\n\t\t\t\t\t\"wildcard patterns are Subscriptions/Subgraphs-only\",\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n}\n\n/** The Index API treats `trait` and `contractId` as mutually exclusive (a\n *  trait already resolves to a contract set). Throw here, naming the fix,\n *  instead of letting the pair reach the server as a 400. Subgraphs AND them\n *  — that surface accepts both. */\nfunction assertNotTraitAndContract(\n\tsurface: string,\n\tspec: ChainEventFilterSpec,\n): void {\n\tconst trait = \"trait\" in spec ? spec.trait : undefined;\n\tconst contract = \"contractId\" in spec ? spec.contractId : undefined;\n\tif (trait !== undefined && contract !== undefined) {\n\t\tunsupported(\n\t\t\tsurface,\n\t\t\t\"trait with contractId\",\n\t\t\t\"the Index treats them as mutually exclusive — drop one, or use a subgraph source, which ANDs the pair\",\n\t\t);\n\t}\n}\n\n// ── Projections ──────────────────────────────────────────────────────────\n\nfunction toChainTrigger(spec: ChainEventFilterSpec): ChainTriggerShape {\n\tconst out: Record<string, string | number> = {};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (Array.isArray(value)) {\n\t\t\t// One trigger, one contract: silently taking the first would watch\n\t\t\t// a fraction of what the filter says. Create one subscription per\n\t\t\t// contract instead.\n\t\t\tunsupported(\n\t\t\t\t\"Subscriptions\",\n\t\t\t\t`${key} set`,\n\t\t\t\t\"a chain trigger targets ONE contract — create one subscription per contract, or use Index/Subgraphs which accept the set\",\n\t\t\t);\n\t\t}\n\t\t// The one sanctioned bigint→string boundary.\n\t\tout[key] =\n\t\t\ttypeof value === \"bigint\" ? value.toString() : (value as string | number);\n\t}\n\treturn { type: spec.type, ...out };\n}\n\nfunction toIndexParams(\n\tspec: ChainEventFilterSpec,\n\textra: Record<string, unknown> = {},\n): IndexEventsParamsShape {\n\tassertNoWildcards(\"Index events\", spec);\n\tassertNotTraitAndContract(\"Index events\", spec);\n\tconst out: Record<string, unknown> = {\n\t\teventType: spec.type === \"print_event\" ? \"print\" : spec.type,\n\t};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (AMOUNT_FIELDS.has(key)) {\n\t\t\tunsupported(\n\t\t\t\t\"Index events\",\n\t\t\t\tkey,\n\t\t\t\t\"amount predicates are Subscriptions/Subgraphs-only; filter client-side on the decoded rows\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"topic\") {\n\t\t\tunsupported(\n\t\t\t\t\"Index events\",\n\t\t\t\t\"topic\",\n\t\t\t\t\"per-topic reads are Subgraphs/Subscriptions-only (or read the contract's print feed and switch on topic)\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"lockedAddress\") {\n\t\t\t// Index normalizes stx_lock's locked_address INTO the `sender` column\n\t\t\t// (the row's sender IS the locked address) — a rename, not a gap.\n\t\t\tout.sender = value;\n\t\t\tcontinue;\n\t\t}\n\t\tif (key === \"caller\") {\n\t\t\tunsupported(\n\t\t\t\t\"Index events\",\n\t\t\t\t\"caller\",\n\t\t\t\t\"contract-call fields live on index.contractCalls\",\n\t\t\t);\n\t\t}\n\t\tout[key] = value;\n\t}\n\treturn { ...out, ...extra } as IndexEventsParamsShape;\n}\n\nfunction toStreamsParams(\n\tspec: ChainEventFilterSpec,\n\textra: Record<string, unknown> = {},\n): StreamsParamsShape {\n\tassertNoWildcards(\"Streams\", spec);\n\tconst out: Record<string, unknown> = {\n\t\ttypes: [spec.type === \"print_event\" ? \"print\" : spec.type],\n\t};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (AMOUNT_FIELDS.has(key)) {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\tkey,\n\t\t\t\t\"amount predicates are Subscriptions/Subgraphs-only\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"trait\") {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\t\"trait\",\n\t\t\t\t\"Streams has no trait resolution — Index and Subgraphs do\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"topic\") {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\t\"topic\",\n\t\t\t\t\"per-topic filtering is Subgraphs/Subscriptions-only\",\n\t\t\t);\n\t\t}\n\t\tif (key === \"lockedAddress\") {\n\t\t\tunsupported(\n\t\t\t\t\"Streams\",\n\t\t\t\t\"lockedAddress\",\n\t\t\t\t\"stx_lock address filtering is Subscriptions/Subgraphs-only\",\n\t\t\t);\n\t\t}\n\t\tout[key] = value;\n\t}\n\treturn { ...out, ...extra } as StreamsParamsShape;\n}\n\nfunction toContractCallsParams(\n\tspec: ChainEventFilterSpec,\n\textra: Record<string, unknown> = {},\n): ContractCallsParamsShape {\n\tassertNoWildcards(\"Index contract-calls\", spec);\n\tassertNotTraitAndContract(\"Index contract-calls\", spec);\n\tconst out: Record<string, unknown> = {};\n\tfor (const [key, value] of specEntries(spec)) {\n\t\tif (DECORATIVE_FIELDS.has(key)) continue;\n\t\tif (key === \"caller\") {\n\t\t\t// The endpoint filters by tx sender, which IS the caller — a rename,\n\t\t\t// not a gap.\n\t\t\tout.sender = value;\n\t\t\tcontinue;\n\t\t}\n\t\tout[key] = value;\n\t}\n\treturn { ...out, ...extra } as ContractCallsParamsShape;\n}\n\nfunction toSubgraphSource(spec: ChainEventFilterSpec): ChainEventFilterSpec {\n\t// The spec IS the subgraph source shape (camelCase, bigint amounts,\n\t// literal prints/abi preserved). Strip the projection methods by copying\n\t// data fields only.\n\treturn Object.fromEntries([\n\t\t[\"type\", spec.type],\n\t\t...specEntries(spec),\n\t]) as unknown as ChainEventFilterSpec;\n}\n\n// ── Factory ──────────────────────────────────────────────────────────────\n\nconst DECODED_MEMBERS = new Set<ChainEventFilterType>([\n\t\"stx_transfer\",\n\t\"stx_mint\",\n\t\"stx_burn\",\n\t\"stx_lock\",\n\t\"ft_transfer\",\n\t\"ft_mint\",\n\t\"ft_burn\",\n\t\"nft_transfer\",\n\t\"nft_mint\",\n\t\"nft_burn\",\n\t\"print_event\",\n]);\n\n/** Build a canonical filter: validated spec + the projections its member\n *  supports (methods are attached per member at runtime, matching the\n *  type-level gating exactly). `const F` preserves field literals — a\n *  `prints`/`abi` declaration keeps its exact type through\n *  `toSubgraphSource()`, which is what feeds `defineSubgraph` narrowing. */\nexport function makeChainEventFilter<\n\tT extends ChainEventFilterType,\n\tconst F extends Omit<SpecFor<T>, \"type\">,\n>(type: T, fields: F): ChainEventFilter<T, { type: T } & F> {\n\tconst spec = { type, ...fields } as unknown as SpecFor<T>;\n\tvalidateSpec(spec);\n\n\tconst filter = { ...spec } as unknown as Record<string, unknown>;\n\tfilter.toChainTrigger = () => toChainTrigger(spec);\n\tif (DECODED_MEMBERS.has(type)) {\n\t\tfilter.toIndexParams = (extra?: Record<string, unknown>) =>\n\t\t\ttoIndexParams(spec, extra);\n\t\tfilter.toStreamsParams = (extra?: Record<string, unknown>) =>\n\t\t\ttoStreamsParams(spec, extra);\n\t}\n\tif (type === \"contract_call\") {\n\t\tfilter.toContractCallsParams = (extra?: Record<string, unknown>) =>\n\t\t\ttoContractCallsParams(spec, extra);\n\t}\n\tif (!type.startsWith(\"sbtc_\")) {\n\t\tfilter.toSubgraphSource = () => toSubgraphSource(spec);\n\t}\n\treturn filter as unknown as ChainEventFilter<T, { type: T } & F>;\n}\n\n/**\n * Rehydrate a canonical filter from a subgraph-source-shaped object (the\n * inverse of `toSubgraphSource`). Powers migration and the round-trip\n * property gate: `toSubgraphSource(fromSubgraphSource(f))` must deep-equal\n * `f` for every production subgraph source.\n */\nexport function fromSubgraphSource(\n\tsource: SubgraphSourceSpec,\n): ChainEventFilter<SubgraphMemberType> {\n\tconst { type, ...fields } = source;\n\treturn makeChainEventFilter(\n\t\ttype,\n\t\tfields as Omit<SpecFor<typeof type>, \"type\">,\n\t) as unknown as ChainEventFilter<SubgraphMemberType>;\n}\n\ntype Fields<T extends ChainEventFilterType> = Omit<SpecFor<T>, \"type\">;\n\n/** The `on.*` namespace, annotated explicitly — bunup's dts emitter needs an\n *  annotation on exported values (an inferred object of generic factories\n *  collapses to `{}` in the emitted declarations). */\nexport interface OnNamespace {\n\tstxTransfer(\n\t\tfields?: Fields<\"stx_transfer\">,\n\t): ChainEventFilter<\"stx_transfer\">;\n\tstxMint(fields?: Fields<\"stx_mint\">): ChainEventFilter<\"stx_mint\">;\n\tstxBurn(fields?: Fields<\"stx_burn\">): ChainEventFilter<\"stx_burn\">;\n\tstxLock(fields?: Fields<\"stx_lock\">): ChainEventFilter<\"stx_lock\">;\n\tftTransfer(fields?: Fields<\"ft_transfer\">): ChainEventFilter<\"ft_transfer\">;\n\tftMint(fields?: Fields<\"ft_mint\">): ChainEventFilter<\"ft_mint\">;\n\tftBurn(fields?: Fields<\"ft_burn\">): ChainEventFilter<\"ft_burn\">;\n\tnftTransfer(\n\t\tfields?: Fields<\"nft_transfer\">,\n\t): ChainEventFilter<\"nft_transfer\">;\n\tnftMint(fields?: Fields<\"nft_mint\">): ChainEventFilter<\"nft_mint\">;\n\tnftBurn(fields?: Fields<\"nft_burn\">): ChainEventFilter<\"nft_burn\">;\n\t/** `abi` literals are preserved (`const A`) so `toSubgraphSource()` keeps\n\t *  typing `event.input` inside `defineSubgraph`. */\n\tcontractCall<const A extends AbiContract | undefined = undefined>(\n\t\tfields?: Omit<SpecFor<\"contract_call\">, \"type\" | \"abi\"> & { abi?: A },\n\t): ChainEventFilter<\n\t\t\"contract_call\",\n\t\t{ type: \"contract_call\" } & Omit<\n\t\t\tSpecFor<\"contract_call\">,\n\t\t\t\"type\" | \"abi\"\n\t\t> & {\n\t\t\t\tabi?: A;\n\t\t\t}\n\t>;\n\tcontractDeploy(\n\t\tfields?: Fields<\"contract_deploy\">,\n\t): ChainEventFilter<\"contract_deploy\">;\n\t/** Canonical member is `print_event` (as Subgraphs and Subscriptions spell\n\t *  it); `toIndexParams`/`toStreamsParams` project to `print`. `prints`\n\t *  literals are preserved (`const P`) for per-topic `event.data` narrowing. */\n\tprint<\n\t\tconst P extends\n\t\t\t| Record<string, Record<string, PrintFieldType>>\n\t\t\t| undefined = undefined,\n\t>(\n\t\tfields?: Omit<SpecFor<\"print_event\">, \"type\" | \"prints\"> & { prints?: P },\n\t): ChainEventFilter<\n\t\t\"print_event\",\n\t\t{ type: \"print_event\" } & Omit<\n\t\t\tSpecFor<\"print_event\">,\n\t\t\t\"type\" | \"prints\"\n\t\t> & {\n\t\t\t\tprints?: P;\n\t\t\t}\n\t>;\n\tsbtcDeposit(\n\t\tfields?: Fields<\"sbtc_deposit\">,\n\t): ChainEventFilter<\"sbtc_deposit\">;\n\tsbtcWithdrawalCreate(\n\t\tfields?: Fields<\"sbtc_withdrawal_create\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_create\">;\n\tsbtcWithdrawalAccept(\n\t\tfields?: Fields<\"sbtc_withdrawal_accept\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_accept\">;\n\tsbtcWithdrawalReject(\n\t\tfields?: Fields<\"sbtc_withdrawal_reject\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_reject\">;\n\tsbtcWithdrawalSweptConfirmed(\n\t\tfields?: Fields<\"sbtc_withdrawal_swept_confirmed\">,\n\t): ChainEventFilter<\"sbtc_withdrawal_swept_confirmed\">;\n}\n\n/**\n * `on.*` — one filter vocabulary for every surface.\n *\n * ```ts\n * import { on } from \"@secondlayer/stacks/filters\";\n *\n * const usdc = on.ftTransfer({ assetIdentifier: USDC, minAmount: 1_000_000n });\n *\n * sl.index.events.list(usdc.toIndexParams({ limit: 100 }));   // pull\n * sl.streams.events.consume({ ...usdc.toStreamsParams(), onBatch });\n * sl.subscriptions.create({ name, url, triggers: [usdc.toChainTrigger()] });\n * defineSubgraph({ sources: { usdc: usdc.toSubgraphSource() }, schema, handlers });\n * ```\n *\n * A surface a member can't reach is a missing method (compile error), and a\n * field a surface can't express throws at projection time — never a silent\n * zero-row or over-wide match.\n */\nexport const on: OnNamespace = {\n\tstxTransfer: (fields: Fields<\"stx_transfer\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_transfer\", fields),\n\tstxMint: (fields: Fields<\"stx_mint\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_mint\", fields),\n\tstxBurn: (fields: Fields<\"stx_burn\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_burn\", fields),\n\tstxLock: (fields: Fields<\"stx_lock\"> = {}) =>\n\t\tmakeChainEventFilter(\"stx_lock\", fields),\n\tftTransfer: (fields: Fields<\"ft_transfer\"> = {}) =>\n\t\tmakeChainEventFilter(\"ft_transfer\", fields),\n\tftMint: (fields: Fields<\"ft_mint\"> = {}) =>\n\t\tmakeChainEventFilter(\"ft_mint\", fields),\n\tftBurn: (fields: Fields<\"ft_burn\"> = {}) =>\n\t\tmakeChainEventFilter(\"ft_burn\", fields),\n\tnftTransfer: (fields: Fields<\"nft_transfer\"> = {}) =>\n\t\tmakeChainEventFilter(\"nft_transfer\", fields),\n\tnftMint: (fields: Fields<\"nft_mint\"> = {}) =>\n\t\tmakeChainEventFilter(\"nft_mint\", fields),\n\tnftBurn: (fields: Fields<\"nft_burn\"> = {}) =>\n\t\tmakeChainEventFilter(\"nft_burn\", fields),\n\tcontractCall: <const A extends AbiContract | undefined = undefined>(\n\t\tfields: Omit<SpecFor<\"contract_call\">, \"type\" | \"abi\"> & { abi?: A } = {},\n\t) => makeChainEventFilter(\"contract_call\", fields),\n\tcontractDeploy: (fields: Fields<\"contract_deploy\"> = {}) =>\n\t\tmakeChainEventFilter(\"contract_deploy\", fields),\n\t/** Canonical member is `print_event` (as Subgraphs and Subscriptions spell\n\t *  it); `toIndexParams`/`toStreamsParams` project to `print`. */\n\tprint: <\n\t\tconst P extends\n\t\t\t| Record<string, Record<string, PrintFieldType>>\n\t\t\t| undefined = undefined,\n\t>(\n\t\tfields: Omit<SpecFor<\"print_event\">, \"type\" | \"prints\"> & {\n\t\t\tprints?: P;\n\t\t} = {},\n\t) => makeChainEventFilter(\"print_event\", fields),\n\tsbtcDeposit: (fields: Fields<\"sbtc_deposit\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_deposit\", fields),\n\tsbtcWithdrawalCreate: (fields: Fields<\"sbtc_withdrawal_create\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_withdrawal_create\", fields),\n\tsbtcWithdrawalAccept: (fields: Fields<\"sbtc_withdrawal_accept\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_withdrawal_accept\", fields),\n\tsbtcWithdrawalReject: (fields: Fields<\"sbtc_withdrawal_reject\"> = {}) =>\n\t\tmakeChainEventFilter(\"sbtc_withdrawal_reject\", fields),\n\tsbtcWithdrawalSweptConfirmed: (\n\t\tfields: Fields<\"sbtc_withdrawal_swept_confirmed\"> = {},\n\t) => makeChainEventFilter(\"sbtc_withdrawal_swept_confirmed\", fields),\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "287B8CB0793CF87664756E2164756E21",
+  "names": []
+}

package/dist/src/filters/index.d.cts

@@ -102,6 +102,50 @@ interface AbiContract {
 	implemented_traits?: ReadonlyArray<string>;
 	defined_traits?: ReadonlyArray<AbiTraitDefinition>;
 }
+/** A validated Stacks principal (standard or contract). Branded so downstream
+*  code can require "already validated" without re-checking. */
+type Principal = string & {
+	readonly __principal: unique symbol
+};
+/**
+* `<contract>::<asset-name>` — the shape a fungible/non-fungible asset filter
+* takes, expressed so the compiler can check it.
+*
+* The most common mistake in this API is passing a CONTRACT ID
+* (`SP….sbtc-token`) where an asset identifier (`SP….sbtc-token::sbtc-token`)
+* belongs, and the failure mode is a query that quietly returns zero rows. The
+* two differ structurally by `::`, so a template-literal type catches it at the
+* call site — no brand, no cast, literals just work.
+*
+* A value that is only known at runtime (config, env) is not narrow enough on
+* purpose; run it through {@link assetId} once, which validates and narrows.
+*
+* Wildcard patterns (Subscriptions/Subgraphs-only) are admitted by the second arm — they
+* are legitimately not full identifiers (`SPB.*`), and the runtime validator
+* short-circuits on them for the same reason.
+*/
+type AssetIdentifier = `${string}::${string}` | `${string}*${string}`;
+/**
+* Narrow a runtime string to an {@link AssetIdentifier}, validating it.
+*
+* The escape hatch for config-driven values: `assetId(process.env.ASSET!)`
+* throws on a contract id instead of letting it through to a zero-row query.
+*/
+declare function assetId(value: string): AssetIdentifier;
+/** `true` for a standard (`SP…`/`ST…`) or contract (`SP….name`) principal. */
+declare function isPrincipal(value: string): value is Principal;
+/** Subscriptions and Subgraph sources match `*` wildcards in
+*  principal/identifier patterns; every
+*  other surface treats the value literally. */
+declare function hasWildcard(value: string): boolean;
+/** Throw unless `value` is a principal or a wildcard pattern. The factories
+*  call this so a swapped argument (asset id where a sender belongs, typo'd
+*  address) fails at construction — not as a silent zero-row query. */
+declare function assertPrincipalish(field: string, value: string): void;
+/** Throw unless `value` looks like `SP….contract::asset` (or a wildcard). */
+declare function assertAssetIdentifier(field: string, value: string): void;
+/** Throw unless `value` is a contract id `SP….name` (or a wildcard). */
+declare function assertContractId(field: string, value: string): void;
 /** Scalar print field types (structural mirror of the subgraphs `ColumnType`). */
 type PrintScalarType = "uint" | "int" | "text" | "principal" | "boolean" | "timestamp" | "jsonb";
 /**
@@ -150,37 +194,37 @@ type TraitScope = {
 };
 interface FtTransferSpec extends TraitScope {
 	type: "ft_transfer";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 	recipient?: string;
 	minAmount?: bigint;
 }
 interface FtMintSpec extends TraitScope {
 	type: "ft_mint";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	recipient?: string;
 	minAmount?: bigint;
 }
 interface FtBurnSpec extends TraitScope {
 	type: "ft_burn";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 	minAmount?: bigint;
 }
 interface NftTransferSpec extends TraitScope {
 	type: "nft_transfer";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 	recipient?: string;
 }
 interface NftMintSpec extends TraitScope {
 	type: "nft_mint";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	recipient?: string;
 }
 interface NftBurnSpec extends TraitScope {
 	type: "nft_burn";
-	assetIdentifier?: string;
+	assetIdentifier?: AssetIdentifier;
 	sender?: string;
 }
 interface ContractCallSpec extends TraitScope {
@@ -262,26 +306,30 @@ type ChainTriggerShape = ChainTriggerOf<ChainEventFilterSpec>;
 /** Params fragment for `index.events.*` (spread into list/walk/consume). */
 type IndexEventsParamsShape = {
 	eventType: DecodedEventType
-	contractId?: string
-	assetIdentifier?: string
+	/** A spec's contract set passes through verbatim (the API takes up to 20). */
+	contractId?: string | readonly string[]
+	assetIdentifier?: AssetIdentifier
 	sender?: string
 	recipient?: string
 	trait?: string
 };
 /** Params fragment for `index.contractCalls.*`. */
 type ContractCallsParamsShape = {
-	contractId?: string
+	/** A spec's contract set passes through verbatim (the API takes up to 20). */
+	contractId?: string | readonly string[]
 	functionName?: string
+	/** Populated from the spec's `caller` — the endpoint filters by tx sender,
+	*  which is the caller. */
 	sender?: string
 	trait?: string
 };
 /** Params fragment for `streams.events.*`. */
 type StreamsParamsShape = {
 	types: readonly DecodedEventType[]
-	contractId?: string
+	contractId?: string | readonly string[]
 	sender?: string
 	recipient?: string
-	assetIdentifier?: string
+	assetIdentifier?: AssetIdentifier
 };
 type DecodedMember = "stx_transfer" | "stx_mint" | "stx_burn" | "stx_lock" | "ft_transfer" | "ft_mint" | "ft_burn" | "nft_transfer" | "nft_mint" | "nft_burn" | "print_event";
 type ProjectionsFor<
@@ -397,22 +445,4 @@ interface OnNamespace {
 * zero-row or over-wide match.
 */
 declare const on: OnNamespace;
-/** A validated Stacks principal (standard or contract). Branded so downstream
-*  code can require "already validated" without re-checking. */
-type Principal = string & {
-	readonly __principal: unique symbol
-};
-/** `true` for a standard (`SP…`/`ST…`) or contract (`SP….name`) principal. */
-declare function isPrincipal(value: string): value is Principal;
-/** Subscriptions match `*` wildcards in principal/identifier patterns; every
-*  other surface treats the value literally. */
-declare function hasWildcard(value: string): boolean;
-/** Throw unless `value` is a principal or a wildcard pattern. The factories
-*  call this so a swapped argument (asset id where a sender belongs, typo'd
-*  address) fails at construction — not as a silent zero-row query. */
-declare function assertPrincipalish(field: string, value: string): void;
-/** Throw unless `value` looks like `SP….contract::asset` (or a wildcard). */
-declare function assertAssetIdentifier(field: string, value: string): void;
-/** Throw unless `value` is a contract id `SP….name` (or a wildcard). */
-declare function assertContractId(field: string, value: string): void;
-export { on, makeChainEventFilter, isPrincipal, hasWildcard, fromSubgraphSource, assertPrincipalish, assertContractId, assertAssetIdentifier, SubgraphSourceSpec, SubgraphMemberType, StxTransferSpec, StxMintSpec, StxLockSpec, StxBurnSpec, StreamsParamsShape, SpecFor, SbtcWithdrawalSweptConfirmedSpec, SbtcWithdrawalRejectSpec, SbtcWithdrawalCreateSpec, SbtcWithdrawalAcceptSpec, SbtcDepositSpec, PrintScalarType, PrintFieldType, PrintEventSpec, Principal, NftTransferSpec, NftMintSpec, NftBurnSpec, IndexEventsParamsShape, FtTransferSpec, FtMintSpec, FtBurnSpec, DecodedEventType, DECODED_EVENT_TYPES, ContractDeploySpec, ContractCallsParamsShape, ContractCallSpec, ChainTriggerShape, ChainTriggerOf, ChainEventFilterType, ChainEventFilterSpec, ChainEventFilter, CHAIN_EVENT_FILTER_TYPES };
+export { on, makeChainEventFilter, isPrincipal, hasWildcard, fromSubgraphSource, assetId, assertPrincipalish, assertContractId, assertAssetIdentifier, SubgraphSourceSpec, SubgraphMemberType, StxTransferSpec, StxMintSpec, StxLockSpec, StxBurnSpec, StreamsParamsShape, SpecFor, SbtcWithdrawalSweptConfirmedSpec, SbtcWithdrawalRejectSpec, SbtcWithdrawalCreateSpec, SbtcWithdrawalAcceptSpec, SbtcDepositSpec, PrintScalarType, PrintFieldType, PrintEventSpec, Principal, NftTransferSpec, NftMintSpec, NftBurnSpec, IndexEventsParamsShape, FtTransferSpec, FtMintSpec, FtBurnSpec, DecodedEventType, DECODED_EVENT_TYPES, ContractDeploySpec, ContractCallsParamsShape, ContractCallSpec, ChainTriggerShape, ChainTriggerOf, ChainEventFilterType, ChainEventFilterSpec, ChainEventFilter, CHAIN_EVENT_FILTER_TYPES, AssetIdentifier };