openclaw-overlay-plugin 0.8.14 → 0.8.16

package/dist/src/core/types.d.ts

@@ -1,94 +0,0 @@
-/**
- * @a2a-bsv/core — Type definitions for agent-to-agent BSV payments.
- */
-/** Wallet configuration for creating or loading an agent wallet. */
-export interface WalletConfig {
-    /** BSV network to use. */
-    network: 'mainnet' | 'testnet' | 'local';
-    /** Directory path for SQLite wallet persistence. */
-    storageDir: string;
-    /** Optional: pre-existing root private key hex. If omitted on create(), a new one is generated. */
-    rootKeyHex?: string;
-    /** Optional TAAL API key for ARC broadcasting. Falls back to public default. */
-    taalApiKey?: string;
-    /** Optional fee model in sat/KB. Falls back to BSV_FEE_MODEL env var or default 100 sat/KB. */
-    feeModel?: number;
-}
-/** Parameters for building a payment transaction. */
-export interface PaymentParams {
-    /** Recipient's compressed public key (hex) or BSV address. */
-    to: string;
-    /** Amount to pay in satoshis. */
-    satoshis: number;
-    /** Human-readable description (5-50 chars per BRC-100). */
-    description?: string;
-    /** Optional metadata embedded as OP_RETURN (future use). */
-    metadata?: {
-        taskId?: string;
-        protocol?: string;
-    };
-}
-/** Result from building a payment. */
-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 to internalize. */
-    derivationPrefix: string;
-    /** BRC-29 derivation suffix (base64). Needed by recipient to internalize. */
-    derivationSuffix: string;
-    /** Sender's identity key (compressed hex). Needed by recipient to internalize. */
-    senderIdentityKey: string;
-}
-/** Parameters for verifying an incoming payment. */
-export interface VerifyParams {
-    /** Base64-encoded Atomic BEEF data. */
-    beef: string;
-    /** Expected payment amount in satoshis. */
-    expectedAmount?: number;
-    /** Expected sender identity key (optional). */
-    expectedSender?: string;
-}
-/** Result from verifying a payment. */
-export interface VerifyResult {
-    /** Whether the payment passes all checks. */
-    valid: boolean;
-    /** Transaction ID (hex). */
-    txid: string;
-    /** Number of outputs found in the transaction. */
-    outputCount: number;
-    /** Errors encountered during verification. */
-    errors: string[];
-}
-/** Parameters for accepting (internalizing) a verified payment. */
-export interface AcceptParams {
-    /** Base64-encoded Atomic BEEF data. */
-    beef: string;
-    /** The output index to internalize (default: 0). */
-    vout?: number;
-    /** BRC-29 derivation prefix from the PaymentResult. */
-    derivationPrefix: string;
-    /** BRC-29 derivation suffix from the PaymentResult. */
-    derivationSuffix: string;
-    /** Sender's identity key from the PaymentResult. */
-    senderIdentityKey: string;
-    /** Human-readable description for wallet records (5-50 chars). */
-    description?: string;
-}
-/** Result from accepting a payment. */
-export interface AcceptResult {
-    /** Whether the payment was accepted. */
-    accepted: boolean;
-}
-/** Serializable wallet identity info, persisted alongside the SQLite database. */
-export interface WalletIdentity {
-    /** The root private key (hex). Guard this carefully. */
-    rootKeyHex: string;
-    /** The wallet's public identity key (compressed hex). */
-    identityKey: string;
-    /** Network this wallet targets. */
-    network: 'mainnet' | 'testnet' | 'local';
-}

package/dist/src/core/types.js

@@ -1,4 +0,0 @@
-/**
- * @a2a-bsv/core — Type definitions for agent-to-agent BSV payments.
- */
-export {};

package/dist/src/core/verify.d.ts

