openclaw-overlay-plugin 0.7.22

package/src/scripts/config.ts

@@ -0,0 +1,81 @@
+/**
+ * Configuration constants and environment variables for the overlay CLI.
+ */
+
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+
+// Auto-load .env from overlay state dir if it exists
+const overlayEnvPath = path.join(os.homedir(), '.clawdbot', 'bsv-overlay', '.env');
+try {
+  if (fs.existsSync(overlayEnvPath)) {
+    for (const line of fs.readFileSync(overlayEnvPath, 'utf-8').split('\n')) {
+      const match = line.match(/^([A-Z_]+)=(.+)$/);
+      if (match && !process.env[match[1]]) {
+        process.env[match[1]] = match[2].trim();
+      }
+    }
+  }
+} catch {
+  // Ignore errors loading .env
+}
+
+/** Wallet storage directory */
+export const WALLET_DIR = process.env.BSV_WALLET_DIR
+  || path.join(os.homedir(), '.clawdbot', 'bsv-wallet');
+
+/** Network to use (mainnet or testnet) */
+export const NETWORK: 'mainnet' | 'testnet' =
+  (process.env.BSV_NETWORK as 'mainnet' | 'testnet') || 'mainnet';
+
+/** Overlay server URL */
+export const OVERLAY_URL = process.env.OVERLAY_URL || 'https://clawoverlay.com';
+
+/** Agent display name on the overlay network */
+export const AGENT_NAME = process.env.AGENT_NAME || 'clawdbot-agent';
+
+/** Agent description for the overlay identity */
+export const AGENT_DESCRIPTION = process.env.AGENT_DESCRIPTION ||
+  `AI agent on the OpenClaw Overlay Network. Offers services for BSV micropayments.`;
+
+/** WhatsOnChain API key (optional, for rate limit bypass) */
+export const WOC_API_KEY = process.env.WOC_API_KEY || '';
+
+/** Overlay state directory for registration, services, etc. */
+export const OVERLAY_STATE_DIR = path.join(os.homedir(), '.clawdbot', 'bsv-overlay');
+
+/** Protocol identifier for overlay transactions */
+export const PROTOCOL_ID = 'clawdbot overlay v1';
+
+/** Topic managers for overlay submissions */
+export const TOPICS = {
+  IDENTITY: 'tm_clawdbot_identity',
+  SERVICES: 'tm_clawdbot_services',
+  X_VERIFICATION: 'tm_clawdbot_x_verification',
+} as const;
+
+/** Lookup services for overlay queries */
+export const LOOKUP_SERVICES = {
+  AGENTS: 'ls_clawdbot_agents',
+  SERVICES: 'ls_clawdbot_services',
+  X_VERIFICATIONS: 'ls_clawdbot_x_verifications',
+} as const;
+
+/** Paths derived from config */
+export const PATHS = {
+  walletIdentity: path.join(WALLET_DIR, 'wallet-identity.json'),
+  registration: path.join(OVERLAY_STATE_DIR, 'registration.json'),
+  services: path.join(OVERLAY_STATE_DIR, 'services.json'),
+  latestChange: path.join(OVERLAY_STATE_DIR, 'latest-change.json'),
+  receivedPayments: path.join(OVERLAY_STATE_DIR, 'received-payments.jsonl'),
+  researchQueue: path.join(OVERLAY_STATE_DIR, 'research-queue.jsonl'),
+  serviceQueue: path.join(OVERLAY_STATE_DIR, 'service-queue.jsonl'),
+  notifications: path.join(OVERLAY_STATE_DIR, 'notifications.jsonl'),
+  xVerifications: path.join(OVERLAY_STATE_DIR, 'x-verifications.json'),
+  pendingXVerification: path.join(OVERLAY_STATE_DIR, 'pending-x-verification.json'),
+  xEngagementQueue: path.join(OVERLAY_STATE_DIR, 'x-engagement-queue.jsonl'),
+  memoryStore: path.join(WALLET_DIR, 'memory-store.json'),
+  baemailConfig: path.join(OVERLAY_STATE_DIR, 'baemail-config.json'),
+  baemailLog: path.join(OVERLAY_STATE_DIR, 'baemail-log.jsonl'),
+} as const;

