プロトコル仕様

本ページは、サードパーティのプロトコル実装者と、ワイヤ形式・データ構造・ネットワークの挙動を理解する必要のある開発者を対象としています。アプリケーションを開発する場合は、まずはじめかたを参照するか、アーキテクチャ概要と Go パッケージから読み進めてください。

アドレス形式（AID）

A2AL の Address は固定長の 21 バイトです。

[ バージョンバイト (1 バイト) ][ ハッシュ (20 バイト) ]

バージョンバイトは鍵アルゴリズムとハッシュの導出方法を表します。

現在の割り当て

バージョンバイト	名称	鍵アルゴリズム	20 バイト導出	用途
`0xA0`	Ed25519	Ed25519	`SHA-256(pubkey)[0:20]`	A2AL ネイティブのアイデンティティ
`0xA1`	P256	P-256 (NIST)	`SHA-256(pubkey)[0:20]`	A2AL ネイティブの P-256 アイデンティティ
`0xA2`	Paralism	secp256k1	`RIPEMD160(SHA-256(pubkey))`	Paralism、Bitcoin P2PKH、Cosmos SDK
`0xA3`	Ethereum	secp256k1	`Keccak-256(pubkey)[12:32]`	Ethereum および EVM 互換チェーン

バージョンバイト空間

範囲	状態	ポリシー
`0xA0`〜`0xA7`	正式	専門家レビューが必要
`0xA8`〜`0xAD`	予約	凍結。将来の標準化プロセス専用
`0xAE`	実験	登録不要。一意性は保証されない
`0xAF`	プライベート	登録不要。一意性は保証されない

割り当ての全体像と申請手順はアドレスバージョン登録表にまとめています。

表示エンコーディング

0xA0（Ed25519）と 0xA1（P256）：42 文字の 16 進文字列。大文字・小文字は SHA-256 に基づくチェックサムとして機能します。
0xA2（Paralism）と 0xA3（Ethereum）：0x 接頭辞付きの 16 進表記。

パースは形式から自動的に判別します。コードに組み込む際は daemon が返す文字列をそのまま使い、大文字・小文字を独自に変換しないでください。

DHT の NodeID

DHT のルーティングキーは Address から決定的に導出します。

NodeID = SHA-256(バージョンバイト ‖ 20 バイトハッシュ)   = 32 バイト

NodeID は DHT 内部の XOR 距離ルーティングにのみ使用し、アプリケーション層には露出しません。この分離により、ルーティング方式をアイデンティティ方式から独立して進化させられます。

ワイヤ形式のデータ構造（CBOR）

すべてのレコードは CBOR でエンコードし、SignedRecord コンテナに包みます。

`SignedRecord`

フィールド	型	説明
`RecType`	`uint8`	`0x01` 端点、`0x10` トピック、`0x80` メールボックス、`0x02`〜`0x0f` はカスタム
`Address`	21 バイト	発行者の AID
`Pubkey`	bytes	署名用の公開鍵（操作鍵の場合もあります）
`Payload`	bytes	CBOR でエンコードした種別ごとのペイロード
`Seq`	`uint64`	単調増加するシーケンス番号
`Timestamp`	`uint64`	Unix 秒
`TTL`	`uint32`	有効期間（秒）
`Signature`	bytes	正規化したフィールドに対する Ed25519 または secp256k1 の署名
`Delegation`	bytes	省略可能な CBOR `DelegationProof`（マスター鍵から導出した AID に対し操作鍵が署名する場合に付与）

レコードは書き込み時と読み取り時の両方で検証します。署名の完全性、timestamp + TTL が現在時刻を含むこと、そして署名権限です。署名鍵は、この Address を直接導出するか、マスター鍵が発行した有効な委任を携えている必要があります。

`EndpointPayload`（RecType `0x01`）

フィールド	型	説明
`Endpoints`	`[]string`	端点 URL（例：`quic://1.2.3.4:4122`、`quic://[2001:db8::1]:4122`）
`NatType`	`uint8`	`0` 不明、`1` フルコーン、`2` 制限付き、`3` ポート制限付き、`4` 対称
`Signal`	`string`	省略可能な ICE trickle のシグナリング基点（旧来のピア向け）
`Signals`	`[]string`	複数のシグナリングアドレス。空でない場合は `Signal` より優先
`Turns`	`[]string`	旧レコードからのデコード時のみ。新しいノードは `turn://` ヒントを書き込みません。中継の資格情報はローカルにとどまります

