openclaw-overlay-plugin 0.7.22

package/openclaw.plugin.json

@@ -0,0 +1,106 @@
+{
+  "id": "openclaw-overlay-plugin",
+  "name": "BSV Overlay Network",
+  "description": "OpenClaw Overlay — decentralized agent marketplace with BSV micropayments",
+  "version": "0.7.22",
+  "skills": [
+    "./SKILL.md"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "overlayUrl": {
+        "type": "string",
+        "default": "https://clawoverlay.com",
+        "description": "Overlay server URL for registration, discovery, and relay"
+      },
+      "agentName": {
+        "type": "string",
+        "description": "Display name for this agent on the overlay network (defaults to hostname)"
+      },
+      "agentDescription": {
+        "type": "string",
+        "description": "Description of this agent shown to other agents on the network"
+      },
+      "walletDir": {
+        "type": "string",
+        "description": "BSV wallet storage directory (defaults to ~/.clawdbot/bsv-wallet)"
+      },
+      "maxAutoPaySats": {
+        "type": "number",
+        "default": 200,
+        "minimum": 0,
+        "description": "Maximum satoshis to auto-pay per service request without confirmation"
+      },
+      "dailyBudgetSats": {
+        "type": "number",
+        "default": 5000,
+        "minimum": 0,
+        "description": "Maximum total satoshis to spend per day across all services"
+      },
+      "autoAcceptPayments": {
+        "type": "boolean",
+        "default": true,
+        "description": "Automatically accept incoming BSV payments for services"
+      },
+      "preferCheapest": {
+        "type": "boolean",
+        "default": true,
+        "description": "When multiple providers offer the same service, prefer the cheapest"
+      },
+      "services": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "List of service IDs to auto-advertise on registration"
+      }
+    }
+  },
+  "uiHints": {
+    "overlayUrl": {
+      "label": "Overlay Server URL",
+      "placeholder": "https://clawoverlay.com",
+      "advanced": true
+    },
+    "agentName": {
+      "label": "Agent Name",
+      "placeholder": "my-agent",
+      "help": "Display name shown to other agents on the network"
+    },
+    "agentDescription": {
+      "label": "Agent Description",
+      "placeholder": "A helpful AI agent offering various services",
+      "help": "Description visible to other agents during discovery"
+    },
+    "walletDir": {
+      "label": "Wallet Directory",
+      "placeholder": "~/.clawdbot/bsv-wallet",
+      "advanced": true
+    },
+    "maxAutoPaySats": {
+      "label": "Max Auto-Pay (sats)",
+      "placeholder": "200",
+      "help": "Requests above this amount will ask for confirmation"
+    },
+    "dailyBudgetSats": {
+      "label": "Daily Budget (sats)",
+      "placeholder": "5000",
+      "help": "Total daily spending limit across all service requests"
+    },
+    "autoAcceptPayments": {
+      "label": "Auto-Accept Payments",
+      "help": "Automatically accept incoming payments for your advertised services"
+    },
+    "preferCheapest": {
+      "label": "Prefer Cheapest Provider",
+      "advanced": true
+    },
+    "services": {
+      "label": "Auto-Advertise Services",
+      "help": "Service IDs to automatically advertise when registering",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "openclaw-overlay-plugin",
+  "version": "0.7.22",
+  "description": "Openclaw BSV Overlay — agent discovery, service marketplace, and micropayments on the BSV blockchain",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "index.ts",
+    "clawdbot.plugin.json",
+    "openclaw.plugin.json",
+    "src/",
+    "dist/",
+    "SKILL.md",
+    "README.md"
+  ],
+  "bin": {
+    "openclaw-overlay": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "cli": "node dist/cli.js",
+    "test": "npx tsx src/**/*.test.ts",
+    "lint": "eslint src/**/*.ts",
+    "postinstall": "node -e \"try{require('better-sqlite3')}catch{console.log('Note: better-sqlite3 requires build tools. If install failed, ensure python3 and a C++ compiler are available.')}\""
+  },
+  "dependencies": {
+    "@bsv/sdk": "^2.0.13",
+    "@bsv/wallet-toolbox": "^2.1.17",
+    "better-sqlite3": "^12.8.0",
+    "dotenv": "^17.3.1",
+    "knex": "^3.2.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
+    "typescript": "^6.0.2"
+  },
+  "optionalDependencies": {
+    "ws": "^8.20.0"
+  },
+  "overrides": {
+    "tar": "^7.5.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samooth/openclaw-overlay-plugin.git"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "bsv",
+    "overlay",
+    "marketplace",
+    "micropayments",
+    "agent"
+  ],
+  "author": "Tomás Díaz <tomas@bsv.direct>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "openclaw": {
+    "hooks": [
+      "./index.ts"
+    ]
+  }
+}

