Wallets

ウォレットは、Kovaの中核となる機能です。ブロックチェーン上の資産を管理し、複数のチェーンに対応したアカウントを1つのウォレットで扱うことができます。

ウォレットとは

ウォレットは、暗号資産を送受信するためのデジタルな財布です。Kovaのウォレットは以下の特徴を持ちます：

• HDウォレット - 1つのシードから複数のアカウントを派生
• マルチチェーン対応 - Ethereum、Base、Polygon等の9つのチェーンに対応
• ローカル保管 - 秘密鍵はローカルに暗号化保存
• Open Wallet Standard準拠 - OWS (Open Wallet Standard) に準拠した実装
• シングルウォレット - v0.x は1ウォレット固定。kova init で作成され自動解決される

Open Wallet Standard (OWS)

KovaはOpen Wallet Standard に準拠しています。OWSは、AIエージェント向けのウォレット標準であり、以下を提供します：

• 統一されたAPI仕様
• セキュアな鍵管理
• マルチチェーン対応
• ポリシーベースのアクセス制御

OWSに準拠することで、他のOWS対応ツールとの相互運用性が保証されます。

システムアーキテクチャにおける位置づけ

Kovaは、AIエージェントコマースのプラットフォーム全体を支える3つの柱で構成されています。ウォレット機能は、決済基盤の中核を担います。

Kova アーキテクチャ
├── 決済基盤
│   ├── Wallet Interface (OWS) ← このドキュメントが対象
│   └── PolicyEngine
├── 外部サービス統合
│   └── オンランプ/オフランプ（将来）
└── ユーティリティ
    ├── 会計監査ツール（将来）
    └── 管理機能GUI（将来）

ウォレットは、Open Wallet Standard準拠のマルチチェーンウォレットインターフェースとして、暗号資産の送受信、残高管理、トランザクション署名を担当します。PolicyEngine と連携し、AIエージェントが安全に自動決済を行える環境を提供します。

HDウォレットと派生パス

Kovaは、BIP-32/BIP-44準拠のHD (Hierarchical Deterministic) ウォレットを使用します：

マスターシード
└── m/44'/60'/0'/0/0  (Ethereum系チェーン共通アドレス)
    ├── eip155:1 (Ethereum)
    ├── eip155:8453 (Base)
    ├── eip155:137 (Polygon)
    └── ...

派生パスの説明:

• m/44' - BIP-44標準
• 60' - Ethereum (Cointype)
• 0'/0/0 - アカウント/Change/Address Index

1つのウォレットから全チェーンのアドレスが自動生成されるため、チェーンごとにウォレットを作成する必要はありません。

HDウォレットの利点:

1. バックアップの簡素化 - マスターシードをバックアップするだけで、すべてのチェーンのアカウントを復元可能
2. 決定的な派生 - 同じシードからは常に同じアドレスが生成される
3. 階層的な管理 - 用途別にアカウントを分けることができる（将来機能）
4. 監査可能性 - 派生パスから特定のアドレスの生成過程を検証可能

派生パスの実例:

Ethereum系のチェーンでは、すべて同じ派生パスm/44'/60'/0'/0/0を使用するため、アドレスが統一されます。これにより、Baseで受け取ったトークンをEthereumで確認するといった混乱を防ぎます。

例: ウォレット "my-wallet" の場合

マスターシード: [秘密の12単語フレーズ]
↓
派生パス: m/44'/60'/0'/0/0
↓
Ethereum (eip155:1):   0xB8EC761bf83B4374877e903d217222F2cd5512De
Base (eip155:8453):    0xB8EC761bf83B4374877e903d217222F2cd5512De
Polygon (eip155:137):  0xB8EC761bf83B4374877e903d217222F2cd5512De

ウォレットの保管場所

ウォレットは以下のディレクトリに暗号化されて保存されます：

~/.kova/wallets/
└── <wallet-id>.json  # 暗号化されたウォレットファイル

暗号化方式:

• アルゴリズム: AES-256-GCM
• 鍵派生: PBKDF2 (パスワードベース)
• ソルト: ランダム生成
• 認証タグ: 改ざん検出

秘密鍵は平文で保存されることはなく、常に暗号化された状態で保管されます。

ウォレットの作成

ウォレットは kova init のインタラクティブオンボーディングウィザードで作成します。ウォレット作成専用の独立したコマンドは存在しません。

# ウォレット作成はオンボーディングウィザード経由
kova init

kova init は名前・パスフレーズの設定・HD マスターシードの生成・AI エージェント接続設定（credential / API key の発行）をまとめて行います。

ウォレット作成後は、kova wallet info で情報を確認できます：

kova wallet info

出力例:

{
  "ok": true,
  "data": {
    "wallet": {
      "id": "68cf6dba-e5f1-4c3a-9b2e-1234567890ab",
      "name": "my-wallet",
      "accounts": [
        {
          "chainId": "eip155:1",
          "address": "0xB8EC761bf83B4374877e903d217222F2cd5512De",
          "derivationPath": "m/44'/60'/0'/0/0"
        },
        {
          "chainId": "eip155:8453",
          "address": "0xB8EC761bf83B4374877e903d217222F2cd5512De",
          "derivationPath": "m/44'/60'/0'/0/0"
        }
      ]
    }
  }
}

全チェーンで同じアドレスが生成されることに注目してください。これにより、複数チェーン間での資産管理がシンプルになります。

ウォレット管理コマンド

v0.x では1ウォレット固定です。kova wallet が提供するサブコマンドは以下の3つです：

# ウォレット情報を表示
kova wallet info
 
# ウォレットのシークレット（ニーモニックまたは秘密鍵）をエクスポート
kova wallet export
 
# シードフレーズを使ってパスフレーズをリセット
kova wallet reset-passphrase

