@secondlayer/stacks 2.2.1 → 2.4.0

package/dist/src/index.d.ts

@@ -867,7 +867,7 @@ declare namespace exports_on {
 * The user supplies which subgraph + table to bind against — these factories
 * don't assume Foundation Datasets are subscribable. To watch FT transfers
 * to an address, build a subgraph with a `transfers` table (see
-* `sl subgraphs new --template sip-010-balances`) and bind here.
+* `sl subgraphs create --template sip-010-balances`) and bind here.
 */
 /**
 * What every factory takes as its first arg: which user-owned subgraph table
@@ -922,7 +922,7 @@ type BnsAction = "new-name" | "transfer-name" | "renew-name" | "burn-name" | "ne
 *
 * Bind against a subgraph table that mirrors the `bns_name_events` shape
 * (topic, namespace, name, owner, ...). Easiest path: scaffold via
-* `sl subgraphs new --template bns-names`.
+* `sl subgraphs create --template bns-names`.
 *
 * @param action restrict to one topic; omit to fire on every name event
 */
@@ -934,7 +934,7 @@ type PoxFunction = "stack-stx" | "stack-extend" | "stack-increase" | "delegate-s
 /**
 * Match PoX-4 stacking calls. Bind against a subgraph table mirroring
 * `pox4_calls` (function_name, stacker, caller, ...). Scaffold via
-* `sl subgraphs new --template pox-stacking`.
+* `sl subgraphs create --template pox-stacking`.
 *
 * @param fn restrict to one PoX-4 function; omit to fire on every call
 */
