openclaw-overlay-plugin 0.7.22

package/src/core/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @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';
+
+// All types
+export type {
+  WalletConfig,
+  WalletIdentity,
+  PaymentParams,
+  PaymentResult,
+  VerifyParams,
+  VerifyResult,
+  AcceptParams,
+  AcceptResult,
+} from './types.js';
+
+// Config helpers (for advanced use)
+export { toChain, DEFAULT_TAAL_API_KEYS, DEFAULT_DB_NAME } from './config.js';
+export type { Chain } from './config.js';
+
+// Lower-level helpers (for advanced use)
+export { buildPayment } from './payment.js';
+export { verifyPayment, acceptPayment } from './verify.js';

package/src/core/payment.ts

@@ -0,0 +1,111 @@
+/**
+ * @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';
+import type { SetupWallet } from '@bsv/wallet-toolbox';
+import type { PaymentParams, PaymentResult } from './types.js';
+import type { CachedKeyDeriver } from '@bsv/sdk';
+
+/**
+ * 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: SetupWallet,
+  params: PaymentParams,
+): Promise<PaymentResult> {
+  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 as CachedKeyDeriver;
+  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: string;
+  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: string): string {
+  if (desc.length < 5) return desc.padEnd(5, ' ');
+  if (desc.length > 50) return desc.slice(0, 50);
+  return desc;
+}

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.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.ts

@@ -0,0 +1,282 @@
+/**
+ * @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);
+    serviceOptions.chaintracks = new ChaintracksServiceClient(chain, 'https://chaintracks-us-1.bsvb.tech');
+    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,
+    };
+  }
+}