openclaw-overlay-plugin 0.7.22

package/dist/scripts/payment/index.d.ts

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

package/dist/scripts/payment/index.js

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

package/dist/scripts/payment/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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/dist/scripts/payment/types.js

@@ -0,0 +1,4 @@
+/**
+ * Payment-specific type definitions.
+ */
+export {};

package/dist/scripts/services/index.d.ts

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

package/dist/scripts/services/index.js

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

package/dist/scripts/services/queue.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Service queue commands.
+ */
+/**
+ * Service queue command: list pending service requests.
+ */
+export declare function cmdServiceQueue(): Promise<never>;
+/**
+ * Research queue command: list pending research requests.
+ */
+export declare function cmdResearchQueue(): Promise<never>;

package/dist/scripts/services/queue.js

@@ -0,0 +1,28 @@
+/**
+ * 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() {
+    if (!fs.existsSync(PATHS.serviceQueue)) {
+        return ok({ pending: [], count: 0 });
+    }
+    const entries = readJsonl(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() {
+    if (!fs.existsSync(PATHS.researchQueue)) {
+        return ok({ pending: [] });
+    }
+    const entries = readJsonl(PATHS.researchQueue);
+    return ok({ pending: entries, count: entries.length });
+}

package/dist/scripts/services/request.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Service request command.
+ */
+/**
+ * Request service command: send a service request with optional payment.
+ */
+export declare function cmdRequestService(targetKey: string | undefined, serviceId: string | undefined, satsStr?: string, inputJsonStr?: string): Promise<never>;

package/dist/scripts/services/request.js

@@ -0,0 +1,82 @@
+/**
+ * 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, serviceId, satsStr, inputJsonStr) {
+    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 = null;
+    if (inputJsonStr) {
+        try {
+            inputData = JSON.parse(inputJsonStr);
+        }
+        catch {
+            return fail('inputJson must be valid JSON');
+        }
+    }
+    // Build the service request payload
+    let paymentData = 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) {
+            // 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/dist/scripts/services/respond.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Service response commands.
+ */
+/**
+ * Respond to a service request.
+ */
+export declare function cmdRespondService(requestId: string | undefined, recipientKey: string | undefined, serviceId: string | undefined, resultJson: string | undefined): Promise<never>;
+/**
+ * Respond to a research request with results.
+ */
+export declare function cmdResearchRespond(resultJsonPath: string | undefined): Promise<never>;

package/dist/scripts/services/respond.js

@@ -0,0 +1,132 @@
+/**
+ * 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, recipientKey, serviceId, resultJson) {
+    if (!requestId || !recipientKey || !serviceId || !resultJson) {
+        return fail('Usage: respond-service <requestId> <recipientKey> <serviceId> <resultJson>');
+    }
+    let result;
+    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) {
+    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 });
+}

package/dist/scripts/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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/dist/scripts/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared TypeScript interfaces for the overlay CLI.
+ */
+export {};

package/dist/scripts/utils/index.d.ts

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

package/dist/scripts/utils/index.js

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

package/dist/scripts/utils/merkle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Merkle path utilities for SPV proofs.
+ */
+import type { MerklePath as MerklePathType } from '@bsv/sdk';
+/**
+ * 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 declare function buildMerklePathFromTSC(txid: string, txIndex: number, nodes: string[], blockHeight: number): Promise<MerklePathType>;

package/dist/scripts/utils/merkle.js

@@ -0,0 +1,47 @@
+/**
+ * Merkle path utilities for SPV proofs.
+ */
+// We'll import MerklePath dynamically to avoid issues with ESM resolution
+let _MerklePath = null;
+async function getMerklePath() {
+    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, txIndex, nodes, blockHeight) {
+    const MerklePath = await getMerklePath();
+    const treeHeight = nodes.length;
+    const mpPath = [];
+    // Level 0
+    const level0 = [
+        { 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/dist/scripts/utils/storage.d.ts

@@ -0,0 +1,66 @@
+/**
+ * File-based storage helpers for registration, services, and queues.
+ */
+import type { Registration, ServiceAdvertisement, XVerification, StoredChange } from '../types.js';
+/**
+ * Ensure the overlay state directory exists.
+ */
+export declare function ensureStateDir(): void;
+/**
+ * Load registration data from disk.
+ */
+export declare function loadRegistration(): Registration | null;
+/**
+ * Save registration data to disk.
+ */
+export declare function saveRegistration(data: Registration): void;
+/**
+ * Delete registration file.
+ */
+export declare function deleteRegistration(): void;
+/**
+ * Load services list from disk.
+ */
+export declare function loadServices(): ServiceAdvertisement[];
+/**
+ * Save services list to disk.
+ */
+export declare function saveServices(services: ServiceAdvertisement[]): void;
+/**
+ * Load X verifications from disk.
+ */
+export declare function loadXVerifications(): XVerification[];
+/**
+ * Save X verifications to disk.
+ */
+export declare function saveXVerifications(verifications: XVerification[]): void;
+/**
+ * Append a line to a JSONL file.
+ */
+export declare function appendToJsonl(filePath: string, entry: Record<string, unknown>): void;
+/**
+ * Read and parse a JSONL file.
+ */
+export declare function readJsonl<T>(filePath: string): T[];
+/**
+ * Load stored change BEEF data.
+ */
+export declare function loadStoredChange(): StoredChange | null;
+/**
+ * Save stored change BEEF data.
+ */
+export declare function saveStoredChange(data: StoredChange): void;
+/**
+ * Delete stored change file.
+ */
+export declare function deleteStoredChange(): void;
+/**
+ * Clean up old entries from service queue.
+ * Removes entries older than maxAgeMs or entries with final statuses older than finalStatusMaxAgeMs.
+ */
+export declare function cleanupServiceQueue(maxAgeMs?: number, finalStatusMaxAgeMs?: number): void;
+/**
+ * Atomically update a service queue entry status.
+ * Returns true if the entry was found and updated, false otherwise.
+ */
+export declare function updateServiceQueueStatus(requestId: string, newStatus: string, additionalFields?: Record<string, any>): boolean;