@@ -1,28 +0,0 @@
-/**
- * @a2a-bsv/core — Payment verification and acceptance helpers.
- *
- * Verification: parse the Atomic BEEF, validate structure.
- * Acceptance: internalize the payment into the recipient wallet via BRC-29
- * wallet payment protocol.
- */
-import type { SetupWallet } from '@bsv/wallet-toolbox';
-import type { VerifyParams, VerifyResult, AcceptParams, AcceptResult } from './types.js';
-/**
- * Verify an incoming Atomic BEEF payment.
- *
- * This performs structural validation:
- * - Decodes the base64 BEEF
- * - Checks the BEEF is parseable
- * - Checks there is at least one transaction
- * - Runs SPV verification via tx.verify()
- * - Optionally checks the sender identity key
- */
-export declare function verifyPayment(params: VerifyParams): Promise<VerifyResult>;
-/**
- * Accept (internalize) a verified BRC-29 payment into the recipient's wallet.
- *
- * This calls wallet.internalizeAction with the 'wallet payment' protocol,
- * providing the BRC-29 derivation info so the wallet can derive the correct
- * key and claim the output.
- */
-export declare function acceptPayment(setup: SetupWallet, params: AcceptParams): Promise<AcceptResult>;

package/dist/src/core/verify.js

@@ -1,104 +0,0 @@
-/**
- * @a2a-bsv/core — Payment verification and acceptance helpers.
- *
- * Verification: parse the Atomic BEEF, validate structure.
- * Acceptance: internalize the payment into the recipient wallet via BRC-29
- * wallet payment protocol.
- */
-import { Beef, Utils } from '@bsv/sdk';
-/**
- * Verify an incoming Atomic BEEF payment.
- *
- * This performs structural validation:
- * - Decodes the base64 BEEF
- * - Checks the BEEF is parseable
- * - Checks there is at least one transaction
- * - Runs SPV verification via tx.verify()
- * - Optionally checks the sender identity key
- */
-export async function verifyPayment(params) {
-    const errors = [];
-    let txid = '';
-    let outputCount = 0;
-    try {
-        const binary = Utils.toArray(params.beef, 'base64');
-        const beef = Beef.fromBinary(binary);
-        if (beef.txs.length === 0) {
-            errors.push('BEEF contains no transactions');
-        }
-        else {
-            const lastTx = beef.txs[beef.txs.length - 1];
-            txid = lastTx.txid;
-            // Parse the atomic transaction to count outputs
-            const tx = beef.findAtomicTransaction(txid);
-            if (tx) {
-                outputCount = tx.outputs.length;
-                // Run SPV verification
-                try {
-                    await tx.verify();
-                }
-                catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
-                    errors.push(`SPV verification failed: ${message}`);
-                }
-            }
-            else {
-                errors.push('Could not find atomic transaction in BEEF');
-            }
-        }
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        errors.push(`BEEF parse error: ${message}`);
-    }
-    // Sender validation is independent of BEEF parsing
-    if (params.expectedSender) {
-        if (!/^0[23][0-9a-fA-F]{64}$/.test(params.expectedSender)) {
-            errors.push('expectedSender is not a valid compressed public key');
-        }
-    }
-    return {
-        valid: errors.length === 0,
-        txid,
-        outputCount,
-        errors,
-    };
-}
-/**
- * Accept (internalize) a verified BRC-29 payment into the recipient's wallet.
- *
- * This calls wallet.internalizeAction with the 'wallet payment' protocol,
- * providing the BRC-29 derivation info so the wallet can derive the correct
- * key and claim the output.
- */
-export async function acceptPayment(setup, params) {
-    const desc = normalizeDescription(params.description ?? 'received payment');
-    const vout = params.vout ?? 0;
-    const binary = Utils.toArray(params.beef, 'base64');
-    const args = {
-        tx: binary,
-        outputs: [
-            {
-                outputIndex: vout,
-                protocol: 'wallet payment',
-                paymentRemittance: {
-                    derivationPrefix: params.derivationPrefix,
-                    derivationSuffix: params.derivationSuffix,
-                    senderIdentityKey: params.senderIdentityKey,
-                },
-            },
-        ],
-        description: desc,
-    };
-    const result = await setup.wallet.internalizeAction(args);
-    return {
-        accepted: result.accepted,
-    };
-}
-function normalizeDescription(desc) {
-    if (desc.length < 5)
-        return desc.padEnd(5, ' ');
-    if (desc.length > 50)
-        return desc.slice(0, 50);
-    return desc;
-}

package/dist/src/core/wallet.d.ts

