|
| 1 | +# @opensea/tool-sdk |
| 2 | + |
| 3 | +## 0.1.1 |
| 4 | + |
| 5 | +### Patch Changes |
| 6 | + |
| 7 | +- 905ed4a: Initial release of `@opensea/tool-sdk` — SDK and CLI for building ERC-XXXX compliant AI agent tools. |
| 8 | + |
| 9 | + ### Core SDK |
| 10 | + |
| 11 | + - `createToolHandler` for building tools with manifest validation, JCS keccak256 hashing, well-known endpoint middleware, and a `GateMiddleware` chain. |
| 12 | + - Framework adapters for Vercel, Cloudflare, and Express. Includes `VercelRequest`/`VercelResponse`/`ExpressRequest`/`ExpressResponse` type exports. |
| 13 | + - `ToolHandlerError` for typed HTTP status codes; unhandled errors are logged automatically. |
| 14 | + - `ToolManifestSchema` with optional `verifiability` block (tier, execution, dataRetention, sourceVisibility, attestation, reproducibleBuild). |
| 15 | + |
| 16 | + ### Onchain integration |
| 17 | + |
| 18 | + - `ToolRegistryClient` with `registerTool`, `setAccessPredicate`, `tryHasAccess`, and `listToolsByCreator`. |
| 19 | + - Canonical CREATE2 deployments on Base mainnet: `TOOL_REGISTRY` (v0.1), `ERC721_OWNER_PREDICATE`, `ERC1155_OWNER_PREDICATE`. Each is a `Deployment` object (`{ address, chains, overrides? }`); resolve per-chain with `deploymentAddress(deployment, chainId)`. |
| 20 | + - `register` CLI enforces `creatorAddress` matches the signing wallet per ERC-XXXX spec. |
| 21 | + - `IAccessPredicate` (interface ID `0xbdf9dc18`) and `IToolRegistry` ABIs exported, including `name()` / `version()` view methods. Predicates expose machine-readable access requirements via `getRequirements(toolId)` returning `AccessRequirement[]` with `RequirementLogic` (AND/OR). Marker interfaces `IERC721Holding`, `IERC1155Holding`, `ISubscription` shipped via `IRequirementTypes.sol`. |
| 22 | + |
| 23 | + ### Access gates |
| 24 | + |
| 25 | + - `predicateGate({ toolId })` middleware delegates the access decision to the onchain `ToolRegistry` so the registered access predicate is the single source of truth. One middleware works for every predicate type (single-collection, multi-collection, ERC-1155, subscriptions, composites, future predicates) without per-predicate SDK changes; on-chain `setAccessPredicate` updates are picked up automatically. Returns 403 with the predicate address on `(true, false)`, 502 on predicate misbehavior. |
| 26 | + - `checkToolAccess` is the client-side preview of `predicateGate` (no SIWE) for frontends and CLIs that want to gate UI before invocation. |
| 27 | + - `nftGate` is `@deprecated` in favor of `predicateGate` for any registered tool. It remains exported for local development against unregistered tools. |
| 28 | + - SIWE auth helpers: `createSiweMessage`, `authenticatedFetch`. Now also accepts external signers (Bankr, MPC, HSM) for agent wallets. |
| 29 | + |
| 30 | + ### x402 paywall gates |
| 31 | + |
| 32 | + - `x402Gate` — lower-level gate for self-hosted facilitators. |
| 33 | + - `payaiX402Gate` — uses the PayAI community facilitator (`https://facilitator.payai.network`, no auth, free); recommended for prototyping. |
| 34 | + - `cdpX402Gate` — uses Coinbase Developer Platform (`https://api.cdp.coinbase.com/platform/v2/x402`); accepts a `createAuthHeaders` callback for the CDP JWT auth. |
| 35 | + - All hosted gates settle on chain after the handler succeeds — they invoke `/settle` once the response validates against the schema, moving USDC from payer to recipient and recording the settled tx hash on `ctx.gates.x402.settlementTxHash`. Settlement is synchronous (up to 10s timeout); failures log `[tool-sdk] gate.settle failed:` but the response still returns 200. Operators running their own facilitator via `x402Gate` are responsible for settlement. |
| 36 | + - `defineToolPaywall` helper prevents pricing/gate config drift between the manifest and the gate. |
| 37 | + - Recipient address validation rejects zero and burn addresses. |
| 38 | + - Client helpers: `signX402Payment` (signs an EIP-3009 `TransferWithAuthorization` for USDC, returns base64-encoded `X-Payment` header value) and `paidFetch` (drop-in fetch wrapper that handles the 402 challenge automatically). |
| 39 | + - `GateMiddleware` gains an optional `settle?(ctx)` hook called by `createToolHandler` after a successful run. |
| 40 | + |
| 41 | + ### Wallet adapters |
| 42 | + |
| 43 | + - Wallet provider auto-detection across Privy, Turnkey, Fireblocks, and PrivateKey via the shared `@opensea/wallet-adapters` package. CLI accepts `--wallet-provider` to override. |
| 44 | + - `walletAdapterToClient` delegates to `@opensea/wallet-adapters/viem` (`walletAdapterToViemClient`). |
| 45 | + - Replaces the old `TOOL_SDK_PRIVATE_KEY` env var with the `WalletAdapter` abstraction. |
| 46 | + |
| 47 | + ### CLI commands |
| 48 | + |
| 49 | + - `init` — project scaffolding (Vercel/Express/Cloudflare templates) with TS-manifest support. |
| 50 | + - `validate`, `hash`, `export` — also accept TypeScript manifest files. |
| 51 | + - `verify`, `register`, `update-metadata` — manifest lifecycle. |
| 52 | + - `inspect` — shows predicate type, ERC-721/1155 collections, and accepts `--check-access`. |
| 53 | + - `pay` — pay a paywalled tool from the CLI. |
| 54 | + - `auth` — SIWE-authenticated calls to predicate-gated tools. |
| 55 | + - `dry-run-gate`, `dry-run-predicate-gate` — test gate setup locally before deploy. |
| 56 | + - `deploy --host vercel` — one-command deploy: login check, project link (auto-configured with inferred project and scope), env var setup from `.env.local.example` (with sensitive-input masking), first deploy, `TOOL_ENDPOINT` configuration, force redeploy, and manifest verification. Recovers from non-zero vercel exit when a URL was issued. |
| 57 | + - `smoke` — production endpoint verification. |
| 58 | + |
| 59 | + ### Documentation |
| 60 | + |
| 61 | + - README with full CLI reference (export, update-metadata, inspect, deploy, pay, auth, dry-run-gate, dry-run-predicate-gate). |
| 62 | + - Predicate gating + SIWE authentication guides. |
| 63 | + - Hosting comparison, migration guide, and FAQ. |
| 64 | + - MIT LICENSE. |
| 65 | + |
| 66 | + ### Breaking changes |
| 67 | + |
| 68 | + The `IAccessPredicate` ERC-165 interface ID changed from `0xa11ea958` to `0xbdf9dc18` due to the addition of `getRequirements()` and `name()`. Third-party predicate implementations must add both functions and report the new interface ID; existing predicates that declared support for the old ID will fail registration via `_validatePredicate` until updated. Permissive predicates that do not declare ERC-165 support are unaffected. |
| 69 | + |
| 70 | + `TOOL_REGISTRY_ADDRESS` (chain-keyed map) → `TOOL_REGISTRY` (`Deployment` object). `ERC721_OWNER_PREDICATE` and `ERC1155_OWNER_PREDICATE` shape changed from `Record<number, address | undefined>` to `Deployment`. Use `deploymentAddress(deployment, chainId)` to resolve an address for a specific chain. |
| 71 | + |
| 72 | + `PaidFetchOptions.account` renamed to `signer` (type widened to `WalletAdapter | Account`). `signX402Payment({ account })` renamed to `signX402Payment({ signer })`. `createWalletFromEnv(provider?)` no longer accepts an optional provider argument — use `createWalletForProvider(provider)` instead. `createWalletFromEnv()` no longer emits `console.warn` on multi-provider configs; it silently picks the highest-priority provider. |
| 73 | + |
| 74 | + The `register` CLI's `--nft-gate <address>` flag now configures the canonical multi-tenant `ERC721OwnerPredicate` via `setCollections(toolId, [collection])` after registration, instead of deploying a per-collection predicate. `setCollections` is gated to the tool's creator and the predicate reads the authoritative creator from the registry on every write. If `registerTool` succeeds but `setCollections` fails, the tool is registered with an unconfigured gate and `hasAccess` returns false for everyone — the CLI surfaces transaction details so the creator can re-run `setCollections` manually. |
| 75 | + |
| 76 | +- 959d87f: Sync tool-sdk with recent tool-registry updates: |
| 77 | + |
| 78 | + - **ABI completeness**: Add missing `ToolMetadataUpdated` and `AccessPredicateUpdated` events to `IToolRegistryABI`; add `hasAccess` to `IAccessPredicateABI` to match the full Solidity interface |
| 79 | + - **New predicate ABIs**: Add `SubscriptionPredicateABI` (configureToolGating, getToolGatingConfig, getSubscriptionStatus) and `CompositePredicateABI` (setComposition, getOp, getTerms) with events |
| 80 | + - **ToolRegistryClient**: Add `name()` and `version()` methods for onchain identity introspection |
| 81 | + - **inspect CLI**: Display access requirements via `getRequirements` for any predicate; show SubscriptionPredicate config (collection, minTier) and CompositePredicate terms (op, leaf predicates, negation) |
0 commit comments