package/src/scripts/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Main exports for lib modules.
+ */
+
+export * from './types.js';
+export * from './config.js';
+export * from './output.js';
+export * from './baemail/index.js';

package/src/scripts/messaging/connect.ts

@@ -0,0 +1,121 @@
+/**
+ * Connect command: WebSocket real-time message processing.
+ */
+
+import fs from 'node:fs';
+import { OVERLAY_URL, PATHS } from '../config.js';
+import { fail } from '../output.js';
+import { loadIdentity } from '../wallet/identity.js';
+import { processMessage } from './handlers.js';
+import { ensureStateDir } from '../utils/storage.js';
+
+/**
+ * Connect command: establish WebSocket connection for real-time messaging.
+ * Note: This function never returns normally - it runs until SIGINT/SIGTERM.
+ */
+export async function cmdConnect(): Promise<void> {
+  let WebSocketClient: any;
+  try {
+    const ws = await import('ws');
+    WebSocketClient = ws.default || (ws as any).WebSocket || ws;
+  } catch {
+    return fail('WebSocket client not available. Install it: npm install ws');
+  }
+
+  const { identityKey, privKey } = await loadIdentity();
+  const wsUrl = OVERLAY_URL.replace(/^http/, 'ws') + '/relay/subscribe?identity=' + identityKey;
+
+  let reconnectDelay = 1000;
+  let shouldReconnect = true;
+  let currentWs: any = null;
+
+  function shutdown() {
+    shouldReconnect = false;
+    if (currentWs) {
+      try { currentWs.close(); } catch {}
+    }
+    process.exit(0);
+  }
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  function connect() {
+    const ws = new WebSocketClient(wsUrl);
+    currentWs = ws;
+
+    ws.on('open', () => {
+      reconnectDelay = 1000; // reset on successful connect
+      console.error(JSON.stringify({ event: 'connected', identity: identityKey, overlay: OVERLAY_URL }));
+    });
+
+    ws.on('message', async (data: any) => {
+      try {
+        const envelope = JSON.parse(data.toString());
+        if (envelope.type === 'message') {
+          const result = await processMessage(envelope.message, identityKey, privKey);
+          // Output the result as a JSON line to stdout
+          console.log(JSON.stringify(result));
+
+          // Also append to notification log
+          ensureStateDir();
+          try {
+            fs.appendFileSync(PATHS.notifications, JSON.stringify({ ...result, _ts: Date.now() }) + '\n');
+          } catch {}
+
+          // Ack the message
+          if (result.ack) {
+            try {
+              await fetch(OVERLAY_URL + '/relay/ack', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ identity: identityKey, messageIds: [result.id] }),
+              });
+            } catch (ackErr: any) {
+              console.error(JSON.stringify({ event: 'ack-error', id: result.id, message: String(ackErr) }));
+            }
+          }
+        }
+
+        // Handle service announcements
+        if (envelope.type === 'service-announced') {
+          const svc = envelope.service || {};
+          const announcement = {
+            event: 'service-announced',
+            serviceId: svc.serviceId,
+            name: svc.name,
+            description: svc.description,
+            priceSats: svc.pricingSats,
+            provider: svc.identityKey,
+            txid: envelope.txid,
+            _ts: Date.now(),
+          };
+          console.log(JSON.stringify(announcement));
+          ensureStateDir();
+          try {
+            fs.appendFileSync(PATHS.notifications, JSON.stringify(announcement) + '\n');
+          } catch {}
+        }
+      } catch (err: any) {
+        console.error(JSON.stringify({ event: 'process-error', message: String(err) }));
+      }
+    });
+
+    ws.on('close', () => {
+      currentWs = null;
+      if (shouldReconnect) {
+        console.error(JSON.stringify({ event: 'disconnected', reconnectMs: reconnectDelay }));
+        setTimeout(connect, reconnectDelay);
+        reconnectDelay = Math.min(reconnectDelay * 2, 30000);
+      }
+    });
+
+    ws.on('error', (err: any) => {
+      console.error(JSON.stringify({ event: 'error', message: err.message }));
+    });
+  }
+
+  connect();
+  // Keep the process alive — never resolves
+  await new Promise(() => {});
+}

