Прокси PPOI

Railgun SDK вызывает JSON-RPC агрегатора POI для проверки статусов коммитментов, корней Меркла и отправки доказательств. Скорость и доступность зависят от настроенного агрегатора, по умолчанию ppoi.fdi.network.

Прокси между расширением и агрегатором кеширует чтение и ставит повторные записи в очередь.

Архитектура

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

Расширение настраивает движок Railgun на эндпоинт прокси Umbra вместо прямого агрегатора. Все RPC-методы SDK обрабатываются прозрачно.

Стратегия кеширования

Ответы 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`],
});

Изменения SDK не нужны: прокси использует тот же JSON-RPC, что и агрегатор.