Release v0.7.0

Author: CodySearsOS

.env.example

@@ -24,6 +24,9 @@
 # FIREBLOCKS_ASSET_ID=        # optional — override auto-detected asset ID
 # FIREBLOCKS_MAX_POLL_ATTEMPTS=  # optional — max poll attempts for tx confirmation (default: 60)
 
-# --- Option D: Raw Private Key (local dev only, NOT recommended) ---
+# --- Option D: Bankr (agent wallet API) ---
+# BANKR_API_KEY=              # https://bankr.bot
+
+# --- Option E: Raw Private Key (local dev only, NOT recommended) ---
 # PRIVATE_KEY=                # hex-encoded — no spending limits or guardrails
 # RPC_URL=                    # RPC endpoint for the target chain

AGENTS.md

@@ -30,7 +30,7 @@ pnpm run type-check  # TypeScript type checking
 | `src/lib/onchain/predicate-clients.ts` | Typed clients for predicate contracts |
 | `src/lib/manifest/` | Manifest schema, validation, types |
 | `src/lib/handler/` | `createToolHandler` — Web Request/Response handler factory |
-| `src/lib/middleware/` | Gating middleware (NFT gate, predicate gate, x402, x402 facilitators, well-known endpoint) |
+| `src/lib/middleware/` | Gating middleware (predicate gate, x402, x402 facilitators, well-known endpoint) |
 | `src/lib/wallet/` | Re-exports from `@opensea/wallet-adapters` (adapters, types, and viem bridge) |
 | `src/lib/adapters/` | Framework adapters (Vercel, Cloudflare, Express) |
 | `src/lib/utils.ts` | Shared utilities used across `lib/` |
@@ -55,7 +55,7 @@ When reviewing changes to this package, verify:
 
 5. **CLI error messages**: Error messages shown to SDK consumers should not reference internal file paths (e.g., "Update chains.ts"). Link to the README or provide actionable instructions instead.
 
-6. **Multi-step CLI flows**: Commands that require multiple onchain transactions (e.g., `register --nft-gate` does `registerTool` then `setCollections`) must handle partial failure gracefully — print recovery instructions if the second TX fails.
+6. **Multi-step CLI flows**: Commands that require multiple onchain transactions must handle partial failure gracefully — print recovery instructions if a subsequent TX fails.
 
 7. **`--dry-run` accuracy**: Dry-run output must reflect the full onchain footprint. If the command sends multiple transactions, the dry-run should mention all of them.
 

CHANGELOG.md

@@ -1,5 +1,59 @@
 # @opensea/tool-sdk
 
