wallet

钱包技能

管理存储在本地 ~/.aibtc/ 的加密 BIP39 钱包。提供 Stacks L2 和 Bitcoin L1（原生 SegWit + Taproot）地址的完整生命周期操作。钱包使用密码通过 AES-GCM 加密，绝不会以明文形式存储。

用法

bun run wallet/wallet.ts <subcommand> [options]

子命令

create

创建钱包，并生成一个 24 词 BIP39 助记词。

bun run wallet/wallet.ts create --name <name> --password <password> [--network mainnet|testnet]

选项：

• --name（必需）— 钱包标签（例如“main”“trading”）
• --password（必需，至少 8 个字符）— 加密密码（敏感信息）
• --network（可选）— mainnet 或 testnet（默认：testnet）

输出：

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet",
  "mnemonic": "word1 word2 ... word24",
  "warning": "CRITICAL: Save this mnemonic..."
}

import

使用 BIP39 助记词导入现有钱包。

bun run wallet/wallet.ts import --name <name> --mnemonic "<24 words>" --password <password> [--network mainnet|testnet]

选项：

• --name（必需）— 钱包标签
• --mnemonic（必需）— 24 词 BIP39 助记词（敏感信息）
• --password（必需，至少 8 个字符）— 加密密码（敏感信息）
• --network（可选）— mainnet 或 testnet（默认：testnet）

输出：

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet"
}

unlock

解锁钱包以启用交易。会话将保留在进程内存中，直到钱包被锁定或超时。

bun run wallet/wallet.ts unlock --password <password> [--wallet-id <id>]

选项：

• --password（必需）— 钱包密码（敏感信息）
• --wallet-id（可选）— 要解锁的钱包 ID（若省略则使用当前钱包）

输出：

{
  "success": true,
  "walletId": "...",
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." },
  "Stacks (L2)": { "Address": "SP..." },
  "network": "testnet"
}

lock

锁定钱包，并清除内存中的敏感密钥材料。

bun run wallet/wallet.ts lock

输出：

{ "success": true, "message": "Wallet is now locked." }

list

列出所有可用钱包及其元数据（不含敏感数据）。

bun run wallet/wallet.ts list

输出：

{
  "wallets": [
    {
      "id": "...",
      "name": "main",
      "btcAddress": "bc1q...",
      "address": "SP...",
      "network": "testnet",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "isActive": true,
      "isUnlocked": false
    }
  ],
  "totalCount": 1
}

switch

切换当前钱包（切换后需要解锁）。

bun run wallet/wallet.ts switch --wallet-id <id>

选项：

• --wallet-id（必需）— 要设为当前钱包的钱包 ID

输出：

{
  "success": true,
  "activeWalletId": "...",
  "address": "SP...",
  "network": "testnet"
}

delete

永久删除钱包（需要密码和确认）。

bun run wallet/wallet.ts delete --wallet-id <id> --password <password> --confirm DELETE

选项：

• --wallet-id（必需）— 要删除的钱包 ID
• --password（必需）— 用于验证的钱包密码（敏感信息）
• --confirm（必需）— 必须严格为 DELETE

输出：

{
  "success": true,
  "deletedWalletId": "...",
  "message": "Wallet deleted permanently."
}

export

导出钱包的助记词（需要密码和安全确认）。

bun run wallet/wallet.ts export --password <password> --confirm I_UNDERSTAND_THE_RISKS [--wallet-id <id>]

选项：

• --password（必需）— 钱包密码（敏感信息）
• --confirm（必需）— 必须严格为 I_UNDERSTAND_THE_RISKS
• --wallet-id（可选）— 钱包 ID（若省略则使用当前钱包）

输出：

{
  "walletId": "...",
  "mnemonic": "word1 word2 ... word24",
  "warning": "SECURITY WARNING: ..."
}

rotate-password

更改钱包加密密码（通过备份、验证和回滚实现原子操作）。

bun run wallet/wallet.ts rotate-password --old-password <pass> --new-password <pass> [--wallet-id <id>]

选项：

• --old-password（必需）— 当前密码（敏感信息）
• --new-password（必需，至少 8 个字符）— 新密码（敏感信息）
• --wallet-id（可选）— 钱包 ID（若省略则使用当前钱包）

输出：

{
  "success": true,
  "walletId": "...",
  "message": "Password rotated. Use unlock with the new password."
}

set-timeout

设置自动锁定超时时间（分钟）（0 = 永不自动锁定）。

bun run wallet/wallet.ts set-timeout --minutes <n>

选项：

• --minutes（必需）— 自动锁定前的分钟数（0 = 禁用）

输出：

{
  "success": true,
  "autoLockMinutes": 15,
  "message": "Auto-lock set to 15 minutes."
}

status

获取钱包就绪状态：是否存在钱包、是否为当前钱包，以及是否已解锁。

bun run wallet/wallet.ts status

输出：

{
  "message": "Wallet is locked. Unlock to perform transactions.",
  "readyForTransactions": false,
  "isUnlocked": false,
  "currentNetwork": "testnet",
  "wallet": { "id": "...", "address": "SP...", "btcAddress": "bc1q..." }
}

info

获取当前钱包的地址和会话信息。

bun run wallet/wallet.ts info

输出：

{
  "status": "ready",
  "network": "testnet",
  "Stacks (L2)": { "Address": "SP..." },
  "Bitcoin (L1)": { "Native SegWit": "bc1q...", "Taproot": "bc1p..." }
}

stx-balance

获取钱包地址的 STX 余额。

bun run wallet/wallet.ts stx-balance [--address <addr>]

选项：

• --address（可选）— 要查询的 Stacks 地址（若省略则使用当前钱包）

输出：

{
  "address": "SP...",
  "network": "testnet",
  "balance": { "stx": "100 STX", "microStx": "100000000" },
  "locked": { "stx": "0 STX", "microStx": "0" }
}

安全说明

• 助记词经过 AES-GCM 加密后才会写入磁盘
• 存储的文件中绝不会出现密码
• 执行敏感操作后使用 lock 清除内存中的密钥
• export 和 delete 需要明确的确认字符串，以防意外操作
• rotate-password 是原子操作：原始密钥库会在失败时备份并还原