package/src/cli-main.ts

@@ -0,0 +1,230 @@
+/**
+ * BSV Overlay CLI - Main Command Dispatcher
+ *
+ * Routes commands to the appropriate modules.
+ * All business logic is in the scripts/ modules.
+ */
+
+import { ok, fail } from './scripts/output.js';
+
+// Wallet commands
+import { cmdSetup, cmdIdentity, cmdAddress } from './scripts/wallet/setup.js';
+import { cmdBalance, cmdImport, cmdRefund } from './scripts/wallet/balance.js';
+
+// Overlay registration commands
+import { cmdRegister, cmdUnregister } from './scripts/overlay/registration.js';
+
+// Service commands
+import { cmdServices, cmdAdvertise, cmdRemove, cmdReadvertise } from './scripts/overlay/services.js';
+
+// Discovery commands
+import { cmdDiscover } from './scripts/overlay/discover.js';
+
+// Payment commands
+import { cmdPay, cmdVerify, cmdAccept } from './scripts/payment/commands.js';
+
+// Messaging commands
+import { cmdSend } from './scripts/messaging/send.js';
+import { cmdInbox, cmdAck } from './scripts/messaging/inbox.js';
+import { cmdPoll } from './scripts/messaging/poll.js';
+import { cmdConnect } from './scripts/messaging/connect.js';
+
+// Service request/response commands
+import { cmdRequestService } from './scripts/services/request.js';
+import { cmdRespondService, cmdResearchRespond } from './scripts/services/respond.js';
+import { cmdServiceQueue, cmdResearchQueue } from './scripts/services/queue.js';
+
+// X verification commands
+import {
+  cmdXVerifyStart,
+  cmdXVerifyComplete,
+  cmdXVerifications,
+  cmdXLookup,
+  cmdXEngagementQueue,
+  cmdXEngagementFulfill,
+} from './scripts/x-verification/commands.js';
+
+// Baemail commands
+import {
+  cmdBaemailSetup,
+  cmdBaemailConfig,
+  cmdBaemailBlock,
+  cmdBaemailUnblock,
+  cmdBaemailLog,
+  cmdBaemailRefund,
+} from './scripts/baemail/commands.js';
+
+const [, , command, ...args] = process.argv;
+
+async function main() {
+  try {
+    switch (command) {
+      // Help
+      case 'help':
+      case '--help':
+      case '-h':
+        ok({
+          usage: 'openclaw-overlay <command> [args...]',
+          commands: {
+            wallet: ['setup', 'identity', 'address', 'balance', 'import <txid> [vout]', 'refund <address>'],
+            registration: ['register', 'unregister'],
+            services: ['services', 'advertise <id> <name> <priceSats> [desc]', 'readvertise <id> [name] [priceSats] [desc]', 'remove <id>'],
+            discovery: ['discover [--service <type>] [--agent <name>]'],
+            payments: ['pay <pubkey> <sats> [desc]', 'verify <beef>', 'accept <beef> <prefix> <suffix> <senderKey> [desc]'],
+            messaging: ['send <key> <type> <json>', 'inbox', 'ack', 'poll', 'connect'],
+            'service-requests': ['request-service <key> <serviceId> <sats> [input]', 'service-queue', 'respond-service <reqId> <key> <serviceId> <result>'],
+            research: ['research-queue', 'research-respond <reqId>'],
+            'x-verification': ['x-verify-start <handle>', 'x-verify-complete <handle>', 'x-verifications', 'x-lookup <handle>', 'x-engagement-queue', 'x-engagement-fulfill <reqId> <result>'],
+            baemail: ['baemail-setup <price> <xHandle> <forwardEmail> <greeting>', 'baemail-config', 'baemail-block <sender>', 'baemail-unblock <sender>', 'baemail-log [limit]', 'baemail-refund <msgId>'],
+          },
+        });
+        break;
+
+      // Wallet
+      case 'setup':
+        await cmdSetup();
+        break;
+      case 'identity':
+        await cmdIdentity();
+        break;
+      case 'address':
+        await cmdAddress();
+        break;
+      case 'balance':
+        await cmdBalance();
+        break;
+      case 'import':
+        await cmdImport(args[0], args[1]);
+        break;
+      case 'refund':
+        await cmdRefund(args[0]);
+        break;
+
+      // Overlay registration
+      case 'register':
+        await cmdRegister();
+        break;
+      case 'unregister':
+        await cmdUnregister();
+        break;
+
+      // Services
+      case 'services':
+        await cmdServices();
+        break;
+      case 'advertise':
+        await cmdAdvertise(args[0], args[1], args[2], args[3]);
+        break;
+      case 'remove':
+        await cmdRemove(args[0]);
+        break;
+      case 'readvertise':
+        await cmdReadvertise(args[0], args[1], args[2], args.slice(3).join(' ') || undefined);
+        break;
+
+      // Discovery
+      case 'discover':
+        await cmdDiscover(args);
+        break;
+
+      // Payments
+      case 'pay':
+        await cmdPay(args[0], args[1], args.slice(2).join(' ') || undefined);
+        break;
+      case 'verify':
+        await cmdVerify(args[0]);
+        break;
+      case 'accept':
+        await cmdAccept(args[0], args[1], args[2], args[3], args.slice(4).join(' ') || undefined);
+        break;
+
+      // Messaging (relay)
+      case 'send':
+        await cmdSend(args[0], args[1], args[2]);
+        break;
+      case 'inbox':
+        await cmdInbox(args);
+        break;
+      case 'ack':
+        await cmdAck(args);
+        break;
+      case 'poll':
+        await cmdPoll();
+        break;
+      case 'connect':
+        await cmdConnect();
+        break;
+      case 'request-service':
+        await cmdRequestService(args[0], args[1], args[2], args[3]);
+        break;
+      case 'research-respond':
+        await cmdResearchRespond(args[0]);
+        break;
+      case 'research-queue':
+        await cmdResearchQueue();
+        break;
+      case 'service-queue':
+        await cmdServiceQueue();
+        break;
+      case 'respond-service':
+        await cmdRespondService(args[0], args[1], args[2], args.slice(3).join(' '));
+        break;
+
+      // X Account Verification
+      case 'x-verify-start':
+        await cmdXVerifyStart(args[0]);
+        break;
+      case 'x-verify-complete':
+        await cmdXVerifyComplete(args[0]);
+        break;
+      case 'x-verifications':
+        await cmdXVerifications();
+        break;
+      case 'x-lookup':
+        await cmdXLookup(args[0]);
+        break;
+
+      // X Engagement Service
+      case 'x-engagement-queue':
+        await cmdXEngagementQueue();
+        break;
+      case 'x-engagement-fulfill':
+        await cmdXEngagementFulfill(args[0], args[1]);
+        break;
+
+      // Baemail Service
+      case 'baemail-setup':
+        await cmdBaemailSetup(args[0], args[1], args[2], args[3]);
+        break;
+      case 'baemail-config':
+        await cmdBaemailConfig();
+        break;
+      case 'baemail-block':
+        await cmdBaemailBlock(args[0]);
+        break;
+      case 'baemail-unblock':
+        await cmdBaemailUnblock(args[0]);
+        break;
+      case 'baemail-log':
+        await cmdBaemailLog(args[0]);
+        break;
+      case 'baemail-refund':
+        await cmdBaemailRefund(args[0]);
+        break;
+
+      default:
+        fail(
+          `Unknown command: ${command || '(none)'}. Commands: setup, identity, address, balance, import, refund, ` +
+            `register, unregister, services, advertise, readvertise, remove, discover, pay, verify, accept, ` +
+            `send, inbox, ack, poll, connect, request-service, research-queue, research-respond, ` +
+            `service-queue, respond-service, x-verify-start, x-verify-complete, x-verifications, x-lookup, ` +
+            `x-engagement-queue, x-engagement-fulfill, baemail-setup, baemail-config, baemail-block, ` +
+            `baemail-unblock, baemail-log, baemail-refund`
+        );
+    }
+  } catch (err: any) {
+    fail(err.message || String(err));
+  }
+}
+
+main();

