Release v0.23.1

Origin-SHA: dcc65325316bd4ab952c7a77f2bbd0abb3ab1b08

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/tool-sdk
 
+## 0.23.1
+
+### Patch Changes
+
+- cbc654a: `--tool-ref` and the usage reporters now support non-address registries such as `x402:bazaar` and `x402:bankr` for tools that are not registered onchain. The `--tool-ref` field delimiter is a comma (`chainId,registryAddress,onchainId`) so a registry identifier that itself contains a colon stays unambiguous; `parseToolRef` requires exactly three comma-separated fields. `toolRegistryAddress` is widened from `0x${string}` to `string`, and `toolOnchainId` is kept as a string to preserve precision for IDs exceeding `Number.MAX_SAFE_INTEGER`.
+
 ## 0.23.0
 
 ### Minor Changes

README.md

@@ -172,14 +172,20 @@ npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
 | `--max-amount <baseUnits>` | Reject challenges charging more than this (token base units). Pass `unlimited` to disable |
 | `--no-report-usage` | Disable the caller-side usage report sent to OpenSea after a successful payment |
 | `--api-key <key>` | API key for usage reporting (falls back to `OPENSEA_API_KEY`, then an auto-provisioned instant key) |
-| `--tool-ref <ref>` | ERC-8257 tool coordinates as `chainId:registryAddress:onchainId` (e.g. `8453:0x265b...2cf1:65`). Disambiguates usage reporting when multiple tools share one endpoint |
+| `--tool-ref <ref>` | Tool coordinates as `chainId,registryAddress,onchainId` (e.g. `8453,0x265b...2cf1,65`, or `8453,x402:bazaar,123` for x402 registries). Disambiguates usage reporting when multiple tools share one endpoint |
 
-When an endpoint URL maps to more than one registered tool, an endpoint-only usage report is rejected with `400 Multiple tools registered for endpoint`. Pass `--tool-ref` so the report identifies the exact tool by its onchain composite key:
+When an endpoint URL maps to more than one registered tool, an endpoint-only usage report is rejected with `400 Multiple tools registered for endpoint`. Pass `--tool-ref` so the report identifies the exact tool by its composite key. The fields are comma-separated so a registry identifier that contains a colon (such as the `x402:bazaar` / `x402:bankr` registries used for tools that are not registered onchain) stays unambiguous:
 
 ```bash
+# Onchain (ERC-8257) registry:
 npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
   --body '{"query":"hello"}' \
-  --tool-ref 8453:0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1:65
+  --tool-ref 8453,0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1,65
+
+# x402 registry (not registered onchain):
+npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
+  --body '{"query":"hello"}' \
+  --tool-ref 8453,x402:bazaar,8679018179619845322
 ```
 
 ### `auth <url>`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {

src/__tests__/caller-reporter.test.ts

