PPOI プロキシ

Railgun SDK は POI 集約ノードに JSON-RPC を送り、コミットメントの状態、マークルルートの確認、証明の提出を行います。応答時間と可用性は設定された集約サービス（既定は ppoi.fdi.network）に依存します。

拡張と集約サービスの間の PPOI プロキシは、読み取りキャッシュと書き込み再試行キューを提供します。

アーキテクチャー

Extension (SDK)              Umbra                    External
                         PPOI Proxy
  poiNodeURLS: [    -->  /api/v1/ppoi     -->    ppoi.fdi.network
    umbra-api/ppoi       (cache + queue)         (5-10s RTT)
  ]

拡張は直接の集約サービスではなく Umbra PPOI プロキシを使うよう Railgun エンジンを設定します。SDK の RPC メソッドを透過的に処理します。

キャッシュ戦略

同じ入力への PPOI 応答は決定的です。コミットメント状態は新しい証明やシールドのブロック時など、まれに変わります。キーは sha256(method + canonical_json(params)) です。

メソッド別 TTL

メソッド	TTL	理由
`ppoi_node_status`	直接転送	ヘルスチェックはキャッシュを迂回
`ppoi_pois_per_list`	5 分	リストごとのコミットメント状態
`ppoi_pois_per_blinded_commitment`	5 分	特定コミットメントの状態
`ppoi_merkle_proofs`	5 分	マークル包含証明
`ppoi_validate_poi_merkleroots`	5 分	ルート検証
`ppoi_validate_txid_merkleroot`	5 分	TXID ルート検証
`ppoi_submit_transact_proof`	直接転送	書き込み、失敗時にキューへ
`ppoi_submit_single_commitment_proofs`	直接転送	書き込み、失敗時にキューへ

不変性の検出

次の応答は空でなくなると実質的に不変です。

有効な証明データを持つ ppoi_merkle_proofs
検証済み transact・legacy 証明

基礎データが変わらないため、TTL を延ばして保存します。

キャッシュの無効化

ppoi_submit_* の成功後、その chainId の変更可能なキャッシュを無効化します。後続の読み取りが新しい証明を反映するための保守的な方法です。

プライバシー上の注意

ブラインドコミットメントは非公開閲覧鍵から導いたウォレット固有データです。現在のプロキシは読み取りをキャッシュし、要求パラメーターをメタデータに保存できます。キーのハッシュ化はパラメーターを匿名化しません。運用者はネットワークメタデータと関連付けられるため、共通の公開ダイジェスト取得と同じプライバシーではありません。

ppoi_validate_*_merkleroot などの検証を含め、ウォレット固有の読み取りの保存方針を確認する必要があります
直接転送はノードの健全性確認と書き込みです。失敗した書き込みは再試行キューに入る場合があります

書き込みキュー

集約サービスのタイムアウトやエラー時は証明を捨てず再試行キューに入れます。配信は再試行限度と保存期間に依存し、キューへの受理は上流での受理を証明しません。

統合

拡張はエンジン初期化時にプロキシ URL を設定します。

startRailgunEngine({
  poiNodeURLS: [`${UMBRA_API_URL}/api/v1/ppoi`],
});

集約サービスと同じ JSON-RPC を使うため SDK の変更は不要です。