@echoclaw/echo-0g 1.0.0

package/dist/commands/wallet.js

@@ -0,0 +1,748 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, cpSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { platform } from "node:os";
+import { Command } from "commander";
+import { isAddress, getAddress } from "viem";
+import { generatePrivateKey, privateKeyToAddress } from "viem/accounts";
+import { loadConfig, saveConfig } from "../config/store.js";
+import { CONFIG_DIR, BACKUPS_DIR } from "../config/paths.js";
+import { getPublicClient } from "../wallet/client.js";
+import { encryptPrivateKey, decryptPrivateKey, saveKeystore, loadKeystore, keystoreExists, normalizePrivateKey } from "../wallet/keystore.js";
+import { ERC20_ABI } from "../constants/chain.js";
+import { EchoError, ErrorCodes } from "../errors.js";
+import { requireKeystorePassword, getKeystorePassword } from "../utils/env.js";
+import { successBox, infoBox, warnBox, spinner, printTable, colors, formatAddress, formatBalance, } from "../utils/ui.js";
+import { writeStdout, writeStderr, isHeadless, isStdoutTTY, writeJsonSuccess } from "../utils/output.js";
+import logger from "../utils/logger.js";
+const MAX_WATCHLIST_TOKENS = 200;
+const MAX_BACKUPS = 20;
+function getCLIVersion() {
+    try {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(__dirname, "..", "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Create a backup of keystore.json and/or config.json.
+ * Returns backup path, or null if nothing to back up.
+ * Throws EchoError(AUTO_BACKUP_FAILED) on write failure.
+ */
+export async function autoBackup() {
+    const keystorePath = join(CONFIG_DIR, "keystore.json");
+    const configPath = join(CONFIG_DIR, "config.json");
+    const hasKeystore = existsSync(keystorePath);
+    const hasConfig = existsSync(configPath);
+    if (!hasKeystore && !hasConfig) {
+        return null;
+    }
+    try {
+        mkdirSync(BACKUPS_DIR, { recursive: true });
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "").replace("Z", "Z");
+        const backupDir = join(BACKUPS_DIR, timestamp);
+        mkdirSync(backupDir, { recursive: true });
+        const files = [];
+        if (hasKeystore) {
+            cpSync(keystorePath, join(backupDir, "keystore.json"));
+            files.push("keystore.json");
+        }
+        if (hasConfig) {
+            cpSync(configPath, join(backupDir, "config.json"));
+            files.push("config.json");
+        }
+        const cfg = loadConfig();
+        const manifest = {
+            version: 1,
+            cliVersion: getCLIVersion(),
+            createdAt: new Date().toISOString(),
+            walletAddress: cfg.wallet.address ?? null,
+            chainId: cfg.chain.chainId,
+            files,
+        };
+        writeFileSync(join(backupDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");
+        // Enforce retention: remove oldest if over MAX_BACKUPS
+        enforceBackupRetention();
+        logger.debug(`Auto-backup created at ${backupDir}`);
+        return backupDir;
+    }
+    catch (err) {
+        throw new EchoError(ErrorCodes.AUTO_BACKUP_FAILED, `Failed to create auto-backup: ${err instanceof Error ? err.message : String(err)}`, "Check permissions on the config directory.");
+    }
+}
+function enforceBackupRetention() {
+    if (!existsSync(BACKUPS_DIR))
+        return;
+    try {
+        const entries = readdirSync(BACKUPS_DIR, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .sort();
+        while (entries.length > MAX_BACKUPS) {
+            const oldest = entries.shift();
+            rmSync(join(BACKUPS_DIR, oldest), { recursive: true, force: true });
+            logger.debug(`Removed old backup: ${oldest}`);
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+function listBackups() {
+    if (!existsSync(BACKUPS_DIR))
+        return [];
+    try {
+        return readdirSync(BACKUPS_DIR, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => {
+            const manifestPath = join(BACKUPS_DIR, d.name, "manifest.json");
+            if (!existsSync(manifestPath))
+                return null;
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+                return { dir: join(BACKUPS_DIR, d.name), manifest };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((b) => b !== null)
+            .sort((a, b) => a.manifest.createdAt.localeCompare(b.manifest.createdAt));
+    }
+    catch {
+        return [];
+    }
+}
+// ──────────────────────────────────────────────
+// Import action (shared between `wallet import` and top-level `import`)
+// ──────────────────────────────────────────────
+export async function importPrivateKeyAction(privateKeyArg, options) {
+    // 1. Determine private key source: argument > --stdin > ECHO_IMPORT_KEY env
+    let rawKey = privateKeyArg;
+    if (!rawKey && options.stdin) {
+        try {
+            rawKey = readFileSync(0, "utf-8").trim();
+        }
+        catch {
+            throw new EchoError(ErrorCodes.INVALID_PRIVATE_KEY, "Failed to read private key from stdin.", "Usage: echo $KEY | echo wallet import --stdin");
+        }
+    }
+    if (!rawKey && process.env.ECHO_IMPORT_KEY) {
+        rawKey = process.env.ECHO_IMPORT_KEY;
+    }
+    if (!rawKey) {
+        throw new EchoError(ErrorCodes.INVALID_PRIVATE_KEY, "No private key provided.", "Provide via argument, --stdin, or ECHO_IMPORT_KEY env var.\n" +
+            "  echo wallet import 0xABC...\n" +
+            "  echo $KEY | echo wallet import --stdin\n" +
+            "  ECHO_IMPORT_KEY=0x... echo wallet import");
+    }
+    // 2. Validate key
+    let normalizedKey;
+    try {
+        normalizedKey = normalizePrivateKey(rawKey);
+    }
+    catch (err) {
+        throw new EchoError(ErrorCodes.INVALID_PRIVATE_KEY, `Invalid private key: ${err instanceof Error ? err.message : String(err)}`, "Private key must be 32 bytes hex (64 characters), optionally prefixed with 0x.");
+    }
+    // 3. Check existing keystore
+    if (keystoreExists() && !options.force) {
+        throw new EchoError(ErrorCodes.KEYSTORE_ALREADY_EXISTS, "Keystore already exists.", "Use --force to overwrite. Existing keystore will be backed up automatically.");
+    }
+    // 4. Auto-backup before overwrite
+    if (options.force && keystoreExists()) {
+        await autoBackup();
+    }
+    // 5. Get password
+    const password = requireKeystorePassword();
+    // 6. Encrypt and save
+    const spin = spinner("Encrypting and saving keystore...");
+    spin.start();
+    const keystore = encryptPrivateKey(normalizedKey, password);
+    saveKeystore(keystore);
+    // 7. Derive address and update config
+    const address = privateKeyToAddress(normalizedKey);
+    const cfg = loadConfig();
+    cfg.wallet.address = address;
+    saveConfig(cfg);
+    spin.succeed("Wallet imported");
+    // 8. Output (NEVER print private key)
+    const result = { address, chainId: cfg.chain.chainId };
+    if (isHeadless()) {
+        writeJsonSuccess(result);
+    }
+    else {
+        successBox("Wallet Imported", `Address: ${colors.address(address)}\n` +
+            `Chain: ${colors.info(cfg.chain.chainId.toString())}\n\n` +
+            colors.warn("Private key encrypted and stored locally.\n") +
+            colors.muted("Tip: Prefer --stdin or env var over argument (avoids shell history)."));
+    }
+}
+function requireWallet() {
+    const cfg = loadConfig();
+    if (!cfg.wallet.address) {
+        throw new EchoError(ErrorCodes.WALLET_NOT_CONFIGURED, "No wallet configured.", "Run: echo wallet ensure --json  (to check status and get instructions)");
+    }
+    return cfg.wallet.address;
+}
+export function createWalletCommand() {
+    const wallet = new Command("wallet")
+        .description("Wallet operations")
+        .exitOverride();
+    // echo wallet create
+    wallet
+        .command("create")
+        .description("Generate new wallet and save encrypted keystore")
+        .option("--force", "Overwrite existing keystore")
+        .action(async (options) => {
+        // 1. Check if keystore already exists
+        if (keystoreExists() && !options.force) {
+            throw new EchoError(ErrorCodes.KEYSTORE_ALREADY_EXISTS, "Keystore already exists.", "Use --force to overwrite. Existing keystore will be backed up automatically.");
+        }
+        // 2. Auto-backup before overwrite
+        if (options.force && keystoreExists()) {
+            await autoBackup();
+        }
+        // 3. Get password from env (required for automation)
+        const password = requireKeystorePassword();
+        // 4. Generate private key (NEVER print to stdout!)
+        const privateKey = generatePrivateKey();
+        const address = privateKeyToAddress(privateKey);
+        // 4. Encrypt and save
+        const spin = spinner("Encrypting and saving keystore...");
+        spin.start();
+        const keystore = encryptPrivateKey(privateKey, password);
+        saveKeystore(keystore);
+        // 5. Update config with address
+        const cfg = loadConfig();
+        cfg.wallet.address = address;
+        saveConfig(cfg);
+        spin.succeed("Wallet created");
+        // 6. Output
+        const result = { address, chainId: cfg.chain.chainId };
+        if (isHeadless()) {
+            writeJsonSuccess(result);
+        }
+        else {
+            successBox("Wallet Created", `Address: ${colors.address(address)}\n` +
+                `Chain: ${colors.info(cfg.chain.chainId.toString())}\n\n` +
+                colors.warn("⚠ Private key encrypted and stored locally."));
+        }
+    });
+    // echo wallet address
+    wallet
+        .command("address")
+        .description("Display configured wallet address")
+        .action(async () => {
+        const address = requireWallet();
+        if (isHeadless()) {
+            writeJsonSuccess({ address });
+        }
+        else {
+            writeStdout(address);
+        }
+    });
+    // echo wallet balance
+    wallet
+        .command("balance")
+        .description("Show native and token balances")
+        .option("-t, --tokens", "Include watchlist tokens")
+        .action(async (options) => {
+        const address = requireWallet();
+        const cfg = loadConfig();
+        const client = getPublicClient();
+        const spin = spinner(`Fetching balance from ${cfg.chain.chainId === 16661 ? "0G Mainnet" : `chain ${cfg.chain.chainId}`}...`);
+        spin.start();
+        try {
+            // Fetch native balance
+            const nativeBalance = await client.getBalance({ address });
+            spin.succeed("Balance fetched");
+            // Prepare table data
+            const rows = [];
+            // Native balance (0G)
+            rows.push([
+                colors.bold("0G"),
+                colors.value(formatBalance(nativeBalance, 18)),
+                colors.muted("native"),
+            ]);
+            const tokenRows = [];
+            if (options.tokens && cfg.watchlist.tokens.length > 0) {
+                const tokenSpin = spinner(`Fetching ${cfg.watchlist.tokens.length} token(s)...`);
+                tokenSpin.start();
+                for (const tokenAddr of cfg.watchlist.tokens) {
+                    try {
+                        // Multicall for symbol, decimals, balanceOf
+                        const [symbol, decimals, balance] = await Promise.all([
+                            client.readContract({
+                                address: tokenAddr,
+                                abi: ERC20_ABI,
+                                functionName: "symbol",
+                            }).catch(() => null),
+                            client.readContract({
+                                address: tokenAddr,
+                                abi: ERC20_ABI,
+                                functionName: "decimals",
+                            }).catch(() => 18),
+                            client.readContract({
+                                address: tokenAddr,
+                                abi: ERC20_ABI,
+                                functionName: "balanceOf",
+                                args: [address],
+                            }),
+                        ]);
+                        const displaySymbol = (symbol ?? formatAddress(tokenAddr, 4));
+                        const rawDecimals = typeof decimals === "bigint"
+                            ? Number(decimals)
+                            : typeof decimals === "number"
+                                ? decimals
+                                : 18;
+                        const displayDecimals = Math.min(255, Math.max(0, rawDecimals));
+                        // Store for JSON output
+                        tokenRows.push({
+                            address: tokenAddr,
+                            symbol: displaySymbol,
+                            decimals: displayDecimals,
+                            balanceWei: balance.toString(),
+                            balance: formatBalance(balance, displayDecimals),
+                        });
+                        rows.push([
+                            colors.bold(displaySymbol),
+                            colors.value(formatBalance(balance, displayDecimals)),
+                            colors.muted(formatAddress(tokenAddr, 4)),
+                        ]);
+                    }
+                    catch (err) {
+                        logger.debug(`Failed to fetch token ${tokenAddr}: ${err}`);
+                        tokenRows.push({
+                            address: tokenAddr,
+                            symbol: formatAddress(tokenAddr, 4),
+                            decimals: 18,
+                            balanceWei: "0",
+                            balance: "0",
+                            error: true,
+                        });
+                        rows.push([
+                            colors.muted(formatAddress(tokenAddr, 4)),
+                            colors.error("error"),
+                            colors.muted(formatAddress(tokenAddr, 4)),
+                        ]);
+                    }
+                }
+                tokenSpin.succeed(`Fetched ${cfg.watchlist.tokens.length} token(s)`);
+            }
+            // JSON output for automation
+            if (isHeadless()) {
+                const result = {
+                    address,
+                    chainId: cfg.chain.chainId,
+                    native: {
+                        symbol: "0G",
+                        balanceWei: nativeBalance.toString(),
+                        balance: formatBalance(nativeBalance, 18),
+                    },
+                };
+                // Include tokens if requested and fetched
+                if (options.tokens && cfg.watchlist.tokens.length > 0) {
+                    result.tokens = tokenRows;
+                }
+                writeJsonSuccess(result);
+                return;
+            }
+            // Print header
+            writeStderr("");
+            infoBox("Wallet Balance", colors.address(address));
+            // Print table
+            printTable([
+                { header: "Token", width: 12 },
+                { header: "Balance", width: 20 },
+                { header: "Address", width: 16 },
+            ], rows);
+            if (!options.tokens && cfg.watchlist.tokens.length > 0) {
+                writeStderr(colors.muted(`\nTip: Use ${colors.info("--tokens")} to include ${cfg.watchlist.tokens.length} watchlist token(s)`));
+            }
+        }
+        catch (err) {
+            spin.fail("Failed to fetch balance");
+            const errMsg = err instanceof Error ? err.message : String(err);
+            if (errMsg.includes("fetch") || errMsg.includes("timeout") || errMsg.includes("ECONNREFUSED")) {
+                throw new EchoError(ErrorCodes.RPC_ERROR, `Could not connect to RPC: ${cfg.chain.rpcUrl}`, "Check your network or run: echo config set-rpc <new-url>");
+            }
+            throw new EchoError(ErrorCodes.RPC_ERROR, `RPC error: ${errMsg}`);
+        }
+    });
+    // echo wallet import <privateKey>
+    wallet
+        .command("import")
+        .description("Import private key into encrypted keystore (non-interactive)")
+        .argument("[privateKey]", "Private key hex (0x-prefixed or raw)")
+        .option("--stdin", "Read private key from stdin")
+        .option("--force", "Overwrite existing keystore (auto-backup first)")
+        .action(importPrivateKeyAction);
+    // echo wallet ensure
+    wallet
+        .command("ensure")
+        .description("Check wallet readiness (idempotent status check)")
+        .action(async () => {
+        const cfg = loadConfig();
+        const address = cfg.wallet.address;
+        const hasKeystore = keystoreExists();
+        const passwordSet = getKeystorePassword() !== null;
+        // Missing keystore
+        if (!hasKeystore) {
+            const result = {
+                status: "missing_keystore",
+                address: null,
+                hasKeystore: false,
+                passwordSet,
+                hint: "Run: echo wallet create --json OR echo wallet import <key>",
+            };
+            if (isHeadless()) {
+                writeJsonSuccess(result);
+            }
+            else {
+                warnBox("Missing Keystore", result.hint);
+            }
+            return;
+        }
+        // Missing password
+        if (!passwordSet) {
+            const result = {
+                status: "missing_password",
+                address: address ?? null,
+                hasKeystore: true,
+                passwordSet: false,
+                hint: "Run: echo setup password --from-env",
+            };
+            if (isHeadless()) {
+                writeJsonSuccess(result);
+            }
+            else {
+                warnBox("Missing Password", result.hint);
+            }
+            return;
+        }
+        // Try decrypt to verify password matches
+        const keystore = loadKeystore();
+        if (!keystore) {
+            const result = {
+                status: "missing_keystore",
+                address: null,
+                hasKeystore: false,
+                passwordSet,
+                hint: "Keystore file exists but could not be read. Run: echo wallet create --force --json",
+            };
+            if (isHeadless()) {
+                writeJsonSuccess(result);
+            }
+            else {
+                warnBox("Corrupt Keystore", result.hint);
+            }
+            return;
+        }
+        let derivedAddress;
+        try {
+            const pk = decryptPrivateKey(keystore, getKeystorePassword());
+            derivedAddress = privateKeyToAddress(pk);
+        }
+        catch {
+            const result = {
+                status: "password_mismatch",
+                address: address ?? null,
+                hasKeystore: true,
+                passwordSet: true,
+                hint: "Password does not decrypt keystore. Check ECHO_KEYSTORE_PASSWORD.",
+            };
+            if (isHeadless()) {
+                writeJsonSuccess(result);
+            }
+            else {
+                warnBox("Password Mismatch", result.hint);
+            }
+            return;
+        }
+        // Auto-fix address in config if missing or mismatched
+        if (!address || address.toLowerCase() !== derivedAddress.toLowerCase()) {
+            cfg.wallet.address = derivedAddress;
+            saveConfig(cfg);
+        }
+        // All good
+        const result = {
+            status: "ready",
+            address: derivedAddress,
+            hasKeystore: true,
+            passwordSet: true,
+        };
+        if (isHeadless()) {
+            writeJsonSuccess(result);
+        }
+        else {
+            successBox("Wallet Ready", `Address: ${colors.address(derivedAddress)}\n` +
+                `Keystore: ${colors.success("OK")}\n` +
+                `Password: ${colors.success("OK")}`);
+        }
+    });
+    // echo wallet export-key
+    wallet
+        .command("export-key")
+        .description("Export decrypted private key (manual-only, blocked in headless)")
+        .option("--to-file <path>", "Write private key to file (chmod 600)")
+        .option("--stdout", "Print to stdout")
+        .option("--i-understand", "Acknowledge risk of printing to stdout")
+        .action(async (opts) => {
+        // Guardrail: block in headless mode
+        if (isHeadless()) {
+            throw new EchoError(ErrorCodes.EXPORT_BLOCKED_HEADLESS, "export-key is disabled in headless/agent mode.", "This command is for manual use only. Run it in a terminal.");
+        }
+        // Must specify mode
+        if (!opts.toFile && !opts.stdout) {
+            throw new EchoError(ErrorCodes.EXPORT_REQUIRES_ACKNOWLEDGE, "Specify --to-file <path> or --stdout --i-understand.", "Example: echo wallet export-key --to-file ./my-key.txt");
+        }
+        // --stdout requires --i-understand and TTY
+        if (opts.stdout) {
+            if (!opts.iUnderstand) {
+                throw new EchoError(ErrorCodes.EXPORT_REQUIRES_ACKNOWLEDGE, "--stdout requires --i-understand flag.", "Add --i-understand to confirm you want the key printed to terminal.");
+            }
+            if (!isStdoutTTY()) {
+                throw new EchoError(ErrorCodes.EXPORT_BLOCKED_HEADLESS, "--stdout is only available in TTY mode.", "Use --to-file instead.");
+            }
+        }
+        // Decrypt
+        const password = requireKeystorePassword();
+        const keystore = loadKeystore();
+        if (!keystore) {
+            throw new EchoError(ErrorCodes.KEYSTORE_NOT_FOUND, "Keystore not found.", "Run: echo wallet create --json");
+        }
+        const pk = decryptPrivateKey(keystore, password);
+        if (opts.toFile) {
+            const fd = opts.toFile;
+            writeFileSync(fd, pk, { encoding: "utf-8", mode: platform() !== "win32" ? 0o600 : undefined });
+            successBox("Key Exported", `Written to: ${fd}\n${platform() !== "win32" ? "File permissions set to 600." : "Ensure this file is not accessible to other users."}`);
+        }
+        else if (opts.stdout) {
+            writeStdout(pk);
+            warnBox("Key Printed", "Private key was printed to stdout. Clear your terminal history.");
+        }
+    });
+    // echo wallet backup
+    const backupCmd = wallet.command("backup").description("Backup wallet keystore and config");
+    backupCmd
+        .action(async () => {
+        const backupPath = await autoBackup();
+        if (!backupPath) {
+            if (isHeadless()) {
+                writeJsonSuccess({ status: "nothing_to_backup", hint: "No keystore or config files found." });
+            }
+            else {
+                infoBox("Nothing to Backup", "No keystore.json or config.json found.");
+            }
+            return;
+        }
+        if (isHeadless()) {
+            writeJsonSuccess({ status: "created", path: backupPath });
+        }
+        else {
+            successBox("Backup Created", `Path: ${colors.info(backupPath)}`);
+        }
+    });
+    // echo wallet backup list
+    backupCmd
+        .command("list")
+        .description("List all backups")
+        .action(async () => {
+        const backups = listBackups();
+        if (isHeadless()) {
+            writeJsonSuccess({
+                backups: backups.map((b) => ({
+                    path: b.dir,
+                    createdAt: b.manifest.createdAt,
+                    walletAddress: b.manifest.walletAddress,
+                    files: b.manifest.files,
+                })),
+                count: backups.length,
+            });
+            return;
+        }
+        if (backups.length === 0) {
+            infoBox("No Backups", "No backups found. Run: echo wallet backup");
+            return;
+        }
+        writeStderr("");
+        infoBox("Wallet Backups", `${backups.length} backup(s) found`);
+        const rows = backups.map((b, i) => [
+            colors.muted((i + 1).toString()),
+            colors.info(b.manifest.createdAt),
+            colors.address(b.manifest.walletAddress ?? "n/a"),
+            colors.muted(b.manifest.files.join(", ")),
+        ]);
+        printTable([
+            { header: "#", width: 4 },
+            { header: "Created", width: 28 },
+            { header: "Address", width: 46 },
+            { header: "Files", width: 26 },
+        ], rows);
+    });
+    // echo wallet restore <backupDir>
+    wallet
+        .command("restore <backupDir>")
+        .description("Restore wallet from a backup directory")
+        .option("--force", "Required: confirm restore (overwrites current files)")
+        .action(async (backupDir, opts) => {
+        // Must have --force
+        if (!opts.force) {
+            throw new EchoError(ErrorCodes.CONFIRMATION_REQUIRED, "Restore requires --force flag.", "This will overwrite current keystore and config. Use --force to confirm.");
+        }
+        // Validate backup dir
+        const manifestPath = join(backupDir, "manifest.json");
+        if (!existsSync(manifestPath)) {
+            throw new EchoError(ErrorCodes.BACKUP_NOT_FOUND, `No manifest.json found in ${backupDir}.`, "Provide a valid backup directory (e.g. from echo wallet backup list).");
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        }
+        catch {
+            throw new EchoError(ErrorCodes.BACKUP_NOT_FOUND, "Failed to parse backup manifest.", "Backup may be corrupted.");
+        }
+        // Validate manifest.files
+        if (!Array.isArray(manifest.files) || !manifest.files.every((f) => typeof f === "string")) {
+            throw new EchoError(ErrorCodes.BACKUP_NOT_FOUND, "Invalid manifest: files must be an array of strings.", "Backup may be corrupted.");
+        }
+        const ALLOWED_RESTORE_FILES = new Set(["keystore.json", "config.json"]);
+        // Auto-backup current state before restore
+        await autoBackup();
+        // Ensure config directory exists
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        // Copy files from backup to CONFIG_DIR
+        for (const file of manifest.files) {
+            // Reject path traversal and non-allowlisted files
+            if (file.includes("/") || file.includes("\\") || file.includes("..")) {
+                throw new EchoError(ErrorCodes.BACKUP_NOT_FOUND, `Invalid file path in manifest: ${file}`, "Backup may be malicious.");
+            }
+            if (!ALLOWED_RESTORE_FILES.has(file)) {
+                throw new EchoError(ErrorCodes.BACKUP_NOT_FOUND, `Unexpected file in backup manifest: ${file}`, "Only keystore.json and config.json can be restored.");
+            }
+            const src = join(backupDir, file);
+            const dst = join(CONFIG_DIR, file);
+            if (!existsSync(src)) {
+                throw new EchoError(ErrorCodes.BACKUP_NOT_FOUND, `Missing file in backup: ${file}`, "Backup may be corrupted or incomplete.");
+            }
+            cpSync(src, dst);
+        }
+        const cfg = loadConfig();
+        const result = {
+            status: "restored",
+            address: cfg.wallet.address ?? null,
+            chainId: cfg.chain.chainId,
+            restoredFiles: manifest.files,
+            backupDir,
+        };
+        if (isHeadless()) {
+            writeJsonSuccess(result);
+        }
+        else {
+            successBox("Wallet Restored", `Address: ${colors.address(cfg.wallet.address ?? "unknown")}\n` +
+                `Files: ${manifest.files.join(", ")}\n` +
+                `From: ${colors.info(backupDir)}\n\n` +
+                colors.muted("Current state was auto-backed up before restore."));
+        }
+    });
+    // echo wallet tokens (subcommand group)
+    const tokens = wallet.command("tokens").description("Manage token watchlist");
+    // echo wallet tokens add <address>
+    tokens
+        .command("add <address>")
+        .description("Add token to watchlist")
+        .action(async (tokenAddress) => {
+        // Validate address
+        if (!isAddress(tokenAddress)) {
+            throw new EchoError(ErrorCodes.INVALID_ADDRESS, `Invalid address: ${tokenAddress}`);
+        }
+        const checksumAddr = getAddress(tokenAddress);
+        const cfg = loadConfig();
+        // Check if already in watchlist
+        if (cfg.watchlist.tokens.includes(checksumAddr)) {
+            if (isHeadless()) {
+                writeJsonSuccess({ address: checksumAddr, status: "already_exists", count: cfg.watchlist.tokens.length });
+            }
+            else {
+                warnBox("Already Added", `${colors.address(checksumAddr)} is already in your watchlist`);
+            }
+            return;
+        }
+        // Check limit
+        if (cfg.watchlist.tokens.length >= MAX_WATCHLIST_TOKENS) {
+            throw new EchoError(ErrorCodes.WATCHLIST_FULL, `Watchlist full: maximum ${MAX_WATCHLIST_TOKENS} tokens allowed.`, "Remove some tokens first with: echo wallet tokens remove <address>");
+        }
+        cfg.watchlist.tokens.push(checksumAddr);
+        saveConfig(cfg);
+        if (isHeadless()) {
+            writeJsonSuccess({ address: checksumAddr, status: "added", count: cfg.watchlist.tokens.length });
+        }
+        else {
+            successBox("Token Added", `${colors.address(checksumAddr)}\n\n` +
+                `Watchlist now has ${colors.info(cfg.watchlist.tokens.length.toString())} token(s)`);
+        }
+    });
+    // echo wallet tokens remove <address>
+    tokens
+        .command("remove <address>")
+        .description("Remove token from watchlist")
+        .action(async (tokenAddress) => {
+        // Validate address
+        if (!isAddress(tokenAddress)) {
+            throw new EchoError(ErrorCodes.INVALID_ADDRESS, `Invalid address: ${tokenAddress}`);
+        }
+        const checksumAddr = getAddress(tokenAddress);
+        const cfg = loadConfig();
+        const index = cfg.watchlist.tokens.findIndex((t) => t.toLowerCase() === checksumAddr.toLowerCase());
+        if (index === -1) {
+            if (isHeadless()) {
+                writeJsonSuccess({ address: checksumAddr, status: "not_found", count: cfg.watchlist.tokens.length });
+            }
+            else {
+                warnBox("Not Found", `${colors.address(checksumAddr)} is not in your watchlist`);
+            }
+            return;
+        }
+        cfg.watchlist.tokens.splice(index, 1);
+        saveConfig(cfg);
+        if (isHeadless()) {
+            writeJsonSuccess({ address: checksumAddr, status: "removed", count: cfg.watchlist.tokens.length });
+        }
+        else {
+            successBox("Token Removed", `${colors.address(checksumAddr)}\n\n` +
+                `Watchlist now has ${colors.info(cfg.watchlist.tokens.length.toString())} token(s)`);
+        }
+    });
+    // echo wallet tokens list
+    tokens
+        .command("list")
+        .description("List watchlist tokens")
+        .action(async () => {
+        const cfg = loadConfig();
+        if (isHeadless()) {
+            writeJsonSuccess({ tokens: cfg.watchlist.tokens, count: cfg.watchlist.tokens.length });
+            return;
+        }
+        if (cfg.watchlist.tokens.length === 0) {
+            infoBox("Empty Watchlist", `No tokens in watchlist.\n\n` +
+                `Add tokens with: ${colors.info("echo wallet tokens add <address>")}`);
+            return;
+        }
+        writeStderr("");
+        infoBox("Token Watchlist", `${cfg.watchlist.tokens.length} token(s)`);
+        const rows = cfg.watchlist.tokens.map((addr, i) => [
+            colors.muted((i + 1).toString()),
+            colors.address(addr),
+        ]);
+        printTable([
+            { header: "#", width: 5 },
+            { header: "Address", width: 46 },
+        ], rows);
+    });
+    return wallet;
+}
+//# sourceMappingURL=wallet.js.map