openclaw-overlay-plugin 0.8.15 → 0.8.17

package/dist/src/core/index.js

@@ -1,26 +0,0 @@
-/**
- * @a2a-bsv/core — Agent-to-agent BSV payment library.
- *
- * Wraps @bsv/sdk and @bsv/wallet-toolbox to provide a clean, minimal API
- * for AI agents to pay each other using BSV blockchain transactions.
- *
- * @example
- * ```ts
- * import { BSVAgentWallet } from '@a2a-bsv/core';
- *
- * const wallet = await BSVAgentWallet.load({
- *   network: 'testnet',
- *   storageDir: './my-agent-wallet',
- * });
- *
- * const identityKey = await wallet.getIdentityKey();
- * console.log('My identity:', identityKey);
- * ```
- */
-// Main wallet class
-export { BSVAgentWallet } from './wallet.js';
-// Config helpers (for advanced use)
-export { toChain, DEFAULT_TAAL_API_KEYS, DEFAULT_DB_NAME } from './config.js';
-// Lower-level helpers (for advanced use)
-export { buildPayment } from './payment.js';
-export { verifyPayment, acceptPayment } from './verify.js';

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

@@ -1,16 +0,0 @@
-/**
- * @a2a-bsv/core — Payment construction helpers.
- *
- * Uses BRC-29 key derivation so the recipient can internalize the payment
- * without ever reusing an address.
- */
-import type { SetupWallet } from '@bsv/wallet-toolbox';
-import type { PaymentParams, PaymentResult } from './types.js';
-/**
- * Build a BRC-29 payment transaction using the wallet's createAction API.
- *
- * The transaction is created with `acceptDelayedBroadcast: false` — the sender
- * broadcasts immediately. The resulting Atomic BEEF and derivation metadata are
- * returned so the recipient can verify and internalize the payment on their side.
- */
-export declare function buildPayment(setup: SetupWallet, params: PaymentParams): Promise<PaymentResult>;

package/dist/src/core/payment.js

@@ -1,94 +0,0 @@
-/**
- * @a2a-bsv/core — Payment construction helpers.
- *
- * Uses BRC-29 key derivation so the recipient can internalize the payment
- * without ever reusing an address.
- */
-import { Beef, Utils } from '@bsv/sdk';
-import { randomBytesBase64, ScriptTemplateBRC29 } from '@bsv/wallet-toolbox';
-/**
- * Build a BRC-29 payment transaction using the wallet's createAction API.
- *
- * The transaction is created with `acceptDelayedBroadcast: false` — the sender
- * broadcasts immediately. The resulting Atomic BEEF and derivation metadata are
- * returned so the recipient can verify and internalize the payment on their side.
- */
-export async function buildPayment(setup, params) {
-    const { to, satoshis, description } = params;
-    const desc = normalizeDescription(description ?? 'agent payment');
-    // Generate unique BRC-29 derivation prefixes and suffixes
-    const derivationPrefix = randomBytesBase64(8);
-    const derivationSuffix = randomBytesBase64(8);
-    // Build BRC-29 locking script
-    const keyDeriver = setup.keyDeriver;
-    const t = new ScriptTemplateBRC29({
-        derivationPrefix,
-        derivationSuffix,
-        keyDeriver,
-    });
-    // Determine the recipient identity key.
-    // If `to` is a compressed public key hex (66 chars, starts with 02/03), use directly.
-    // Otherwise treat as an address — for BRC-29 we need a public key.
-    let recipientPubKey;
-    if (/^0[23][0-9a-fA-F]{64}$/.test(to)) {
-        recipientPubKey = to;
-    }
-    else {
-        // If it's an address, we can't do BRC-29 (needs pubkey). Throw a clear error.
-        throw new Error('PaymentParams.to must be a compressed public key (hex) for BRC-29 payments. ' +
-            'Raw BSV addresses are not supported — the recipient must share their identity key.');
-    }
-    const lockingScript = t.lock(setup.rootKey.toString(), recipientPubKey);
-    const label = 'a2a-payment';
-    const car = await setup.wallet.createAction({
-        outputs: [
-            {
-                lockingScript: lockingScript.toHex(),
-                satoshis,
-                outputDescription: desc,
-                tags: ['relinquish'],
-                customInstructions: JSON.stringify({
-                    derivationPrefix,
-                    derivationSuffix,
-                    type: 'BRC29',
-                }),
-            },
-        ],
-        options: {
-            randomizeOutputs: false,
-            acceptDelayedBroadcast: false,
-        },
-        labels: [label],
-        description: desc,
-    });
-    // Extract the txid from the createAction result.
-    // The tx field is a number[] (AtomicBEEF binary). Parse it to get txid.
-    if (!car.tx) {
-        throw new Error('createAction did not return a transaction. Check wallet funding.');
-    }
-    const beef = Beef.fromBinary(car.tx);
-    // The last transaction in the beef is our new tx
-    const lastTx = beef.txs[beef.txs.length - 1];
-    const txid = lastTx.txid;
-    // Encode the atomic BEEF as base64
-    const atomicBinary = beef.toBinaryAtomic(txid);
-    const beefBase64 = Utils.toBase64(atomicBinary);
-    return {
-        beef: beefBase64,
-        txid,
-        satoshis,
-        derivationPrefix,
-        derivationSuffix,
-        senderIdentityKey: setup.identityKey,
-    };
-}
-/**
- * Ensure description meets BRC-100's 5-50 character requirement.
- */
-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/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;
-}