+## 0.7.0
+
+### Minor Changes
+
+- 2391e1e: Add `--predicate-config` flag to `register` command (F4d)
+
+  When `--access-predicate <addr>` is supplied, the CLI now:
+
+  - Calls `name()` on the predicate to identify its type
+  - Displays the predicate name in the registration summary
+  - Accepts `--predicate-config <json>` to bundle predicate setup with registration
+    - ERC721OwnerPredicate: `--predicate-config '{"collections":["0x..."]}'`
+    - ERC1155OwnerPredicate: `--predicate-config '{"collection":"0x...","tokenIds":["1","2"]}'`
+  - Prints a warning if `--access-predicate` is used without `--predicate-config`, explaining that the tool will accept any caller until configured
+  - Validates `--access-predicate` addresses
+
+- 1be6808: Add `set-collections`, `get-collections`, and `set-collection-tokens` CLI commands (F4c)
+
+  - `set-collections <toolId> <addr...>` — set the ERC-721 collection gate list for an already-registered tool
+  - `get-collections <toolId>` — read the current ERC-721 collection gate list
+  - `set-collection-tokens <toolId> <addr> <tokenId...>` — set the ERC-1155 collection + token ID gate
+  - All commands auto-detect registry version and select the matching predicate deployment
+  - Supports `--dry-run`, `--wallet-provider`, `--rpc-url`, and `--network` options
+
+- 69b30ff: Fix `--nft-gate` broken end-to-end on Base mainnet (F4a)
+
+  The SDK hardcoded the v0.2 `ERC721OwnerPredicate` address, which is rejected by the live v0.1 registry on Base. The `register` command now queries the registry's `version()` and selects the matching predicate deployment automatically.
+
+  - Re-added `--nft-gate <collection>` to `register` with registry-version-aware predicate selection
+  - Added `ERC721_OWNER_PREDICATE_V1` deployment constant
+  - Added `getPredicateForRegistryVersion()` resolver
+  - Added `registryVersion` option to `PredicateClientConfig`
+  - Updated `tool-registry/README.md` and `SKILLS.md` with v0.1 predicate addresses
+
+- 2c1e552: Add `--auth siwe` flag to the `pay` CLI command. When set, uses `paidAuthenticatedFetch` (SIWE + x402 payment) instead of payment-only flow. Also auto-enables SIWE auth when `--manifest` points to a manifest with an `access` block.
+- 53a49cf: Remove deprecated `nftGate` middleware and `--nft-gate` CLI flag behavior
+
+  - Removed `nftGate` middleware (`src/lib/middleware/nft-gate.ts`) and its `NFTGateConfig` type
+  - Removed `nft` field from `ToolContext.gates` and `BypassGates`
+  - Re-added `--nft-gate` option to `register` with registry-version-aware predicate selection
+  - Use `predicateGate` with `--access-predicate` instead for all access gating middleware
+
+  **BREAKING:** `nftGate`, `NFTGateConfig`, and `ToolContext.gates.nft` are no longer exported. Migrate to `predicateGate({ toolId })`.
+
+- 91d95ba: Add `SubscriptionPredicateClient` and `CompositePredicateClient` typed clients matching `tool-registry` example predicates. Add missing `CollectionsSet` event to `ERC721OwnerPredicateABI`. Fix stale v0.1 predicate addresses in SKILLS.md examples.
+
+### Patch Changes
+
+- b02f9b0: Treat 4xx probe responses (e.g. 400 from Zod validation) as "endpoint reachable" instead of printing a misleading WARN. Only 5xx responses are flagged as failures.
+- cab7a72: Treat 402 with valid `accepts` array as auth-OK in `smoke` command
+
+  - When a paywalled tool returns 402 with payment requirements after SIWE auth, `smoke` now exits 0 and prints: "Auth OK — paywall fired (expected for paywalled tools)."
+  - The `--expect` flag no longer defaults to 200; when omitted, 402-with-accepts is auto-success. When explicitly set, the exact status code is asserted as before.
+
 ## 0.6.0
 
 ### Minor Changes

README.md

@@ -79,15 +79,14 @@ Register a tool onchain via the ToolRegistry contract.
 PRIVATE_KEY=0x... RPC_URL=https://... npx @opensea/tool-sdk register \
   --metadata <url> \
   --network base \
-  --nft-gate 0x...  # optional: NFT collection for predicate
+  --access-predicate 0x...  # optional: access predicate address
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--metadata <url>` | Metadata URI (required) |
 | `--network <network>` | `base` or `mainnet` (default: `base`) |
-| `--nft-gate <address>` | NFT collection for SimpleNFT721PredicateFactory |
-| `--access-predicate <address>` | Manual access predicate address |
+| `--access-predicate <address>` | Access predicate address |
 | `--dry-run` | Print summary without transacting |
 | `-y, --yes` | Skip confirmation prompt |
 
@@ -161,14 +160,14 @@ npx @opensea/tool-sdk pay https://my-tool.vercel.app/api/tool \
 Make an authenticated call to a predicate-gated tool endpoint via SIWE.
 
 ```bash
