@basecred/openclaw-8004 1.0.0 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 An OpenClaw skill that teaches AI agents to register and manage on-chain identities on Base mainnet via [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) using the [agent0-sdk](https://github.com/agent0lab/agent0-ts).
 
-> **HTTP registration only.** This skill covers on-chain registration via HTTP URIs (`agent.registerHTTP()`). IPFS registration is **not** covered.
+> **Scope: On-chain operations + registration file schema.** This skill covers agent identity minting, updates, feedback, reputation, transfers, and the standardized registration file format via `agent0-sdk`. Off-chain hosting (IPFS, CDN) and subgraph queries are not covered — see [References in SKILL.md](./SKILL.md#references).
 
 ## Install
 
@@ -24,7 +24,7 @@ Or copy `SKILL.md` directly into your agent's skill directory.
 | Operation | Description |
 |-----------|-------------|
 | **Register** | Create an on-chain agent identity (ERC-721 NFT) |
-| **Update** | Modify name, description, endpoints, skills, metadata |
+| **Update** | Modify name, description, services, skills, metadata |
 | **Give Feedback** | Submit on-chain reputation scores for other agents |
 | **Search Feedback** | Query reputation summaries and feedback history |
 | **Transfer** | Move agent ownership to a new wallet |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openclaw-8004
-version: 1.0.0
+version: 1.2.0
 description: Register, manage, and build reputation for your AI agent on-chain via ERC-8004
 metadata:
   emoji: "\U0001F916"
@@ -16,7 +16,24 @@ metadata:
 
 Register your AI agent on-chain as an ERC-721 identity on Base mainnet. Advertise capabilities, receive feedback, and build reputation — all permissionless, no intermediaries.
 
-> **HTTP registration only.** This skill covers on-chain registration via HTTP URIs (`agent.registerHTTP()`). IPFS registration is **not** covered.
+> **Scope: On-Chain Operations + Registration File Schema**
+>
+> This skill covers **on-chain** agent identity management — registration (minting), updates, feedback, reputation, and transfers — using [agent0-sdk](https://github.com/agent0lab/agent0-ts) and `agent.registerHTTP()`.
+>
+> **What this skill covers:**
+> - Minting an ERC-721 agent identity on Base mainnet
+> - Updating agent metadata (name, description, services)
+> - Giving and searching on-chain feedback / reputation
+> - Transferring agent ownership
+> - SDK initialization and transaction safety
+> - Registration file schema (field definitions, endpoint types, output format)
+>
+> **What this skill does NOT cover:**
+> - IPFS registration (`agent.registerIPFS()`) or Pinata configuration
+> - Hosting, serving, or updating the registration JSON file
+> - Subgraph indexing or off-chain data queries
+>
+> For off-chain topics, see the [References](#references) section.
 
 | File | Description |
 |---|---|
@@ -24,6 +41,51 @@ Register your AI agent on-chain as an ERC-721 identity on Base mainnet. Advertis
 | **README.md** | Quick-start guide |
 | **IDENTITY.md** | Agent profile card (created after registration) |
 
+## Quick Reference
+
+| Operation | Section | SDK Call |
+|-----------|---------|---------|
+| Register | [Register Agent](#register-agent) | `agent.registerHTTP(url)` |
+| Update | [Update Agent](#update-agent) | `sdk.updateAgent(agentId, updates)` |
+| Feedback | [Give Feedback](#give-feedback) | `sdk.giveFeedback(agentId, score)` |
+| Search | [Search Feedback](#search-feedback) | `sdk.getReputationSummary(agentId)` |
+| Transfer | [Transfer Ownership](#transfer-ownership) | `sdk.transferAgent(agentId, newOwner)` |
+
+### SDK Init (copy-paste)
+
+```typescript
+import 'dotenv/config';
+import { SDK } from 'agent0-sdk';
+
+const sdk = new SDK({
+  chainId: 8453,
+  rpcUrl: process.env.BASE_RPC_URL || 'https://mainnet.base.org',
+  privateKey: process.env.WALLET_PRIVATE_KEY!,
+});
+```
+
+### Direct Mode (No Prompts)
+
+If you already know exactly what to do, skip the conversational flow:
+
+```typescript
+// Register
+const agent = sdk.createAgent('My Agent', 'Does things');
+const tx = await agent.registerHTTP('https://example.com/agent.json');
+await tx.waitConfirmed();
+
+// Give feedback
+await (await sdk.giveFeedback('8453:99', 85, 'helpful')).waitConfirmed();
+
+// Search reputation
+const summary = await sdk.getReputationSummary('8453:99');
+
+// Transfer
+await (await sdk.transferAgent('8453:42', '0xNEW...')).waitConfirmed();
+```
+
+---
+
 ## When to Use This Skill
 
 Use this skill whenever you need to:
@@ -31,7 +93,7 @@ Use this skill whenever you need to:
 - Advertise your MCP tools, A2A skills, or other capabilities
 - Receive or give feedback to other agents
 - Check your reputation score
-- Update your agent profile (name, description, endpoints)
+- Update your agent profile (name, description, services)
 - Transfer ownership of your agent identity to a new wallet
 
 ---
@@ -70,7 +132,7 @@ When the agent is already registered, **always present this menu** to the owner:
 >
 > What would you like to do?
 >
-> 1. **Update Agent** — modify name, description, endpoints, skills, or metadata
+> 1. **Update Agent** — modify name, description, services, skills, or metadata
 > 2. **Give Feedback** — rate another agent on-chain
 > 3. **Search Feedback** — check reputation for any agent
 > 4. **Transfer Ownership** — move your agent identity to a new wallet
@@ -147,6 +209,120 @@ Never skip the preview. On-chain actions cost gas and are irreversible.
 
 ---
 
+## Registration File Schema
+
+The registration file follows the [ERC-8004 specification](https://eips.ethereum.org/EIPS/eip-8004). The SDK generates this JSON when you call `agent.registerHTTP()`.
+
+### Example Registration File
+
+```json
+{
+  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
+  "name": "My Agent",
+  "description": "What this agent does",
+  "image": "https://example.com/avatar.png",
+  "services": [
+    {
+      "name": "MCP",
+      "version": "2025-06-18",
+      "endpoint": "https://example.com/api/mcp"
+    },
+    {
+      "name": "A2A",
+      "version": "0.3.0",
+      "endpoint": "https://example.com/.well-known/agent-card.json"
+    },
+    {
+      "name": "OASF",
+      "version": "0.8",
+      "endpoint": "https://example.com/.well-known/oasf.json",
+      "skills": ["blockchain/transaction_execution", "data_management/data_retrieval"],
+      "domains": ["finance_and_business/cryptocurrency", "technology/blockchain"]
+    },
+    {
+      "name": "web",
+      "endpoint": "https://example.com"
+    },
+    {
+      "name": "email",
+      "endpoint": "dev@example.com"
+    }
+  ],
+  "x402Support": false,
+  "active": true,
+  "registrations": [
+    {
+      "agentId": 42,
+      "agentRegistry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
+    }
+  ],
+  "supportedTrust": ["reputation"]
+}
+```
+
+### Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Always `"https://eips.ethereum.org/EIPS/eip-8004#registration-v1"` |
+| `name` | string | Yes | Agent display name |
+| `description` | string | Yes | What the agent does (MAY include pricing, interaction methods) |
+| `image` | string (URL) | No | Publicly accessible avatar URL |
+| `services` | array | No | Array of service objects (see below) |
+| `x402Support` | boolean | No | Whether agent supports x402 payments |
+| `active` | boolean | Yes | Whether agent is currently active |
+| `registrations` | array | No | On-chain registration references (see below) |
+| `supportedTrust` | string[] | No | Trust models: `"reputation"`, `"crypto-economic"`, `"tee-attestation"` |
+
+> **Note on `type`:** The SDK sets this automatically during `registerHTTP()`. Agents do not need to set it manually.
+
+> **Note on `registrations`:** Each entry has `agentId` (token ID number) and `agentRegistry` in `{namespace}:{chainId}:{identityRegistry}` format (e.g. `eip155:8453:0x8004...`). The SDK populates this after minting.
+
+### Service Types
+
+**EIP-8004 defined services:**
+
+| Service Name | Description | Example |
+|--------------|-------------|---------|
+| `MCP` | Model Context Protocol server | `https://example.com/api/mcp` |
+| `A2A` | Agent-to-Agent protocol | `https://agent.example/.well-known/agent-card.json` |
+| `OASF` | OASF agent card (may include `skills[]` and `domains[]`) | `https://example.com/.well-known/oasf.json` |
+| `ENS` | Ethereum Name Service | `vitalik.eth` |
+| `DID` | W3C Decentralized Identifier | `did:method:foobar` |
+| `web` | Agent website | `https://example.com` |
+| `email` | Contact email | `dev@example.com` |
+
+**Common custom services** (not in EIP spec, but widely used):
+
+| Service Name | Description | Example |
+|--------------|-------------|---------|
+| `twitter` | Twitter/X profile | `https://x.com/MyAgent` |
+| `farcaster` | Farcaster profile | `https://farcaster.xyz/myagent` |
+| `telegram` | Telegram bot | `https://t.me/myagentbot` |
+| `github` | GitHub repository | `https://github.com/myagent` |
+| `agentWallet` | On-chain wallet address | `eip155:8453:0x...` |
+
+> Custom service names are allowed — the `services` array is extensible. Use EIP-defined names when they fit.
+
+> **OASF service object:** The OASF service may include optional `skills` and `domains` arrays directly inside the service object. These follow [OASF categories](https://github.com/agntcy/oasf).
+
+### SDK Method → JSON Field Mapping
+
+| SDK Method | JSON Field | Notes |
+|------------|------------|-------|
+| `sdk.createAgent(name, desc, image)` | `name`, `description`, `image` | — |
+| `agent.setMCP(url)` | `services[{name:"MCP"}]` | — |
+| `agent.setA2A(url)` | `services[{name:"A2A"}]` | — |
+| `agent.setENS(name)` | `services[{name:"ENS"}]` | Also stored on-chain |
+| `agent.addSkill(skill, verified)` | `services[{name:"OASF"}].skills` | One per call |
+| `agent.addDomain(domain, verified)` | `services[{name:"OASF"}].domains` | One per call |
+| `agent.setTrust(rep, crypto, tee)` | `supportedTrust` | Booleans → string array |
+| `agent.setMetadata({...})` | Custom fields | Merged into root |
+| `agent.setActive(true)` | `active` | — |
+| `agent.registerHTTP(url)` | Generates & publishes JSON | Sets `type` and `registrations` automatically |
+
+---
+
 ## Register Agent
 
 ### Step 1: Pre-Fill from Existing Files
@@ -155,7 +331,7 @@ Before asking the owner for details, scan the project for files that may already
 
 | File | What to extract |
 |---|---|
-| `IDENTITY.md` | Name, description, image, endpoints (MCP, A2A), ENS, OASF skills/domains, trust models, metadata |
+| `IDENTITY.md` | Name, description, image, services (MCP, A2A), ENS, OASF skills/domains, trust models, metadata |
 | `TOOLS.md` | Tool names and descriptions — suggest as MCP capabilities or OASF skills |
 | `README.md` | Project name and description — suggest as agent name and description |
 | `package.json` | `name`, `description`, `homepage` — suggest as agent name, description, HTTP URL |
@@ -178,13 +354,16 @@ Present pre-filled values (if any) and ask the owner to confirm or edit:
 
 **Optional:**
 - **Image URL** — a publicly accessible URL for your agent's avatar
-- **MCP endpoint** — if your agent exposes MCP tools (e.g. `https://mcp.example.com/`)
-- **A2A endpoint** — if your agent exposes A2A skills (e.g. `https://a2a.example.com/agent-card.json`)
+- **MCP service** — if your agent exposes MCP tools (e.g. `https://mcp.example.com/`)
+- **A2A service** — if your agent exposes A2A skills (e.g. `https://a2a.example.com/.well-known/agent-card.json`)
 - **ENS name** — a human-readable name (e.g. `myagent.eth`)
+- **DID** — a W3C Decentralized Identifier (e.g. `did:web:example.com`)
 - **HTTP URL** — where to host your registration file (e.g. `https://myserver.com/agents/my-agent.json`)
 - **OASF skills** — standardized skill categories (e.g. `data_engineering/data_transformation_pipeline`)
 - **OASF domains** — standardized domain categories (e.g. `finance_and_business/investment_services`)
 - **Trust models** — which trust models to advertise: `reputation`, `crypto-economic`, `tee-attestation`
+- **x402 Support** — does your agent accept x402 payments? (true/false)
+- **Additional services** — website URL, email, etc. (see [Service Types](#service-types-eip-8004-defined))
 - **Metadata** — key-value pairs for additional info (e.g. `{ version: '1.0.0', category: 'ai-assistant' }`)
 
 If pre-filled values were found, present them like this:
@@ -208,18 +387,25 @@ const agent = sdk.createAgent(
   'https://example.com/agent-image.png'    // image URL (optional)
 );
 
-// Configure endpoints (optional — each auto-extracts capabilities)
-await agent.setMCP('https://mcp.example.com/');              // extracts tools, prompts, resources
-await agent.setA2A('https://a2a.example.com/agent-card.json'); // extracts skills
-agent.setENS('myagent.eth');
+// Configure services (optional)
+await agent.setMCP('https://mcp.example.com/');              // → services[{name:"MCP"}]
+await agent.setA2A('https://a2a.example.com/agent-card.json'); // → services[{name:"A2A"}]
+agent.setENS('myagent.eth');                                  // → services[{name:"ENS"}]
 
-// Add OASF skills and domains (optional)
+// Add OASF skills and domains (optional) — stored inside OASF service object
 agent.addSkill('data_engineering/data_transformation_pipeline', true);
 agent.addDomain('finance_and_business/investment_services', true);
 
 // Set trust models (optional): reputation, cryptoEconomic, teeAttestation
 agent.setTrust(true, false, false);
 
+// Set x402 payment support (optional)
+agent.setMetadata({ x402Support: true });
+
+// Add additional services (optional)
+agent.addEndpoint('web', 'https://example.com');
+agent.addEndpoint('email', 'dev@example.com');
+
 // Add metadata (optional)
 agent.setMetadata({ version: '1.0.0', category: 'ai-assistant' });
 
@@ -227,6 +413,8 @@ agent.setMetadata({ version: '1.0.0', category: 'ai-assistant' });
 agent.setActive(true);
 ```
 
+> **Note:** If `addEndpoint()` doesn't exist in agent0-sdk, additional services are set via `setMetadata()`. Adjust code to match actual SDK API. Service names must follow EIP-8004 casing: `MCP`, `A2A`, `OASF`, `ENS`, `DID` (uppercase), `web`, `email` (lowercase).
+
 ### Step 4: Preview Draft
 
 Before signing, present a summary to the owner for approval:
@@ -236,12 +424,11 @@ Before signing, present a summary to the owner for approval:
 > - **Name:** My AI Agent
 > - **Description:** An intelligent assistant for tasks.
 > - **Image:** https://example.com/agent-image.png
-> - **MCP Endpoint:** https://mcp.example.com/
-> - **A2A Endpoint:** https://a2a.example.com/agent-card.json
-> - **ENS:** myagent.eth
+> - **Services:** MCP, A2A, OASF, ENS, web, email
 > - **OASF Skills:** data_engineering/data_transformation_pipeline
 > - **OASF Domains:** finance_and_business/investment_services
 > - **Trust Models:** reputation
+> - **x402 Support:** false
 > - **Registration URI:** https://myserver.com/agents/my-agent.json
 >
 > This will mint an ERC-721 NFT on Base and cost gas. Shall I proceed?
@@ -251,7 +438,7 @@ Before signing, present a summary to the owner for approval:
 ### Step 5: Register On-Chain via HTTP
 
 The `registerHTTP()` call does three things:
-1. Serializes your agent's registration file (name, description, endpoints, skills, metadata) as JSON
+1. Serializes your agent's registration file (name, description, services, trust, metadata) as JSON
 2. Mints an ERC-721 NFT on-chain representing your agent identity
 3. Records the HTTP URL on-chain as the agent's URI, pointing to the hosted registration file
 
@@ -264,6 +451,26 @@ const { result: registration } = await txHandle.waitConfirmed();
 
 console.log(`Agent ID: ${registration.agentId}`);   // e.g. "8453:42"
 console.log(`Agent URI: ${registration.agentURI}`);  // the HTTP URL
+
+// The SDK generates a registration file like this:
+// {
+//   "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
+//   "name": "My AI Agent",
+//   "description": "An intelligent assistant for tasks.",
+//   "image": "https://example.com/agent-image.png",
+//   "services": [
+//     { "name": "MCP", "version": "2025-06-18", "endpoint": "https://mcp.example.com/" },
+//     { "name": "A2A", "version": "0.3.0", "endpoint": "https://a2a.example.com/agent-card.json" },
+//     { "name": "OASF", "version": "0.8", "endpoint": "...", "skills": [...], "domains": [...] },
+//     { "name": "ENS", "version": "v1", "endpoint": "myagent.eth" },
+//     { "name": "web", "endpoint": "https://example.com" },
+//     { "name": "email", "endpoint": "dev@example.com" }
+//   ],
+//   "x402Support": false,
+//   "active": true,
+//   "registrations": [{ "agentId": 42, "agentRegistry": "eip155:8453:0x8004..." }],
+//   "supportedTrust": ["reputation"]
+// }
 ```
 
 ### Step 6: Save Agent ID
@@ -345,7 +552,7 @@ agent.updateInfo(
   'New description with enhanced capabilities.'
 );
 
-// Update or add endpoints
+// Update or add services
 await agent.setMCP('https://mcp-v2.example.com/');
 await agent.setA2A('https://a2a-v2.example.com/agent-card.json');
 
@@ -604,6 +811,43 @@ console.log(`New owner: ${verifiedOwner}`);
 
 ---
 
+## IDENTITY.md Schema
+
+The IDENTITY.md file is a human-readable agent profile card saved locally after registration. Use this exact format:
+
+> This file is a local reference card. The actual registration file (JSON) is generated by the SDK — see [Registration File Schema](#registration-file-schema).
+
+```markdown
+# Agent Identity
+
+| Field | Value |
+|---|---|
+| **Agent ID** | {chainId}:{tokenId} |
+| **Name** | {agent name} |
+| **Description** | {agent description} |
+| **Chain** | Base ({chainId}) |
+| **Registration URI** | {HTTP URL} |
+| **Services** | {comma-separated service names or "—"} |
+| **MCP** | {MCP URL or "—"} |
+| **A2A** | {A2A URL or "—"} |
+| **ENS** | {ENS name or "—"} |
+| **Image** | {image URL or "—"} |
+| **x402 Support** | {true/false} |
+| **Website** | {URL or "—"} |
+| **Active** | {true/false} |
+| **Registered** | {YYYY-MM-DD} |
+
+> On-chain identity minted as ERC-721 on Base mainnet.
+```
+
+**Rules:**
+- Use "—" for optional fields that are not set (never leave blank)
+- Date format is always `YYYY-MM-DD`
+- Agent ID format is always `{chainId}:{tokenId}` (e.g. `8453:42`)
+- This file is for local reference only — it is NOT published to npm or uploaded on-chain
+
+---
+
 ## Error Handling
 
 | Error | Cause | Recovery |
@@ -616,6 +860,7 @@ console.log(`New owner: ${verifiedOwner}`);
 | `network error` / `timeout` | RPC endpoint is down or unreachable | Check `BASE_RPC_URL` in `.env`, try an alternative Base RPC |
 | `IPFS` or `Pinata` errors | Should not occur — this skill uses HTTP only | Verify you are using `agent.registerHTTP()`, not `agent.registerIPFS()` |
 | `setMCP` / `setA2A` soft failure | Endpoint unreachable during capability extraction | Non-blocking — the endpoint is still set, but tools/skills won't be auto-extracted. Verify the endpoint URL is correct and accessible. |
+| `receipt.gasUsed` undefined | SDK or RPC may return receipt fields as optional | Always use optional chaining (`receipt?.gasUsed`) when accessing receipt properties — do not assume all fields are present |
 
 **General rules:**
 - Never silently swallow errors. Log them and inform the owner.
@@ -641,6 +886,24 @@ console.log(`New owner: ${verifiedOwner}`);
 
 ---
 
+## References
+
+| Topic | Resource |
+|-------|----------|
+| **ERC-8004 Standard** | [EIP-8004](https://eips.ethereum.org/EIPS/eip-8004) |
+| **agent0-sdk Documentation** | [agent0-ts GitHub](https://github.com/agent0lab/agent0-ts) |
+| **Agent0 Platform** | [agent0.xyz](https://agent0.xyz) |
+| **IPFS Registration** | See `agent.registerIPFS()` in agent0-sdk docs — not covered by this skill |
+| **Registration File Format** | Defined by ERC-8004 spec — see EIP link above |
+| **Subgraph / Indexing** | Agent0 subgraph indexes both on-chain and IPFS data — see agent0-sdk docs |
+| **Base Network** | [Base Docs](https://docs.base.org) |
+| **OpenClaw Skills** | [openclaw.xyz](https://openclaw.xyz) |
+
+> This skill focuses on on-chain operations. For off-chain registration file hosting,
+> IPFS pinning, or subgraph queries, refer to the agent0-sdk documentation directly.
+
+---
+
 ## Example Interaction
 
 Below is a complete conversation showing first boot through registration, feedback, and transfer.
@@ -769,7 +1032,7 @@ const { result: registration } = await txHandle.waitConfirmed();
 >
 > What would you like to do?
 >
-> 1. **Update Agent** — modify name, description, endpoints, skills, or metadata
+> 1. **Update Agent** — modify name, description, services, skills, or metadata
 > 2. **Give Feedback** — rate another agent on-chain
 > 3. **Search Feedback** — check reputation for any agent
 > 4. **Transfer Ownership** — move your agent identity to a new wallet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basecred/openclaw-8004",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "OpenClaw skill for registering and managing AI agent identities on-chain via ERC-8004",
   "license": "MIT",
   "keywords": [
@@ -27,5 +27,8 @@
   "dependencies": {
     "agent0-sdk": "^1.5.3",
     "dotenv": "^16.4.7"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }