openclaw-overlay-plugin 0.7.22

package/src/scripts/overlay/transaction.ts

@@ -0,0 +1,124 @@
+/**
+ * Overlay transaction building utilities.
+ * 
+ * Follows the clawdbot-overlay server API:
+ * - Submit: POST /submit with binary BEEF and X-Topics header
+ * - OP_RETURN format: OP_FALSE OP_RETURN <"clawdbot-overlay-v1"> <JSON>
+ */
+
+import { NETWORK, OVERLAY_URL, PROTOCOL_ID, WALLET_DIR } from '../config.js';
+import type { OverlayPayload } from '../types.js';
+import { Utils, PushDrop, Transaction } from '@bsv/sdk';
+import { BSVAgentWallet } from '../../core/wallet.js';
+
+/**
+ * Build an PushDrop locking script with JSON payload using SDK's Script class.
+ * 
+ * @param payload - The data to embed in the OP_RETURN
+ * @returns A proper Script object that the SDK can serialize
+ */
+export async function buildPushDropScript(wallet: BSVAgentWallet, payload: OverlayPayload): Promise<string> {
+  const jsonBytes = Utils.toArray(JSON.stringify(payload), 'utf8')
+  const fields: number[][] = [jsonBytes]
+  const token = new PushDrop(wallet._setup.wallet);
+  const script = await token.lock(fields, [0, PROTOCOL_ID], '1', 'self', true, true)
+  return script.toHex();
+}
+
+/**
+ * Build and submit an overlay transaction.
+ * @param payload - JSON data to store in OP_RETURN
+ * @param topic - Topic manager for submission
+ * @returns Transaction result with txid and funding info
+ */
+export async function buildRealOverlayTransaction(
+  payload: OverlayPayload,
+  topic: string
+): Promise<{ txid: string; funded: string; explorer: string }> {
+  
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR })
+  const lockingScript = await buildPushDropScript(wallet, payload)
+
+  const response = await wallet._setup.wallet.createAction({
+    description: 'topic manager submission',
+    outputs: [
+      {
+        lockingScript,
+        satoshis: 1,
+        outputDescription: 'overlay',
+        basket: topic, // basket is the topic manager
+      }
+    ],
+    options: {
+      acceptDelayedBroadcast: false,
+    }
+  })
+
+  // --- Submit to overlay ---
+  // Use binary BEEF with X-Topics header (matches clawdbot-overlay server API)
+  const submitResp = await fetch(`${OVERLAY_URL}/submit`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/octet-stream',
+      'X-Topics': JSON.stringify([topic]),
+    },
+    body: new Uint8Array(response.tx as number[]),
+  });
+
+  if (!submitResp.ok) {
+    const errText = await submitResp.text();
+    throw new Error(`Overlay submission failed: ${submitResp.status} — ${errText}`);
+  }
+
+  const wocNet = NETWORK === 'mainnet' ? '' : 'test.';
+  return {
+    txid: response.txid as string,
+    funded: 'stored-beef',
+    explorer: `https://${wocNet}whatsonchain.com/tx/${response.txid as string}`,
+  };
+}
+
+/**
+ * Lookup data from an overlay lookup service.
+ */
+export async function lookupOverlay(
+  service: string,
+  query: Record<string, unknown>
+): Promise<any> {
+  const resp = await fetch(`${OVERLAY_URL}/lookup`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ service, query }),
+  });
+
+  if (!resp.ok) {
+    const errText = await resp.text();
+    throw new Error(`Lookup failed: ${resp.status} — ${errText}`);
+  }
+
+  return resp.json();
+}
+
+/**
+ * Parse an overlay output from BEEF data.
+ * 
+ * Handles both formats:
+ * - OP_FALSE OP_RETURN <protocol> <json> (standard)
+ * - OP_RETURN <protocol> <json> (legacy)
+ */
+export async function parseOverlayOutput(
+  beefData: string | Uint8Array | number[],
+  outputIndex: number
+): Promise<{ data: OverlayPayload | null; txid: string | null }> {
+  try {
+    const tx = Transaction.fromBEEF(beefData as number[]);
+    const txid = tx.id('hex')
+    const output = tx.outputs[outputIndex];
+    if (!output) return { data: null, txid: null };
+
+    const { fields } = PushDrop.decode(output.lockingScript);
+    return { data: JSON.parse(Utils.toUTF8(fields[0])), txid };
+  } catch {
+    return { data: null, txid: null };
+  }
+}

