@secondlayer/stacks 3.0.0 → 3.1.0

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

@@ -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 };

package/dist/src/filters/index.js

@@ -4,12 +4,13 @@ import {
   assertAssetIdentifier,
   assertContractId,
   assertPrincipalish,
+  assetId,
   fromSubgraphSource,
   hasWildcard,
   isPrincipal,
   makeChainEventFilter,
   on
-} from "../../shared/stacks-tqrws7kd.js";
+} from "../../shared/stacks-0j16z8ev.js";
 import"../../shared/stacks-azp00pve.js";
 import"../../shared/stacks-qs5fzts5.js";
 export {
@@ -18,6 +19,7 @@ export {
   isPrincipal,
   hasWildcard,
   fromSubgraphSource,
+  assetId,
   assertPrincipalish,
   assertContractId,
   assertAssetIdentifier,
@@ -25,5 +27,5 @@ export {
   CHAIN_EVENT_FILTER_TYPES
 };
 
-//# debugId=0BF4319B462244F964756E2164756E21
+//# debugId=FBE00090F020672E64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/src/filters/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "0BF4319B462244F964756E2164756E21",
+  "debugId": "FBE00090F020672E64756E2164756E21",
   "names": []
 }

package/dist/src/index.d.cts

@@ -116,6 +116,24 @@ interface AbiContract {
 	implemented_traits?: ReadonlyArray<string>;
 	defined_traits?: ReadonlyArray<AbiTraitDefinition>;
 }
+/**
+* `<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}`;
 /** Scalar print field types (structural mirror of the subgraphs `ColumnType`). */
 type PrintScalarType = "uint" | "int" | "text" | "principal" | "boolean" | "timestamp" | "jsonb";
 /**
@@ -164,37 +182,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 {
@@ -263,26 +281,30 @@ type ChainTriggerOf<S> = { [K in keyof Omit<S, "abi" | "prints">] : Exclude<S[K]
 /** 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<

package/dist/src/index.d.ts

@@ -116,6 +116,24 @@ interface AbiContract {
 	implemented_traits?: ReadonlyArray<string>;
 	defined_traits?: ReadonlyArray<AbiTraitDefinition>;
 }
+/**
+* `<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}`;
 /** Scalar print field types (structural mirror of the subgraphs `ColumnType`). */
 type PrintScalarType = "uint" | "int" | "text" | "principal" | "boolean" | "timestamp" | "jsonb";
 /**
@@ -164,37 +182,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 {
@@ -263,26 +281,30 @@ type ChainTriggerOf<S> = { [K in keyof Omit<S, "abi" | "prints">] : Exclude<S[K]
 /** 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<

package/dist/src/index.js

@@ -1,6 +1,6 @@
 import {
   on
-} from "../shared/stacks-tqrws7kd.js";
+} from "../shared/stacks-0j16z8ev.js";
 import {
   providerToAccount
 } from "../shared/stacks-qcae5852.js";

package/dist/src/pox/index.cjs

@@ -8,18 +8,13 @@ __export(exports_pox, {
   burnHeightToRewardCycle: () => burnHeightToRewardCycle,
   POX_CONTRACTS: () => POX_CONTRACTS,
   POX_ADDRESS_VERSION: () => POX_ADDRESS_VERSION,
+  POX_ABI: () => POX_ABI,
   MIN_LOCK_PERIOD: () => MIN_LOCK_PERIOD,
   MAX_LOCK_PERIOD: () => MAX_LOCK_PERIOD
 });
 module.exports = __toCommonJS(exports_pox);
 
 // src/pox/abi.ts
-var poxAddressTuple = {
-  tuple: [
-    { name: "version", type: { buff: { length: 1 } } },
-    { name: "hashbytes", type: { buff: { length: 32 } } }
-  ]
-};
 var POX_ABI = {
   functions: [
     {
@@ -49,7 +44,15 @@ var POX_ABI = {
       outputs: {
         optional: {
           tuple: [
-            { name: "pox-addr", type: poxAddressTuple },
+            {
+              name: "pox-addr",
+              type: {
+                tuple: [
+                  { name: "version", type: { buff: { length: 1 } } },
+                  { name: "hashbytes", type: { buff: { length: 32 } } }
+                ]
+              }
+            },
             { name: "lock-period", type: "uint128" },
             { name: "first-reward-cycle", type: "uint128" },
             {
@@ -71,7 +74,17 @@ var POX_ABI = {
             { name: "amount-ustx", type: "uint128" },
             { name: "delegated-to", type: "principal" },
             { name: "until-burn-ht", type: { optional: "uint128" } },
-            { name: "pox-addr", type: { optional: poxAddressTuple } }
+            {
+              name: "pox-addr",
+              type: {
+                optional: {
+                  tuple: [
+                    { name: "version", type: { buff: { length: 1 } } },
+                    { name: "hashbytes", type: { buff: { length: 32 } } }
+                  ]
+                }
+              }
+            }
           ]
         }
       }
@@ -80,7 +93,15 @@ var POX_ABI = {
       name: "can-stack-stx",
       access: "read-only",
       args: [
-        { name: "pox-addr", type: poxAddressTuple },
+        {
+          name: "pox-addr",
+          type: {
+            tuple: [
+              { name: "version", type: { buff: { length: 1 } } },
+              { name: "hashbytes", type: { buff: { length: 32 } } }
+            ]
+          }
+        },
         { name: "amount-ustx", type: "uint128" },
         { name: "first-reward-cycle", type: "uint128" },
         { name: "num-cycles", type: "uint128" }
@@ -92,7 +113,15 @@ var POX_ABI = {
       access: "public",
       args: [
         { name: "amount-ustx", type: "uint128" },
-        { name: "pox-addr", type: poxAddressTuple },
+        {
+          name: "pox-addr",
+          type: {
+            tuple: [
+              { name: "version", type: { buff: { length: 1 } } },
+              { name: "hashbytes", type: { buff: { length: 32 } } }
+            ]
+          }
+        },
         { name: "start-burn-ht", type: "uint128" },
         { name: "lock-period", type: "uint128" },
         {
@@ -124,7 +153,17 @@ var POX_ABI = {
         { name: "amount-ustx", type: "uint128" },
         { name: "delegate-to", type: "principal" },
         { name: "until-burn-ht", type: { optional: "uint128" } },
-        { name: "pox-addr", type: { optional: poxAddressTuple } }
+        {
+          name: "pox-addr",
+          type: {
+            optional: {
+              tuple: [
+                { name: "version", type: { buff: { length: 1 } } },
+                { name: "hashbytes", type: { buff: { length: 32 } } }
+              ]
+            }
+          }
+        }
       ],
       outputs: { response: { ok: "bool", error: "int128" } }
     },
@@ -140,7 +179,17 @@ var POX_ABI = {
                 { name: "amount-ustx", type: "uint128" },
                 { name: "delegated-to", type: "principal" },
                 { name: "until-burn-ht", type: { optional: "uint128" } },
-                { name: "pox-addr", type: { optional: poxAddressTuple } }
+                {
+                  name: "pox-addr",
+                  type: {
+                    optional: {
+                      tuple: [
+                        { name: "version", type: { buff: { length: 1 } } },
+                        { name: "hashbytes", type: { buff: { length: 32 } } }
+                      ]
+                    }
+                  }
+                }
               ]
             }
           },
@@ -153,7 +202,15 @@ var POX_ABI = {
       access: "public",
       args: [
         { name: "extend-count", type: "uint128" },
-        { name: "pox-addr", type: poxAddressTuple },
+        {
+          name: "pox-addr",
+          type: {
+            tuple: [
+              { name: "version", type: { buff: { length: 1 } } },
+              { name: "hashbytes", type: { buff: { length: 32 } } }
+            ]
+          }
+        },
         {
           name: "signer-sig",
           type: { optional: { buff: { length: 65 } } }
@@ -447,5 +504,5 @@ function pox() {
   });
 }
 
-//# debugId=690246EFCDC2A66B64756E2164756E21
+//# debugId=6A5F5DD3CC1B75FC64756E2164756E21
 //# sourceMappingURL=index.cjs.map