Release v0.28.0

Origin-SHA: bc74e084cd87ab22021450b305a106763c153794

Co-authored-by: Ryan Ghods <ryan@ryanio.com>

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,17 @@
 # @opensea/tool-sdk
 
+## 0.28.0
+
+### Minor Changes
+
+- f1db520: Add Robinhood Chain (4663) support: `--network robinhood` on all CLI commands (custom viem chain definition until viem ships one), 4663 added to every canonical `Deployment.chains` array in `chains.ts`, and skill/docs chain enumerations updated.
+
+### Patch Changes
+
+- ac4ac6f: tool-registry: add an explicit Etherscan v2 `url` to the `monad` entry in `foundry.toml`. Forge's built-in chain list doesn't know chain 143, so config resolution failed during `forge script --verify` and aborted verification for every chain in the run (including Robinhood).
+- 10dcac1: Fix x402 CAIP-2 network handling asymmetry. The server-side predicate gates now accept CAIP-2 (`eip155:8453`) and numeric (`8453`) network identifiers in the `X-Payment` payload — previously they only accepted the short names (`base`, `base-sepolia`) and rejected anything else as an "unsupported network", even though the client already tolerated CAIP-2 forms. Additionally, the client now normalizes the `network` field in v1 payment payloads to the canonical short name so that v1 gates (which key off short names) don't reject a verbatim CAIP-2 echo.
+- 6649847: Fix x402 usage reporting when the facilitator returns a CAIP-2/numeric network. The predicate gate's `settle()` now resolves the settlement network via `resolveNetwork`, so `settlementChainId` (used by the usage-reporting REST endpoint) is populated for `eip155:8453` / `8453` responses, not just the short name `base`.
+
 ## 0.27.0
 
 ### Minor Changes

biome.json