-TOOL_SDK_PRIVATE_KEY=0x... npx @opensea/tool-sdk auth https://my-tool.vercel.app/api/tool \
+PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org npx @opensea/tool-sdk auth https://my-tool.vercel.app/api/tool \
   --body '{"query":"hello"}'
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--body <json>` | JSON body (inline string or `@path/to/file.json`) |
-| `--key <hex>` | Wallet private key (defaults to `TOOL_SDK_PRIVATE_KEY` env var) — use env var in production to avoid exposing keys in shell history |
+| `--wallet-provider <provider>` | Wallet provider to use for signing |
 
 ### `dry-run-gate`
 
@@ -201,6 +200,39 @@ npx @opensea/tool-sdk dry-run-predicate-gate \
 | `--tool-id <id>` | Onchain tool ID to configure in the gate |
 | `--input <json>` | JSON input body (inline or `@path`) |
 
+## Wallet Configuration
+
+All commands that sign transactions (`register`, `update-metadata`, `pay`, `auth`, `smoke`) need a wallet. You can configure one in two ways:
+
+1. **Environment variables** — set the env vars for your provider and the CLI auto-detects it (priority: Privy > Fireblocks > Turnkey > Bankr > PrivateKey).
+2. **`--wallet-provider` flag** — explicitly select a provider by name.
+
+| Provider | `--wallet-provider` value | Required env vars |
+|----------|--------------------------|-------------------|
+| Privy | `privy` | `PRIVY_APP_ID`, `PRIVY_APP_SECRET`, `PRIVY_WALLET_ID` |
+| Fireblocks | `fireblocks` | `FIREBLOCKS_API_KEY`, `FIREBLOCKS_API_SECRET`, `FIREBLOCKS_VAULT_ID` |
+| Turnkey | `turnkey` | `TURNKEY_API_PUBLIC_KEY`, `TURNKEY_API_PRIVATE_KEY`, `TURNKEY_ORGANIZATION_ID`, `TURNKEY_WALLET_ADDRESS`, `TURNKEY_RPC_URL` |
+| Bankr | `bankr` | `BANKR_API_KEY` |
+| Private Key | `private-key` | `PRIVATE_KEY`, `RPC_URL` |
+
+See [`.env.example`](.env.example) for a full annotated template.
+
+### Examples
+
+```bash
+# Auto-detect from env vars (simplest)
+PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org npx @opensea/tool-sdk register \
+  --metadata <url> --network base
+
+# Explicit provider selection
+BANKR_API_KEY=... npx @opensea/tool-sdk register \
+  --metadata <url> --network base --wallet-provider bankr
+
+# Privy server wallet
+PRIVY_APP_ID=... PRIVY_APP_SECRET=... PRIVY_WALLET_ID=... npx @opensea/tool-sdk auth \
+  https://my-tool.vercel.app/api/tool --body '{"query":"hello"}'
+```
+
 ## Library API
 
 ### `defineManifest(manifest)`
@@ -256,7 +288,7 @@ const handler = createToolHandler({
   manifest,
   inputSchema: z.object({ query: z.string() }),
   outputSchema: z.object({ result: z.string() }),
-  gates: [], // optional: nftGate, x402Gate
+  gates: [], // optional: predicateGate, x402Gate
   handler: async (input, ctx) => {
     return { result: `Hello: ${input.query}` }
   },
@@ -414,46 +446,6 @@ if (ok && granted) {
 `ok === false` means the predicate misbehaved upstream and the result is
 indeterminate; treat it as a transient failure, not a denial.
 
-### NFT Gate (deprecated)
-
-> **Deprecated.** Prefer `predicateGate` for any tool registered against the
-> canonical `ToolRegistry`. `nftGate` re-implements ERC-721 ownership
-> off-chain against a single hardcoded collection address, which means the
-> off-chain policy can drift from the onchain `accessPredicate` and
-> multi-collection / non-ERC-721 access models require parallel
-> implementations. Use `nftGate` only for local development and unregistered
-> tools where you do not yet have a `toolId`.
-
-Requires callers to hold an ERC-721 NFT. Uses SIWE (Sign-In with Ethereum) for address verification.
-
-```typescript
-import { nftGate } from "@opensea/tool-sdk"
-
-const gate = nftGate({
-  collection: "0x1234...5678", // ERC-721 on Base
-  rpcUrl: "https://mainnet.base.org", // optional
-})
-
-const handler = createToolHandler({
-  manifest,
-  inputSchema,
-  outputSchema,
-  gates: [gate],
-  handler: async (input, ctx) => {
-    // ctx.callerAddress is set on success
-    // ctx.gates.nft.granted === true
-    return { result: "access granted" }
-  },
-})
-```
-
-Authorization header format: `SIWE <base64url(siwe-message)>.<hex-signature>`
-
-> **Note:** The NFT gate is stateless and does not track nonces. Callers should
-> include a short-lived `expirationTime` in their SIWE messages to limit replay
-> window. Tool operators requiring stronger replay protection should implement
-> server-side nonce tracking.
-
 ### x402 Gate (hosted facilitator)
 
 The SDK ships two hosted-facilitator gates with the same shape: