Release v0.28.3

Origin-SHA: 1d4b5b0b49c51d8b9d9f741d6643c99bff566f22

Co-authored-by: Cody <132297275+CodySearsOS@users.noreply.github.com>

Author: BCLeFevre

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/tool-sdk
 
+## 0.28.3
+
+### Patch Changes
+
+- Scope predicate gate reads to the configured registry chain. `predicateGate`/`paidPredicateGate` no longer force reads to the Base RPC when `rpcUrl` is unset, so a non-Base registry chain is actually queried, and the x402 identity/payment chain is decoupled from the registry chain so non-Base gating no longer fails closed.
+
 ## 0.28.2
 
 ### Patch Changes

package.json

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

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

@@ -260,6 +260,35 @@ describe("paidPredicateGate", () => {
     expect(mockFetch).not.toHaveBeenCalled()
   })
 
+  it("verifies a Base payment against a non-Base registry chain", async () => {
+    const { mainnet } = await import("viem/chains")
+    const { paidPredicateGate } = await import(
+      "../lib/middleware/predicate-gate.js"
+    )
+    mockFacilitatorVerifySuccess()
+    // Registry on Ethereum mainnet, payment on Base USDC. Identity must pin to
+    // the x402 payment network (base), not the registry chain, otherwise every
+    // caller fails closed with a network mismatch.
+    const gate = paidPredicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+      amountUsdc: "1.00",
+      chain: mainnet,
+      network: "base",
+    })
+    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()
+    expect(ctx.callerAddress).toBe(TEST_CALLER)
+    expect(ctx.gates?.x402).toEqual({ paid: true, payer: TEST_CALLER })
+  })
+
   it("fails closed with 500 when operatorAddress is unset", async () => {
     const { paidPredicateGate } = await import(
       "../lib/middleware/predicate-gate.js"

src/__tests__/predicate-gate.test.ts

@@ -696,6 +696,53 @@ describe("predicateGate", () => {
     expect(ctx.callerAddress).toBeUndefined()
   })
 
+  it("verifies a Base-signed identity against a non-Base registry chain", async () => {
+    mockTryHasAccess.mockResolvedValueOnce({ ok: true, granted: true })
+    const { mainnet } = await import("viem/chains")
+    const { predicateGate } = await import(
+      "../lib/middleware/predicate-gate.js"
+    )
+    // Registry on Ethereum mainnet, identity proof on Base USDC. The identity
+    // chain must not be pinned to the registry chain, or every caller fails
+    // closed and operators fall back to the leaky Base default.
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+      chain: mainnet,
+    })
+    const ctx: Partial<ToolContext> = { gates: {} }
+
+    const response = await gate.check(makeAuthorizedRequest(), ctx)
+
+    expect(response).toBeNull()
+    expect(ctx.callerAddress).toBe(TEST_CALLER)
+    // Reads follow the configured chain (undefined rpcUrl → viem chain default),
+    // not a hardcoded Base RPC.
+    expect(mockConstructorArgs).toHaveBeenCalledWith(
+      expect.objectContaining({ chain: mainnet, rpcUrl: undefined }),
+    )
+  })
+
+  it("advertises network=base in the 402 challenge for a non-Base registry chain", async () => {
+    const { mainnet } = await import("viem/chains")
+    const { predicateGate } = await import(
+      "../lib/middleware/predicate-gate.js"
+    )
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+      chain: mainnet,
+    })
+    const request = new Request("https://example.com/api", { method: "POST" })
+    const ctx: Partial<ToolContext> = { gates: {} }
+
+    const response = await gate.check(request, ctx)
+
+    expect(response?.status).toBe(402)
+    const body = await response?.json()
+    expect(body.accepts[0].network).toBe("base")
+  })
+
   it("X-Payment: fails closed with 500 when operatorAddress is unset", async () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"

src/lib/middleware/predicate-gate.ts

@@ -98,7 +98,10 @@ export interface PredicateGateConfig {
  */
 export function predicateGate(config: PredicateGateConfig): GateMiddleware {
   const chain = config.chain ?? base
-  const rpcUrl = config.rpcUrl ?? "https://mainnet.base.org"
+  // Leave rpcUrl undefined when unset so reads follow the configured chain's
+  // default RPC (viem), instead of silently reading Base for a non-Base chain.
+  const rpcUrl = config.rpcUrl
+  const identityChainId = x402IdentityChainId(chain.id)
 
   const publicClient = createPublicClient({
     chain,
@@ -148,12 +151,15 @@ export function predicateGate(config: PredicateGateConfig): GateMiddleware {
       const paymentHeader = request.headers.get("X-Payment")
 
       if (!paymentHeader) {
-        return buildPredicateChallengeResponse(config.operatorAddress, chain.id)
+        return buildPredicateChallengeResponse(
+          config.operatorAddress,
+          identityChainId,
+        )
       }
 
       const result = await verifyXPaymentAuth(paymentHeader, {
         operatorAddress: config.operatorAddress,
-        expectedChainId: chain.id,
+        expectedChainId: identityChainId,
         requireZeroValue: true,
       })
       if (result.error) {
@@ -316,9 +322,10 @@ interface VerifyXPaymentOptions {
    */
   operatorAddress: `0x${string}`
   /**
-   * Chain id the gate is configured for. The resolved chainId of the
-   * client-declared `network` must match, so an authorization signed for a
-   * different chain (e.g. base-sepolia) cannot authenticate to this gate.
+   * ChainId of the x402 payment network the identity proof must be signed for
+   * (Base / Base-Sepolia), independent of the registry chain. The resolved
+   * chainId of the client-declared `network` must match, so an authorization
+   * signed for a different chain (e.g. base-sepolia) cannot authenticate here.
    */
   expectedChainId: number
   /**
@@ -436,10 +443,10 @@ async function verifyXPaymentAuth(
   const chainId = resolved.chainId
   const tokenAddress = resolved.usdc as `0x${string}`
 
-  // Pin the authorization to the gate's configured chain. The EIP-712 domain
-  // used for signature recovery comes from the client-declared network, so
-  // without this an authorization signed for a different chain (e.g.
-  // base-sepolia) would authenticate to a mainnet gate.
+  // Pin the authorization to the gate's x402 payment network. The EIP-712
+  // domain used for signature recovery comes from the client-declared network,
+  // so without this an authorization signed for a different chain (e.g.
+  // base-sepolia) would authenticate to a mainnet-payment gate.
   if (chainId !== options.expectedChainId) {
     return {
       error: `Predicate gate: X-Payment network mismatch (expected chainId ${options.expectedChainId}, got ${chainId})`,
@@ -535,6 +542,25 @@ const CHAIN_ID_TO_NETWORK: Record<number, string> = {
   84532: "base-sepolia",
 }
 
+const BASE_CHAIN_ID = 8453
+
+/**
+ * The chainId the x402 identity/payment authorization must be signed for.
+ *
+ * The X-Payment proof is an EIP-3009 USDC authorization that only exists on
+ * supported x402 networks (Base / Base-Sepolia); it is independent of the
+ * chain the `ToolRegistry` is read from. A registry chain that is itself a
+ * supported x402 network verifies identity against that network; any other
+ * registry chain (e.g. mainnet, Monad) verifies against Base — matching the
+ * `network=base` the 402 challenge advertises. Without this decoupling, a
+ * non-Base registry chain would pin identity to a chainId no USDC
+ * authorization is ever signed for, so every caller fails closed and the only
+ * working configuration is the Base default (which reads the wrong registry).
+ */
+function x402IdentityChainId(registryChainId: number): number {
+  return CHAIN_ID_TO_NETWORK[registryChainId] ? registryChainId : BASE_CHAIN_ID
+}
+
 function buildPredicateChallengeResponse(
   operatorAddress: `0x${string}`,
   chainId: number,
@@ -677,8 +703,13 @@ export function paidPredicateGate(
   }
 
   const chain = config.chain ?? base
-  const rpcUrl = config.rpcUrl ?? "https://mainnet.base.org"
+  // Leave rpcUrl undefined when unset so reads follow the configured chain's
+  // default RPC (viem), instead of silently reading Base for a non-Base chain.
+  const rpcUrl = config.rpcUrl
   const network = config.network ?? "base"
+  // Identity/payment rides on the x402 payment network (advertised in the 402
+  // and used to sign the X-Payment authorization), not the registry chain.
+  const identityChainId = resolveNetwork(network)?.chainId ?? BASE_CHAIN_ID
   const facilitatorUrl =
     config.facilitatorUrl ??
     (config.facilitator === "cdp"
@@ -791,7 +822,7 @@ export function paidPredicateGate(
       // --- Identity verification (X-Payment signature) ---
       const authResult = await verifyXPaymentAuth(paymentHeader, {
         operatorAddress: config.operatorAddress,
-        expectedChainId: chain.id,
+        expectedChainId: identityChainId,
         requireZeroValue: false,
       })
       if (authResult.error) {