Skip to Content
Introductionアーキテクチャ

アーキテクチャ

Kova プロジェクトは、AI エージェントや開発者が安全に Web3 決済を行えるよう、複数のコンポーネントを組み合わせて構成されています。本ページは現行のコンポーネント構成と責務を示します。

現行構成: OperationKind 分類 / Signer 抽象化 / spending_limit を中心とする構成です。旧 KOVA_MODE env による mode 検知設計は廃止されました。

全体像

  • Kova (kova): ウォレット管理・送金を担う CLI コア
  • kova-skills: Claude Code や GPT などの AI エージェントが CLI を自然言語で操作するためのスキル集
  • OWS (Open Wallet Standard): ウォレット管理の標準と server-side 署名 API を提供する層
  • Chain Providers: Base / Ethereum / Polygon 等のブロックチェーンへの RPC 接続

コンポーネント図

ユーザーまたは AI エージェントは、直接 CLI を操作するか、kova-skills を介して自然言語で CLI を呼び出します。CLI は Signer interface を経由して OWS server / ローカル署名のいずれかで署名し、chain provider 経由でブロックチェーンに送信します。

主要コンポーネント

Commands 層

init / send / call / sign / delegate / balance / wallet / policy / key / status / swap / token 等の各コマンドを提供する層。

責務:

  • 引数を受け取って入力を検証
  • Guard 層で OperationKind に応じた事前チェック
  • Signer 抽象を呼び出して署名 / 送信を実行
  • すべての出力を JSON で stdout に返す

Guard 層（OperationKind チェック）

CLI 入口のガードがコマンドの OperationKind に応じて：

  • read-only → 認証チェックなし、そのまま通過
  • policy-gated → TTY 検出 + passphrase 経路、または credential + API key 経路を選択
  • owner-only → 非 TTY なら INTERACTIVE_INPUT_REQUIRED で fail-closed 拒否

を強制します。詳細は Security: OperationKind 3 分類 を参照。

Signer 層

すべての署名操作は Signer 抽象を介して実行され、command 層は credential の種類を意識しません。

実装kind役割
PassphraseSignerpassphraseTTY で passphrase を受け取り、ローカルで wallet file を復号して署名
ApiKeySignerapi-keyOWS API key を提示し、OWS server-side で署名（agent 経路）

Signer.enforce(ctx) は実 RPC 呼び出しの 前 に呼ばれ、ApiKeySigner では OWS server に policy + spending_limit を事前評価させます（fail-closed）。

OWS 層

OWS（Open Wallet Standard）は、ウォレット管理の標準仕様と server-side 署名 API を提供します。

  • ローカルファイル（~/.kova/wallets/<wallet-id>.json）を AES-256-GCM で暗号化保存
  • HD ウォレット（BIP-32 / BIP-44）の階層導出
  • API key 経由の server-side 署名（agent 経路）
  • policy / spending_limit の評価 gate

Chain Provider 層

Base / Ethereum / Polygon 等の各チェーンに対する RPC 接続。CAIP-2 形式のチェーン ID（例: eip155:8453）でアドレッシングされます。

Config / State

ファイル用途
~/.kova/config.jsonprofiles / activeProfile / credential / apiKeyId / defaultWallet 等
~/.kova/wallets/<id>.json暗号化されたウォレットファイル
~/.kova/spend.jsonspending_limit の累積記録（chain × token × 日付）

config.json の profiles[<name>].credential は kova init の AI 接続設定フェーズ（内部的にエージェントセットアップを実行）で書き込まれます。claude 等を起動した新しい kova プロセスはここから credential を直接読み取ります。launch は KOVA_CREDENTIAL / KOVA_API_KEY_ID を環境変数として子プロセスに注入する任意のラッパです。

実行経路（context × 認証）

context（TTY 有無）と認証手段の組み合わせで Signer が自動選択されます。

実行 contextcredential--owner flag選ばれる Signerenforce 動作
terminal（TTY）あり/なしなしPassphraseSignerno-op（terminal owner）
terminal（TTY）あり/なしありPassphraseSignerno-op
agent（非 TTY）ありなしApiKeySignerOWS で policy + spending_limit を評価
agent（非 TTY）なし-エラー（signing 不可）-
agent（非 TTY）あり/なしありエラー（passphrase 入力不可）-

kova status で現在の認証経路と policy enforcement を確認できます。詳細は status リファレンス を参照。

データフロー

通常の送金フロー（agent 経路）

初期セットアップフロー（agent 用）

  1. kova init で wallet 作成 / HD master 設定 / AI 接続設定（Step 3/4: permissive policy + API key 発行）/ skills 取得（Step 4/4）
  2. AI 接続設定フェーズが permissive policy（expires_at 1 年）+ API key を発行し、config.json に credential / apiKeyId を保存
  3. claude を直接起動すると、新しい kova プロセスが config.json から credential を読み取る（kova launch claude は環境変数を sanitize する任意のラッパ）
  4. agent から呼ばれた Kova は credential を見て ApiKeySigner 経路を選択

技術スタック

技術用途
OWS（Open Wallet Standard）ウォレット管理 + server-side 署名の標準
BIP-32 / BIP-44HD ウォレット階層導出
AES-256-GCMローカルウォレットの暗号化保存
CAIP-2チェーン ID の標準表記（例: eip155:8453）
viemEVM トランザクション構築 / authorization 署名
@clack/promptsinit などの対話 UI

次のステップ

Last updated on
Kovaとはユースケース