@@ -103,8 +103,7 @@ describe("reportCallerX402Usage", () => {
     const result = await reportCallerX402Usage(
       makeX402Event({
         toolChainId: 8453,
-        toolRegistryAddress:
-          "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1" as `0x${string}`,
+        toolRegistryAddress: "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1",
         toolOnchainId: 65,
       }),
       makeConfig(),
@@ -126,6 +125,24 @@ describe("reportCallerX402Usage", () => {
     })
   })
 
+  it("sends x402:bazaar registry and string onchainId in the composite key", async () => {
+    const result = await reportCallerX402Usage(
+      makeX402Event({
+        toolChainId: 8453,
+        toolRegistryAddress: "x402:bazaar",
+        toolOnchainId: "8679018179619845322",
+      }),
+      makeConfig(),
+    )
+    expect(result.outcome).toBe("reported")
+
+    const body = JSON.parse(fetchSpy.mock.calls[0]![1].body)
+    expect(body.tool_chain_id).toBe(8453)
+    expect(body.tool_registry_address).toBe("x402:bazaar")
+    expect(body.tool_onchain_id).toBe("8679018179619845322")
+    expect(body.tool_endpoint).toBeUndefined()
+  })
+
   it("skips the report when only partial composite coordinates are given", async () => {
     const result = await reportCallerX402Usage(
       // chainId without registry/onchainId — must be all-or-nothing.
@@ -137,11 +154,11 @@ describe("reportCallerX402Usage", () => {
     expect(fetchSpy).not.toHaveBeenCalled()
   })
 
-  it("skips the report when the composite registry address is invalid", async () => {
+  it("skips the report when the composite registry address is empty", async () => {
     const result = await reportCallerX402Usage(
       makeX402Event({
         toolChainId: 8453,
-        toolRegistryAddress: "not-an-address" as `0x${string}`,
+        toolRegistryAddress: "",
         toolOnchainId: 65,
       }),
       makeConfig(),

src/__tests__/eip3009-reporter.test.ts

@@ -10,8 +10,7 @@ const CALLER_ADDRESS =
   "0xabcdefabcdef1234567890abcdefabcdef12345678" as `0x${string}`
 const PAYER_ADDRESS =
   "0x1234561234561234561234561234561234561234" as `0x${string}`
-const REGISTRY_ADDRESS =
-  "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1" as `0x${string}`
+const REGISTRY_ADDRESS = "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1"
 
 function makeConfig(
   overrides: Partial<Parameters<typeof createEip3009UsageReporter>[0]> = {},
@@ -312,12 +311,21 @@ describe("createEip3009UsageReporter", () => {
     expect(() => createEip3009UsageReporter(makeConfig())).not.toThrow()
   })
 
-  it("throws for invalid toolRegistryAddress", () => {
+  it("throws for empty toolRegistryAddress", () => {
+    expect(() =>
+      createEip3009UsageReporter(makeConfig({ toolRegistryAddress: "" })),
+    ).toThrow("toolRegistryAddress must not be empty")
+  })
+
+  it("accepts x402:bankr registry and string onchainId", () => {
     expect(() =>
       createEip3009UsageReporter(
-        makeConfig({ toolRegistryAddress: "0xinvalid" as `0x${string}` }),
+        makeConfig({
+          toolRegistryAddress: "x402:bankr",
+          toolOnchainId: "5311379622895099236",
+        }),
       ),
-    ).toThrow("invalid toolRegistryAddress")
+    ).not.toThrow()
   })
 
   it("throws for negative toolOnchainId", () => {

src/__tests__/pay.test.ts

@@ -23,33 +23,63 @@ afterEach(() => {
 describe("parseToolRef", () => {
   const REGISTRY = "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1"
 
-  it("parses chainId:registryAddress:onchainId", async () => {
+  it("parses chainId,registryAddress,onchainId for onchain tools", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
-    expect(parseToolRef(`8453:${REGISTRY}:65`)).toEqual({
+    expect(parseToolRef(`8453,${REGISTRY},65`)).toEqual({
       toolChainId: 8453,
       toolRegistryAddress: REGISTRY,
-      toolOnchainId: 65,
+      toolOnchainId: "65",
     })
   })
 
+  it("parses an x402:bazaar registry whose name contains a colon", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(parseToolRef("8453,x402:bazaar,8679018179619845322")).toEqual({
+      toolChainId: 8453,
+      toolRegistryAddress: "x402:bazaar",
+      toolOnchainId: "8679018179619845322",
+    })
+  })
+
+  it("parses an x402:bankr registry", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(parseToolRef("8453,x402:bankr,5311379622895099236")).toEqual({
+      toolChainId: 8453,
+      toolRegistryAddress: "x402:bankr",
+      toolOnchainId: "5311379622895099236",
+    })
+  })
+
+  it("preserves an onchain id beyond Number.MAX_SAFE_INTEGER as a string", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    const big = "9007199254740993" // 2^53 + 1, not representable as a JS number
+    expect(parseToolRef(`8453,x402:bazaar,${big}`).toolOnchainId).toBe(big)
+  })
+
   it("accepts onchain id 0", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
-    expect(parseToolRef(`8453:${REGISTRY}:0`).toolOnchainId).toBe(0)
+    expect(parseToolRef(`8453,${REGISTRY},0`).toolOnchainId).toBe("0")
   })
 
-  it("throws when the ref does not have exactly three parts", async () => {
+  it("throws when the ref does not have exactly three comma fields", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
-    expect(() => parseToolRef(`8453:${REGISTRY}`)).toThrow(/tool-ref/)
+    expect(() => parseToolRef(`8453,${REGISTRY}`)).toThrow(/tool-ref/)
+    expect(() => parseToolRef(`8453,${REGISTRY},65,extra`)).toThrow(/tool-ref/)
   })
 
   it("throws on a non-numeric chain id", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
-    expect(() => parseToolRef(`base:${REGISTRY}:65`)).toThrow(/chain/i)
+    expect(() => parseToolRef(`base,${REGISTRY},65`)).toThrow(/chain/i)
+  })
+
+  it("throws on an empty registry", async () => {
+    const { parseToolRef } = await import("../cli/commands/pay.js")
+    expect(() => parseToolRef("8453,,65")).toThrow(/registry/i)
   })
 
-  it("throws on an invalid registry address", async () => {
+  it("throws on a non-numeric onchain id", async () => {
     const { parseToolRef } = await import("../cli/commands/pay.js")
-    expect(() => parseToolRef("8453:not-an-address:65")).toThrow(/registry/i)
+    expect(() => parseToolRef(`8453,${REGISTRY},abc`)).toThrow(/onchain/i)
   })
 })
 

src/__tests__/x402-reporter.test.ts

@@ -5,8 +5,7 @@ import {
   type X402UsageReporterConfig,
 } from "../lib/usage/x402-reporter.js"
 
-const REGISTRY_ADDRESS =
-  "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1" as `0x${string}`
+const REGISTRY_ADDRESS = "0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1"
 const CALLER_ADDRESS =
   "0xabcdefabcdef1234567890abcdefabcdef123456" as `0x${string}`
 
@@ -123,13 +122,26 @@ describe("createX402UsageReporter", () => {
     expect(consoleSpy).not.toHaveBeenCalled()
   })
 
+  it("accepts x402:bazaar registry and string onchainId", async () => {
+    const report = createX402UsageReporter(
+      makeConfig({
+        toolRegistryAddress: "x402:bazaar",
+        toolOnchainId: "8679018179619845322",
+      }),
+    )
+    await report(makeEvent())
+
+    expect(fetchSpy).toHaveBeenCalledOnce()
+    const body = JSON.parse(fetchSpy.mock.calls[0]![1].body)
+    expect(body.tool_registry_address).toBe("x402:bazaar")
+    expect(body.tool_onchain_id).toBe("8679018179619845322")
+  })
+
   // Validation tests
-  it("throws for invalid toolRegistryAddress", () => {
+  it("throws for empty toolRegistryAddress", () => {
     expect(() =>
-      createX402UsageReporter(
-        makeConfig({ toolRegistryAddress: "0xinvalid" as `0x${string}` }),
-      ),
-    ).toThrow("invalid toolRegistryAddress")
+      createX402UsageReporter(makeConfig({ toolRegistryAddress: "" })),
+    ).toThrow("toolRegistryAddress must not be empty")
   })
 
   it("throws for negative toolOnchainId", () => {

src/cli/commands/pay.ts

@@ -1,6 +1,5 @@
 import { Command } from "commander"
 import pc from "picocolors"
-import { isAddress } from "viem"
 import {
   parseX402Challenge,
   resolveNetwork,
@@ -34,45 +33,56 @@ interface PayOptions {
   toolRef?: string
 }
 
-/** ERC-8257 composite key identifying a tool onchain. */
+/** Composite key identifying a tool (ERC-8257 onchain or x402 registry). */
 export interface ToolRef {
   toolChainId: number
-  toolRegistryAddress: `0x${string}`
-  toolOnchainId: number
+  toolRegistryAddress: string
+  toolOnchainId: string
 }
 
 /**
- * Parse a `--tool-ref` value of the form `chainId:registryAddress:onchainId`
- * (e.g. `8453:0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1:65`) into an ERC-8257
- * composite key. The registry address contains no colons and both IDs are
- * numeric, so a 3-way split is unambiguous. Throws on a malformed ref.
+ * Parse a `--tool-ref` value of the form `chainId,registryAddress,onchainId`
+ * (comma-separated, exactly three fields).
+ *
+ * A comma delimiter keeps the registry identifier unambiguous even when it
+ * contains a colon, as the x402 registries do (`x402:bazaar`, `x402:bankr`).
+ *
+ * Examples:
+ *   `8453,0x265bb2dbfc0a8165c9a1941eb1372f349bad2cf1,65`  → onchain ERC-8257
+ *   `8453,x402:bazaar,8679018179619845322`                → x402 bazaar tool
+ *   `8453,x402:bankr,5311379622895099236`                 → x402 bankr tool
+ *
+ * The onchainId is kept as a string to preserve precision for IDs that
+ * exceed `Number.MAX_SAFE_INTEGER`.
  */
 export function parseToolRef(ref: string): ToolRef {
-  const parts = ref.split(":")
+  const parts = ref.split(",")
   if (parts.length !== 3) {
     throw new Error(
-      `Invalid --tool-ref "${ref}": expected chainId:registryAddress:onchainId`,
+      `Invalid --tool-ref "${ref}": expected chainId,registryAddress,onchainId`,
     )
   }
-  const [chainStr, registry, onchainStr] = parts
+  const [chainStr = "", registry = "", onchainStr = ""] = parts
+
   const toolChainId = Number(chainStr)
   if (!Number.isInteger(toolChainId) || toolChainId <= 0) {
     throw new Error(
       `Invalid --tool-ref chain id "${chainStr}": expected a positive integer`,
     )
   }
-  if (!isAddress(registry)) {
-    throw new Error(
-      `Invalid --tool-ref registry address "${registry}": expected a 0x address`,
-    )
+  if (!registry) {
+    throw new Error(`Invalid --tool-ref registry: must not be empty`)
   }
-  const toolOnchainId = Number(onchainStr)
-  if (!Number.isInteger(toolOnchainId) || toolOnchainId < 0) {
+  if (!/^\d+$/.test(onchainStr)) {
     throw new Error(
       `Invalid --tool-ref onchain id "${onchainStr}": expected a non-negative integer`,
     )
   }
-  return { toolChainId, toolRegistryAddress: registry, toolOnchainId }
+  return {
+    toolChainId,
+    toolRegistryAddress: registry,
+    toolOnchainId: onchainStr,
+  }
 }
 
 /** HTTP verbs that carry no request body — inputs go in the query string. */
@@ -111,7 +121,7 @@ export const payCommand = new Command("pay")
   )
   .option(
     "--tool-ref <ref>",
-    "ERC-8257 tool coordinates as chainId:registryAddress:onchainId (e.g. 8453:0x265b...2cf1:65). Disambiguates usage reporting when multiple tools share one endpoint.",
+    "Tool coordinates as chainId,registryAddress,onchainId (e.g. 8453,0x265b...2cf1,65 or 8453,x402:bazaar,123). Disambiguates usage reporting when multiple tools share one endpoint.",
   )
   .action(async (url: string, options: PayOptions) => {
     // The x402 X-Payment signature is a gasless EIP-3009 authorization — it is

src/lib/usage/caller-reporter.ts

@@ -1,5 +1,7 @@
 import { isAddress } from "viem"
 
+const NUMERIC_STRING_RE = /^\d+$/
+
 /**
  * Configuration for caller-side usage reporting. Unlike the server-side
  * reporters, this identifies the tool by its canonical endpoint URL — the
@@ -64,8 +66,8 @@ export interface CallerX402UsageEvent {
    * server-side reporter's payload.
    */
   toolChainId?: number
-  toolRegistryAddress?: `0x${string}`
-  toolOnchainId?: number
+  toolRegistryAddress?: string
+  toolOnchainId?: number | string
 }
 
 export interface CallerEip3009UsageEvent {
@@ -127,15 +129,23 @@ function buildToolIdentity(
       detail: "invalid toolChainId",
     }
   }
-  if (!isAddress(event.toolRegistryAddress)) {
+  if (!event.toolRegistryAddress) {
     return {
-      error: `invalid toolRegistryAddress: ${event.toolRegistryAddress}`,
+      error: "toolRegistryAddress must not be empty",
       detail: "invalid toolRegistryAddress",
     }
   }
-  if (!Number.isInteger(event.toolOnchainId) || event.toolOnchainId < 0) {
+  const onchainId = event.toolOnchainId
+  if (typeof onchainId === "number") {
+    if (!Number.isInteger(onchainId) || onchainId < 0) {
+      return {
+        error: `toolOnchainId must be a non-negative integer, got: ${onchainId}`,
+        detail: "invalid toolOnchainId",
+      }
+    }
+  } else if (!NUMERIC_STRING_RE.test(onchainId)) {
     return {
-      error: `toolOnchainId must be a non-negative integer, got: ${event.toolOnchainId}`,
+      error: `toolOnchainId must be a non-negative integer, got: ${onchainId}`,
       detail: "invalid toolOnchainId",
     }
   }