package/src/scripts/payment/build.ts

@@ -0,0 +1,65 @@
+/**
+ * Payment building using a2a-bsv wallet.createPayment().
+ *
+ * This replaces the old buildDirectPayment() which used plain P2PKH scripts
+ * and manual UTXO management. The new implementation:
+ * - Uses proper BRC-29 locking scripts via wallet.createPayment()
+ * - Relies on wallet's createAction() for UTXO management
+ * - Uses noSend: true (recipient broadcasts via acceptPayment())
+ */
+
+import { NETWORK, WALLET_DIR } from '../config.js';
+import type { PaymentResult } from './types.js';
+
+import { BSVAgentWallet } from '../../core/index.js';
+
+async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
+  return BSVAgentWallet;
+}
+
+/**
+ * Build a BRC-29 payment using the a2a-bsv wallet.
+ *
+ * This creates a payment transaction using proper BRC-29 locking scripts.
+ * The transaction uses noSend: true, meaning:
+ * - The sender does NOT broadcast the transaction
+ * - The recipient broadcasts it when they call acceptPayment()
+ *
+ * @param recipientPubKey - Recipient's compressed public key (66 hex chars, 02/03 prefix)
+ * @param sats - Amount to send in satoshis
+ * @param desc - Optional description for the payment
+ * @returns PaymentResult with BEEF and derivation metadata for the recipient
+ */
+export async function buildDirectPayment(
+  recipientPubKey: string,
+  sats: number,
+  desc?: string
+): Promise<PaymentResult> {
+  // Validate recipient pubkey format
+  if (!/^0[23][0-9a-fA-F]{64}$/.test(recipientPubKey)) {
+    throw new Error('Recipient must be a compressed public key (66 hex chars starting with 02 or 03)');
+  }
+
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+
+  try {
+    const result = await wallet.createPayment({
+      to: recipientPubKey,
+      satoshis: sats,
+      description: desc || 'agent payment',
+    });
+
+    // Return format compatible with existing code
+    return {
+      beef: result.beef,
+      txid: result.txid,
+      satoshis: result.satoshis,
+      derivationPrefix: result.derivationPrefix,
+      derivationSuffix: result.derivationSuffix,
+      senderIdentityKey: result.senderIdentityKey,
+    };
+  } finally {
+    await wallet.destroy();
+  }
+}

package/src/scripts/payment/commands.ts