@@ -1,20 +1,20 @@
 {
   "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
   "files": {
     "includes": [
       "**/*.ts",
       "**/*.js",
       "**/*.json",
-      "!**/node_modules",
-      "!**/dist",
-      "!**/lib",
-      "!**/coverage",
-      "!**/.nyc_output",
-      "!packages/sdk/src/typechain",
+      "!**/.claude",
       "!**/typechain",
-      "!packages/api-types/src/generated.ts",
-      "!**/pnpm-lock.yaml",
-      "!**/package-lock.json"
+      "!**/package-lock.json",
+      "!**/src/generated.ts",
+      "!**/src/*-generated.ts"
     ]
   },
   "formatter": {
@@ -35,7 +35,7 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true,
+      "preset": "recommended",
       "suspicious": {
         "noConsole": "off",
         "noExplicitAny": "off"

docs/predicate-gating-guide.md

@@ -27,7 +27,7 @@ Use predicate gating when access should be tied to **who the caller is**. Use x4
 
 Tool creators configure the predicate onchain (via `register --access-predicate` or direct contract calls). The `predicateGate` middleware picks it up at runtime — no code changes needed when the access policy changes.
 
-The canonical `ERC721OwnerPredicate` (v0.2) is deployed on Ethereum mainnet, Base, Shape, Abstract, and Monad at `0xc8721c9A776958FfFfEb602DA1b708bf1D318379` (see `src/lib/onchain/chains.ts`).
+The canonical `ERC721OwnerPredicate` (v0.2) is deployed on Ethereum mainnet, Base, Shape, Abstract, Monad, and Robinhood Chain at `0xc8721c9A776958FfFfEb602DA1b708bf1D318379` (see `src/lib/onchain/chains.ts`).
 
 ## Prerequisites
 
@@ -129,7 +129,7 @@ PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org npx @opensea/tool-sdk registe
   --dry-run
 ```
 
-For ERC-721 gating, use the canonical v0.2 `ERC721OwnerPredicate` at `0xc8721c9A776958FfFfEb602DA1b708bf1D318379` (Ethereum mainnet, Base, Shape, Abstract, Monad). After registration, call `setCollections(toolId, [collectionAddress])` on the predicate to configure which collections gate the tool.
+For ERC-721 gating, use the canonical v0.2 `ERC721OwnerPredicate` at `0xc8721c9A776958FfFfEb602DA1b708bf1D318379` (Ethereum mainnet, Base, Shape, Abstract, Monad, Robinhood Chain). After registration, call `setCollections(toolId, [collectionAddress])` on the predicate to configure which collections gate the tool.
 
 ## Step 3: Verify the setup
 

examples/nft-appraisal-tool/scripts/read-tool-registration.ts

@@ -63,7 +63,6 @@ try {
   const res = await fetch(config.metadataURI)
   if (!res.ok) throw new Error(`fetch returned ${res.status}`)
   liveManifest = await res.json()
-  // biome-ignore lint/suspicious/noExplicitAny: SDK validates shape internally
   const liveHash = computeManifestHash(liveManifest as any)
   checks.push([
     "manifestHash matches live manifest hash",

examples/wallet-personality-tool/src/opensea.ts

@@ -286,7 +286,7 @@ function ethValueFromPayment(payment?: {
   decimals?: number
   quantity?: string
 }): { ethValue?: number; symbol?: string } {
-  if (!payment || !payment.quantity) return {}
+  if (!payment?.quantity) return {}
   const decimals = payment.decimals ?? 18
   const symbol = payment.symbol ?? "ETH"
   // Only treat ETH/WETH as eth-equivalent. Stable-priced sales (USDC etc.)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {
@@ -32,10 +32,10 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
-    "lint": "biome check --config-path . .",
-    "lint:fix": "biome check --config-path . --write .",
-    "format": "biome format --config-path . --write .",
-    "format:check": "biome format --config-path . .",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
@@ -55,7 +55,7 @@
     "tsup": "8.5.1",
     "typescript": "6.0.2",
     "vitest": "3.2.4",
-    "@biomejs/biome": "^2.4.10"
+    "@biomejs/biome": "^2.5.2"
   },
   "engines": {
     "node": ">=18.0.0"

skill/SKILL.md

@@ -67,7 +67,7 @@ This SDK is for tool *providers and consumers*. To query OpenSea marketplace dat
 
 If you need your API on a subdomain, serve the manifest from that same subdomain (e.g., both on `api.example.com`).
 
-## Deployed Contracts (Ethereum mainnet, Base, Shape, Abstract, Monad)
+## Deployed Contracts (Ethereum mainnet, Base, Shape, Abstract, Monad, Robinhood Chain)
 
 Canonical v0.2 deployments — identical CREATE2 address on every supported chain.
 

skill/references/known-predicates.md

@@ -1,6 +1,6 @@
 # Known Predicates
 
-These predicates are deployed on Ethereum mainnet, Base, Shape, Abstract, and Monad and available for any tool to use. They are multi-tenant: one deployment serves all tools, configured per `toolId`.
+These predicates are deployed on Ethereum mainnet, Base, Shape, Abstract, Monad, and Robinhood Chain and available for any tool to use. They are multi-tenant: one deployment serves all tools, configured per `toolId`.
 
 ## ERC721OwnerPredicate
 
@@ -283,7 +283,7 @@ if (decoded.type === "erc7496Trait") {
 
 ## ERC20BalancePredicate
 
-Gates access based on holding a configurable minimum balance of an ERC-20 token. Multi-tenant: one deployment per chain, configured per `toolId`. Canonical deployment: `0x1a834FC48B5f6e119c62C12a98b32137bCFA77cD` (Ethereum mainnet, Base, Shape, Abstract, Monad). The CLI commands default to this address; pass `--predicate-address` only to override it.
+Gates access based on holding a configurable minimum balance of an ERC-20 token. Multi-tenant: one deployment per chain, configured per `toolId`. Canonical deployment: `0x1a834FC48B5f6e119c62C12a98b32137bCFA77cD` (Ethereum mainnet, Base, Shape, Abstract, Monad, Robinhood Chain). The CLI commands default to this address; pass `--predicate-address` only to override it.
 
 | Field | Value |
 |-------|-------|

src/__tests__/get-chain.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest"
+import { defaultRpcUrl, getChain } from "../cli/commands/get-chain.js"
+
+describe("getChain", () => {
+  it.each([
+    ["mainnet", 1],
+    ["base", 8453],
+    ["base-sepolia", 84532],
+    ["shape", 360],
+    ["abstract", 2741],
+    ["monad", 143],
+    ["robinhood", 4663],
+  ])("returns the %s chain with id %i", (network, chainId) => {
+    expect(getChain(network).id).toBe(chainId)
+  })
+
+  it("throws on an unsupported network", () => {
+    expect(() => getChain("dogechain")).toThrow(
+      "Unsupported network: dogechain",
+    )
+  })
+
+  it("defines robinhood with an RPC URL, explorer, and multicall3", () => {
+    const chain = getChain("robinhood")
+    expect(defaultRpcUrl(chain)).toBe("https://rpc.mainnet.chain.robinhood.com")
+    expect(chain.blockExplorers?.default.url).toBe(
+      "https://robinhoodchain.blockscout.com",
+    )
+    expect(chain.contracts?.multicall3?.address).toBe(
+      "0xcA11bde05977b3631167028862bE2a173976CA11",
+    )
+  })
+})

src/__tests__/paid-predicate-gate.test.ts

@@ -20,7 +20,6 @@ vi.mock("../lib/onchain/registry.js", () => ({
   ToolRegistryClient: class {
     tryHasAccess = mockTryHasAccess
     getToolConfig = mockGetToolConfig
-    constructor() {}
   },
 }))
 
@@ -93,13 +92,13 @@ function mockFacilitatorVerifySuccess() {
   )
 }
 
-function mockFacilitatorSettleSuccess() {
+function mockFacilitatorSettleSuccess(network = "base") {
   mockFetch.mockResolvedValueOnce(
     new Response(
       JSON.stringify({
         success: true,
         transaction: "0xtxhash123",
-        network: "base",
+        network,
       }),
       { status: 200 },
     ),
@@ -292,6 +291,34 @@ describe("paidPredicateGate", () => {
     expect(settleCall[0]).toContain("/settle")
   })
 
+  it("resolves settlementChainId from a CAIP-2 facilitator network", async () => {
+    const { paidPredicateGate } = await import(
+      "../lib/middleware/predicate-gate.js"
+    )
+    mockFacilitatorVerifySuccess()
+    const gate = paidPredicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+      amountUsdc: "1.00",
+    })
+    const ctx: Partial<ToolContext> = { gates: {} }
+    const request = new Request("https://example.com/api", {
+      method: "POST",
+      headers: { "X-Payment": makeXPaymentHeader() },
+    })
+
+    const response = await gate.check(request, ctx)
+    expect(response).toBeNull()
+
+    // Facilitator reports the CAIP-2 network form; the usage-reporting
+    // chain id must still resolve so downstream reporters get a numeric id.
+    mockFacilitatorSettleSuccess("eip155:8453")
+    await gate.settle!(ctx as ToolContext)
+
+    expect(ctx.gates?.x402?.settlementTxHash).toBe("0xtxhash123")
+    expect(ctx.gates?.x402?.settlementChainId).toBe(8453)
+  })
+
   it("returns 502 when registry call fails", async () => {
     const { paidPredicateGate } = await import(
       "../lib/middleware/predicate-gate.js"