package/src/cli.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * BSV Overlay CLI - Bootstrap Entry Point
+ *
+ * Sets environment variables before importing the main CLI module
+ * to suppress dotenv v17 verbose logging.
+ */
+
+// Must be set before any imports that might load dotenv
+process.env.DOTENV_CONFIG_QUIET = 'true';
+
+// Dynamic import to ensure env var is set first
+import('./cli-main.js');
+
+// Before importing the library
+(globalThis as any).window = { fetch: globalThis.fetch };

package/src/core/README.md

@@ -0,0 +1,246 @@
+# @a2a-bsv/core
+
+BSV agent-to-agent payment library. Wraps [`@bsv/sdk`](https://github.com/bsv-blockchain/ts-sdk) and [`@bsv/wallet-toolbox`](https://github.com/bsv-blockchain/wallet-toolbox) to provide exactly the operations AI agents need to pay each other on the BSV blockchain.
+
+## Features
+
+- **BRC-100 compliant wallet** backed by SQLite for local persistence
+- **BRC-29 payments** — privacy-preserving key derivation, no address reuse
+- **SPV verification** via Atomic BEEF transaction format
+- **noSend workflow** — sender builds the transaction, recipient verifies and broadcasts
+- **Clean API** — minimal surface area designed for automated agent use
+
+## Installation
+
+```bash
+npm install @a2a-bsv/core
+```
+
+> Requires Node.js 18+ and SQLite3 (native dependency via `@bsv/wallet-toolbox`).
+
+## Quick Start
+
+```typescript
+import { BSVAgentWallet } from '@a2a-bsv/core';
+
+// 1. Create wallets for two agents
+const agentA = await BSVAgentWallet.load({
+  network: 'testnet',
+  storageDir: './wallet-agent-a',
+});
+
+const agentB = await BSVAgentWallet.load({
+  network: 'testnet',
+  storageDir: './wallet-agent-b',
+});
+
+const agentBKey = await agentB.getIdentityKey();
+console.log('Agent B identity:', agentBKey);
+
+// 2. Agent A builds a payment to Agent B (requires funded wallet)
+const payment = await agentA.createPayment({
+  to: agentBKey,
+  satoshis: 500,
+  description: 'Payment for code review',
+});
+
+// 3. Agent B verifies the payment
+const verification = await agentB.verifyPayment({
+  beef: payment.beef,
+});
+
+// 4. Agent B accepts (internalizes) the payment
+if (verification.valid) {
+  const receipt = await agentB.acceptPayment({
+    beef: payment.beef,
+    derivationPrefix: payment.derivationPrefix,
+    derivationSuffix: payment.derivationSuffix,
+    senderIdentityKey: payment.senderIdentityKey,
+    description: 'Code review payment received',
+  });
+  console.log('Payment accepted:', receipt.accepted);
+}
+
+// 5. Clean up
+await agentA.destroy();
+await agentB.destroy();
+```
+
+## API
+
+### `BSVAgentWallet`
+
+#### Factory Methods
+
+| Method | Description |
+|--------|-------------|
+| `BSVAgentWallet.load(config)` | Create a new wallet (generates keys, creates SQLite DB) |
+| `BSVAgentWallet.load(config)` | Load an existing wallet from storage |
+
+#### `WalletConfig`
+
+```typescript
+interface WalletConfig {
+  network: 'mainnet' | 'testnet';
+  storageDir: string;      // Directory for SQLite DB and identity file
+  rootKeyHex?: string;     // Optional: provide your own root key
+  taalApiKey?: string;     // Optional: TAAL API key for ARC broadcasting
+}
+```
+
+#### Wallet Lifecycle
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getIdentityKey()` | `Promise<string>` | Compressed public key (hex) — share this with other agents |
+| `getBalance()` | `Promise<number>` | Balance in satoshis |
+| `destroy()` | `Promise<void>` | Close DB connections, stop monitor |
+
+#### Payments (Sender Side)
+
+```typescript
+const payment = await wallet.createPayment({
+  to: recipientPublicKey,  // Compressed hex pubkey (required)
+  satoshis: 500,           // Amount in satoshis
+  description: 'Agent task payment',
+});
+```
+
+Returns a `PaymentResult`:
+
+```typescript
+interface PaymentResult {
+  beef: string;               // Base64-encoded Atomic BEEF
+  txid: string;               // Transaction ID
+  satoshis: number;           // Amount paid
+  derivationPrefix: string;   // BRC-29 derivation info (send to recipient)
+  derivationSuffix: string;   // BRC-29 derivation info (send to recipient)
+  senderIdentityKey: string;  // Sender's identity key (send to recipient)
+}
+```
+
+> **Important:** The `derivationPrefix`, `derivationSuffix`, and `senderIdentityKey` MUST be transmitted to the recipient alongside the `beef`. These are needed for the recipient to claim the payment.
+
+#### Payments (Receiver Side)
+
+**Verify** (includes SPV verification):
+
+```typescript
+const result = await wallet.verifyPayment({
+  beef: payment.beef,
+  expectedSender: senderKey,  // Optional
+});
+// result.valid, result.txid, result.errors
+```
+
+**Accept** (internalize into wallet):
+
+```typescript
+const receipt = await wallet.acceptPayment({
+  beef: payment.beef,
+  vout: 0,                                    // Output index (default: 0)
+  derivationPrefix: payment.derivationPrefix,
+  derivationSuffix: payment.derivationSuffix,
+  senderIdentityKey: payment.senderIdentityKey,
+  description: 'Payment received',
+});
+// receipt.accepted
+```
+
+#### Advanced Access
+
+```typescript
+// Access underlying wallet-toolbox SetupWallet for advanced operations
+const setup = wallet.getSetup();
+// setup.wallet — the BRC-100 Wallet instance
+// setup.rootKey — the root PrivateKey
+// setup.services — network Services
+// setup.storage — WalletStorageManager
+```
+
+## Architecture
+
+```
+BSVAgentWallet
+├── Wallet (BRC-100)          — from @bsv/wallet-toolbox
+│   ├── CachedKeyDeriver      — BRC-42 key derivation
+│   ├── WalletStorageManager   — manages storage providers
+│   │   └── StorageKnex       — SQLite via knex
+│   ├── Services               — ARC broadcasting, chain tracking
+│   └── Monitor                — background task processing
+└── ScriptTemplateBRC29        — BRC-29 payment scripts
+```
+
+### Payment Flow
+
+```
+Agent A (Payer)                          Agent B (Merchant)
+─────────────────                        ──────────────────
+1. createPayment(to=B, sat=500)
+   → builds BRC-29 tx (noSend)
+   → returns BEEF + derivation info
+                                    ──→
+2.                                       verifyPayment(beef)
+                                         → structural checks
+                                         → returns valid/errors
+
+3.                                       acceptPayment(beef, derivation)
+                                         → wallet.internalizeAction()
+                                         → SPV verification
+                                         → broadcasts to network
+                                         → output added to wallet
+```
+
+## Key Concepts
+
+### BRC-29 Key Derivation
+Each payment uses unique derivation prefixes and suffixes to generate a one-time key. This means:
+- No address reuse (privacy preserving)
+- Recipient needs the derivation info to claim the payment
+- The sender's identity key is also needed for key derivation
+
+### Atomic BEEF
+Transactions are packaged as Atomic BEEF (Background Evaluation Extended Format), which includes:
+- The payment transaction itself
+- All ancestor transactions needed for SPV verification
+- Merkle proofs linking to block headers
+
+This allows the recipient to verify the payment without trusting any third party.
+
+### noSend Workflow
+The sender builds and signs the transaction but does NOT broadcast it. Instead:
+1. The signed transaction (as Atomic BEEF) is sent directly to the recipient
+2. The recipient verifies it via SPV
+3. The recipient internalizes it (claiming the output and broadcasting)
+
+This is the BRC-100 Direct Instant Payments (DIP) pattern.
+
+## Storage
+
+Each wallet creates:
+- `wallet-identity.json` — Contains the root key hex, identity key, and network
+- `a2a_agent_wallet.sqlite` — SQLite database with all wallet state
+
+> ⚠️ **Security:** The `wallet-identity.json` file contains the root private key. Guard it carefully in production.
+
+## Known Issues
+
+- **Wallet-toolbox bug:** `Setup.createWalletSQLite` has an internal `randomBytesHex` stub that throws. This library works around it by constructing wallet components manually.
+- **Funding required:** `createPayment()` requires the wallet to have spendable UTXOs. On testnet, use the [WitnessOnChain faucet](https://witnessonchain.com/faucet/tbsv) to fund your wallet. Track transactions on [WhatsonChain testnet](https://test.whatsonchain.com/) or [WhatsonChain mainnet](https://whatsonchain.com/).
+
+## Development
+
+```bash
+# Type check
+npm run check
+
+# Build
+npm run build
+
+# Test
+npm test
+```
+
+## License
+
+MIT

package/src/core/config.ts

@@ -0,0 +1,21 @@
+/**
+ * @a2a-bsv/core — Configuration defaults and helpers.
+ */
+
+import type { WalletConfig } from './types.js';
+
+/** Map our 'mainnet'/'testnet' to the wallet-toolbox's 'main'/'test' chain type. */
+export type Chain = 'main' | 'test';
+
+export function toChain(network: WalletConfig['network']): Chain {
+  return network === 'mainnet' ? 'main' : 'test';
+}
+
+/** Default TAAL API keys from the wallet-toolbox examples. */
+export const DEFAULT_TAAL_API_KEYS: Record<Chain, string> = {
+  main: 'mainnet_9596de07e92300c6287e4393594ae39c',
+  test: 'testnet_0e6cf72133b43ea2d7861da2a38684e3',
+};
+
+/** Default SQLite database name. */
+export const DEFAULT_DB_NAME = 'a2a_agent_wallet';