package/src/scripts/messaging/handlers.ts

@@ -0,0 +1,394 @@
+/**
+ * Message type handlers and processMessage function.
+ */
+
+import fs from 'node:fs';
+import { OVERLAY_URL, WALLET_DIR, PATHS } from '../config.js';
+import { signRelayMessage, verifyRelaySignature, loadWalletIdentity } from '../wallet/identity.js';
+import { loadServices, appendToJsonl } from '../utils/storage.js';
+import { fetchWithTimeout } from '../utils/woc.js';
+import { serviceManager } from '../../services/index.js';
+import type { RelayMessage, ProcessMessageResult } from '../types.js';
+
+// Dynamic import for @bsv/sdk (needed for hash160 computation)
+let _sdk: any = null;
+
+async function getSdk(): Promise<any> {
+  if (_sdk) return _sdk;
+
+  try {
+    _sdk = await import('@bsv/sdk');
+    return _sdk;
+  } catch {
+    const { fileURLToPath } = await import('node:url');
+    const path = await import('node:path');
+    const os = await import('node:os');
+
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+      path.resolve(__dirname, '..', '..', '..', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(__dirname, '..', '..', '..', '..', '..', 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(os.homedir(), 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+    ];
+
+    for (const p of candidates) {
+      try {
+        _sdk = await import(p);
+        return _sdk;
+      } catch {
+        // Try next
+      }
+    }
+    throw new Error('Cannot find @bsv/sdk. Run setup.sh first.');
+  }
+}
+
+import { BSVAgentWallet } from '../../core/index.js';
+
+async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
+  return BSVAgentWallet;
+}
+
+// Import NETWORK lazily to avoid circular dependencies
+async function getNetwork(): Promise<'mainnet' | 'testnet'> {
+  const config = await import('../config.js');
+  return config.NETWORK;
+}
+
+/**
+ * Verify and accept a payment from a service request.
+ * Uses a2a-bsv wallet.acceptPayment() for proper BRC-29 handling.
+ */
+export async function verifyAndAcceptPayment(
+  payment: any,
+  minSats: number,
+  senderKey: string,
+  serviceId: string,
+  ourHash160: Uint8Array
+): Promise<{
+  accepted: boolean;
+  txid: string | null;
+  satoshis: number;
+  outputIndex: number;
+  walletAccepted: boolean;
+  error: string | null;
+}> {
+  if (!payment) {
+    return { accepted: false, txid: null, satoshis: 0, outputIndex: 0, walletAccepted: false, error: 'no payment' };
+  }
+
+  if (payment.error) {
+    return { accepted: false, txid: null, satoshis: 0, outputIndex: 0, walletAccepted: false, error: payment.error };
+  }
+
+  if (!payment.beef || !payment.satoshis) {
+    return { accepted: false, txid: null, satoshis: 0, outputIndex: 0, walletAccepted: false, error: 'missing beef or satoshis' };
+  }
+
+  if (payment.satoshis < minSats) {
+    return { accepted: false, txid: payment.txid || null, satoshis: payment.satoshis, outputIndex: 0, walletAccepted: false, error: `insufficient payment: ${payment.satoshis} < ${minSats}` };
+  }
+
+  // Accept the payment using a2a-bsv wallet
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const network = await getNetwork();
+  const wallet = await BSVAgentWallet.load({ network, storageDir: WALLET_DIR });
+
+  try {
+    // First verify the payment structure
+    const verifyResult = await wallet.verifyPayment({ beef: payment.beef });
+    if (!verifyResult.valid) {
+      await wallet.destroy();
+      return { accepted: false, txid: payment.txid || null, satoshis: payment.satoshis, outputIndex: 0, walletAccepted: false, error: `verification failed: ${verifyResult.errors.join(', ')}` };
+    }
+
+    // Accept the payment (this broadcasts the transaction)
+    const acceptResult = await wallet.acceptPayment({
+      beef: payment.beef,
+      derivationPrefix: payment.derivationPrefix,
+      derivationSuffix: payment.derivationSuffix,
+      senderIdentityKey: payment.senderIdentityKey,
+      description: `Payment for ${serviceId}`,
+    });
+
+    await wallet.destroy();
+
+    if (!acceptResult.accepted) {
+      return { accepted: false, txid: payment.txid || null, satoshis: payment.satoshis, outputIndex: 0, walletAccepted: false, error: 'wallet rejected payment' };
+    }
+
+    return {
+      accepted: true,
+      txid: payment.txid,
+      satoshis: payment.satoshis,
+      outputIndex: 0,
+      walletAccepted: true,
+      error: null,
+    };
+  } catch (err: any) {
+    await wallet.destroy();
+    return { accepted: false, txid: payment.txid || null, satoshis: payment.satoshis, outputIndex: 0, walletAccepted: false, error: err.message };
+  }
+}
+
+/**
+ * Queue a service request for agent processing.
+ */
+async function queueForAgent(
+  msg: RelayMessage,
+  identityKey: string,
+  privKey: any,
+  serviceId: string
+): Promise<ProcessMessageResult> {
+  // Check if this request has already been processed to prevent duplicates
+  if (fs.existsSync(PATHS.serviceQueue)) {
+    const lines = fs.readFileSync(PATHS.serviceQueue, 'utf-8').trim().split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.requestId === msg.id) {
+          // Request already exists in queue - return existing status
+          return {
+            id: msg.id,
+            type: 'service-request',
+            serviceId,
+            action: entry.status === 'pending' ? 'already-queued' : `already-${entry.status}`,
+            paymentAccepted: true,
+            paymentTxid: entry.paymentTxid,
+            satoshisReceived: entry.satoshisReceived,
+            from: msg.from,
+            ack: true,
+          };
+        }
+      } catch {}
+    }
+  }
+
+  const sdk = await getSdk();
+  const payment = msg.payload?.payment as any;
+  const input = msg.payload?.input || msg.payload;
+
+  // Verify and accept payment
+  const walletIdentity = loadWalletIdentity();
+  const ourHash160 = sdk.Hash.hash160(sdk.PrivateKey.fromHex(walletIdentity.rootKeyHex).toPublicKey().encode(true));
+
+  // Find the service price using the service registry
+  const serviceDefinition = serviceManager.registry.get(serviceId);
+  let minPrice = 5; // default fallback
+
+  if (serviceDefinition) {
+    minPrice = serviceDefinition.defaultPrice;
+
+    // Validate service input if possible
+    const validation = serviceManager.validate(serviceId, input);
+    if (!validation.valid) {
+      // Send validation rejection
+      const rejectPayload = {
+        requestId: msg.id,
+        serviceId,
+        status: 'rejected',
+        reason: `Input validation failed: ${validation.error}`
+      };
+      const sig = await signRelayMessage(privKey, msg.from, 'service-response', rejectPayload);
+      await fetchWithTimeout(`${OVERLAY_URL}/relay/send`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ from: identityKey, to: msg.from, type: 'service-response', payload: rejectPayload, signature: sig }),
+      });
+
+      // Also add the rejected entry to the queue for tracking
+      const rejectedEntry = {
+        status: 'rejected',
+        requestId: msg.id,
+        serviceId,
+        from: msg.from,
+        identityKey,
+        input: input,
+        paymentTxid: null,
+        satoshisReceived: 0,
+        walletAccepted: false,
+        error: validation.error,
+        _ts: Date.now(),
+      };
+      appendToJsonl(PATHS.serviceQueue, rejectedEntry);
+
+      return {
+        id: msg.id,
+        type: 'service-request',
+        serviceId,
+        action: 'rejected',
+        reason: validation.error || 'input validation failed',
+        from: msg.from,
+        ack: true
+      };
+    }
+  } else {
+    // Fall back to legacy service loading for backward compatibility
+    const services = loadServices();
+    const svc = services.find(s => s.serviceId === serviceId);
+    minPrice = svc?.priceSats || 5;
+  }
+
+  const payResult = await verifyAndAcceptPayment(payment, minPrice, msg.from, serviceId, ourHash160);
+  if (!payResult.accepted) {
+    // Send rejection
+    const rejectPayload = { requestId: msg.id, serviceId, status: 'rejected', reason: `Payment rejected: ${payResult.error}` };
+    const sig = await signRelayMessage(privKey, msg.from, 'service-response', rejectPayload);
+    await fetchWithTimeout(`${OVERLAY_URL}/relay/send`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ from: identityKey, to: msg.from, type: 'service-response', payload: rejectPayload, signature: sig }),
+    });
+
+    // Also add the rejected entry to the queue for tracking
+    const rejectedEntry = {
+      status: 'rejected',
+      requestId: msg.id,
+      serviceId,
+      from: msg.from,
+      identityKey,
+      input: input,
+      paymentTxid: null,
+      satoshisReceived: 0,
+      walletAccepted: false,
+      error: payResult.error,
+      _ts: Date.now(),
+    };
+    appendToJsonl(PATHS.serviceQueue, rejectedEntry);
+
+    return { id: msg.id, type: 'service-request', serviceId, action: 'rejected', reason: payResult.error || 'payment rejected', from: msg.from, ack: true };
+  }
+
+  // Queue for agent processing
+  const queueEntry = {
+    status: 'pending',
+    requestId: msg.id,
+    serviceId,
+    from: msg.from,
+    identityKey,
+    input: input,
+    paymentTxid: payResult.txid,
+    satoshisReceived: payResult.satoshis,
+    walletAccepted: payResult.walletAccepted,
+    _ts: Date.now(),
+  };
+
+  appendToJsonl(PATHS.serviceQueue, queueEntry);
+
+  return {
+    id: msg.id,
+    type: 'service-request',
+    serviceId,
+    action: 'queued-for-agent',
+    paymentAccepted: true,
+    paymentTxid: payResult.txid,
+    satoshisReceived: payResult.satoshis,
+    from: msg.from,
+    ack: true,
+  };
+}
+
+/**
+ * Process a single relay message.
+ * Handles pings, service requests, pongs, and service responses.
+ */
+export async function processMessage(
+  msg: RelayMessage,
+  identityKey: string,
+  privKey: any
+): Promise<ProcessMessageResult> {
+  // Verify signature if present
+  const sigCheck: { valid: boolean | null; reason?: string } = msg.signature
+    ? await verifyRelaySignature(msg.from, msg.to, msg.type, msg.payload, msg.signature)
+    : { valid: null };
+
+  // Reject unsigned/forged service-requests
+  if (msg.type === 'service-request' && sigCheck.valid !== true) {
+    console.error(JSON.stringify({ event: 'signature-rejected', type: msg.type, from: msg.from, reason: sigCheck.reason || 'missing signature' }));
+    return {
+      id: msg.id,
+      type: msg.type,
+      from: msg.from,
+      action: 'rejected',
+      reason: 'invalid-signature',
+      signatureValid: sigCheck.valid,
+      ack: true,
+    };
+  }
+
+  if (msg.type === 'ping') {
+    // Auto-respond with pong
+    const pongPayload = {
+      text: 'pong',
+      inReplyTo: msg.id,
+      originalText: (msg.payload as any)?.text || null,
+    };
+    const pongSig = await signRelayMessage(privKey, msg.from, 'pong', pongPayload);
+    await fetch(`${OVERLAY_URL}/relay/send`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        from: identityKey,
+        to: msg.from,
+        type: 'pong',
+        payload: pongPayload,
+        signature: pongSig,
+      }),
+    });
+    return { id: msg.id, type: 'ping', action: 'replied-pong', from: msg.from, ack: true };
+  }
+
+  if (msg.type === 'service-request') {
+    const serviceId = (msg.payload as any)?.serviceId;
+
+    // Agent-routed mode: queue for the agent
+    if (process.env.AGENT_ROUTED === 'true') {
+      return await queueForAgent(msg, identityKey, privKey, serviceId);
+    }
+
+    // No hardcoded handlers in TypeScript version — always queue
+    return await queueForAgent(msg, identityKey, privKey, serviceId);
+  }
+
+  if (msg.type === 'pong') {
+    return {
+      id: msg.id,
+      type: 'pong',
+      action: 'received',
+      from: msg.from,
+      text: (msg.payload as any)?.text,
+      inReplyTo: (msg.payload as any)?.inReplyTo,
+      ack: true,
+    };
+  }
+
+  if (msg.type === 'service-response') {
+    const serviceId = (msg.payload as any)?.serviceId;
+    const status = (msg.payload as any)?.status;
+    const result = (msg.payload as any)?.result;
+
+    return {
+      id: msg.id,
+      type: 'service-response',
+      action: 'received',
+      from: msg.from,
+      serviceId,
+      status,
+      result,
+      requestId: (msg.payload as any)?.requestId,
+      direction: 'incoming-response',
+      ack: true,
+    };
+  }
+
+  // Unknown type
+  return {
+    id: msg.id,
+    type: msg.type,
+    from: msg.from,
+    payload: msg.payload,
+    signatureValid: sigCheck.valid,
+    action: 'unhandled',
+    ack: false,
+  };
+}