残高確認はウォレットを指定する必要がなく、登録済みウォレットを自動解決します：

# 残高確認（全チェーン分を表示）
kova balance

ウォレットのバックアップ

ウォレットを失うと、資産へのアクセスが永久に失われます。必ずバックアップを取りましょう：

# ウォレットファイルのバックアップ
cp ~/.kova/wallets/<wallet-id>.json ~/backup/

重要:

• バックアップファイルは安全な場所に保管してください
• 暗号化されていても、パスワードが漏洩すると危険です
• 本番環境では、ハードウェアウォレットやKMSの使用を検討してください

セキュリティのポイント

ウォレットを安全に使用するための推奨事項：

1. 強力なパスワード - 12文字以上、大文字・小文字・数字・記号を含む
2. 定期的なバックアップ - 週次または月次でバックアップを取る
3. アクセス制限 - ウォレットファイルのパーミッションを制限 (chmod 600)
4. ポリシー設定 - API鍵にポリシーを関連付けて使用制限を設ける
5. dry-runの活用 - 本番送金前に必ずdry-runで確認

詳細なセキュリティ設定については、Securityを参照してください。

よくあるトラブルシューティング

ウォレットのパスワードを忘れた場合

パスフレーズを忘れた場合は、kova wallet reset-passphrase でシードフレーズ（ニーモニック）を使ってリセットできます。シードフレーズ自体を紛失した場合は、ウォレットの復号化は不可能です。バックアップファイルがあっても、シードフレーズがなければアクセスできません。これは、セキュリティを担保するための仕様です。

対処法:

• シードフレーズを安全な場所に保管する
• 定期的にバックアップと復元のテストを行う
• パスワードマネージャーで安全にパスフレーズを保管する
• 信頼できる場所にパスワードのヒントを記録する（完全なパスワードは記録しない）

ウォレットファイルが破損した場合

ウォレットファイルが破損した場合、バックアップから復元できます。

# バックアップから復元
cp ~/backup/<wallet-id>.json ~/.kova/wallets/

定期的にバックアップを取ることで、ファイル破損のリスクを軽減できます。

複数マシンでウォレットを使用する場合

ウォレットファイルを複数のマシンで共有する場合は、安全な方法でコピーしてください。

# マシンAでバックアップ
scp ~/.kova/wallets/<wallet-id>.json user@machineB:~/
 
# マシンBで配置
mkdir -p ~/.kova/wallets
mv ~/<wallet-id>.json ~/.kova/wallets/
 
# ウォレット情報で確認
kova wallet info

注意事項:

• 平文での転送は避け、必ずSSH/SCPなどの暗号化された通信を使用
• 公開ネットワーク経由での転送は避ける
• 不要になったコピーは速やかに削除

トランザクションが失敗する場合

送金トランザクションが失敗する場合、以下を確認してください：

1. 残高不足 - ガス代を含めた十分な残高があるか確認

   kova balance

2. ネットワークの混雑 - ガス代が高騰している場合は時間を置く

3. チェーンとトークンの組み合わせ - 指定したチェーンでトークンがサポートされているか確認

4. アドレスの形式 - 送信先アドレスが正しい形式（0x…）か確認

実践例

例1: テストネットで動作確認

本番環境での使用前に、必ずテストネットで動作確認を行いましょう：

# kova init でウォレットを作成（初回セットアップ）
kova init
 
# テストネットのフォーセットでETHを取得
# https://www.alchemy.com/faucets/base-sepolia
 
# 残高確認（全チェーン）
kova balance
 
# テスト送金（dry-run）
kova send --name my-wallet --to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --amount 0.001 --chain base-sepolia
 
# 問題なければbroadcast
kova send --name my-wallet --to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --amount 0.001 --chain base-sepolia --broadcast

例2: 本番環境での運用

テストネットでの動作確認後、本番環境に移行：

# ウォレットに入金（取引所から送金）
# アドレスは wallet info で確認
kova wallet info
 
# 残高確認（全チェーン）
kova balance
 
# 送金時は必ずdry-runで確認
kova send --name my-wallet --to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --amount 10 --chain base --token USDC
 
# 内容を確認してからbroadcast
kova send --name my-wallet --to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --amount 10 --chain base --token USDC --broadcast

セキュリティのベストプラクティス（詳細）

ウォレットを安全に運用するための詳細なガイドライン：

開発環境と本番環境の分離

v0.x は1ウォレット固定のため、開発と本番は 別マシン（または別ユーザー） で分離することを推奨します。開発環境では絶対に本番ウォレットを使用しないでください。誤送金やテストコードでの資産流出を防ぎます。

定期的なセキュリティチェック

月次または週次で以下を実施：

1. バックアップの検証 - バックアップから復元できるか確認
2. パーミッションの確認 - ls -la ~/.kova/wallets/ でパーミッションを確認
3. トランザクション履歴の確認 - 不審な送金がないかBlock Explorerで確認
4. API鍵の棚卸し - 使用していないAPI鍵を無効化

マルチシグ・ハードウェアウォレットの検討

高額の資産を扱う場合は、以下を検討してください：

• マルチシグウォレット - 複数の署名者による承認（将来対応予定）
• ハードウェアウォレット - Ledger、Trezor等（将来対応予定）
• KMS統合 - AWS KMS、Google Cloud KMS等（将来対応予定）

現在のKovaはローカル暗号化ウォレットのみですが、将来的にこれらの統合が予定されています。

次のステップ

• Chains and Tokens - サポートされているチェーンとトークンを確認
• Security - セキュリティのベストプラクティスを学ぶ
• CLI Commands: wallet - ウォレット管理コマンドの詳細
• Getting Started: Quickstart - 初めてのウォレット作成からエージェント起動までの手順