openclaw-messagebox-plugin 0.1.3 → 0.1.5

package/src/core/types.ts

@@ -0,0 +1,102 @@
+/**
+ * @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';
+  /** 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';
+}

package/src/core/verify.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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>;
+//# sourceMappingURL=verify.d.ts.map

package/src/core/verify.ts

@@ -0,0 +1,119 @@
+/**
+ * @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';
+import type { SetupWallet } from '@bsv/wallet-toolbox';
+import type { VerifyParams, VerifyResult, AcceptParams, AcceptResult } from './types.js';
+import type { InternalizeActionArgs } 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: VerifyParams): Promise<VerifyResult> {
+  const errors: string[] = [];
+  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: unknown) {
+          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: unknown) {
+    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: SetupWallet,
+  params: AcceptParams,
+): Promise<AcceptResult> {
+  const desc = normalizeDescription(params.description ?? 'received payment');
+  const vout = params.vout ?? 0;
+
+  const binary = Utils.toArray(params.beef, 'base64');
+
+  const args: InternalizeActionArgs = {
+    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: string): string {
+  if (desc.length < 5) return desc.padEnd(5, ' ');
+  if (desc.length > 50) return desc.slice(0, 50);
+  return desc;
+}

package/src/core/wallet.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @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): 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 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;
+}
+//# sourceMappingURL=wallet.d.ts.map

package/src/core/wallet.ts

@@ -0,0 +1,289 @@
+/**
+ * @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 type { SetupWallet } from '@bsv/wallet-toolbox';
+import knexLib from 'knex';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+import type {
+  WalletConfig,
+  WalletIdentity,
+  PaymentParams,
+  PaymentResult,
+  VerifyParams,
+  VerifyResult,
+  AcceptParams,
+  AcceptResult,
+} from './types.js';
+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) */
+  public readonly _setup: SetupWallet;
+
+  private constructor(setup: SetupWallet) {
+    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`.
+   */
+  private static async create(config: WalletConfig): Promise<BSVAgentWallet> {
+    // 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();
+
+    // Ensure the storage directory exists
+    fs.mkdirSync(config.storageDir, { recursive: true });
+
+    // Persist identity for later loading
+    const identity: WalletIdentity = {
+      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: WalletConfig): Promise<BSVAgentWallet> {
+    const identityPath = path.join(config.storageDir, IDENTITY_FILE);
+    if (!fs.existsSync(identityPath)) {
+      return this.create(config);
+    }
+
+    const identity: WalletIdentity = 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(): Promise<string> {
+    return this._setup.identityKey;
+  }
+
+  /**
+   * 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(): Promise<number> {
+    return await this._setup.wallet.balance();
+  }
+
+  /**
+   * Cleanly shut down the wallet, releasing database connections and
+   * stopping the background monitor.
+   */
+  async destroy(): Promise<void> {
+    await this._setup.wallet.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: PaymentParams): Promise<PaymentResult> {
+    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: VerifyParams): Promise<VerifyResult> {
+    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: AcceptParams): Promise<AcceptResult> {
+    return acceptPayment(this._setup, params);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Access to underlying toolbox objects (for advanced use)
+  // ---------------------------------------------------------------------------
+
+  /** Get the underlying wallet-toolbox SetupWallet for advanced operations. */
+  getSetup(): SetupWallet {
+    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.
+   */
+  private static async buildSetup(
+    config: WalletConfig,
+    rootKeyHex: string,
+  ): Promise<SetupWallet> {
+    const chain = toChain(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.env.BSV_CHAINTRACKS_URL || 'https://chaintracks-us-1.bsvb.tech';
+    const arcUrl = process.env.BSV_ARC_URL;
+    
+    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);
+    monitor.addDefaultTasks();
+
+    // 5. The BRC-100 Wallet
+    const wallet = 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: 'sqlite3',
+      connection: { filename: filePath },
+      useNullAsDefault: true,
+    });
+
+    // Fee model: configurable via BSV_FEE_MODEL env var (default: 100 sat/KB)
+    const feeModelValue = config.feeModel ?? 
+      (process.env.BSV_FEE_MODEL ? parseInt(process.env.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,
+      storage,
+      services,
+      monitor,
+      wallet,
+    };
+  }
+}