openclaw-simplesv-plugin 0.1.4 → 0.1.6

package/openclaw.plugin.json

@@ -1,5 +1,5 @@
 {
-  "id": "openclaw-simplesv",
+  "id": "openclaw-simplesv-plugin",
   "name": "BSV Simple Utility Belt",
   "description": "High-level blockchain operations: DIDs, PushDrop tokens, and Inscriptions. Supports optional MCP integration.",
   "version": "0.1.2",
@@ -20,6 +20,11 @@
         "default": "https://chaintracks-us-1.bsvb.tech",
         "description": "Custom Chaintracks server URL for SPV header verification"
       },
+      "arcUrl": {
+        "type": "string",
+        "default": "https://arc.gorillapool.io",
+        "description": "Custom ARC/Arcade server URL for transaction broadcasting"
+      },
       "walletDir": {
         "type": "string",
         "description": "Path to BSV wallet storage (defaults to ~/.openclaw/bsv-wallet)"
@@ -41,6 +46,12 @@
       "help": "Custom server for SPV block header verification",
       "advanced": true
     },
+    "arcUrl": {
+      "label": "ARC/Arcade Server URL",
+      "placeholder": "https://arc.gorillapool.io",
+      "help": "Custom server for transaction broadcasting",
+      "advanced": true
+    },
     "enableMcp": {
       "label": "Enable Advanced MCP Tools",
       "help": "Requires @bsv/simple-mcp to be installed"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-simplesv-plugin",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "OpenClaw plugin for advanced BSV operations (DIDs, Tokens, Inscriptions) via @bsv/simple and optional MCP integration",
   "type": "module",
   "main": "dist/index.js",

package/src/actions.ts

@@ -0,0 +1,54 @@
+import { ClawWalletCore } from './wallet.js';
+// @ts-ignore
+import { createDIDMethods } from '@bsv/simple/dist/modules/did.js';
+// @ts-ignore
+import { createInscriptionMethods } from '@bsv/simple/dist/modules/inscriptions.js';
+// @ts-ignore
+import { createTokenMethods } from '@bsv/simple/dist/modules/tokens.js';
+
+export class SimpleSVManager {
+  private didMethods: any;
+  private inscriptionMethods: any;
+  private tokenMethods: any;
+  private core: ClawWalletCore;
+
+  constructor(core: ClawWalletCore) {
+    this.core = core;
+    // Initialize high-level modules
+    this.didMethods = createDIDMethods(core);
+    this.inscriptionMethods = createInscriptionMethods(core);
+    this.tokenMethods = createTokenMethods(core);
+  }
+
+  async resolveDid(did: string) {
+    return await this.didMethods.resolveDID(did);
+  }
+
+  async getMyDid() {
+    return await this.didMethods.getDID();
+  }
+
+  async inscribe(data: any, text?: string) {
+    if (text) {
+      return await this.inscriptionMethods.createInscription({ text });
+    }
+    return await this.inscriptionMethods.createInscription({ data });
+  }
+
+  async issueToken(basket: string, data: any) {
+    return await this.tokenMethods.issueToken({ basket, data });
+  }
+
+  async transferToken(tokenId: string, recipientKey: string) {
+    return await this.tokenMethods.transferToken({ tokenId, recipientKey });
+  }
+
+  getStatus() {
+    return {
+      identityKey: this.core.identityKey,
+      address: this.core.getAddress(),
+      // @ts-ignore
+      status: this.core.getStatus()
+    };
+  }
+}

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

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;
+}