@@ -0,0 +1,92 @@
+/**
+ * Payment CLI commands: pay, verify, accept.
+ */
+
+import { NETWORK, WALLET_DIR } from '../config.js';
+import { ok, fail } from '../output.js';
+import { buildDirectPayment } from './build.js';
+
+import { BSVAgentWallet } from '../../core/index.js';
+
+async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
+  return BSVAgentWallet;
+}
+
+/**
+ * Pay command: send satoshis to another agent.
+ */
+export async function cmdPay(
+  pubkey: string | undefined,
+  satoshis: string | undefined,
+  description?: string
+): Promise<never> {
+  if (!pubkey || !satoshis) {
+    return fail('Usage: pay <pubkey> <satoshis> [description]');
+  }
+
+  const sats = parseInt(satoshis, 10);
+  if (isNaN(sats) || sats <= 0) {
+    return fail('satoshis must be a positive integer');
+  }
+
+  try {
+    const payment = await buildDirectPayment(pubkey, sats, description || 'agent payment');
+    return ok(payment);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/**
+ * Verify command: verify an incoming payment BEEF.
+ */
+export async function cmdVerify(beefBase64: string | undefined): Promise<never> {
+  if (!beefBase64) {
+    return fail('Usage: verify <beef_base64>');
+  }
+
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+
+  try {
+    const result = wallet.verifyPayment({ beef: beefBase64 });
+    await wallet.destroy();
+    return ok(result);
+  } catch (err) {
+    await wallet.destroy();
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/**
+ * Accept command: accept and internalize a payment.
+ */
+export async function cmdAccept(
+  beef: string | undefined,
+  derivationPrefix: string | undefined,
+  derivationSuffix: string | undefined,
+  senderIdentityKey: string | undefined,
+  description?: string
+): Promise<never> {
+  if (!beef || !derivationPrefix || !derivationSuffix || !senderIdentityKey) {
+    return fail('Usage: accept <beef> <prefix> <suffix> <senderKey> [description]');
+  }
+
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+
+  try {
+    const receipt = await wallet.acceptPayment({
+      beef,
+      derivationPrefix,
+      derivationSuffix,
+      senderIdentityKey,
+      description: description || undefined,
+    });
+    await wallet.destroy();
+    return ok(receipt);
+  } catch (err) {
+    await wallet.destroy();
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+}

package/src/scripts/payment/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Payment module exports.
+ */
+
+export * from './types.js';
+export * from './build.js';
+export * from './commands.js';

package/src/scripts/payment/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Payment-specific type definitions.
+ */
+
+export interface PaymentResult {
+  /** Base64-encoded Atomic BEEF transaction data */
+  beef: string;
+  /** Transaction ID (hex) */
+  txid: string;
+  /** Amount paid in satoshis */
+  satoshis: number;
+  /** BRC-29 derivation prefix (base64) - needed by recipient */
+  derivationPrefix: string;
+  /** BRC-29 derivation suffix (base64) - needed by recipient */
+  derivationSuffix: string;
+  /** Sender's identity key (compressed hex) - needed by recipient */
+  senderIdentityKey: string;
+}
+
+export interface PaymentParams {
+  /** Recipient's compressed public key (hex, 66 chars starting with 02/03) */
+  to: string;
+  /** Amount to pay in satoshis */
+  satoshis: number;
+  /** Optional human-readable description */
+  description?: string;
+}
+
+export interface VerifyParams {
+  /** Base64-encoded BEEF */
+  beef: string;
+  /** Expected amount (optional) */
+  expectedAmount?: number;
+  /** Expected sender identity key (optional) */
+  expectedSender?: string;
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  txid: string;
+  outputCount: number;
+  errors: string[];
+}
+
+export interface AcceptParams {
+  /** Base64-encoded Atomic BEEF */
+  beef: string;
+  /** Output index (default: 0) */
+  vout?: number;
+  /** BRC-29 derivation prefix from PaymentResult */
+  derivationPrefix: string;
+  /** BRC-29 derivation suffix from PaymentResult */
+  derivationSuffix: string;
+  /** Sender's identity key from PaymentResult */
+  senderIdentityKey: string;
+  /** Optional description */
+  description?: string;
+}
+
+export interface AcceptResult {
+  accepted: boolean;
+}

package/src/scripts/services/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Services module exports.
+ */
+
+export * from './request.js';
+export * from './respond.js';
+export * from './queue.js';

package/src/scripts/services/queue.ts

@@ -0,0 +1,35 @@
+/**
+ * Service queue commands.
+ */
+
+import fs from 'node:fs';
+import { PATHS } from '../config.js';
+import { ok } from '../output.js';
+import { readJsonl } from '../utils/storage.js';
+
+/**
+ * Service queue command: list pending service requests.
+ */
+export async function cmdServiceQueue(): Promise<never> {
+  if (!fs.existsSync(PATHS.serviceQueue)) {
+    return ok({ pending: [], count: 0 });
+  }
+
+  const entries = readJsonl<any>(PATHS.serviceQueue);
+  const pending = entries.filter(e => e.status === 'pending');
+
+  return ok({ pending, count: pending.length, total: entries.length });
+}
+
+/**
+ * Research queue command: list pending research requests.
+ */
+export async function cmdResearchQueue(): Promise<never> {
+  if (!fs.existsSync(PATHS.researchQueue)) {
+    return ok({ pending: [] });
+  }
+
+  const entries = readJsonl<any>(PATHS.researchQueue);
+
+  return ok({ pending: entries, count: entries.length });
+}

package/src/scripts/services/request.ts

@@ -0,0 +1,98 @@
+/**
+ * Service request command.
+ */
+
+import { OVERLAY_URL } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadIdentity, signRelayMessage } from '../wallet/identity.js';
+import { buildDirectPayment } from '../payment/build.js';
+
+/**
+ * Request service command: send a service request with optional payment.
+ */
+export async function cmdRequestService(
+  targetKey: string | undefined,
+  serviceId: string | undefined,
+  satsStr?: string,
+  inputJsonStr?: string
+): Promise<never> {
+  if (!targetKey || !serviceId) {
+    return fail('Usage: request-service <identityKey> <serviceId> [sats] [inputJson]');
+  }
+
+  if (!/^0[23][0-9a-fA-F]{64}$/.test(targetKey)) {
+    return fail('Target must be a compressed public key (66 hex chars, 02/03 prefix)');
+  }
+
+  const { identityKey, privKey } = await loadIdentity();
+  const sats = parseInt(satsStr || '5', 10);
+
+  // Parse optional input JSON
+  let inputData: unknown = null;
+  if (inputJsonStr) {
+    try {
+      inputData = JSON.parse(inputJsonStr);
+    } catch {
+      return fail('inputJson must be valid JSON');
+    }
+  }
+
+  // Build the service request payload
+  let paymentData: any = null;
+
+  if (sats > 0) {
+    try {
+      const payment = await buildDirectPayment(targetKey, sats, `service-request: ${serviceId}`);
+      paymentData = {
+        beef: payment.beef,
+        txid: payment.txid,
+        satoshis: payment.satoshis,
+        derivationPrefix: payment.derivationPrefix,
+        derivationSuffix: payment.derivationSuffix,
+        senderIdentityKey: payment.senderIdentityKey,
+      };
+    } catch (err: any) {
+      // Payment failed — send request without payment
+      paymentData = { error: String(err.message || err) };
+    }
+  }
+
+  const requestPayload = {
+    serviceId,
+    ...(inputData ? { input: inputData } : {}),
+    payment: paymentData,
+    requestedAt: new Date().toISOString(),
+  };
+
+  const signature = await signRelayMessage(privKey, targetKey, 'service-request', requestPayload);
+
+  const resp = await fetch(`${OVERLAY_URL}/relay/send`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      from: identityKey,
+      to: targetKey,
+      type: 'service-request',
+      payload: requestPayload,
+      signature,
+    }),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    return fail(`Relay send failed (${resp.status}): ${body}`);
+  }
+
+  const result = await resp.json();
+
+  return ok({
+    sent: true,
+    requestId: result.id,
+    to: targetKey,
+    serviceId,
+    paymentIncluded: paymentData && !paymentData.error,
+    paymentTxid: paymentData?.txid || null,
+    satoshis: paymentData?.satoshis || 0,
+    note: 'Poll for service-response to get the result',
+  });
+}

package/src/scripts/services/respond.ts

@@ -0,0 +1,149 @@
+/**
+ * Service response commands.
+ */
+
+import fs from 'node:fs';
+import { OVERLAY_URL, PATHS } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadIdentity, signRelayMessage } from '../wallet/identity.js';
+import { updateServiceQueueStatus } from '../utils/storage.js';
+
+/**
+ * Respond to a service request.
+ */
+export async function cmdRespondService(
+  requestId: string | undefined,
+  recipientKey: string | undefined,
+  serviceId: string | undefined,
+  resultJson: string | undefined
+): Promise<never> {
+  if (!requestId || !recipientKey || !serviceId || !resultJson) {
+    return fail('Usage: respond-service <requestId> <recipientKey> <serviceId> <resultJson>');
+  }
+
+  let result: unknown;
+  try {
+    result = JSON.parse(resultJson);
+  } catch {
+    return fail('resultJson must be valid JSON');
+  }
+
+  const { identityKey, privKey } = await loadIdentity();
+
+  // Check if already processed before sending response (idempotency)
+  if (fs.existsSync(PATHS.serviceQueue)) {
+    const lines = fs.readFileSync(PATHS.serviceQueue, 'utf-8').trim().split('\n').filter(Boolean);
+    const finalStatuses = ['fulfilled', 'rejected', 'delivery_failed', 'failed', 'error'];
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.requestId === requestId && finalStatuses.includes(entry.status)) {
+          return ok({
+            sent: false,
+            requestId,
+            serviceId,
+            to: recipientKey,
+            message: `Request already processed with status: ${entry.status}`,
+            alreadyProcessed: true,
+            previousStatus: entry.status
+          });
+        }
+      } catch {}
+    }
+  }
+
+  const responsePayload = {
+    requestId,
+    serviceId,
+    status: 'fulfilled',
+    result,
+  };
+
+  const sig = await signRelayMessage(privKey, recipientKey, 'service-response', responsePayload);
+  const resp = await fetch(`${OVERLAY_URL}/relay/send`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      from: identityKey,
+      to: recipientKey,
+      type: 'service-response',
+      payload: responsePayload,
+      signature: sig,
+    }),
+  });
+
+  if (!resp.ok) {
+    // Mark as failed in queue using atomic update
+    updateServiceQueueStatus(requestId, 'failed', {
+      failedAt: Date.now(),
+      error: `Relay send failed: ${resp.status}`
+    });
+    return fail(`Relay send failed: ${resp.status}`);
+  }
+
+  // Mark as fulfilled in queue using atomic update
+  updateServiceQueueStatus(requestId, 'fulfilled', {
+    fulfilledAt: Date.now()
+  });
+
+  return ok({ sent: true, requestId, serviceId, to: recipientKey });
+}
+
+/**
+ * Respond to a research request with results.
+ */
+export async function cmdResearchRespond(resultJsonPath: string | undefined): Promise<never> {
+  if (!resultJsonPath) return fail('Usage: research-respond <resultJsonFile>');
+  if (!fs.existsSync(resultJsonPath)) return fail(`File not found: ${resultJsonPath}`);
+
+  const result = JSON.parse(fs.readFileSync(resultJsonPath, 'utf-8'));
+  const { requestId, from: recipientKey, query, research } = result;
+
+  if (!requestId || !recipientKey || !research) {
+    return fail('Result JSON must have: requestId, from, query, research');
+  }
+
+  const { identityKey, privKey } = await loadIdentity();
+
+  const responsePayload = {
+    requestId,
+    serviceId: 'web-research',
+    status: 'fulfilled',
+    result: research,
+    paymentAccepted: true,
+    paymentTxid: result.paymentTxid || null,
+    satoshisReceived: result.satoshisReceived || 0,
+    walletAccepted: result.walletAccepted ?? true,
+  };
+
+  const sig = await signRelayMessage(privKey, recipientKey, 'service-response', responsePayload);
+  const sendResp = await fetch(`${OVERLAY_URL}/relay/send`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      from: identityKey,
+      to: recipientKey,
+      type: 'service-response',
+      payload: responsePayload,
+      signature: sig,
+    }),
+  });
+
+  if (!sendResp.ok) {
+    return fail(`Failed to send response: ${await sendResp.text()}`);
+  }
+
+  const sendResult = await sendResp.json();
+
+  // Remove from queue
+  if (fs.existsSync(PATHS.researchQueue)) {
+    const lines = fs.readFileSync(PATHS.researchQueue, 'utf-8').trim().split('\n').filter(Boolean);
+    const remaining = lines.filter(l => {
+      try { return JSON.parse(l).requestId !== requestId; } catch { return true; }
+    });
+    fs.writeFileSync(PATHS.researchQueue, remaining.length ? remaining.join('\n') + '\n' : '');
+  }
+
+  return ok({ responded: true, requestId, to: recipientKey, query, pushed: sendResult.pushed });
+}