@@ -945,7 +945,7 @@ declare function poxStack(target: FactoryTarget, fn?: PoxFunction, opts?: {
 /**
 * Match sBTC deposit completion events. Bind against a subgraph table
 * mirroring `sbtc_events` (topic, amount, sender, bitcoin_txid, ...).
-* Scaffold via `sl subgraphs new --template sbtc-flows`.
+* Scaffold via `sl subgraphs create --template sbtc-flows`.
 */
 declare function sbtcDeposit(target: FactoryTarget, opts?: {
 	sender?: string

package/dist/src/index.js.map

@@ -14,10 +14,10 @@
     "import { createTransport } from \"./createTransport.ts\";\nimport type { RequestFn, TransportFactory } from \"./types.ts\";\n\n/** Create a transport backed by a user-provided request function. */\nexport function custom(params: { request: RequestFn }): TransportFactory {\n\treturn () => createTransport(\"custom\", { request: params.request });\n}\n",
     "import { createTransport } from \"./createTransport.ts\";\nimport type { TransportFactory } from \"./types.ts\";\n\n/** Create a transport that tries each transport in order until one succeeds. */\nexport function fallback(transports: TransportFactory[]): TransportFactory {\n\treturn (params) => {\n\t\tconst resolved = transports.map((t) => t(params));\n\n\t\treturn createTransport(\"fallback\", {\n\t\t\trequest: async (path, options) => {\n\t\t\t\tlet lastError: Error | undefined;\n\t\t\t\tfor (const transport of resolved) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\treturn await transport.request(path, options);\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\tlastError =\n\t\t\t\t\t\t\terror instanceof Error ? error : new Error(String(error));\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tthrow lastError ?? new Error(\"All transports failed\");\n\t\t\t},\n\t\t});\n\t};\n}\n",
     "import { WebSocketError } from \"../errors/websocket.ts\";\nimport type {\n\tSubscription,\n\tWsSubscribeParams,\n} from \"../subscriptions/types.ts\";\nimport { buildRequestFn } from \"./createTransport.ts\";\nimport type { Transport, TransportConfig, TransportFactory } from \"./types.ts\";\n\n/** Configuration for the WebSocket transport, extending base {@link TransportConfig}. */\nexport type WebSocketTransportConfig = TransportConfig & {\n\t/** WebSocket URL (resolved from chain if omitted) */\n\turl?: string;\n\t/** Enable auto-reconnect (default: true) */\n\treconnect?: boolean;\n\t/** Max reconnect attempts (default: 10) */\n\treconnectMaxAttempts?: number;\n\t/** Base delay in ms for exponential backoff (default: 1000) */\n\treconnectBaseDelay?: number;\n};\n\n/** Transport with WebSocket subscription capabilities and auto-reconnect. */\nexport type WebSocketTransport = Transport & {\n\ttype: \"webSocket\";\n\tsubscribe: (\n\t\tparams: WsSubscribeParams,\n\t\t// biome-ignore lint/suspicious/noExplicitAny: interop boundary or dynamic-shape value where typing adds friction without runtime safety\n\t\tcallback: (data: any) => void,\n\t) => Promise<Subscription>;\n\tdestroy: () => void;\n};\n\ntype JsonRpcRequest = {\n\tjsonrpc: \"2.0\";\n\tid: number;\n\tmethod: string;\n\tparams: Record<string, unknown>;\n};\n\ntype JsonRpcResponse = {\n\tjsonrpc: \"2.0\";\n\tid: number;\n\tresult?: unknown;\n\terror?: { code: number; message: string };\n};\n\ntype JsonRpcNotification = {\n\tjsonrpc: \"2.0\";\n\tmethod: string;\n\tparams: unknown;\n};\n\ntype SubEntry = {\n\tparams: WsSubscribeParams;\n\t// biome-ignore lint/suspicious/noExplicitAny: interop boundary or dynamic-shape value where typing adds friction without runtime safety\n\tcallbacks: Set<(data: any) => void>;\n};\n\nfunction subKey(params: WsSubscribeParams): string {\n\tconst parts: string[] = [params.event];\n\tif (params.tx_id) parts.push(`tx_id:${params.tx_id}`);\n\tif (params.address) parts.push(`address:${params.address}`);\n\tif (params.asset_identifier) parts.push(`asset:${params.asset_identifier}`);\n\tif (params.value) parts.push(`value:${params.value}`);\n\treturn parts.join(\"|\");\n}\n\nexport class WebSocketChannel {\n\tprivate ws: WebSocket | null = null;\n\tprivate url: string;\n\tprivate nextId = 1;\n\tprivate pending = new Map<\n\t\tnumber,\n\t\t{ resolve: (v: unknown) => void; reject: (e: Error) => void }\n\t>();\n\tprivate subs = new Map<string, SubEntry>();\n\tprivate destroyed = false;\n\tprivate reconnecting = false;\n\tprivate reconnectAttempt = 0;\n\tprivate reconnectTimer: ReturnType<typeof setTimeout> | null = null;\n\n\tprivate reconnect: boolean;\n\tprivate reconnectMaxAttempts: number;\n\tprivate reconnectBaseDelay: number;\n\n\tconstructor(url: string, config?: WebSocketTransportConfig) {\n\t\tthis.url = url;\n\t\tthis.reconnect = config?.reconnect ?? true;\n\t\tthis.reconnectMaxAttempts = config?.reconnectMaxAttempts ?? 10;\n\t\tthis.reconnectBaseDelay = config?.reconnectBaseDelay ?? 1000;\n\t}\n\n\tprivate connect(): Promise<void> {\n\t\tif (this.ws?.readyState === WebSocket.OPEN) return Promise.resolve();\n\t\tif (this.ws?.readyState === WebSocket.CONNECTING) {\n\t\t\treturn new Promise((resolve, reject) => {\n\t\t\t\tconst onOpen = () => {\n\t\t\t\t\tthis.ws?.removeEventListener(\"error\", onError);\n\t\t\t\t\tresolve();\n\t\t\t\t};\n\t\t\t\tconst onError = (e: Event) => {\n\t\t\t\t\tthis.ws?.removeEventListener(\"open\", onOpen);\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew WebSocketError(\"WebSocket connection failed\", {\n\t\t\t\t\t\t\tdetails: String(e),\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t};\n\t\t\t\tthis.ws?.addEventListener(\"open\", onOpen, { once: true });\n\t\t\t\tthis.ws?.addEventListener(\"error\", onError, { once: true });\n\t\t\t});\n\t\t}\n\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tthis.ws = new WebSocket(this.url);\n\n\t\t\tthis.ws.addEventListener(\n\t\t\t\t\"open\",\n\t\t\t\t() => {\n\t\t\t\t\tthis.reconnectAttempt = 0;\n\t\t\t\t\tthis.reconnecting = false;\n\t\t\t\t\tresolve();\n\t\t\t\t},\n\t\t\t\t{ once: true },\n\t\t\t);\n\n\t\t\tthis.ws.addEventListener(\n\t\t\t\t\"error\",\n\t\t\t\t(e) => {\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew WebSocketError(\"WebSocket connection failed\", {\n\t\t\t\t\t\t\tdetails: String(e),\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\t{ once: true },\n\t\t\t);\n\n\t\t\tthis.ws.addEventListener(\"message\", (event) => {\n\t\t\t\tthis.handleMessage(event.data);\n\t\t\t});\n\n\t\t\tthis.ws.addEventListener(\"close\", () => {\n\t\t\t\tif (!this.destroyed) this.handleDisconnect();\n\t\t\t});\n\t\t});\n\t}\n\n\tprivate handleMessage(raw: string | ArrayBuffer | Blob) {\n\t\tconst data =\n\t\t\ttypeof raw === \"string\"\n\t\t\t\t? raw\n\t\t\t\t: new TextDecoder().decode(raw as ArrayBuffer);\n\n\t\tlet msg: JsonRpcResponse | JsonRpcNotification;\n\t\ttry {\n\t\t\tmsg = JSON.parse(data);\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\n\t\t// RPC response\n\t\tif (\"id\" in msg && msg.id != null) {\n\t\t\tconst rpc = msg as JsonRpcResponse;\n\t\t\tconst p = this.pending.get(rpc.id);\n\t\t\tif (!p) return;\n\t\t\tthis.pending.delete(rpc.id);\n\t\t\tif (rpc.error) {\n\t\t\t\tp.reject(\n\t\t\t\t\tnew WebSocketError(rpc.error.message, {\n\t\t\t\t\t\tdetails: `JSON-RPC error ${rpc.error.code}`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tp.resolve(rpc.result);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\t// Notification\n\t\tconst notif = msg as JsonRpcNotification;\n\t\tif (!notif.method) return;\n\n\t\tfor (const [, entry] of this.subs) {\n\t\t\tif (entry.params.event === notif.method) {\n\t\t\t\tfor (const cb of entry.callbacks) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tcb(notif.params);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// subscriber error — don't crash channel\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate handleDisconnect() {\n\t\tthis.ws = null;\n\n\t\t// reject pending RPCs\n\t\tfor (const [, p] of this.pending) {\n\t\t\tp.reject(new WebSocketError(\"WebSocket disconnected\"));\n\t\t}\n\t\tthis.pending.clear();\n\n\t\tif (\n\t\t\tthis.reconnect &&\n\t\t\tthis.subs.size > 0 &&\n\t\t\tthis.reconnectAttempt < this.reconnectMaxAttempts\n\t\t) {\n\t\t\tthis.scheduleReconnect();\n\t\t}\n\t}\n\n\tprivate scheduleReconnect() {\n\t\tif (this.destroyed || this.reconnecting) return;\n\t\tthis.reconnecting = true;\n\t\tconst delay = this.reconnectBaseDelay * 2 ** this.reconnectAttempt;\n\t\tthis.reconnectAttempt++;\n\n\t\tthis.reconnectTimer = setTimeout(async () => {\n\t\t\tthis.reconnecting = false;\n\t\t\ttry {\n\t\t\t\tawait this.connect();\n\t\t\t\tawait this.resubscribeAll();\n\t\t\t} catch {\n\t\t\t\tif (!this.destroyed && this.subs.size > 0) {\n\t\t\t\t\tthis.handleDisconnect();\n\t\t\t\t}\n\t\t\t}\n\t\t}, delay);\n\t}\n\n\tprivate async resubscribeAll() {\n\t\tfor (const [, entry] of this.subs) {\n\t\t\tawait this.sendRpc(\"subscribe\", entry.params);\n\t\t}\n\t}\n\n\tprivate sendRpc(\n\t\tmethod: string,\n\t\tparams: Record<string, unknown>,\n\t): Promise<unknown> {\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tif (!this.ws || this.ws.readyState !== WebSocket.OPEN) {\n\t\t\t\treturn reject(new WebSocketError(\"WebSocket not connected\"));\n\t\t\t}\n\n\t\t\tconst id = this.nextId++;\n\t\t\tconst msg: JsonRpcRequest = {\n\t\t\t\tjsonrpc: \"2.0\",\n\t\t\t\tid,\n\t\t\t\tmethod,\n\t\t\t\tparams,\n\t\t\t};\n\n\t\t\tthis.pending.set(id, { resolve, reject });\n\t\t\tthis.ws.send(JSON.stringify(msg));\n\t\t});\n\t}\n\n\tasync subscribe(\n\t\tparams: WsSubscribeParams,\n\t\t// biome-ignore lint/suspicious/noExplicitAny: interop boundary or dynamic-shape value where typing adds friction without runtime safety\n\t\tcallback: (data: any) => void,\n\t): Promise<Subscription> {\n\t\tif (this.destroyed) {\n\t\t\tthrow new WebSocketError(\"WebSocket channel has been destroyed\");\n\t\t}\n\n\t\tawait this.connect();\n\n\t\tconst key = subKey(params);\n\t\tlet entry = this.subs.get(key);\n\n\t\tif (entry) {\n\t\t\t// Dedup: reuse existing WS subscription\n\t\t\tentry.callbacks.add(callback);\n\t\t} else {\n\t\t\t// New WS subscription\n\t\t\tentry = { params, callbacks: new Set([callback]) };\n\t\t\tthis.subs.set(key, entry);\n\t\t\tawait this.sendRpc(\"subscribe\", params);\n\t\t}\n\n\t\treturn {\n\t\t\tunsubscribe: () => {\n\t\t\t\tconst e = this.subs.get(key);\n\t\t\t\tif (!e) return;\n\t\t\t\te.callbacks.delete(callback);\n\t\t\t\tif (e.callbacks.size === 0) {\n\t\t\t\t\tthis.subs.delete(key);\n\t\t\t\t\t// Best-effort unsubscribe RPC\n\t\t\t\t\tif (this.ws?.readyState === WebSocket.OPEN) {\n\t\t\t\t\t\tthis.sendRpc(\"unsubscribe\", params).catch(() => {});\n\t\t\t\t\t}\n\t\t\t\t\t// Auto-close when no subscribers remain\n\t\t\t\t\tif (this.subs.size === 0) this.closeQuietly();\n\t\t\t\t}\n\t\t\t},\n\t\t};\n\t}\n\n\tprivate closeQuietly() {\n\t\tif (this.ws) {\n\t\t\tthis.ws.close();\n\t\t\tthis.ws = null;\n\t\t}\n\t}\n\n\tdestroy(): void {\n\t\tthis.destroyed = true;\n\t\tif (this.reconnectTimer) clearTimeout(this.reconnectTimer);\n\n\t\tfor (const [, p] of this.pending) {\n\t\t\tp.reject(new WebSocketError(\"WebSocket channel destroyed\"));\n\t\t}\n\t\tthis.pending.clear();\n\t\tthis.subs.clear();\n\n\t\tif (this.ws) {\n\t\t\tthis.ws.close();\n\t\t\tthis.ws = null;\n\t\t}\n\t}\n}\n\nfunction deriveWsUrl(httpUrl: string): string {\n\treturn `${httpUrl.replace(/^http/, \"ws\").replace(/\\/$/, \"\")}/extended/v1/ws`;\n}\n\n/**\n * Create a WebSocket transport for real-time Stacks event subscriptions.\n * HTTP requests use the resolved RPC URL; subscriptions use the WS endpoint.\n */\nexport function webSocket(\n\turl?: string,\n\tconfig?: WebSocketTransportConfig,\n): TransportFactory {\n\treturn (params) => {\n\t\tconst httpUrl =\n\t\t\tconfig?.url ??\n\t\t\tparams?.chain?.rpcUrls.default.http[0] ??\n\t\t\t\"http://localhost:3999\";\n\n\t\tconst wsUrl =\n\t\t\turl ?? params?.chain?.rpcUrls.default.ws?.[0] ?? deriveWsUrl(httpUrl);\n\n\t\tconst resolvedHttpConfig: TransportConfig = {\n\t\t\t...config,\n\t\t\turl: httpUrl,\n\t\t};\n\n\t\tconst channel = new WebSocketChannel(wsUrl, config);\n\n\t\tconst transport: WebSocketTransport = {\n\t\t\ttype: \"webSocket\",\n\t\t\trequest: buildRequestFn(httpUrl, resolvedHttpConfig),\n\t\t\tconfig: resolvedHttpConfig,\n\t\t\tsubscribe: (subParams, callback) =>\n\t\t\t\tchannel.subscribe(subParams, callback),\n\t\t\tdestroy: () => channel.destroy(),\n\t\t};\n\n\t\treturn transport;\n\t};\n}\n",
-    "/**\n * Filter specs for `@secondlayer/sdk` subscriptions.\n *\n * Each `on.*` factory in this directory binds typed filter clauses to a\n * known table shape and returns a `SubscriptionFilterSpec`. Spread it into\n * a full subscription input alongside `name`, `url`, `format`, etc:\n *\n *   const spec = on.transferTo(\n *     { subgraph: \"my-watcher\", table: \"transfers\" },\n *     \"SP1ABC...\",\n *   );\n *   await sdk.subscriptions.create({\n *     ...spec,\n *     name: \"watch-incoming\",\n *     url: \"https://my-app.com/webhook\",\n *   });\n *\n * The user supplies which subgraph + table to bind against — these factories\n * don't assume Foundation Datasets are subscribable. To watch FT transfers\n * to an address, build a subgraph with a `transfers` table (see\n * `sl subgraphs new --template sip-010-balances`) and bind here.\n */\n\n/**\n * What every factory takes as its first arg: which user-owned subgraph table\n * to filter against.\n */\nexport type FactoryTarget = {\n\tsubgraph: string;\n\ttable: string;\n};\n\n/**\n * A primitive value that can appear in a filter clause.\n * Mirrors `SubscriptionFilterPrimitive` in\n * `@secondlayer/shared/schemas/subscriptions` — duplicated here to keep\n * `@secondlayer/stacks` from importing the api/server schema package.\n */\nexport type FilterPrimitive = string | number | boolean;\n\n/** Operator forms a filter clause can take. */\nexport type FilterOperator =\n\t| { eq: FilterPrimitive }\n\t| { neq: FilterPrimitive }\n\t| { gt: string | number }\n\t| { gte: string | number }\n\t| { lt: string | number }\n\t| { lte: string | number }\n\t| { in: FilterPrimitive[] };\n\n/** A single column's filter: bare value (eq) or operator object. */\nexport type FilterClause = FilterPrimitive | FilterOperator;\n\n/** Map of column → filter clause. Empty `{}` matches every row. */\nexport type Filter = Record<string, FilterClause>;\n\n/**\n * Output of every `on.*` factory. Use directly as a partial input to\n * `sdk.subscriptions.create` — the SDK's existing `CreateSubscriptionRequest`\n * already accepts these three fields.\n */\nexport type SubscriptionFilterSpec = {\n\tsubgraphName: string;\n\ttableName: string;\n\tfilter: Filter;\n};\n\n/** Thin helper to build a spec without restating the field-name mapping. */\nexport function makeSpec(\n\ttarget: FactoryTarget,\n\tfilter: Filter,\n): SubscriptionFilterSpec {\n\treturn {\n\t\tsubgraphName: target.subgraph,\n\t\ttableName: target.table,\n\t\tfilter,\n\t};\n}\n",
-    "import {\n\ttype FactoryTarget,\n\ttype SubscriptionFilterSpec,\n\tmakeSpec,\n} from \"./spec.ts\";\n\nexport type BnsAction =\n\t| \"new-name\"\n\t| \"transfer-name\"\n\t| \"renew-name\"\n\t| \"burn-name\"\n\t| \"new-airdrop\";\n\n/**\n * Match BNS-V2 name lifecycle events.\n *\n * Bind against a subgraph table that mirrors the `bns_name_events` shape\n * (topic, namespace, name, owner, ...). Easiest path: scaffold via\n * `sl subgraphs new --template bns-names`.\n *\n * @param action restrict to one topic; omit to fire on every name event\n */\nexport function bnsName(\n\ttarget: FactoryTarget,\n\taction?: BnsAction,\n\topts?: { namespace?: string; owner?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\t...(action && { topic: action }),\n\t\t...(opts?.namespace && { namespace: opts.namespace }),\n\t\t...(opts?.owner && { owner: opts.owner }),\n\t});\n}\n",
-    "import {\n\ttype FactoryTarget,\n\ttype SubscriptionFilterSpec,\n\tmakeSpec,\n} from \"./spec.ts\";\n\nexport type PoxFunction =\n\t| \"stack-stx\"\n\t| \"stack-extend\"\n\t| \"stack-increase\"\n\t| \"delegate-stx\"\n\t| \"revoke-delegate-stx\"\n\t| \"delegate-stack-stx\"\n\t| \"delegate-stack-extend\"\n\t| \"delegate-stack-increase\"\n\t| \"stack-aggregation-commit\"\n\t| \"stack-aggregation-commit-indexed\"\n\t| \"stack-aggregation-increase\"\n\t| \"set-signer-key-authorization\";\n\n/**\n * Match PoX-4 stacking calls. Bind against a subgraph table mirroring\n * `pox4_calls` (function_name, stacker, caller, ...). Scaffold via\n * `sl subgraphs new --template pox-stacking`.\n *\n * @param fn restrict to one PoX-4 function; omit to fire on every call\n */\nexport function poxStack(\n\ttarget: FactoryTarget,\n\tfn?: PoxFunction,\n\topts?: { stacker?: string; signerKey?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\t...(fn && { function_name: fn }),\n\t\t...(opts?.stacker && { stacker: opts.stacker }),\n\t\t...(opts?.signerKey && { signer_key: opts.signerKey }),\n\t});\n}\n",
-    "import {\n\ttype FactoryTarget,\n\ttype SubscriptionFilterSpec,\n\tmakeSpec,\n} from \"./spec.ts\";\n\n/**\n * Match sBTC deposit completion events. Bind against a subgraph table\n * mirroring `sbtc_events` (topic, amount, sender, bitcoin_txid, ...).\n * Scaffold via `sl subgraphs new --template sbtc-flows`.\n */\nexport function sbtcDeposit(\n\ttarget: FactoryTarget,\n\topts?: { sender?: string; bitcoinTxid?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\ttopic: \"completed-deposit\",\n\t\t...(opts?.sender && { sender: opts.sender }),\n\t\t...(opts?.bitcoinTxid && { bitcoin_txid: opts.bitcoinTxid }),\n\t});\n}\n\n/**\n * Match sBTC withdrawal lifecycle events. Phase defaults to all three\n * (`create` / `accept` / `reject`); pass an explicit `phase` to narrow.\n */\nexport function sbtcWithdrawal(\n\ttarget: FactoryTarget,\n\topts?: {\n\t\tphase?: \"create\" | \"accept\" | \"reject\";\n\t\tsender?: string;\n\t\trequestId?: number;\n\t},\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\ttopic: opts?.phase\n\t\t\t? { eq: `withdrawal-${opts.phase}` }\n\t\t\t: { in: [\"withdrawal-create\", \"withdrawal-accept\", \"withdrawal-reject\"] },\n\t\t...(opts?.sender && { sender: opts.sender }),\n\t\t...(opts?.requestId !== undefined && { request_id: opts.requestId }),\n\t});\n}\n",
+    "/**\n * Filter specs for `@secondlayer/sdk` subscriptions.\n *\n * Each `on.*` factory in this directory binds typed filter clauses to a\n * known table shape and returns a `SubscriptionFilterSpec`. Spread it into\n * a full subscription input alongside `name`, `url`, `format`, etc:\n *\n *   const spec = on.transferTo(\n *     { subgraph: \"my-watcher\", table: \"transfers\" },\n *     \"SP1ABC...\",\n *   );\n *   await sdk.subscriptions.create({\n *     ...spec,\n *     name: \"watch-incoming\",\n *     url: \"https://my-app.com/webhook\",\n *   });\n *\n * The user supplies which subgraph + table to bind against — these factories\n * don't assume Foundation Datasets are subscribable. To watch FT transfers\n * to an address, build a subgraph with a `transfers` table (see\n * `sl subgraphs create --template sip-010-balances`) and bind here.\n */\n\n/**\n * What every factory takes as its first arg: which user-owned subgraph table\n * to filter against.\n */\nexport type FactoryTarget = {\n\tsubgraph: string;\n\ttable: string;\n};\n\n/**\n * A primitive value that can appear in a filter clause.\n * Mirrors `SubscriptionFilterPrimitive` in\n * `@secondlayer/shared/schemas/subscriptions` — duplicated here to keep\n * `@secondlayer/stacks` from importing the api/server schema package.\n */\nexport type FilterPrimitive = string | number | boolean;\n\n/** Operator forms a filter clause can take. */\nexport type FilterOperator =\n\t| { eq: FilterPrimitive }\n\t| { neq: FilterPrimitive }\n\t| { gt: string | number }\n\t| { gte: string | number }\n\t| { lt: string | number }\n\t| { lte: string | number }\n\t| { in: FilterPrimitive[] };\n\n/** A single column's filter: bare value (eq) or operator object. */\nexport type FilterClause = FilterPrimitive | FilterOperator;\n\n/** Map of column → filter clause. Empty `{}` matches every row. */\nexport type Filter = Record<string, FilterClause>;\n\n/**\n * Output of every `on.*` factory. Use directly as a partial input to\n * `sdk.subscriptions.create` — the SDK's existing `CreateSubscriptionRequest`\n * already accepts these three fields.\n */\nexport type SubscriptionFilterSpec = {\n\tsubgraphName: string;\n\ttableName: string;\n\tfilter: Filter;\n};\n\n/** Thin helper to build a spec without restating the field-name mapping. */\nexport function makeSpec(\n\ttarget: FactoryTarget,\n\tfilter: Filter,\n): SubscriptionFilterSpec {\n\treturn {\n\t\tsubgraphName: target.subgraph,\n\t\ttableName: target.table,\n\t\tfilter,\n\t};\n}\n",
+    "import {\n\ttype FactoryTarget,\n\ttype SubscriptionFilterSpec,\n\tmakeSpec,\n} from \"./spec.ts\";\n\nexport type BnsAction =\n\t| \"new-name\"\n\t| \"transfer-name\"\n\t| \"renew-name\"\n\t| \"burn-name\"\n\t| \"new-airdrop\";\n\n/**\n * Match BNS-V2 name lifecycle events.\n *\n * Bind against a subgraph table that mirrors the `bns_name_events` shape\n * (topic, namespace, name, owner, ...). Easiest path: scaffold via\n * `sl subgraphs create --template bns-names`.\n *\n * @param action restrict to one topic; omit to fire on every name event\n */\nexport function bnsName(\n\ttarget: FactoryTarget,\n\taction?: BnsAction,\n\topts?: { namespace?: string; owner?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\t...(action && { topic: action }),\n\t\t...(opts?.namespace && { namespace: opts.namespace }),\n\t\t...(opts?.owner && { owner: opts.owner }),\n\t});\n}\n",
+    "import {\n\ttype FactoryTarget,\n\ttype SubscriptionFilterSpec,\n\tmakeSpec,\n} from \"./spec.ts\";\n\nexport type PoxFunction =\n\t| \"stack-stx\"\n\t| \"stack-extend\"\n\t| \"stack-increase\"\n\t| \"delegate-stx\"\n\t| \"revoke-delegate-stx\"\n\t| \"delegate-stack-stx\"\n\t| \"delegate-stack-extend\"\n\t| \"delegate-stack-increase\"\n\t| \"stack-aggregation-commit\"\n\t| \"stack-aggregation-commit-indexed\"\n\t| \"stack-aggregation-increase\"\n\t| \"set-signer-key-authorization\";\n\n/**\n * Match PoX-4 stacking calls. Bind against a subgraph table mirroring\n * `pox4_calls` (function_name, stacker, caller, ...). Scaffold via\n * `sl subgraphs create --template pox-stacking`.\n *\n * @param fn restrict to one PoX-4 function; omit to fire on every call\n */\nexport function poxStack(\n\ttarget: FactoryTarget,\n\tfn?: PoxFunction,\n\topts?: { stacker?: string; signerKey?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\t...(fn && { function_name: fn }),\n\t\t...(opts?.stacker && { stacker: opts.stacker }),\n\t\t...(opts?.signerKey && { signer_key: opts.signerKey }),\n\t});\n}\n",
+    "import {\n\ttype FactoryTarget,\n\ttype SubscriptionFilterSpec,\n\tmakeSpec,\n} from \"./spec.ts\";\n\n/**\n * Match sBTC deposit completion events. Bind against a subgraph table\n * mirroring `sbtc_events` (topic, amount, sender, bitcoin_txid, ...).\n * Scaffold via `sl subgraphs create --template sbtc-flows`.\n */\nexport function sbtcDeposit(\n\ttarget: FactoryTarget,\n\topts?: { sender?: string; bitcoinTxid?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\ttopic: \"completed-deposit\",\n\t\t...(opts?.sender && { sender: opts.sender }),\n\t\t...(opts?.bitcoinTxid && { bitcoin_txid: opts.bitcoinTxid }),\n\t});\n}\n\n/**\n * Match sBTC withdrawal lifecycle events. Phase defaults to all three\n * (`create` / `accept` / `reject`); pass an explicit `phase` to narrow.\n */\nexport function sbtcWithdrawal(\n\ttarget: FactoryTarget,\n\topts?: {\n\t\tphase?: \"create\" | \"accept\" | \"reject\";\n\t\tsender?: string;\n\t\trequestId?: number;\n\t},\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\ttopic: opts?.phase\n\t\t\t? { eq: `withdrawal-${opts.phase}` }\n\t\t\t: { in: [\"withdrawal-create\", \"withdrawal-accept\", \"withdrawal-reject\"] },\n\t\t...(opts?.sender && { sender: opts.sender }),\n\t\t...(opts?.requestId !== undefined && { request_id: opts.requestId }),\n\t});\n}\n",
     "import {\n\ttype FactoryTarget,\n\ttype SubscriptionFilterSpec,\n\tmakeSpec,\n} from \"./spec.ts\";\n\n/**\n * Match transfer events into a recipient address.\n *\n * Works against any subgraph table that has a `recipient` column (and\n * optionally `asset_identifier`). Templates that scaffold this shape:\n * `sip-010-balances`, `sbtc-flows`.\n *\n * @param target the user's subgraph + table to bind against\n * @param recipient stx principal that should receive the transfer\n * @param opts.asset optional asset identifier (e.g. `\"SP1...usdc::usdc-token\"`)\n *   to filter to a specific FT/NFT contract\n */\nexport function transferTo(\n\ttarget: FactoryTarget,\n\trecipient: string,\n\topts?: { asset?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\trecipient,\n\t\t...(opts?.asset && { asset_identifier: opts.asset }),\n\t});\n}\n\n/**\n * SIP-010 (fungible token) transfer sugar — alias for `transferTo` that\n * makes the asset filter intent explicit at the call site. Same backing\n * filter; the `asset` param is optional (omit to match every SIP-010\n * transfer in the bound table).\n */\nexport function sip010Transfer(\n\ttarget: FactoryTarget,\n\tasset?: string,\n\topts?: { recipient?: string },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\t...(asset && { asset_identifier: asset }),\n\t\t...(opts?.recipient && { recipient: opts.recipient }),\n\t});\n}\n\n/**\n * SIP-009 (non-fungible token) transfer sugar — same pattern as\n * `sip010Transfer`. Bind against an NFT-shaped table (see template\n * `nft-transfers` if/when published).\n */\nexport function sip009Transfer(\n\ttarget: FactoryTarget,\n\tasset?: string,\n\topts?: { recipient?: string; tokenId?: string | number },\n): SubscriptionFilterSpec {\n\treturn makeSpec(target, {\n\t\t...(asset && { asset_identifier: asset }),\n\t\t...(opts?.recipient && { recipient: opts.recipient }),\n\t\t...(opts?.tokenId !== undefined && { token_id: String(opts.tokenId) }),\n\t});\n}\n",
     "import { BaseError } from \"./base.ts\";\n\nexport class ContractCallError extends BaseError {\n\toverride name = \"ContractCallError\";\n}\n\nexport class ReadOnlyCallError extends BaseError {\n\toverride name = \"ReadOnlyCallError\";\n}\n"
   ],

package/dist/src/tools/index.cjs

@@ -1576,6 +1576,251 @@ class ContractResponseError extends Error {
     this.errorValue = errorValue;
   }
 }
+// src/clarity/abi/standards.ts
+var SIP010_ABI = {
+  functions: [
+    {
+      name: "transfer",
+      access: "public",
+      args: [
+        { name: "amount", type: "uint128" },
+        { name: "sender", type: "principal" },
+        { name: "recipient", type: "principal" },
+        { name: "memo", type: { optional: { buff: { length: 34 } } } }
+      ],
+      outputs: { response: { ok: "bool", error: "uint128" } }
+    },
+    {
+      name: "get-balance",
+      access: "read-only",
+      args: [{ name: "account", type: "principal" }],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-total-supply",
+      access: "read-only",
+      args: [],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-name",
+      access: "read-only",
+      args: [],
+      outputs: {
+        response: {
+          ok: { "string-ascii": { length: 32 } },
+          error: "uint128"
+        }
+      }
+    },
+    {
+      name: "get-symbol",
+      access: "read-only",
+      args: [],
+      outputs: {
+        response: {
+          ok: { "string-ascii": { length: 10 } },
+          error: "uint128"
+        }
+      }
+    },
+    {
+      name: "get-decimals",
+      access: "read-only",
+      args: [],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-token-uri",
+      access: "read-only",
+      args: [],
+      outputs: {
+        response: {
+          ok: { optional: { "string-utf8": { length: 256 } } },
+          error: "uint128"
+        }
+      }
+    }
+  ],
+  fungible_tokens: [{ name: "token" }]
+};
+var SIP009_ABI = {
+  functions: [
+    {
+      name: "transfer",
+      access: "public",
+      args: [
+        { name: "id", type: "uint128" },
+        { name: "sender", type: "principal" },
+        { name: "recipient", type: "principal" }
+      ],
+      outputs: { response: { ok: "bool", error: "uint128" } }
+    },
+    {
+      name: "get-owner",
+      access: "read-only",
+      args: [{ name: "id", type: "uint128" }],
+      outputs: {
+        response: { ok: { optional: "principal" }, error: "uint128" }
+      }
+    },
+    {
+      name: "get-last-token-id",
+      access: "read-only",
+      args: [],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-token-uri",
+      access: "read-only",
+      args: [{ name: "id", type: "uint128" }],
+      outputs: {
+        response: {
+          ok: { optional: { "string-utf8": { length: 256 } } },
+          error: "uint128"
+        }
+      }
+    }
+  ],
+  non_fungible_tokens: [{ name: "nft", type: "uint128" }]
+};
+var SIP013_ABI = {
+  functions: [
+    {
+      name: "transfer",
+      access: "public",
+      args: [
+        { name: "token-id", type: "uint128" },
+        { name: "amount", type: "uint128" },
+        { name: "sender", type: "principal" },
+        { name: "recipient", type: "principal" }
+      ],
+      outputs: { response: { ok: "bool", error: "uint128" } }
+    },
+    {
+      name: "transfer-memo",
+      access: "public",
+      args: [
+        { name: "token-id", type: "uint128" },
+        { name: "amount", type: "uint128" },
+        { name: "sender", type: "principal" },
+        { name: "recipient", type: "principal" },
+        { name: "memo", type: { buff: { length: 34 } } }
+      ],
+      outputs: { response: { ok: "bool", error: "uint128" } }
+    },
+    {
+      name: "transfer-many",
+      access: "public",
+      args: [
+        {
+          name: "transfers",
+          type: {
+            list: {
+              type: {
+                tuple: [
+                  { name: "token-id", type: "uint128" },
+                  { name: "amount", type: "uint128" },
+                  { name: "sender", type: "principal" },
+                  { name: "recipient", type: "principal" }
+                ]
+              },
+              length: 200
+            }
+          }
+        }
+      ],
+      outputs: { response: { ok: "bool", error: "uint128" } }
+    },
+    {
+      name: "transfer-many-memo",
+      access: "public",
+      args: [
+        {
+          name: "transfers",
+          type: {
+            list: {
+              type: {
+                tuple: [
+                  { name: "token-id", type: "uint128" },
+                  { name: "amount", type: "uint128" },
+                  { name: "sender", type: "principal" },
+                  { name: "recipient", type: "principal" },
+                  { name: "memo", type: { buff: { length: 34 } } }
+                ]
+              },
+              length: 200
+            }
+          }
+        }
+      ],
+      outputs: { response: { ok: "bool", error: "uint128" } }
+    },
+    {
+      name: "get-balance",
+      access: "read-only",
+      args: [
+        { name: "token-id", type: "uint128" },
+        { name: "account", type: "principal" }
+      ],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-overall-balance",
+      access: "read-only",
+      args: [{ name: "account", type: "principal" }],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-total-supply",
+      access: "read-only",
+      args: [{ name: "token-id", type: "uint128" }],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-overall-supply",
+      access: "read-only",
+      args: [],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-decimals",
+      access: "read-only",
+      args: [{ name: "token-id", type: "uint128" }],
+      outputs: { response: { ok: "uint128", error: "uint128" } }
+    },
+    {
+      name: "get-token-uri",
+      access: "read-only",
+      args: [{ name: "token-id", type: "uint128" }],
+      outputs: {
+        response: {
+          ok: { optional: { "string-utf8": { length: 256 } } },
+          error: "uint128"
+        }
+      }
+    }
+  ],
+  fungible_tokens: [],
+  non_fungible_tokens: []
+};
+// src/clarity/abi/classify.ts
+var STANDARDS = [
+  { id: "sip-010", abi: SIP010_ABI, optional: new Set(["get-token-uri"]) },
+  { id: "sip-009", abi: SIP009_ABI, optional: new Set(["get-token-uri"]) },
+  {
+    id: "sip-013",
+    abi: SIP013_ABI,
+    optional: new Set([
+      "transfer-memo",
+      "transfer-many",
+      "transfer-many-memo",
+      "get-token-uri",
+      "get-overall-balance",
+      "get-overall-supply"
+    ])
+  }
+];
 // src/bns/abi.ts
 var BNS_ABI = {
   functions: [
@@ -2465,5 +2710,5 @@ var getNftHoldings = import_ai.tool({
   execute: ({ principal, limit }) => nftHoldings(getDefaultPublicClient(), principal, limit)
 });
 
-//# debugId=5BBF31DE9C4100A864756E2164756E21
+//# debugId=2C93FD5D1703F35064756E2164756E21
 //# sourceMappingURL=index.cjs.map