feat(solana): add Solana x402 payment support + SDK migration

[tenequm]

Summary

Add Solana x402 payment support alongside existing EVM (Base) payments, and migrate from hand-rolled x402 implementation to official @x402/fetch, @x402/evm, and @x402/svm SDKs.

Key changes:

• BIP-39/BIP-44 HD wallet derivation - single mnemonic derives both EVM and Solana keys
• Dual-chain x402 payment signing via registerExactEvmScheme + registerExactSvmScheme
• Solana USDC balance monitoring with configurable RPC (CLAWROUTER_SOLANA_RPC_URL)
• Payment chain logging via x402.onAfterPaymentCreation() hook
• /wallet export now includes mnemonic + Solana address for full backup
• /wallet setup-solana command for existing EVM-only users
• Fund-loss protection: refuses to overwrite mnemonic if wallet.key is deleted
• ProxyOptions refactored to accept wallet: WalletConfig object (prevents callers from forgetting to forward Solana keys)

Files added:

• src/wallet.ts - BIP-39 mnemonic + BIP-44 key derivation
• src/solana-balance.ts - Solana USDC balance checker
• src/spend-control.ts - Time-windowed spending limits
• src/wallet.test.ts (14 tests), src/x402-sdk.test.ts (7 tests), src/spend-control.test.ts (23 tests)
• test/test-solana-e2e.ts - E2E test against real blockrun.ai with dual-chain proxy

Files removed (replaced by SDK):

• src/x402.ts, src/payment-cache.ts, src/x402.test.ts

Three wallet scenarios supported:

1. wallet.key exists, no mnemonic - EVM-only mode
2. wallet.key + mnemonic exist - dual-chain mode
3. Nothing exists - generates BIP-39 mnemonic, derives both chains

Test plan

• TypeScript typecheck passes (npx tsc --noEmit)
• Build succeeds (npm run build)
• 256 unit/integration tests pass (npm test)
• Solana E2E test passes against real blockrun.ai (npx tsx test/test-solana-e2e.ts)
• Payment chain logging verified in E2E output: [ClawRouter] Payment signed on Base (EVM) (eip155:8453)
• Wallet migration scenarios traced through code for all 3 paths + edge cases

[1bcMax]

Code review

Found 2 issues:

1. src/spend-control.ts uses fs.readFileSync() directly instead of readTextFileSync from ./fs-read.js. PR Create helper function to handle reads #42 established and enforced a pattern that all production disk reads must go through the readTextFile/readTextFileSync helpers to avoid false-positive "potential exfiltration" warnings from the OpenClaw security scanner. All other production files follow this pattern. The fix is to replace fs.readFileSync(this.spendingFile, "utf-8") with readTextFileSync(this.spendingFile).

ClawRouter/src/spend-control.ts

Lines 14 to 16 in 6071556

	import * as fs from "node:fs";
	import * as path from "node:path";

ClawRouter/src/spend-control.ts

Lines 76 to 79 in 6071556

	try {
	if (fs.existsSync(this.spendingFile)) {
	const data = JSON.parse(fs.readFileSync(this.spendingFile, "utf-8"));
	const rawLimits = data.limits ?? {};

2. loadMnemonic() silently returns undefined when the mnemonic file exists but contains invalid/corrupt data. The existing loadSavedWallet() in the same file has an explicit safety pattern: "do NOT silently fall through to generate a new wallet — this would silently replace a funded wallet with an empty one" (line 57). The new loadMnemonic violates this principle — a corrupt mnemonic file causes the Solana wallet to be silently abandoned without any error or warning, potentially losing Solana funds at the derived address. It should throw an error (matching the loadSavedWallet pattern) when the file exists but fails validation.

ClawRouter/src/auth.ts

Lines 57 to 67 in 6071556

	// File exists but content is wrong — do NOT silently fall through to generate a new wallet.
	// This would silently replace a funded wallet with an empty one.
	console.error(`[ClawRouter] ✗ CRITICAL: Wallet file exists but has invalid format!`);
	console.error(`[ClawRouter] File: ${WALLET_FILE}`);
	console.error(`[ClawRouter] Expected: 0x followed by 64 hex characters (66 chars total)`);
	console.error(`[ClawRouter] To fix: restore your backup key or set BLOCKRUN_WALLET_KEY env var`);
	throw new Error(
	`Wallet file at ${WALLET_FILE} is corrupted or has wrong format. ` +
	`Refusing to auto-generate new wallet to protect existing funds. ` +
	`Restore your backup key or set BLOCKRUN_WALLET_KEY environment variable.`,
	);

ClawRouter/src/auth.ts

Lines 88 to 100 in 6071556

	/**
	* Load mnemonic from disk if it exists.
	*/
	async function loadMnemonic(): Promise<string | undefined> {
	try {
	const mnemonic = (await readTextFile(MNEMONIC_FILE)).trim();
	if (mnemonic && isValidMnemonic(mnemonic)) {
	return mnemonic;
	}
	} catch {
	// No mnemonic file or invalid - that's fine
	}
	return undefined;

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}