各レコードは複数の端点候補を公開します。接続する側はすべての候補に同時にダイヤルし（Happy Eyeballs）、最初に成功したものを採用します。

`TopicPayload`（RecType `0x10`）

agent 自身の NodeID ではなく SHA-256("topic:" + 能力名) に保存され、同じ能力名の複数の発行者は DHT が集約します。

フィールド	型	説明
`Name`	`string`	人が読める agent 名
`Protocols`	`[]string`	対応プロトコル（例：`"mcp"`、`"http"`、`"a2a"`）
`Tags`	`[]string`	絞り込み用のタグ
`Brief`	`string`	短い説明（140 文字以内）
`Meta`	map	省略可能な拡張メタデータ

TopicPayload 全体の CBOR エンコードは 512 バイトを上限とします。

`DelegationProof`

操作鍵をマスター AID に結びつける委任表明です。

フィールド	説明
`MasterAID`	委任される恒久的な AID
`OperationalPubkey`	`MasterAID` の代理で発行する権限を与えられた公開鍵
`Scope`	権限の範囲（現在はネットワーク操作）
`IssuedAt` / `ExpiresAt`	有効期間（Unix 秒）
`Signature`	上記の正規化フィールドに対するマスター鍵の署名

マスター鍵が必要になるのは DelegationProof を生成するときだけです。以降 a2ald が保持するのは操作鍵と CBOR エンコードされた証明のみです。資格情報のローテーションは証明の再発行であり、AID は変わりません。

メールボックス（RecType `0x80`）

NodeID(recipient) に保存します。外側の SignedRecord.Address が送信者を示し、ペイロードは X25519 + HKDF + AES-256-GCM で暗号化されるため、受信者の秘密鍵を持つ者だけが復号できます。

DHT の操作

A2AL は Kademlia 系の DHT を使い、FIND_NODE、FIND_VALUE、STORE を反復的に実行します。

レコードの保存時には RecordAuth を適用します。書き込まれるレコードは、自身の Address に対して自己署名されているか、その Address を導出するマスター鍵が発行した有効な DelegationProof を伴っている必要があります。

ブートストラップノードは、初回起動時にネットワークへ参加するための公開ノードです。参加後は a2ald が自身のルーティングテーブルを構築し、ブートストラップノードに依存しなくなります。

接続の確立

直接接続（主経路）

ConnectFromRecord は、対象の端点レコードにあるすべての Endpoints へ同時にダイヤルし、最初に QUIC ハンドシェイクが成功したものを採用します。双方は自身の Ed25519 鍵から導出した証明書で認証するため、認証は相互 TLS の内部で完結し、CA やドメイン名、証明書配布に依存しません。ワイルドカードで待ち受ける場合は既定でデュアルスタックとなり、IPv6 の候補があれば優先します。

ICE（フォールバック経路）

直接接続がすべて失敗し、レコードにシグナリングアドレスがある場合、双方は 2 つの AID から決定的に導出した room ID でシグナリングサービスに接続し、WebSocket trickle で ICE 候補を交換して、点対点の UDP 経路を確立したうえで QUIC を流します。この段階では、任意で外部 TURN が中継候補を提供できます。**A2AL は中継を設けません。**資格情報はローカルにとどまり、DHT には公開しません。

agent-route フレーム

TLS ハンドシェイクの後、クライアントは a2r2 + 21 バイトの対象 AID（4 バイトのマジックとアドレス）を送り、続いて短い制御交換を行います。データは以降のストリームで流れます。これにより、1 つの QUIC リスナーを共有する複数の AID を個別に宛先指定できます。受信側では旧版の a2r1（25 バイトのフレームのみ）も引き続き受け付けます。

アプリケーション層との境界

プロトコルが担うのはアドレス解決と接続のみです。以下はプロトコルではなく daemon（a2ald）に属します。便箋、対話、ルーム、ファイルオブジェクト、そしてアクセス制御です。ACL は特定の AID への受信 HTTP とオブジェクトのダウンロードにのみ作用し、DHT、便箋、対話のエンベロープには作用しません。

アドレスバージョンの申請

0xA4〜0xA7 の未割り当てのバージョンバイトを申請するには、Address Version Request テンプレートで GitHub Issue を作成し、名称、鍵アルゴリズム、20 バイト導出、署名検証の方法、理由、代表実装を記載します。審査基準と詳細な手順はアドレスバージョン登録表にあります。

目的	ページ
バージョンバイトの割り当てと申請	アドレスバージョン登録表
階層構造と実装構成	アーキテクチャ概要
実装とドキュメントへの参加	コントリビュートガイド