PPOI Proxy

The Railgun SDK makes JSON-RPC calls to a POI aggregator node to check commitment compliance status, validate merkle roots, and submit proofs. Upstream response time and availability depend on the configured aggregator (ppoi.fdi.network by default).

The PPOI proxy sits between the extension and the aggregator, providing read caching and queued write retries.

Architecture

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

The extension configures the Railgun engine to use the Umbra PPOI proxy endpoint instead of the aggregator directly. The proxy handles all SDK RPC methods transparently.

Caching Strategy

PPOI responses are deterministic for a given set of inputs. A commitment's POI status changes very infrequently (only when a new proof is submitted or a shield is blocked). The proxy caches responses keyed by sha256(method + canonical_json(params)).

TTLs by Method

Method	TTL	Rationale
`ppoi_node_status`	Pass-through	Health checks bypass the cache
`ppoi_pois_per_list`	5 min	POI status per commitment per list
`ppoi_pois_per_blinded_commitment`	5 min	POI status for specific commitments
`ppoi_merkle_proofs`	5 min	Merkle inclusion proofs
`ppoi_validate_poi_merkleroots`	5 min	Root validation
`ppoi_validate_txid_merkleroot`	5 min	TXID root validation
`ppoi_submit_transact_proof`	Pass-through	Write operation, queued on failure
`ppoi_submit_single_commitment_proofs`	Pass-through	Write operation, queued on failure

Immutability Detection

Some responses are effectively immutable once non-empty:

ppoi_merkle_proofs with valid proof data
Transact/legacy proofs that have been validated

These are cached with extended TTLs since the underlying data will never change.

Cache Invalidation

On successful write operations (ppoi_submit_*), mutable cached entries for that chainId are invalidated. This is conservative but safe — ensures subsequent reads reflect the newly submitted proof.

Privacy Considerations

Blinded commitments are wallet-specific (derived from the user's private viewing key). The current proxy can cache these reads and stores request parameters in cache metadata. A hashed cache key does not anonymize those parameters. Operators may correlate wallet-specific requests with network metadata; this path does not have the privacy properties of the uniform public digest downloads.

Cache policy must be reviewed for wallet-specific reads, including validation methods such as ppoi_validate_*_merkleroot
Pass-through: node health checks and writes; failed writes may still enter a retry queue

Write Queue

When proof submissions fail (aggregator timeout or error), the proxy queues them for retry rather than dropping them. Delivery remains subject to retry limits and queue retention; an accepted queue entry is not proof of upstream acceptance.

Integration

The extension sets the PPOI proxy URL during Railgun engine initialization:

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

No SDK changes are needed — the proxy speaks the same JSON-RPC protocol as the aggregator.