openclaw-messagebox-plugin 0.1.3 → 0.1.4

package/openclaw.plugin.json

@@ -28,6 +28,7 @@
       },
       "arcUrl": {
         "type": "string",
+        "default": "https://arc.gorillapool.io",
         "description": "Custom ARC/Arcade server URL for transaction broadcasting"
       },
       "walletDir": {
@@ -56,7 +57,7 @@
     },
     "arcUrl": {
       "label": "ARC/Arcade Server URL",
-      "placeholder": "https://arc.taal.com",
+      "placeholder": "https://arc.gorillapool.io",
       "help": "Custom server for transaction broadcasting",
       "advanced": true
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-messagebox-plugin",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "OpenClaw plugin for P2P encrypted messaging and payments via BSV MessageBox",
   "type": "module",
   "main": "dist/index.js",
@@ -19,16 +19,17 @@
     "test": "npx tsx src/**/*.test.ts"
   },
   "dependencies": {
-    "@bsv/sdk": "^2.0.13",
     "@bsv/message-box-client": "^2.0.4",
+    "@bsv/sdk": "^2.0.13",
+    "@bsv/wallet-toolbox": "^2.1.17",
     "better-sqlite3": "^12.8.0",
-    "knex": "^3.2.8",
-    "dotenv": "^17.3.1"
+    "dotenv": "^17.3.1",
+    "knex": "^3.2.8"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
-    "typescript": "^6.0.2",
-    "eslint": "^10.1.0"
+    "eslint": "^10.1.0",
+    "typescript": "^6.0.2"
   },
   "openclaw": {
     "extensions": [

package/src/client.ts

@@ -1,27 +1,119 @@
 import { MessageBoxClient } from '@bsv/message-box-client';
+import { PrivateKey } from '@bsv/sdk';
 import { MessageBoxConfig, MessageRecord } from './types.js';
+import { MessageStore } from './store.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { BSVAgentWallet } from './core/wallet.js';
 
 export class MessageBoxManager {
-  private client!: MessageBoxClient;
+  private client: MessageBoxClient;
+  private privKey: PrivateKey;
+  private store: MessageStore;
+  private wallet: BSVAgentWallet;
 
-  constructor(_config: MessageBoxConfig) {
-    // Note: MessageBoxClient requires a WalletClient/Identity
-    // This will be initialized in an async init method or similar
+  constructor(config: MessageBoxConfig, store: MessageStore, wallet: BSVAgentWallet) {
+    const identityPath = path.join(config.walletDir, 'wallet-identity.json');
+    if (!fs.existsSync(identityPath)) {
+      throw new Error(`Identity file not found at ${identityPath}. Please onboard your agent first.`);
+    }
+
+    const identity = JSON.parse(fs.readFileSync(identityPath, 'utf-8'));
+    this.privKey = PrivateKey.fromHex(identity.rootKeyHex);
+    this.store = store;
+    this.wallet = wallet;
+
+    // Initialize the MessageBoxClient with correct SDK-style wallet interface
+    // @ts-ignore
+    this.client = new MessageBoxClient({
+      host: config.host,
+      walletClient: this.wallet._setup.wallet,
+      networkPreset: config.walletDir.includes('testnet') ? 'testnet' : 'mainnet'
+    });
+  }
+
+  async send(recipientKey: string, body: string, box: string = 'default'): Promise<string> {
+    // sendMessage handles BRC-2 encryption internally using the walletClient
+    // @ts-ignore
+    const response = await this.client.sendMessage({
+      recipient: recipientKey,
+      messageBox: box,
+      body: body
+    });
+
+    // Save to local store
+    await this.store.saveMessage({
+      id: response.messageId,
+      senderKey: this.privKey.toPublicKey().toString(),
+      recipientKey,
+      body, // store decrypted locally
+      box,
+      ts: Date.now(),
+      acknowledged: false
+    });
+
+    return response.messageId;
   }
 
-  async send(_recipientKey: string, _body: string, _box: string = 'default'): Promise<string> {
-    // 1. Encrypt body for recipient
-    // 2. Call client.sendMessage
-    return "msg_id";
+  async poll(box: string = 'default'): Promise<MessageRecord[]> {
+    // listMessages handles BRC-2 decryption internally using the walletClient
+    // @ts-ignore
+    const messages = await this.client.listMessages({ messageBox: box });
+    const records: MessageRecord[] = [];
+
+    for (const msg of messages) {
+      const record: MessageRecord = {
+        // @ts-ignore
+        id: msg.id || (msg as any).messageId,
+        // @ts-ignore
+        senderKey: msg.sender || (msg as any).senderKey,
+        recipientKey: this.privKey.toPublicKey().toString(),
+        body: typeof msg.body === 'string' ? msg.body : JSON.stringify(msg.body),
+        // @ts-ignore
+        box: msg.box || box,
+        // @ts-ignore
+        ts: msg.timestamp || Date.now(),
+        acknowledged: false
+      };
+
+      await this.store.saveMessage(record);
+      records.push(record);
+    }
+
+    return records;
   }
 
-  async poll(_box: string = 'default'): Promise<MessageRecord[]> {
-    // 1. Call client.listMessages
-    // 2. Decrypt and format
-    return [];
+  async acknowledge(messageIds: string[]) {
+    // @ts-ignore
+    await this.client.acknowledgeMessage({ messageIds });
+    await this.store.markAcknowledged(messageIds);
+  }
+
+  async listen(onMessage: (msg: MessageRecord) => void) {
+    // @ts-ignore
+    return this.client.listenForLiveMessages({
+      messageBox: 'default',
+      onMessage: async (msg: any) => {
+        const record: MessageRecord = {
+          // @ts-ignore
+          id: msg.id || (msg as any).messageId,
+          // @ts-ignore
+          senderKey: msg.sender || (msg as any).senderKey,
+          recipientKey: this.privKey.toPublicKey().toString(),
+          body: typeof msg.body === 'string' ? msg.body : JSON.stringify(msg.body),
+          // @ts-ignore
+          box: msg.box || 'default',
+          ts: Date.now(),
+          acknowledged: false
+        };
+
+        await this.store.saveMessage(record);
+        onMessage(record);
+      }
+    });
   }
 
-  async acknowledge(_messageIds: string[]) {
-    // Call client.acknowledgeMessage
+  getIdentityKey(): string {
+    return this.privKey.toPublicKey().toString();
   }
 }

package/src/core/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @a2a-bsv/core — Configuration defaults and helpers.
+ */
+import type { WalletConfig } from './types.js';
+/** Map our 'mainnet'/'testnet' to the wallet-toolbox's 'main'/'test' chain type. */
+export type Chain = 'main' | 'test';
+export declare function toChain(network: WalletConfig['network']): Chain;
+/** Default TAAL API keys from the wallet-toolbox examples. */
+export declare const DEFAULT_TAAL_API_KEYS: Record<Chain, string>;
+/** Default SQLite database name. */
+export declare const DEFAULT_DB_NAME = "a2a_agent_wallet";
+//# sourceMappingURL=config.d.ts.map

package/src/core/config.ts

@@ -0,0 +1,21 @@
+/**
+ * @a2a-bsv/core — Configuration defaults and helpers.
+ */
+
+import type { WalletConfig } from './types.js';
+
+/** Map our 'mainnet'/'testnet' to the wallet-toolbox's 'main'/'test' chain type. */
+export type Chain = 'main' | 'test';
+
+export function toChain(network: WalletConfig['network']): Chain {
+  return network === 'mainnet' ? 'main' : 'test';
+}
+
+/** Default TAAL API keys from the wallet-toolbox examples. */
+export const DEFAULT_TAAL_API_KEYS: Record<Chain, string> = {
+  main: 'mainnet_9596de07e92300c6287e4393594ae39c',
+  test: 'testnet_0e6cf72133b43ea2d7861da2a38684e3',
+};
+
+/** Default SQLite database name. */
+export const DEFAULT_DB_NAME = 'a2a_agent_wallet';

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

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

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

@@ -0,0 +1,95 @@
+/**
+ * @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';
+}
+//# sourceMappingURL=types.d.ts.map

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