プロトコル概要

Raiznetは、分散型の作物モニタリングのための階層化プロトコルを定義します。このページは、ESP32センサーからサーバーまでの通信スタックを — 今日実装されている通りに — 説明し、プロトコルがどこへ向かうかを示します。

階層

┌──────────────────────────────────────────┐
│        アプリケーション  (HTTP JSON API) │
├──────────────────────────────────────────┤
│  ワイヤフォーマット  (JSON + 署名付き raw)│
├──────────────────────────────────────────┤
│        トランスポート  (HTTP POST)       │
├──────────────────────────────────────────┤
│          アイデンティティ  (Ed25519)     │
└──────────────────────────────────────────┘

計画中の追加: 正規のProtobufエンコーディング（ADR-001）、ESP-NOWによるデバイス間メッシュ、署名付きイベントログのサーバー間複製（ADR-004 — ロードマップ を参照）。

ワイヤフォーマット

現在のワイヤフォーマットは HTTP上のJSON で、1つの重要な点があります。JSONはトランスポートのエンベロープであり、署名されるメッセージは別個のパイプ区切りASCIIストリング で、raw と呼ばれます。

<device_pubkey_hex>|<seq>|<timestamp_ms>|<key_version>[|ec=<v>][|ph=<v>][|waterLevel=<v>][|tempAmbient=<v>][|humidity=<v>]

デバイスはこのストリングのUTF-8バイトを自身のEd25519鍵で署名し、hexエンコードした raw と signature の両方をJSONブロック内で送ります。サーバーはデバイスの 登録済み pubkeyに対して署名を検証します。完全な文法は テレメトリ を参照してください。

正規バイナリエンコーディング用のProtobufスキーマはすでに packages/protocol/proto/ に存在しますが、まだワイヤ上では使われていません — Protobufスキーマ を参照してください。

ホップごとのトランスポート

ホップ	プロトコル	状態
ESP32 → サーバー	HTTP POST（/v1/telemetry、JSON）	実装済み
ESP32 → ESP32（メッシュ）	Wi-Fiチャンネル上のESP-NOW	計画中
サーバー → サーバー	署名付きイベントログの複製	設計段階（ADR-004）

ESP32 → サーバーのホップにHTTPを選んだのは、センサーの送信頻度が低いためです（リファレンスファームウェアは既定で毎分1回の読み取り。バッテリーデバイスははるかに長くスリープします）。永続接続（WebSocket、MQTT）は無駄に開かれたままになり、バッテリーを消耗します。ステートレスなHTTP POSTは、頻度の低いfire-and-forget取り込みに正しいモデルです。

パケットのライフサイクル

今日、1つの読み取りに何が起きるか:

ESP32がセンサーを読む
  → rawストリングを組み立てて署名（Ed25519、デバイス鍵）
  → raw + signature + plain/encryptedフィールドをJSONブロックに包む
  → POST /v1/telemetry（バッチ、1..100ブロック）

サーバーがバッチを受け取り、ブロックごとに:
  → 宛先データベースでデバイスを検索
  → rawバイトに対して署名を検証
  → 各フィールドの処分を解決（plain / encrypted / omit）
  → raiznet_public.db または raiznet_private.db に挿入
     （INSERT OR IGNORE — 重複は冪等）

複製のステップ（公開ブロックを署名付きログに追記しノード間で同期すること）は次のプロトコルフェーズであり、まだ実装されていません。

識別子

すべてのエンティティは、その Ed25519公開鍵（32バイト）で識別され、JSONでは小文字のhexとしてシリアライズされます。プロトコルに自動採番の整数はありません。

エンティティ	IDの源	状態
ユーザー	BIP-39シードから導出したpubkey	実装済み
サーバー	初回起動時に生成したpubkey（identity.mnemonic）	実装済み
デバイス	プロビジョニング時に生成したpubkey（ハードウェアTRNG）	実装済み
フィルター／カタログ	公開ログのpubkey	設計

シーケンス番号

各デバイスは単調増加する seq カウンタを保持します。

• フラッシュの摩耗を防ぐため、リファレンスファームウェアは seq を 100単位のブロック で予約します。NVSには次ブロックの開始のみを永続化します。再起動後、デバイスは次の予約ブロックから再開します — seq の小さなギャップは正常で想定内です。
• デバイスは最近の読み取りをRAMのリングバッファに保持し、HTTP 200 で確認されていないものをすべて再送 します。サーバーは (device_pubkey, seq) で重複排除するため、再送は常に安全です。
• サーバーは単調性を 強制しません — 古いseqを拒否すると再接続後の回復が壊れます。

同期前にデバイスのバッファから押し出された読み取りは、ネットワークから失われます — 所有者がローカルHTTP、BLE、シリアル経由でデバイスから直接取り出さない限り。