openclaw-overlay-plugin 0.7.22

package/src/scripts/types.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared TypeScript interfaces for the overlay CLI.
+ */
+
+export interface WalletIdentity {
+  rootKeyHex: string;
+  identityKey: string;
+  network: 'mainnet' | 'testnet';
+}
+
+export interface PaymentResult {
+  beef: string;
+  txid: string;
+  satoshis: number;
+  derivationPrefix: string;
+  derivationSuffix: string;
+  senderIdentityKey: string;
+}
+
+export interface PaymentParams {
+  to: string;
+  satoshis: number;
+  description?: string;
+}
+
+export interface ServiceAdvertisement {
+  serviceId: string;
+  name: string;
+  description: string;
+  priceSats: number;
+  txid?: string;
+  registeredAt?: string;
+}
+
+export interface Message {
+  id: string;
+  from: string;
+  to: string;
+  type: string;
+  payload: unknown;
+  signature?: string;
+  timestamp?: number;
+}
+
+export interface CommandResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+export interface Registration {
+  identityKey: string;
+  agentName: string;
+  agentDescription: string;
+  overlayUrl: string;
+  identityTxid: string;
+  serviceTxid: string | null;
+  funded: string;
+  registeredAt: string;
+}
+
+export interface OverlayPayload {
+  protocol: string;
+  type: string;
+  identityKey?: string;
+  [key: string]: unknown;
+}
+
+export interface VerifyAndAcceptResult {
+  accepted: boolean;
+  txid: string | null;
+  satoshis: number;
+  outputIndex: number;
+  walletAccepted: boolean;
+  error: string | null;
+}
+
+export interface ProcessMessageResult {
+  id: string;
+  type: string;
+  action: string;
+  from: string;
+  ack: boolean;
+  [key: string]: unknown;
+}
+
+export interface RelayMessage {
+  id: string;
+  from: string;
+  to: string;
+  type: string;
+  payload: Record<string, unknown>;
+  signature?: string;
+}
+
+export interface XVerification {
+  identityKey: string;
+  xHandle: string;
+  xUserId: string;
+  tweetId: string;
+  tweetUrl: string;
+  signature: string;
+  verifiedAt: string;
+  txid?: string | null;
+}
+
+export interface StoredChange {
+  txHex: string;
+  txid: string;
+  vout: number;
+  satoshis: number;
+  sourceChain?: SourceChainEntry[];
+  savedAt: string;
+}
+
+export interface SourceChainEntry {
+  txHex: string;
+  txid: string;
+  merklePathHex?: string;
+  blockHeight?: number;
+}

package/src/scripts/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Utility module exports.
+ */
+
+export * from './woc.js';
+export * from './storage.js';
+export * from './merkle.js';

package/src/scripts/utils/merkle.ts

@@ -0,0 +1,57 @@
+/**
+ * Merkle path utilities for SPV proofs.
+ */
+
+import type { MerklePath as MerklePathType } from '@bsv/sdk';
+
+// We'll import MerklePath dynamically to avoid issues with ESM resolution
+let _MerklePath: typeof MerklePathType | null = null;
+
+async function getMerklePath(): Promise<typeof MerklePathType> {
+  if (_MerklePath) return _MerklePath;
+  const sdk = await import('@bsv/sdk');
+  _MerklePath = sdk.MerklePath;
+  return _MerklePath;
+}
+
+/**
+ * Build a MerklePath from TSC (Transaction Status Check) proof data.
+ * @param txid - Transaction ID
+ * @param txIndex - Transaction's index in the block
+ * @param nodes - Array of sibling hashes (or '*' for duplicate)
+ * @param blockHeight - Block height
+ */
+export async function buildMerklePathFromTSC(
+  txid: string,
+  txIndex: number,
+  nodes: string[],
+  blockHeight: number
+): Promise<MerklePathType> {
+  const MerklePath = await getMerklePath();
+  const treeHeight = nodes.length;
+  const mpPath: Array<Array<{ offset: number; hash?: string; txid?: boolean; duplicate?: boolean }>> = [];
+
+  // Level 0
+  const level0: Array<{ offset: number; hash?: string; txid?: boolean; duplicate?: boolean }> = [
+    { offset: txIndex, hash: txid, txid: true }
+  ];
+  if (nodes[0] === '*') {
+    level0.push({ offset: txIndex ^ 1, duplicate: true });
+  } else {
+    level0.push({ offset: txIndex ^ 1, hash: nodes[0] });
+  }
+  level0.sort((a, b) => a.offset - b.offset);
+  mpPath.push(level0);
+
+  // Higher levels
+  for (let i = 1; i < treeHeight; i++) {
+    const siblingOffset = (txIndex >> i) ^ 1;
+    if (nodes[i] === '*') {
+      mpPath.push([{ offset: siblingOffset, duplicate: true }]);
+    } else {
+      mpPath.push([{ offset: siblingOffset, hash: nodes[i] }]);
+    }
+  }
+
+  return new MerklePath(blockHeight, mpPath);
+}

