wallet

Wallet Skill

~/.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 はアトミックに処理されます。失敗した場合は、元のキーストアがバックアップから復元されます