openclaw-overlay-plugin 0.7.22

package/src/scripts/wallet/balance.ts

@@ -0,0 +1,277 @@
+/**
+ * Wallet balance commands: balance, import, refund.
+ */
+
+import fs from 'node:fs';
+import { NETWORK, WALLET_DIR, PATHS } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadWalletIdentity } from './identity.js';
+import { wocFetch, fetchBeefFromWoC, getExplorerBaseUrl } from '../utils/woc.js';
+import { buildMerklePathFromTSC } from '../utils/merkle.js';
+import { loadStoredChange, deleteStoredChange } from '../utils/storage.js';
+
+import { BSVAgentWallet } from '../../core/index.js';
+
+async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
+  return BSVAgentWallet;
+}
+
+// Dynamic import for @bsv/sdk
+let _sdk: any = null;
+
+async function getSdk(): Promise<any> {
+  if (_sdk) return _sdk;
+
+  try {
+    _sdk = await import('@bsv/sdk');
+    return _sdk;
+  } catch {
+    const { fileURLToPath } = await import('node:url');
+    const path = await import('node:path');
+    const os = await import('node:os');
+
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+      path.resolve(__dirname, '..', '..', '..', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(__dirname, '..', '..', '..', '..', '..', 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(os.homedir(), 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+    ];
+
+    for (const p of candidates) {
+      try {
+        _sdk = await import(p);
+        return _sdk;
+      } catch {
+        // Try next
+      }
+    }
+    throw new Error('Cannot find @bsv/sdk. Run setup.sh first.');
+  }
+}
+
+/**
+ * Sleep helper for polling
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Balance command: show wallet balance.
+ */
+export async function cmdBalance(): Promise<never> {
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const sdk = await getSdk();
+
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const total = await wallet.getBalance();
+  await wallet.destroy();
+
+  return ok({ walletBalance: total });
+}
+
+/**
+ * Import command: import external UTXO with merkle proof.
+ * 
+ * This function handles both confirmed and unconfirmed transactions.
+ * For unconfirmed transactions, it uses BEEF from WoC which includes
+ * the source chain back to confirmed ancestors (SPV-compliant).
+ * 
+ * If the transaction isn't yet on WoC (just broadcast), it will poll
+ * with exponential backoff for up to 60 seconds.
+ */
+export async function cmdImport(txidArg: string | undefined, voutStr?: string): Promise<never> {
+  if (!txidArg) {
+    return fail('Usage: import <txid> [vout]');
+  }
+
+  const vout = parseInt(voutStr || '0', 10);
+  const txid = txidArg.toLowerCase();
+
+  if (!/^[0-9a-f]{64}$/.test(txid)) {
+    return fail('Invalid txid — must be 64 hex characters');
+  }
+
+  const sdk = await getSdk();
+  const BSVAgentWallet = await getBSVAgentWallet();
+
+  // Poll for transaction on WoC with exponential backoff
+  // This handles the case where user just broadcast and WoC hasn't indexed yet
+  let txInfo: any = null;
+  const maxWaitMs = 60000; // 60 seconds max
+  const startTime = Date.now();
+  let attempt = 0;
+  
+  while (Date.now() - startTime < maxWaitMs) {
+    const txInfoResp = await wocFetch(`/tx/${txid}`, {}, 1, 10000); // Single retry, 10s timeout
+    
+    if (txInfoResp.ok) {
+      txInfo = await txInfoResp.json();
+      break;
+    } else if (txInfoResp.status === 404) {
+      // Transaction not found yet - wait and retry
+      attempt++;
+      const delayMs = Math.min(1000 * Math.pow(1.5, attempt), 10000); // 1s, 1.5s, 2.25s, ... max 10s
+      console.error(`[import] Transaction not on WoC yet, waiting ${Math.round(delayMs/1000)}s... (attempt ${attempt})`);
+      await sleep(delayMs);
+      continue;
+    } else {
+      return fail(`Failed to fetch tx info: ${txInfoResp.status}`);
+    }
+  }
+
+  if (!txInfo) {
+    return fail(`Transaction ${txid} not found on WhatsOnChain after ${Math.round((Date.now() - startTime) / 1000)}s. The transaction may not have been broadcast yet, or the txid may be incorrect.`);
+  }
+
+  const isConfirmed = txInfo.confirmations && txInfo.confirmations >= 1;
+  const blockHeight = txInfo.blockheight;
+
+  // Validate output exists
+  if (!txInfo.vout || !txInfo.vout[vout]) {
+    return fail(`Output index ${vout} not found in transaction (has ${txInfo.vout?.length || 0} outputs)`);
+  }
+
+  let atomicBeefBytes: Uint8Array | undefined;
+
+  // Try WoC BEEF first - works for both confirmed and unconfirmed transactions
+  // WoC provides BEEF with full source chain back to confirmed ancestors
+  const wocBeefBytes = await fetchBeefFromWoC(txid);
+  
+  if (wocBeefBytes) {
+    try {
+      const wocBeef = sdk.Beef.fromBinary(Array.from(wocBeefBytes));
+      const foundTx = wocBeef.findTxid(txid);
+      
+      if (foundTx) {
+        // Verify the output exists in the parsed tx
+        const txObj = foundTx.tx || foundTx._tx;
+        if (txObj) {
+          const output = txObj.outputs[vout];
+          if (!output) {
+            return fail(`Output index ${vout} not found in BEEF transaction (has ${txObj.outputs.length} outputs)`);
+          }
+        }
+        atomicBeefBytes = wocBeef.toBinaryAtomic(txid);
+      }
+    } catch (beefErr: any) {
+      console.error(`[import] WoC BEEF parse failed: ${beefErr.message}`);
+      // Fall through to manual construction
+    }
+  }
+
+  // Fallback for confirmed txs: construct BEEF manually using TSC merkle proof
+  if (!atomicBeefBytes && isConfirmed) {
+    try {
+      const rawTxResp = await wocFetch(`/tx/${txid}/hex`);
+      if (!rawTxResp.ok) {
+        return fail(`Failed to fetch raw transaction: ${rawTxResp.status}`);
+      }
+      const rawTxHex = await rawTxResp.text();
+      const sourceTx = sdk.Transaction.fromHex(rawTxHex.trim());
+
+      const proofResp = await wocFetch(`/tx/${txid}/proof/tsc`);
+      if (!proofResp.ok) {
+        return fail(`Failed to fetch merkle proof: ${proofResp.status}`);
+      }
+      const proofData = await proofResp.json();
+      
+      if (!Array.isArray(proofData) || proofData.length === 0) {
+        return fail('Merkle proof not available from WoC');
+      }
+
+      const proof = proofData[0];
+      const merklePath = await buildMerklePathFromTSC(txid, proof.index, proof.nodes, blockHeight);
+      sourceTx.merklePath = merklePath;
+
+      const beef = new sdk.Beef();
+      beef.mergeTransaction(sourceTx);
+      atomicBeefBytes = beef.toBinaryAtomic(txid);
+    } catch (manualErr: any) {
+      return fail(`Failed to construct BEEF manually: ${manualErr.message}`);
+    }
+  }
+
+  // If still no BEEF, we can't import
+  if (!atomicBeefBytes) {
+    if (isConfirmed) {
+      return fail(`Transaction ${txid} is confirmed but BEEF construction failed. This is unexpected — please report this issue.`);
+    } else {
+      // Unconfirmed and no BEEF available
+      // This can happen if the funding tx itself spends unconfirmed inputs
+      return fail(
+        `Transaction ${txid} is unconfirmed (${txInfo.confirmations || 0} confirmations) and BEEF is not available.\n\n` +
+        `This usually means the funding transaction spends from other unconfirmed transactions, creating a chain.\n` +
+        `Wait for 1 block confirmation (~10 minutes) and try again, or use a fresh UTXO as the funding source.`
+      );
+    }
+  }
+
+  // Get output satoshis for reporting
+  const outputSatoshis = txInfo.vout[vout].value != null
+    ? Math.round(txInfo.vout[vout].value * 1e8)
+    : undefined;
+
+  // Import into wallet
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const identityKey = await wallet.getIdentityKey();
+
+  try {
+    await wallet._setup.wallet.storage.internalizeAction({
+      tx: Array.from(atomicBeefBytes),
+      outputs: [{
+        outputIndex: vout,
+        protocol: 'wallet payment',
+        paymentRemittance: {
+          derivationPrefix: sdk.Utils.toBase64(sdk.Utils.toArray('import', 'utf8')),
+          derivationSuffix: sdk.Utils.toBase64(sdk.Utils.toArray('now', 'utf8')),
+          senderIdentityKey: identityKey,
+        },
+      }],
+      description: 'External funding import',
+    });
+
+    const balance = await wallet.getBalance();
+    await wallet.destroy();
+
+    const explorerBase = getExplorerBaseUrl();
+    return ok({
+      txid,
+      vout,
+      satoshis: outputSatoshis,
+      blockHeight: blockHeight || null,
+      confirmations: txInfo.confirmations || 0,
+      imported: true,
+      unconfirmed: !isConfirmed,
+      balance,
+      explorer: `${explorerBase}/tx/${txid}`,
+    });
+  } catch (err: any) {
+    await wallet.destroy();
+    
+    // Provide helpful error messages for common issues
+    if (err.message?.includes('already') || err.message?.includes('duplicate')) {
+      return fail(`UTXO ${txid}:${vout} appears to already be imported.`);
+    }
+    if (err.message?.includes('script') || err.message?.includes('locking')) {
+      return fail(`UTXO ${txid}:${vout} does not belong to this wallet's address. Make sure you sent to the correct address.`);
+    }
+    
+    return fail(`Failed to import UTXO: ${err.message}`);
+  }
+}
+
+/**
+ * Refund command: sweep wallet to an address.
+ */
+export async function cmdRefund(targetAddress: string | undefined): Promise<void> {
+  if (!targetAddress) {
+    return fail('Usage: refund <address>');
+  }
+
+  if (!fs.existsSync(PATHS.walletIdentity)) {
+    return fail('Wallet not initialized. Run: setup');
+  }
+
+  // TODO IMPLEMENT THIS
+}

package/src/scripts/wallet/identity.ts

@@ -0,0 +1,203 @@
+/**
+ * Wallet identity helpers.
+ */
+
+import fs from 'node:fs';
+import { PATHS } from '../config.js';
+import type { WalletIdentity } from '../types.js';
+import { CachedKeyDeriver, Utils } from '@bsv/sdk';
+import { brc29ProtocolID } from '@bsv/wallet-toolbox';
+
+// Dynamic import for @bsv/sdk
+let _sdk: any = null;
+
+async function getSdk(): Promise<any> {
+  if (_sdk) return _sdk;
+
+  try {
+    _sdk = await import('@bsv/sdk');
+    return _sdk;
+  } catch {
+    const { fileURLToPath } = await import('node:url');
+    const path = await import('node:path');
+    const os = await import('node:os');
+
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+      path.resolve(__dirname, '..', '..', '..', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(__dirname, '..', '..', '..', '..', '..', 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(os.homedir(), 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+    ];
+
+    for (const p of candidates) {
+      try {
+        _sdk = await import(p);
+        return _sdk;
+      } catch {
+        // Try next
+      }
+    }
+    throw new Error('Cannot find @bsv/sdk. Run setup.sh first.');
+  }
+}
+
+/**
+ * Load wallet identity from disk.
+ * @returns Identity object with rootKeyHex and identityKey
+ * @throws Error if wallet not initialized
+ */
+export function loadWalletIdentity(): WalletIdentity {
+  if (!fs.existsSync(PATHS.walletIdentity)) {
+    throw new Error('Wallet not initialized. Run: cli setup');
+  }
+
+  // Security warning for overly permissive file mode
+  try {
+    const fileMode = fs.statSync(PATHS.walletIdentity).mode & 0o777;
+    if (fileMode & 0o044) { // world or group readable
+      console.error(`[security] WARNING: ${PATHS.walletIdentity} has permissive mode 0${fileMode.toString(8)}. Run: chmod 600 ${PATHS.walletIdentity}`);
+    }
+  } catch {
+    // Ignore stat errors
+  }
+
+  return JSON.parse(fs.readFileSync(PATHS.walletIdentity, 'utf-8'));
+}
+
+/**
+ * Load identity and private key for relay message signing.
+ * @returns Object with identityKey and privKey
+ */
+export async function loadIdentity(): Promise<{ identityKey: string; privKey: any }> {
+  const identity = loadWalletIdentity();
+  const sdk = await getSdk();
+  const privKey = sdk.PrivateKey.fromHex(identity.rootKeyHex);
+  return { identityKey: identity.identityKey, privKey };
+}
+
+/**
+ * Sign a relay message using ECDSA.
+ * @param privKey - Private key for signing
+ * @param to - Recipient's identity key
+ * @param type - Message type
+ * @param payload - Message payload
+ * @returns Hex-encoded DER signature
+ */
+export async function signRelayMessage(
+  privKey: any,
+  to: string,
+  type: string,
+  payload: unknown
+): Promise<string> {
+  const sdk = await getSdk();
+  const preimage = to + type + JSON.stringify(payload);
+  const msgHash = sdk.Hash.sha256(Array.from(new TextEncoder().encode(preimage)));
+  const sig = privKey.sign(msgHash);
+  return (Array.from(sig.toDER()) as number[]).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Verify a relay message signature.
+ * @param fromKey - Sender's public key
+ * @param to - Recipient's identity key
+ * @param type - Message type
+ * @param payload - Message payload
+ * @param signatureHex - Hex-encoded DER signature
+ * @returns Verification result
+ */
+export async function verifyRelaySignature(
+  fromKey: string,
+  to: string,
+  type: string,
+  payload: unknown,
+  signatureHex: string | undefined
+): Promise<{ valid: boolean; reason?: string }> {
+  if (!signatureHex) return { valid: false, reason: 'no signature' };
+
+  try {
+    const sdk = await getSdk();
+    const preimage = to + type + JSON.stringify(payload);
+    const msgHash = sdk.Hash.sha256(Array.from(new TextEncoder().encode(preimage)));
+    const sigBytes: number[] = [];
+    for (let i = 0; i < signatureHex.length; i += 2) {
+      sigBytes.push(parseInt(signatureHex.substring(i, i + 2), 16));
+    }
+    const sig = sdk.Signature.fromDER(sigBytes);
+    const pubKey = sdk.PublicKey.fromString(fromKey);
+    return { valid: pubKey.verify(msgHash, sig) };
+  } catch (err) {
+    return { valid: false, reason: String(err) };
+  }
+}
+
+/**
+ * Derive wallet address components from a private key.
+ * 
+ * IMPORTANT: This uses BRC-29 key derivation to create a child key.
+ * Any transactions spending to this address MUST use the matching
+ * child private key for signing, NOT the root key.
+ * 
+ * Use deriveWalletKeys() to get both the address and signing key.
+ */
+export async function deriveWalletAddress(privKey: any): Promise<{
+  address: string;
+  hash160: Uint8Array;
+  pubKey: any;
+}> {
+  
+  const keyDeriver = new CachedKeyDeriver(privKey);
+  const pubKey = keyDeriver.derivePublicKey(
+    brc29ProtocolID,
+    Utils.toBase64(Utils.toArray('import')) + ' ' + Utils.toBase64(Utils.toArray('now')),
+    'self',
+    true
+  );
+
+  const address = pubKey.toAddress();
+  const hash160 = Buffer.from(pubKey.toHash());
+
+  return { address, hash160, pubKey };
+}
+
+/**
+ * Derive wallet keys for both address AND transaction signing.
+ * 
+ * CRITICAL: Use this function to get the child private key for signing
+ * transactions that spend from the derived address. Do NOT use the
+ * root private key - it will cause signature verification failures!
+ * 
+ * @param rootPrivKey - Root private key from wallet identity
+ * @returns Object with address, hash160, and CHILD private key for signing
+ */
+export async function deriveWalletKeys(rootPrivKey: any): Promise<{
+  address: string;
+  hash160: Uint8Array;
+  pubKey: any;
+  childPrivKey: any;
+}> {
+  const keyDeriver = new CachedKeyDeriver(rootPrivKey);
+  
+  const derivationPrefix = Utils.toBase64(Utils.toArray('import'));
+  const derivationSuffix = Utils.toBase64(Utils.toArray('now'));
+  const keyString = `${derivationPrefix} ${derivationSuffix}`;
+  
+  // Derive child private key (for signing)
+  const childPrivKey = keyDeriver.derivePrivateKey(
+    brc29ProtocolID,
+    keyString,
+    'self'
+  );
+  
+  // Derive child public key (for address)
+  const pubKey = keyDeriver.derivePublicKey(
+    brc29ProtocolID,
+    keyString,
+    'self',
+    true
+  );
+
+  const address = pubKey.toAddress();
+  const hash160 = Buffer.from(pubKey.toHash());
+
+  return { address, hash160, pubKey, childPrivKey };
+}

package/src/scripts/wallet/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Wallet module exports.
+ */
+
+export * from './identity.js';
+export * from './setup.js';
+export * from './balance.js';

package/src/scripts/wallet/setup.ts

@@ -0,0 +1,121 @@
+/**
+ * Wallet setup commands: setup, identity, address.
+ */
+
+import fs from 'node:fs';
+import { NETWORK, WALLET_DIR, OVERLAY_URL, PATHS } from '../config.js';
+import { ok, fail } from '../output.js';
+import { loadWalletIdentity, deriveWalletAddress } from './identity.js';
+
+import { BSVAgentWallet } from '../../core/index.js';
+
+async function getBSVAgentWallet(): Promise<typeof BSVAgentWallet> {
+  return BSVAgentWallet;
+}
+
+// Dynamic import for @bsv/sdk
+let _sdk: any = null;
+
+async function getSdk(): Promise<any> {
+  if (_sdk) return _sdk;
+
+  try {
+    _sdk = await import('@bsv/sdk');
+    return _sdk;
+  } catch {
+    const { fileURLToPath } = await import('node:url');
+    const path = await import('node:path');
+    const os = await import('node:os');
+
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+      path.resolve(__dirname, '..', '..', '..', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(__dirname, '..', '..', '..', '..', '..', 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+      path.resolve(os.homedir(), 'a2a-bsv', 'packages', 'core', 'node_modules', '@bsv', 'sdk', 'dist', 'esm', 'mod.js'),
+    ];
+
+    for (const p of candidates) {
+      try {
+        _sdk = await import(p);
+        return _sdk;
+      } catch {
+        // Try next
+      }
+    }
+    throw new Error('Cannot find @bsv/sdk. Run setup.sh first.');
+  }
+}
+
+/**
+ * Setup command: create wallet and show identity.
+ */
+export async function cmdSetup(): Promise<never> {
+  const BSVAgentWallet = await getBSVAgentWallet();
+
+  if (fs.existsSync(PATHS.walletIdentity)) {
+    const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+    const identityKey = await wallet.getIdentityKey();
+    await wallet.destroy();
+
+    return ok({
+      identityKey,
+      walletDir: WALLET_DIR,
+      network: NETWORK,
+      overlayUrl: OVERLAY_URL,
+      alreadyExisted: true,
+    });
+  }
+
+  fs.mkdirSync(WALLET_DIR, { recursive: true });
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const identityKey = await wallet.getIdentityKey();
+  await wallet.destroy();
+
+  // Restrict permissions on wallet-identity.json (contains private key)
+  if (fs.existsSync(PATHS.walletIdentity)) {
+    fs.chmodSync(PATHS.walletIdentity, 0o600);
+  }
+
+  return ok({
+    identityKey,
+    walletDir: WALLET_DIR,
+    network: NETWORK,
+    overlayUrl: OVERLAY_URL,
+    alreadyExisted: false,
+  });
+}
+
+/**
+ * Identity command: show identity public key.
+ */
+export async function cmdIdentity(): Promise<never> {
+  const BSVAgentWallet = await getBSVAgentWallet();
+  const wallet = await BSVAgentWallet.load({ network: NETWORK, storageDir: WALLET_DIR });
+  const identityKey = await wallet.getIdentityKey();
+  await wallet.destroy();
+
+  return ok({ identityKey });
+}
+
+/**
+ * Address command: show P2PKH receive address.
+ */
+export async function cmdAddress(): Promise<never> {
+  if (!fs.existsSync(PATHS.walletIdentity)) {
+    return fail('Wallet not initialized. Run: setup');
+  }
+
+  const sdk = await getSdk();
+  const identity = loadWalletIdentity();
+  const privKey = sdk.PrivateKey.fromHex(identity.rootKeyHex);
+  const { address } = await deriveWalletAddress(privKey);
+
+  return ok({
+    address,
+    network: NETWORK,
+    identityKey: identity.identityKey,
+    note: NETWORK === 'mainnet'
+      ? `Fund this address at an exchange — Explorer: https://whatsonchain.com/address/${address}`
+      : `Fund via faucet: https://witnessonchain.com/faucet/tbsv — Explorer: https://test.whatsonchain.com/address/${address}`,
+  });
+}