PPOI 代理

Railgun SDK 向 POI 聚合器发送 JSON-RPC 请求，检查承诺的合规状态、验证 Merkle 根及提交证明。上游响应时间和可用性取决于配置的聚合器，默认是 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)
  ]

扩展配置 Railgun 引擎使用 Umbra PPOI 代理端点，而非直接访问聚合器。代理透明处理所有 SDK RPC 方法。

缓存策略

对给定输入，PPOI 响应具有确定性。承诺的 POI 状态很少改变，通常仅在提交新证明或屏蔽被阻止时变化。缓存键为 sha256(method + canonical_json(params))。

各方法的 TTL

方法	TTL	原因
`ppoi_node_status`	直通	健康检查绕过缓存
`ppoi_pois_per_list`	5 分钟	各承诺在各名单中的 POI 状态
`ppoi_pois_per_blinded_commitment`	5 分钟	特定承诺的 POI 状态
`ppoi_merkle_proofs`	5 分钟	Merkle 包含证明
`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 等验证方法
直通：节点健康检查与写入；失败写入仍可能进入重试队列

写入队列

证明提交因聚合器超时或错误失败时，代理将其排队重试而非直接丢弃。交付仍受重试限制和队列保留期限约束；进入队列不证明上游已接受。

集成

扩展初始化 Railgun 引擎时设置代理 URL：

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

无需修改 SDK，代理使用与聚合器相同的 JSON-RPC 协议。