Shoon A2A Trust Services (pilot)

A2A Service System — Phase 0 Sandbox (ローカルテスト専用)

テストサンドボックスです。 すべて無料（$0.00）で、テストネットの仕様に基づき、127.0.0.1 のみにバインドします。実際の暗号資産、実際の支払い、外部アカウント、資金移動は一切ありません。公開されておらず、商用でもありません。

実行

cd ~/workspace/compound/a2a-economy/sandbox
pip3 install --user --break-system-packages -r requirements.txt
# admin secret is REQUIRED — the server refuses to start without it
export A2A_SANDBOX_ADMIN="$(cat ~/.config/a2a-sandbox-admin)"
python3 -m uvicorn app:app --host 127.0.0.1 --port 8741

シークレットを一度だけ生成します（所有者のみがアクセスできる権限で保存され、チャットやログに記録されることはありません）。

mkdir -p ~/.config
python3 -c "import secrets; print(secrets.token_hex(32))" > ~/.config/a2a-sandbox-admin
chmod 600 ~/.config/a2a-sandbox-admin

続いて、別のターミナルで実行します。

# machine-readable catalog (Tier A)
curl -s http://127.0.0.1:8741/v1/catalog.json | head -c 600

# public free-slot counter
curl -s http://127.0.0.1:8741/v1/slots

# synthetic buyer harness (full loop per service, green/red per stage)
python3 harness.py

# human test page
# open http://127.0.0.1:8741/test.html in a browser (test API key prefilled)

実装済みの機能とスタブ

実装済み（プロトコルは完全に実装されています）：

• POST /quote — 無料、トークン消費ゼロ、数式に基づく固定見積もり、有効期限15分、入力上限とポリシーのチェック、台帳への記録
• POST /execute — 支払いなしの場合は402（x402形式のレスポンス）、モックのコミット後決済認可検証（構造、見積もりとの一致、validBeforeの有効期限）、202 + task_id、非同期ジョブキュー、Ed25519署名付き納品物、決済イベント
• クォータの適用：ID必須、ウォレットまたはAPIキーごとに1日あたり10タスク以下、サービス全体で1日あたり20タスク以下（公開スロットカウンター付き）、グローバルな1日のトークン予算（超過時は自動一時停止）
• キルスイッチを機能フラグとして実装（POST /v1/admin/kill / POST /v1/admin/resume、トークンはA2A_SANDBOX_ADMIN env経由 — トークンがない場合、サーバーは起動を拒否します）。自動再開はありません
• SSRF対策：タスクから提供されたURLを解決し、すべてのアドレスがパブリックであることを確認します（ループバック、プライベートLAN、リンクローカル、クラウドメタデータの各範囲を拒否し、リダイレクト経由の場合も対象です）。http(s)以外のスキームも拒否します
• 追記専用のJSONL台帳 + CSV/JSON税務エクスポート用スタブ（/v1/ledger/export）
• タスクごとのプライバシー保護（購入者ごとに固定）： タスクを受け付ける際、各タスクにランダムな256ビットのread_tokenが発行されます（202レスポンスで返されます — 秘密にし、パスワードと同様に扱ってください）。タスクのステータス、納品物、署名チェック、そのタスクの台帳エントリーへのアクセスには、すべてAuthorization: Bearer <token>ヘッダーが必要です。設計上、トークンはヘッダーのみで送信します。URLに含めると、サーバーのアクセスログに記録されるためです。トークンがない場合は401を返します。台帳全体（すべての購入者分）へのアクセスは管理者専用です（X-Admin-Tokenヘッダー）。タスクIDと見積もりIDは128ビットのランダム値です。管理者トークンの比較は時間差が一定になるように行われます
• 永続クォータ： 使用カウンターと一時停止状態はSQLite（data/quotas.db）に保存されるため、再起動しても1日の上限やキルスイッチの状態はリセットされません
• MCP（Model Context Protocol）： POST /mcpはStreamable HTTPに対応し、ステートレスなJSON-RPC 2.0を話します。対応機能はinitialize、tools/list（5つのサービス）、tools/call（見積もり → 受付 → 同期的に待機を実行し、署名付きの納品物を返します）。認証フローは2種類あります。人間向けの1ステップ方式（X-API-KEYヘッダー + arguments.input）、またはマシン向けの2ステップ方式（先にPOST /quoteを実行し、その見積もりを認可するX-PAYMENTヘッダーとarguments.quote_idを指定してtools/callを実行します）。呼び出しはmcpオリジンのトラフィックとして計上されます
• オリジンの追跡： 受け付けたすべてのタスクを、チャネル（human、machine、mcp）ごとに計上します。クォータ使用状況と併せて、管理者専用のGET /v1/admin/statsで確認できます
• Tier Aの機械可読ファイル：/v1/catalog.json、/.well-known/agent.json、/llms.txt、/v1/openapi.json、/robots.txt（AIクローラーを許可）
• 誠実なサービスロジック：ユーザーが提供したURLを実際にHTTPSで取得し、結果を明確に表示します

スタブ／シミュレーション：

• EIP-3009の認可はモックです（X-PAYMENTヘッダー内のbase64 JSON）。検証では形式、見積もりとの一致、有効期限をチェックしますが、オンチェーン署名は検証しません
• 決済は「テストネットの仕様」に基づく$0.00の台帳イベントです。チェーンとのやり取りも、フォーセットの資金もありません
• トークン予算は実際のLLMトークン数ではなく、入力バイト数からの推定によるシミュレーションです
• ニュースのトリップワイヤーは要求時にチェックします。バックグラウンドスケジューラーはまだありません
• ファシリテーター、エスクロー、Webhook配信はありません（webhook_urlは受け付けますが、呼び出しません）。Postgres/Inngestもありません
• 人間向けのパイロット用APIキーは固定のテストキーで、ユーザーごとには発行されません

誠実性に関するルール（コードで強制）

• すべての成果物に "sandbox": true が含まれます
• 主張の検証：「supported」とは、引用文が引用元に逐語的に記載されていることを意味し、「主張が真実である」ことではありません。検証できない場合は「unverified」とします
• 引用監査：実際の HTTP ステータスと逐語的なテキストの一致を報告します
• 作業証明：エビデンスの解決状況のみを確認し、作業が検証済みであるとは決して主張しません
• QA ゲート：sandbox フラグまたは必須の出力キーが欠けている結果はすべて失敗とします

ファイル

• app.py — FastAPI ゲートウェイ
• catalog.py — 5 つのサービス定義（スキーマ、上限、スロット）
• services.py — 誠実性を重視した最小限のサービスロジックと QA ゲート
• signing.py — Ed25519 の鍵管理
• ledger.py — 追記専用の JSONL 台帳
• quotas.py — 希少性に基づくクォータ、トークン予算、キルスイッチ
• harness.py — 合成バイヤーのハーネス
• static/ — agent.json、llms.txt、robots.txt、test.html（人間向けページ）
• data/ — 鍵と ledger.jsonl（実行時に作成され、慣例により Git の追跡対象外）