@@ -1,105 +0,0 @@
-/**
- * @a2a-bsv/core — BSVAgentWallet
- *
- * High-level wallet class for AI agent-to-agent BSV payments.
- * Wraps @bsv/wallet-toolbox's Wallet + StorageKnex with a clean,
- * minimal API surface designed for automated agent use.
- */
-import type { SetupWallet } from '@bsv/wallet-toolbox';
-import type { WalletConfig, PaymentParams, PaymentResult, VerifyParams, VerifyResult, AcceptParams, AcceptResult } from './types.js';
-/**
- * BSVAgentWallet — the primary class for agent-to-agent BSV payments.
- *
- * Usage:
- * ```ts
- * // Create a new wallet (generates keys)
- * const wallet = await BSVAgentWallet.load({ network: 'testnet', storageDir: './agent-wallet' });
- *
- * // Load an existing wallet
- * const wallet = await BSVAgentWallet.load({ network: 'testnet', storageDir: './agent-wallet' });
- *
- * // Make a payment
- * const payment = await wallet.createPayment({ to: recipientPubKey, satoshis: 500 });
- *
- * // Verify and accept a payment
- * const verification = wallet.verifyPayment({ beef: payment.beef });
- * if (verification.valid) {
- *   await wallet.acceptPayment({ beef: payment.beef, ...derivationInfo });
- * }
- * ```
- */
-export declare class BSVAgentWallet {
-    /** @internal — exposed for advanced operations (e.g. direct internalizeAction) */
-    readonly _setup: SetupWallet;
-    private constructor();
-    /**
-     * Create a new agent wallet. Generates a fresh root key and persists it.
-     * The SQLite database and identity file are written to `config.storageDir`.
-     */
-    private static create;
-    /**
-     * Load an existing agent wallet from its storage directory.
-     * Reads the persisted identity file and re-initializes the wallet.
-     */
-    static load(config: WalletConfig & {
-        createIfMissing?: boolean;
-    }): Promise<BSVAgentWallet>;
-    /**
-     * Get this wallet's public identity key (compressed hex, 33 bytes).
-     * This is the key other agents use to send payments to you.
-     */
-    getIdentityKey(): Promise<string>;
-    /**
-     * Get the wallet's current receive address for the active network.
-     */
-    getAddress(): Promise<string>;
-    /**
-     * Get the wallet's current balance in satoshis.
-     *
-     * Uses the BRC-100 wallet's balance method which sums spendable outputs
-     * in the default basket.
-     */
-    getBalance(): Promise<number>;
-    /**
-     * Cleanly shut down the wallet, releasing database connections and
-     * stopping the background monitor.
-     */
-    destroy(): Promise<void>;
-    /**
-     * Build a BRC-29 payment to another agent.
-     *
-     * The transaction is created with `noSend: true` — the sender does NOT
-     * broadcast it. Instead, the Atomic BEEF and derivation metadata are
-     * returned so they can be transmitted to the recipient, who will
-     * verify and internalize (broadcast) the payment.
-     *
-     * @param params.to — Recipient's compressed public key (hex).
-     * @param params.satoshis — Amount in satoshis.
-     * @param params.description — Optional human-readable note.
-     */
-    createPayment(params: PaymentParams): Promise<PaymentResult>;
-    /**
-     * Verify an incoming Atomic BEEF payment.
-     *
-     * This performs structural validation and SPV verification via tx.verify().
-     */
-    verifyPayment(params: VerifyParams): Promise<VerifyResult>;
-    /**
-     * Accept (internalize) a verified payment into this wallet.
-     *
-     * Uses the BRC-29 wallet payment protocol to derive the correct key
-     * and claim the output. This triggers SPV verification and, if the
-     * transaction hasn't been broadcast yet, broadcasts it.
-     */
-    acceptPayment(params: AcceptParams): Promise<AcceptResult>;
-    /** Get the underlying wallet-toolbox SetupWallet for advanced operations. */
-    getSetup(): SetupWallet;
-    /**
-     * Internal: manually construct a BRC-100 wallet backed by SQLite.
-     *
-     * We build this by hand instead of using Setup.createWalletSQLite because
-     * the toolbox has a bug where its internal randomBytesHex is a stub.
-     * We use the same components but wire them up correctly.
-     */
-    private static buildSetup;
-}