package/src/scripts/messaging/inbox.ts

@@ -0,0 +1,64 @@
+/**
+ * Inbox and ack commands.
+ */
+
+import { OVERLAY_URL } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadIdentity, verifyRelaySignature } from '../wallet/identity.js';
+
+/**
+ * Inbox command: fetch pending messages.
+ */
+export async function cmdInbox(args: string[]): Promise<never> {
+  const { identityKey } = await loadIdentity();
+
+  let since = '';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--since' && args[i + 1]) since = `&since=${args[++i]}`;
+  }
+
+  const resp = await fetch(`${OVERLAY_URL}/relay/inbox?identity=${identityKey}${since}`);
+  if (!resp.ok) {
+    const body = await resp.text();
+    return fail(`Relay inbox failed (${resp.status}): ${body}`);
+  }
+
+  const result = await resp.json();
+
+  // Verify signatures on received messages
+  const messages = await Promise.all(
+    result.messages.map(async (msg: any) => ({
+      ...msg,
+      signatureValid: msg.signature
+        ? (await verifyRelaySignature(msg.from, msg.to, msg.type, msg.payload, msg.signature)).valid
+        : null,
+    }))
+  );
+
+  return ok({ messages, count: messages.length, identityKey });
+}
+
+/**
+ * Ack command: acknowledge processed messages.
+ */
+export async function cmdAck(messageIds: string[]): Promise<never> {
+  if (!messageIds || messageIds.length === 0) {
+    return fail('Usage: ack <messageId> [messageId2 ...]');
+  }
+
+  const { identityKey } = await loadIdentity();
+
+  const resp = await fetch(`${OVERLAY_URL}/relay/ack`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ identity: identityKey, messageIds }),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    return fail(`Relay ack failed (${resp.status}): ${body}`);
+  }
+
+  const result = await resp.json();
+  return ok({ acked: result.acked, messageIds });
+}

package/src/scripts/messaging/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Messaging module exports.
+ */
+
+export * from './send.js';
+export * from './inbox.js';
+export * from './handlers.js';
+export * from './poll.js';
+export * from './connect.js';