package/src/scripts/utils/storage.ts

@@ -0,0 +1,231 @@
+/**
+ * File-based storage helpers for registration, services, and queues.
+ */
+
+import fs from 'node:fs';
+import { OVERLAY_STATE_DIR, PATHS } from '../config.js';
+import type { Registration, ServiceAdvertisement, XVerification, StoredChange } from '../types.js';
+
+/**
+ * Ensure the overlay state directory exists.
+ */
+export function ensureStateDir(): void {
+  fs.mkdirSync(OVERLAY_STATE_DIR, { recursive: true });
+}
+
+/**
+ * Load registration data from disk.
+ */
+export function loadRegistration(): Registration | null {
+  try {
+    if (fs.existsSync(PATHS.registration)) {
+      return JSON.parse(fs.readFileSync(PATHS.registration, 'utf-8'));
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return null;
+}
+
+/**
+ * Save registration data to disk.
+ */
+export function saveRegistration(data: Registration): void {
+  ensureStateDir();
+  fs.writeFileSync(PATHS.registration, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Delete registration file.
+ */
+export function deleteRegistration(): void {
+  try {
+    fs.unlinkSync(PATHS.registration);
+  } catch {
+    // Ignore if file doesn't exist
+  }
+}
+
+/**
+ * Load services list from disk.
+ */
+export function loadServices(): ServiceAdvertisement[] {
+  try {
+    if (fs.existsSync(PATHS.services)) {
+      return JSON.parse(fs.readFileSync(PATHS.services, 'utf-8'));
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return [];
+}
+
+/**
+ * Save services list to disk.
+ */
+export function saveServices(services: ServiceAdvertisement[]): void {
+  ensureStateDir();
+  fs.writeFileSync(PATHS.services, JSON.stringify(services, null, 2), 'utf-8');
+}
+
+/**
+ * Load X verifications from disk.
+ */
+export function loadXVerifications(): XVerification[] {
+  try {
+    if (fs.existsSync(PATHS.xVerifications)) {
+      return JSON.parse(fs.readFileSync(PATHS.xVerifications, 'utf-8'));
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return [];
+}
+
+/**
+ * Save X verifications to disk.
+ */
+export function saveXVerifications(verifications: XVerification[]): void {
+  ensureStateDir();
+  fs.writeFileSync(PATHS.xVerifications, JSON.stringify(verifications, null, 2), 'utf-8');
+}
+
+/**
+ * Append a line to a JSONL file.
+ */
+export function appendToJsonl(filePath: string, entry: Record<string, unknown>): void {
+  ensureStateDir();
+  fs.appendFileSync(filePath, JSON.stringify(entry) + '\n');
+}
+
+/**
+ * Read and parse a JSONL file.
+ */
+export function readJsonl<T>(filePath: string): T[] {
+  if (!fs.existsSync(filePath)) return [];
+  const lines = fs.readFileSync(filePath, 'utf-8').trim().split('\n').filter(Boolean);
+  return lines.map(line => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }).filter(Boolean) as T[];
+}
+
+/**
+ * Load stored change BEEF data.
+ */
+export function loadStoredChange(): StoredChange | null {
+  try {
+    if (fs.existsSync(PATHS.latestChange)) {
+      return JSON.parse(fs.readFileSync(PATHS.latestChange, 'utf-8'));
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return null;
+}
+
+/**
+ * Save stored change BEEF data.
+ */
+export function saveStoredChange(data: StoredChange): void {
+  ensureStateDir();
+  fs.writeFileSync(PATHS.latestChange, JSON.stringify(data));
+}
+
+/**
+ * Delete stored change file.
+ */
+export function deleteStoredChange(): void {
+  try {
+    fs.unlinkSync(PATHS.latestChange);
+  } catch {
+    // Ignore if file doesn't exist
+  }
+}
+
+/**
+ * Clean up old entries from service queue.
+ * Removes entries older than maxAgeMs or entries with final statuses older than finalStatusMaxAgeMs.
+ */
+export function cleanupServiceQueue(maxAgeMs: number = 24 * 60 * 60 * 1000, finalStatusMaxAgeMs: number = 2 * 60 * 60 * 1000): void {
+  if (!fs.existsSync(PATHS.serviceQueue)) return;
+
+  const now = Date.now();
+  const finalStatuses = ['fulfilled', 'rejected', 'delivery_failed', 'failed', 'error'];
+
+  const lines = fs.readFileSync(PATHS.serviceQueue, 'utf-8').trim().split('\n').filter(Boolean);
+  const keptLines: string[] = [];
+  let removedCount = 0;
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      const entryAge = now - (entry._ts || 0);
+
+      // Always keep pending entries that aren't too old
+      if (entry.status === 'pending' && entryAge < maxAgeMs) {
+        keptLines.push(line);
+        continue;
+      }
+
+      // Keep final status entries only if they're recent
+      if (finalStatuses.includes(entry.status) && entryAge < finalStatusMaxAgeMs) {
+        keptLines.push(line);
+        continue;
+      }
+
+      // Remove this entry
+      removedCount++;
+    } catch {
+      // Keep malformed entries to avoid data loss
+      keptLines.push(line);
+    }
+  }
+
+  if (removedCount > 0) {
+    fs.writeFileSync(PATHS.serviceQueue, keptLines.join('\n') + (keptLines.length ? '\n' : ''));
+    console.error(JSON.stringify({ event: 'queue-cleanup', removed: removedCount, kept: keptLines.length }));
+  }
+}
+
+/**
+ * Atomically update a service queue entry status.
+ * Returns true if the entry was found and updated, false otherwise.
+ */
+export function updateServiceQueueStatus(
+  requestId: string,
+  newStatus: string,
+  additionalFields: Record<string, any> = {}
+): boolean {
+  if (!fs.existsSync(PATHS.serviceQueue)) return false;
+
+  const lines = fs.readFileSync(PATHS.serviceQueue, 'utf-8').trim().split('\n').filter(Boolean);
+  let updated = false;
+
+  const updatedLines = lines.map(line => {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.requestId === requestId) {
+        updated = true;
+        return JSON.stringify({
+          ...entry,
+          status: newStatus,
+          ...additionalFields,
+          updatedAt: Date.now()
+        });
+      }
+      return line;
+    } catch {
+      return line;
+    }
+  });
+
+  if (updated) {
+    fs.writeFileSync(PATHS.serviceQueue, updatedLines.join('\n') + '\n');
+  }
+
+  return updated;
+}

package/src/scripts/utils/woc.ts

@@ -0,0 +1,106 @@
+/**
+ * WhatsOnChain API helpers with retry logic and rate limiting.
+ */
+
+import { NETWORK, WOC_API_KEY } from '../config.js';
+
+/**
+ * Fetch from WhatsonChain with optional API key auth and retry logic.
+ * Retries on 429 (rate limit) and 5xx errors with exponential backoff.
+ * Includes timeout to prevent hanging indefinitely.
+ */
+export async function wocFetch(
+  urlPath: string,
+  options: RequestInit = {},
+  maxRetries = 3,
+  timeoutMs = 30000
+): Promise<Response> {
+  const wocNet = NETWORK === 'mainnet' ? 'main' : 'test';
+  const base = `https://api.whatsonchain.com/v1/bsv/${wocNet}`;
+  const url = urlPath.startsWith('http') ? urlPath : `${base}${urlPath}`;
+  const headers: Record<string, string> = { ...(options.headers as Record<string, string> || {}) };
+  if (WOC_API_KEY) {
+    headers['Authorization'] = `Bearer ${WOC_API_KEY}`;
+  }
+
+  let lastError: Error | undefined;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+      const resp = await fetch(url, { ...options, headers, signal: controller.signal });
+      clearTimeout(timeout);
+
+      // Retry on 429 (rate limit) or 5xx (server error)
+      if ((resp.status === 429 || resp.status >= 500) && attempt < maxRetries) {
+        const delayMs = Math.min(1000 * Math.pow(2, attempt), 8000);
+        await new Promise(r => setTimeout(r, delayMs));
+        continue;
+      }
+
+      return resp;
+    } catch (err) {
+      lastError = err as Error;
+      if (attempt < maxRetries) {
+        const delayMs = Math.min(1000 * Math.pow(2, attempt), 8000);
+        await new Promise(r => setTimeout(r, delayMs));
+        continue;
+      }
+    }
+  }
+
+  throw lastError || new Error('WoC fetch failed after retries');
+}
+
+/**
+ * Fetch with timeout using AbortController.
+ */
+export async function fetchWithTimeout(
+  url: string,
+  options: RequestInit = {},
+  timeoutMs = 15000
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(url, { ...options, signal: controller.signal });
+    return resp;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Fetch a pre-built BEEF from WhatsonChain for a given txid.
+ * WoC returns raw binary BEEF that includes the full source chain and merkle proofs.
+ */
+export async function fetchBeefFromWoC(txid: string): Promise<Uint8Array | null> {
+  try {
+    const resp = await wocFetch(`/tx/${txid}/beef`);
+    if (!resp.ok) return null;
+    const hexStr = (await resp.text()).trim();
+    if (!hexStr || hexStr.length < 8) return null;
+    const bytes = hexStr.match(/.{2}/g)!.map(h => parseInt(h, 16));
+    return new Uint8Array(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the WoC base URL for the current network.
+ */
+export function getWocBaseUrl(): string {
+  const wocNet = NETWORK === 'mainnet' ? 'main' : 'test';
+  return `https://api.whatsonchain.com/v1/bsv/${wocNet}`;
+}
+
+/**
+ * Get the explorer base URL for the current network.
+ */
+export function getExplorerBaseUrl(): string {
+  return NETWORK === 'mainnet'
+    ? 'https://whatsonchain.com'
+    : 'https://test.whatsonchain.com';
+}