Sync from opensea-devtools

Author: ryanio

.env.example

@@ -0,0 +1,29 @@
+# Tool SDK — Environment Variables
+# Copy to .env and fill in the values you need.
+
+# =============================================================================
+# Wallet signing — pick ONE provider for onchain operations (register, update)
+# =============================================================================
+
+# --- Option A: Privy (default, recommended) ---
+# PRIVY_APP_ID=               # https://dashboard.privy.io
+# PRIVY_APP_SECRET=
+# PRIVY_WALLET_ID=
+
+# --- Option B: Turnkey (HSM-backed) ---
+# TURNKEY_API_PUBLIC_KEY=     # https://app.turnkey.com
+# TURNKEY_API_PRIVATE_KEY=    # hex-encoded P-256 private key
+# TURNKEY_ORGANIZATION_ID=
+# TURNKEY_WALLET_ADDRESS=
+# TURNKEY_RPC_URL=            # required — RPC endpoint for gas estimation and tx broadcast
+
+# --- Option C: Fireblocks (enterprise MPC) ---
+# FIREBLOCKS_API_KEY=         # https://www.fireblocks.com
+# FIREBLOCKS_API_SECRET=      # RSA PEM key from Fireblocks console
+# FIREBLOCKS_VAULT_ID=
+# 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) ---
+# PRIVATE_KEY=                # hex-encoded — no spending limits or guardrails
+# RPC_URL=                    # RPC endpoint for the target chain

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+      - run: npm install
+      - run: npm run build
+      - run: npm run lint
+      - run: npm run type-check
+      - run: npm test

.github/workflows/npm-publish-reusable.yml

@@ -0,0 +1,60 @@
+name: Publish npm package
+
+on:
+  workflow_call:
+    inputs:
+      build-before-publish:
+        description: Run build and test before publishing
+        type: boolean
+        default: true
+      stub-package-dir:
+        description: Path to stub package directory (e.g. packages/opensea-js-stub)
+        type: string
+        default: ""
+      node-version-file:
+        description: Path to node version file
+        type: string
+        default: .nvmrc
+    secrets:
+      OPENSEA_API_KEY:
+        required: false
+      ALCHEMY_API_KEY:
+        required: false
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: ${{ inputs.node-version-file }}
+          registry-url: https://registry.npmjs.org/
+
+      # Use npm install (not npm ci) because the package-lock.json may be
+      # out of sync after the sync-package workflow resolves workspace: protocols
+      # and updates dependencies. npm ci requires exact lockfile match.
+      #
+      # --legacy-peer-deps mirrors pnpm's permissive peer-dep behavior used in the
+      # monorepo. Without it, packages like api-types fail on openapi-typescript@^7
+      # which declares a strict `typescript@^5.x` peer while we ship typescript@^6.
+      - run: npm install --legacy-peer-deps
+
+      - if: ${{ inputs.build-before-publish }}
+        run: npm run build
+
+      - if: ${{ inputs.build-before-publish }}
+        run: npm test
+        env:
+          OPENSEA_API_KEY: ${{ secrets.OPENSEA_API_KEY }}
+          ALCHEMY_API_KEY: ${{ secrets.ALCHEMY_API_KEY }}
+
+      - run: npm publish --provenance --access public
+
+      - if: ${{ inputs.stub-package-dir != '' }}
+        run: npm publish --provenance --access public
+        working-directory: ${{ inputs.stub-package-dir }}
+        continue-on-error: true

.nvmrc

@@ -0,0 +1 @@
+24.14.1

AGENTS.md

@@ -0,0 +1,60 @@
+# tool-sdk — Agent Conventions
+
+TypeScript SDK and CLI for building ERC-XXXX compliant AI agent tools.
+
+## Quick Reference
+
+```bash
+cd packages/tool-sdk
+pnpm install
+pnpm run build       # Build with tsup
+pnpm run test        # Run tests with Vitest
+pnpm run lint        # Lint with Biome
+pnpm run format      # Format with Biome
+pnpm run type-check  # TypeScript type checking
+```
+
+## Architecture
+
+| Path | Role |
+|------|------|
+| `src/index.ts` | Library entry point — public `tool-sdk` exports |
+| `src/cli.ts` | CLI entry point (Commander program wiring) |
+| `src/types.ts` | Shared public types |
+| `src/cli/commands/` | CLI commands: `register`, `validate`, `verify`, `hash`, `init` |
+| `src/lib/onchain/abis.ts` | TypeScript ABI definitions mirroring Solidity interfaces |
+| `src/lib/onchain/chains.ts` | Deployed contract addresses per chain |
+| `src/lib/onchain/registry.ts` | `ToolRegistryClient` — onchain interaction wrapper |
+| `src/lib/onchain/hash.ts` | JCS keccak256 manifest hashing |
+| `src/lib/manifest/` | Manifest schema, validation, types |
+| `src/lib/handler/` | `createToolHandler` — Web Request/Response handler factory |
+| `src/lib/middleware/` | Gating middleware (NFT gate, x402, 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/` |
+| `src/templates/` | Scaffolding templates for `init` command |
+| `src/__tests__/` | Vitest test suite |
+
+## Review Checklist
+
+When reviewing changes to this package, verify:
+
+1. **ABI completeness**: `abis.ts` must include every function and event from the corresponding Solidity interfaces in `../tool-registry/src/interfaces/`. If the Solidity interface adds a function, `abis.ts` must add it too. Missing ABI entries mean SDK consumers cannot call those functions.
+
+2. **Address sync**: Addresses in `chains.ts` must match `../tool-registry/README.md`. After a new deploy, both files must be updated together.
+
+3. **Dead code after refactors**: When removing features (e.g., dropping a predicate factory), verify that all related imports, constants, and references are also removed. Check for unused imports at the top of refactored files.
+
+4. **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.
+
+5. **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. **`--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.
+
+## Conventions
+
+- ESM-only (`"type": "module"`). Use `.js` extensions in import paths.
+- Biome for linting and formatting: double quotes, 2-space indent, trailing commas.
+- `as const` on all ABI definitions for type narrowing with viem.
+- CLI commands use Commander.js. Wallet is configured via `--wallet-provider` flag or env vars (see `.env.example`).
+- `ToolRegistryClient` wraps viem `PublicClient` and `WalletClient` — all onchain reads/writes go through it.

LICENSE

@@ -1,21 +1,7 @@
-MIT License
+Copyright 2026 Ozone Networks, Inc.
 
-Copyright (c) 2026 OpenSea
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.