openclaw-messagebox-plugin 0.1.2 → 0.1.4

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC"}

package/dist/src/core/types.js

@@ -0,0 +1,5 @@
+/**
+ * @a2a-bsv/core — Type definitions for agent-to-agent BSV payments.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/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/dist/src/core/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/core/verify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGzF;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAkD/E;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CA2BvB"}

package/dist/src/core/verify.js

@@ -0,0 +1,105 @@
+/**
+ * @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;
+}
+//# sourceMappingURL=verify.js.map

package/dist/src/core/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/core/verify.ts"],"names":[],"mappings":"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"}

package/dist/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/dist/src/core/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../../src/core/wallet.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD,OAAO,KAAK,EACV,YAAY,EAEZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAQpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAc;IACzB,kFAAkF;IAClF,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,OAAO;IAQP;;;OAGG;mBACkB,MAAM;IAwB3B;;;OAGG;WACU,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAoBhE;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAInC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAQlE;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAIhE;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAQhE,6EAA6E;IAC7E,QAAQ,IAAI,WAAW;IAQvB;;;;;;OAMG;mBACkB,UAAU;CAyEhC"}

package/dist/src/core/wallet.js

@@ -0,0 +1,225 @@
+/**
+ * @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 { 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) {
+        // 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 = {
+            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) {
+        const identityPath = path.join(config.storageDir, IDENTITY_FILE);
+        if (!fs.existsSync(identityPath)) {
+            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 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() {
+        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) {
+        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);
+        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,
+        };
+    }
+}
+//# sourceMappingURL=wallet.js.map

package/dist/src/core/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../../src/core/wallet.ts"],"names":[],"mappings":"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"}

package/index.ts

@@ -1,18 +1,51 @@
-import path from "path";
-import os from "os";
-import fs from "fs";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { MessageBoxManager } from "./src/client.js";
+import { MessageStore } from "./src/store.js";
+import { BSVAgentWallet } from "./src/core/wallet.js";
 
 /**
  * OpenClaw MessageBox Plugin
  * Enables secure P2P encrypted messaging and payments.
  */
 export default function register(api: any) {
-  // Capture configuration from the gateway
-  const pluginConfig = api.getConfig?.()?.plugins?.entries?.['openclaw-messagebox-plugin']?.config || api.config || {};
+  // Capture configuration from the gateway (handle multiple IDs and flat/nested structures)
+  const entries = api.getConfig?.()?.plugins?.entries || {};
+  const entry = entries['openclaw-messagebox'] 
+    || entries['openclaw-messagebox-plugin'] 
+    || entries['bsv-messagebox'] 
+    || {};
+    
+  const pluginConfig = { ...entry, ...(entry.config || {}), ...(api.config || {}) };
   const host = pluginConfig.host || 'https://msg.bsv.direct';
+  const network = pluginConfig.network || 'mainnet';
+  const chaintracksUrl = pluginConfig.chaintracksUrl || 'https://chaintracks-us-1.bsvb.tech';
+  const arcUrl = pluginConfig.arcUrl || (network === 'testnet' ? 'https://testnet.arc.gorillapool.io' : 'https://arc.gorillapool.io');
   const walletDir = pluginConfig.walletDir || path.join(os.homedir(), '.openclaw', 'bsv-wallet');
+  const dbPath = pluginConfig.dbPath || path.join(os.homedir(), '.openclaw', 'openclaw-messagebox', 'messages.sqlite');
 
-  api.logger.info(`[messagebox] Initializing MessageBox Plugin (host: ${host})`);
+  let manager: MessageBoxManager | null = null;
+  let store: MessageStore | null = null;
+  let wallet: BSVAgentWallet | null = null;
+
+  api.logger.info(`[messagebox] Initializing MessageBox Plugin (network: ${network}, host: ${host})`);
+
+  async function ensureInitialized() {
+    if (manager) return manager;
+    
+    // Initialize shared wallet
+    wallet = await BSVAgentWallet.load({
+      network: network as any,
+      storageDir: walletDir
+    });
+
+    store = new MessageStore(dbPath);
+    await store.init();
+    
+    manager = new MessageBoxManager({ host, walletDir, dbPath }, store, wallet);
+    return manager;
+  }
 
   // Register the messagebox tool
   api.registerTool({
@@ -34,6 +67,11 @@ export default function register(api: any) {
           type: "string",
           description: "Message content (will be encrypted client-side)"
         },
+        box: {
+          type: "string",
+          default: "default",
+          description: "Target mailbox/folder"
+        },
         sats: {
           type: "number",
           description: "Amount in satoshis for direct P2P payment"
@@ -48,13 +86,44 @@ export default function register(api: any) {
     },
     async execute(_id: string, params: any) {
       try {
-        // Implementation logic will go here
-        return {
-          content: [{
-            type: "text",
-            text: `MessageBox action '${params.action}' received. (Logic implementation pending)`
-          }]
-        };
+        const m = await ensureInitialized();
+        
+        switch (params.action) {
+          case "send":
+            if (!params.recipientKey || !params.body) throw new Error("recipientKey and body required");
+            const msgId = await m.send(params.recipientKey, params.body, params.box);
+            return { content: [{ type: "text", text: `✅ Message sent successfully. ID: ${msgId}` }] };
+          
+          case "inbox":
+            await m.poll(params.box);
+            const messages = await store!.getInbox();
+            if (messages.length === 0) return { content: [{ type: "text", text: "Your inbox is empty." }] };
+            
+            const list = messages.map(msg => `[${new Date(msg.ts).toLocaleString()}] FROM: ${msg.senderKey.slice(0, 12)}... - "${msg.body}"`).join('\n');
+            return { content: [{ type: "text", text: `📬 Inbox (Last ${messages.length} messages):\n\n${list}` }] };
+
+          case "acknowledge":
+            if (!params.messageIds || params.messageIds.length === 0) throw new Error("messageIds array required");
+            await m.acknowledge(params.messageIds);
+            return { content: [{ type: "text", text: `✅ Acknowledged ${params.messageIds.length} messages.` }] };
+
+          case "status":
+            return { content: [{ type: "text", text: `MessageBox Status:\nHost: ${host}\nIdentity: ${m.getIdentityKey()}\nDatabase: ${dbPath}` }] };
+
+          case "pay":
+            if (!params.recipientKey || !params.sats) throw new Error("recipientKey and sats required");
+            const payResult = await wallet!.createPayment({
+              to: params.recipientKey,
+              satoshis: params.sats,
+              description: "P2P Payment via MessageBox"
+            });
+            // Send the BEEF payment as a message to the recipient's payment_inbox
+            const pmsgId = await m.send(params.recipientKey, JSON.stringify(payResult), 'payment_inbox');
+            return { content: [{ type: "text", text: `✅ P2P Payment sent! Amount: ${params.sats} sats. Notification ID: ${pmsgId}` }] };
+
+          default:
+            throw new Error(`Unknown action: ${params.action}`);
+        }
       } catch (error: any) {
         return {
           content: [{
@@ -70,11 +139,27 @@ export default function register(api: any) {
   api.registerService({
     id: "messagebox-listener",
     start: async () => {
-      api.logger.info("[messagebox] Starting WebSocket listener...");
-      // Logic for client.listenForLiveMessages goes here
+      try {
+        const m = await ensureInitialized();
+        api.logger.info("[messagebox] Starting WebSocket listener...");
+        
+        await m.listen((msg) => {
+          api.logger.info(`[messagebox] ⚡ New message from ${msg.senderKey.slice(0, 12)}...`);
+          
+          // Wake the agent to handle the incoming private message
+          const wakeText = `⚡ New private message received!\n\nFrom: ${msg.senderKey}\nMessage: ${msg.body}\n\nYou can reply using messagebox({ action: "send", recipientKey: "${msg.senderKey}", body: "..." })`;
+          
+          api.wakeAgent?.({
+            prompt: wakeText,
+            sessionKey: `hook:messagebox:${msg.id}`
+          });
+        });
+      } catch (err: any) {
+        api.logger.error(`[messagebox] WebSocket listener failed: ${err.message}`);
+      }
     },
     stop: async () => {
-      api.logger.info("[messagebox] Stopping MessageBox WebSocket listener...");
+      api.logger.info("[messagebox] Stopping WebSocket listener...");
     }
   });
 }