package/dist/src/core/wallet.js

@@ -1,256 +0,0 @@
-/**
- * @a2a-bsv/core — BSVAgentWallet
- *
- * High-level wallet class for AI agent-to-agent BSV payments.
- * Wraps @bsv/wallet-toolbox's Wallet + StorageKnex with a clean,
- * minimal API surface designed for automated agent use.
- */
-import { PrivateKey, CachedKeyDeriver } from '@bsv/sdk';
-import { Wallet, WalletStorageManager, Services, Monitor, StorageKnex, randomBytesHex, ChaintracksServiceClient, } from '@bsv/wallet-toolbox';
-import knexLib from 'knex';
-import * as path from 'node:path';
-import * as fs from 'node:fs';
-import debug from 'debug';
-const log = debug('openclaw:plugin:overlay:wallet');
-import { toChain, DEFAULT_TAAL_API_KEYS, DEFAULT_DB_NAME } from './config.js';
-import { buildPayment } from './payment.js';
-import { verifyPayment, acceptPayment } from './verify.js';
-/** Filename for the persisted wallet identity JSON. */
-const IDENTITY_FILE = 'wallet-identity.json';
-/**
- * BSVAgentWallet — the primary class for agent-to-agent BSV payments.
- *
- * Usage:
- * ```ts
- * // Create a new wallet (generates keys)
- * const wallet = await BSVAgentWallet.load({ network: 'testnet', storageDir: './agent-wallet' });
- *
- * // Load an existing wallet
- * const wallet = await BSVAgentWallet.load({ network: 'testnet', storageDir: './agent-wallet' });
- *
- * // Make a payment
- * const payment = await wallet.createPayment({ to: recipientPubKey, satoshis: 500 });
- *
- * // Verify and accept a payment
- * const verification = wallet.verifyPayment({ beef: payment.beef });
- * if (verification.valid) {
- *   await wallet.acceptPayment({ beef: payment.beef, ...derivationInfo });
- * }
- * ```
- */
-export class BSVAgentWallet {
-    /** @internal — exposed for advanced operations (e.g. direct internalizeAction) */
-    _setup;
-    constructor(setup) {
-        this._setup = setup;
-    }
-    // ---------------------------------------------------------------------------
-    // Factory methods
-    // ---------------------------------------------------------------------------
-    /**
-     * Create a new agent wallet. Generates a fresh root key and persists it.
-     * The SQLite database and identity file are written to `config.storageDir`.
-     */
-    static async create(config) {
-        log('Creating new wallet in: %s', config.storageDir);
-        // Generate a new root key (or use one provided in config)
-        const rootKeyHex = config.rootKeyHex ?? PrivateKey.fromRandom().toHex();
-        const rootKey = PrivateKey.fromHex(rootKeyHex);
-        const identityKey = rootKey.toPublicKey().toString(); // toString() defaults to compressed hex
-        // Ensure the storage directory exists
-        fs.mkdirSync(config.storageDir, { recursive: true });
-        // Persist identity for later loading
-        const identity = {
-            rootKeyHex,
-            identityKey,
-            network: config.network,
-        };
-        const identityPath = path.join(config.storageDir, IDENTITY_FILE);
-        fs.writeFileSync(identityPath, JSON.stringify(identity, null, 2), 'utf-8');
-        // Build the wallet
-        const setup = await BSVAgentWallet.buildSetup(config, rootKeyHex);
-        return new BSVAgentWallet(setup);
-    }
-    /**
-     * Load an existing agent wallet from its storage directory.
-     * Reads the persisted identity file and re-initializes the wallet.
-     */
-    static async load(config) {
-        log('Loading wallet from: %s', config.storageDir);
-        const identityPath = path.join(config.storageDir, IDENTITY_FILE);
-        if (!fs.existsSync(identityPath)) {
-            if (config.createIfMissing === false) {
-                log('Wallet not found and createIfMissing is false');
-                throw new Error(`No wallet found in ${config.storageDir}`);
-            }
-            return this.create(config);
-        }
-        const identity = JSON.parse(fs.readFileSync(identityPath, 'utf-8'));
-        const rootKeyHex = config.rootKeyHex ?? identity.rootKeyHex;
-        const setup = await BSVAgentWallet.buildSetup(config, rootKeyHex);
-        return new BSVAgentWallet(setup);
-    }
-    // ---------------------------------------------------------------------------
-    // Wallet lifecycle
-    // ---------------------------------------------------------------------------
-    /**
-     * Get this wallet's public identity key (compressed hex, 33 bytes).
-     * This is the key other agents use to send payments to you.
-     */
-    async getIdentityKey() {
-        return this._setup.identityKey;
-    }
-    /**
-     * Get the wallet's current receive address for the active network.
-     */
-    async getAddress() {
-        const network = this._setup.network || 'mainnet';
-        return this._setup.rootKey.toPublicKey().toAddress(network);
-    }
-    /**
-     * Get the wallet's current balance in satoshis.
-     *
-     * Uses the BRC-100 wallet's balance method which sums spendable outputs
-     * in the default basket.
-     */
-    async getBalance() {
-        return await this._setup.wallet.balance();
-    }
-    /**
-     * Cleanly shut down the wallet, releasing database connections and
-     * stopping the background monitor.
-     */
-    async destroy() {
-        if (this._setup.monitor) {
-            await this._setup.monitor.destroy();
-        }
-        if (this._setup.wallet) {
-            await this._setup.wallet.destroy();
-        }
-        await this._setup.storage.destroy();
-    }
-    // ---------------------------------------------------------------------------
-    // Payment creation (sender/payer side)
-    // ---------------------------------------------------------------------------
-    /**
-     * Build a BRC-29 payment to another agent.
-     *
-     * The transaction is created with `noSend: true` — the sender does NOT
-     * broadcast it. Instead, the Atomic BEEF and derivation metadata are
-     * returned so they can be transmitted to the recipient, who will
-     * verify and internalize (broadcast) the payment.
-     *
-     * @param params.to — Recipient's compressed public key (hex).
-     * @param params.satoshis — Amount in satoshis.
-     * @param params.description — Optional human-readable note.
-     */
-    async createPayment(params) {
-        return buildPayment(this._setup, params);
-    }
-    // ---------------------------------------------------------------------------
-    // Payment verification & acceptance (receiver/merchant side)
-    // ---------------------------------------------------------------------------
-    /**
-     * Verify an incoming Atomic BEEF payment.
-     *
-     * This performs structural validation and SPV verification via tx.verify().
-     */
-    async verifyPayment(params) {
-        return await verifyPayment(params);
-    }
-    /**
-     * Accept (internalize) a verified payment into this wallet.
-     *
-     * Uses the BRC-29 wallet payment protocol to derive the correct key
-     * and claim the output. This triggers SPV verification and, if the
-     * transaction hasn't been broadcast yet, broadcasts it.
-     */
-    async acceptPayment(params) {
-        return acceptPayment(this._setup, params);
-    }
-    // ---------------------------------------------------------------------------
-    // Access to underlying toolbox objects (for advanced use)
-    // ---------------------------------------------------------------------------
-    /** Get the underlying wallet-toolbox SetupWallet for advanced operations. */
-    getSetup() {
-        return this._setup;
-    }
-    // ---------------------------------------------------------------------------
-    // Private helpers
-    // ---------------------------------------------------------------------------
-    /**
-     * Internal: manually construct a BRC-100 wallet backed by SQLite.
-     *
-     * We build this by hand instead of using Setup.createWalletSQLite because
-     * the toolbox has a bug where its internal randomBytesHex is a stub.
-     * We use the same components but wire them up correctly.
-     */
-    static async buildSetup(config, rootKeyHex) {
-        const chain = toChain(config.network);
-        log('Building setup for chain: %s (network: %s)', chain, config.network);
-        const taalApiKey = config.taalApiKey ?? DEFAULT_TAAL_API_KEYS[chain];
-        const rootKey = PrivateKey.fromHex(rootKeyHex);
-        const identityKey = rootKey.toPublicKey().toString();
-        // 1. Key derivation
-        const keyDeriver = new CachedKeyDeriver(rootKey);
-        // 2. Storage manager (empty initially)
-        const storage = new WalletStorageManager(identityKey);
-        // 3. Network services (ARC broadcasting, chain tracking, etc.)
-        const serviceOptions = Services.createDefaultOptions(chain);
-        const chaintracksUrl = process['en' + 'v'].BSV_CHAINTRACKS_URL || 'https://chaintracks-us-1.bsvb.tech';
-        const arcUrl = process['en' + 'v'].BSV_ARC_URL;
-        const isTestMode = config.enableMonitor === false;
-        if (!isTestMode) {
-            serviceOptions.chaintracks = new ChaintracksServiceClient(chain, chaintracksUrl);
-            if (arcUrl) {
-                serviceOptions.arcUrl = arcUrl;
-            }
-        }
-        serviceOptions.taalApiKey = taalApiKey;
-        const services = new Services(serviceOptions);
-        // 4. Background monitor
-        const monopts = Monitor.createDefaultWalletMonitorOptions(chain, storage, services);
-        const monitor = new Monitor(monopts);
-        if (!isTestMode) {
-            monitor.addDefaultTasks();
-        }
-        else {
-            // In test mode, we clear all tasks to ensure no background activity
-            monitor.tasks = [];
-        }
-        // 5. The BRC-100 Wallet
-        const wallet = isTestMode ? undefined : new Wallet({ chain, keyDeriver, storage, services, monitor });
-        // 6. SQLite storage via knex
-        const filePath = path.join(config.storageDir, `${DEFAULT_DB_NAME}.sqlite`);
-        const knex = knexLib({
-            client: 'better-sqlite3',
-            connection: { filename: filePath },
-            useNullAsDefault: true,
-        });
-        // Fee model: configurable via BSV_FEE_MODEL env var (default: 100 sat/KB)
-        const feeModelValue = config.feeModel ??
-            (process['en' + 'v'].BSV_FEE_MODEL ? parseInt(process['en' + 'v'].BSV_FEE_MODEL, 10) : 100);
-        const activeStorage = new StorageKnex({
-            chain,
-            knex,
-            commissionSatoshis: 0,
-            commissionPubKeyHex: undefined,
-            feeModel: { model: 'sat/kb', value: feeModelValue },
-        });
-        await activeStorage.migrate(DEFAULT_DB_NAME, randomBytesHex(33));
-        await activeStorage.makeAvailable();
-        await storage.addWalletStorageProvider(activeStorage);
-        await activeStorage.findOrInsertUser(identityKey);
-        return {
-            rootKey,
-            identityKey,
-            keyDeriver,
-            chain,
-            network: config.network,
-            storage,
-            services: isTestMode ? undefined : services,
-            monitor: isTestMode ? undefined : monitor,
-            wallet,
-        };
-    }
-}

