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 프록시를 사용하도록 엔진을 구성합니다. 프록시는 모든 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 변경은 필요 없습니다.