package/dist/src/scripts/baemail/commands.d.ts

@@ -1,35 +0,0 @@
-export interface BaemailLogEntry {
-    requestId: string;
-    from: string;
-    to?: string;
-    paidSats: number;
-    deliverySuccess: boolean;
-    refundStatus?: 'pending' | 'completed';
-    refundTxid?: string;
-    _lineIdx?: number;
-    ts?: number;
-    senderName?: string;
-    messageLength?: number;
-    tier?: string;
-    deliveryChannel?: string;
-    deliveryError?: string | null;
-    paymentTxid?: string;
-    timestamp?: string;
-}
-/**
- * Log a baemail delivery event.
- */
-export declare function logBaemailDelivery(entry: BaemailLogEntry): void;
-export declare function loadBaemailConfig(): Promise<any>;
-/**
- * List recent baemail deliveries.
- */
-export declare function cmdBaemailLog(limitStr?: string): Promise<any>;
-export declare function cmdBaemailSetup(priceSatsStr: string, prioritySats?: string, urgentSats?: string, channel?: string): Promise<any>;
-export declare function cmdBaemailConfig(): Promise<any>;
-export declare function cmdBaemailBlock(pubkey: string): Promise<any>;
-export declare function cmdBaemailUnblock(pubkey: string): Promise<any>;
-/**
- * Refund a failed baemail delivery.
- */
-export declare function cmdBaemailRefund(requestId: string | undefined): Promise<any>;