Caching and deduplication

The Gateway uses two strategies to reduce load on observer nodes and improve response times: TTL-based caching for stable data and in-flight request deduplication for concurrent identical requests.

TTL caching

Some responses change infrequently. The Gateway caches them with a time-to-live (TTL) and serves cached responses directly until the TTL expires.

Endpoint	Cached	Notes
`/block/{shard}/by-nonce/{nonce}`	Yes	Finalized blocks are immutable
`/block/{shard}/by-hash/{hash}`	Yes	Hash-keyed, immutable
`/hyperblock/by-hash/{hash}`	Yes	Hash-keyed, immutable
`/hyperblock/by-nonce/{nonce}`	Yes	Nonce-keyed, immutable after finalization
`/node/heartbeatstatus`	Yes	Aggregated heartbeat refreshes periodically
`/validator/statistics`	Yes	Statistics update once per epoch
`/network/economics`	Yes	Refreshes periodically
Account endpoints	No	Fetched fresh from observer
Transaction endpoints	No	Status changes frequently
VM query endpoints	No	Results depend on current state

Block and hyperblock responses are safe to cache indefinitely on the client side once finalized. Use the block nonce or hash as a cache key.

In-flight request deduplication

When multiple clients request the same data at once, the Gateway sends one request to the observer. Subsequent identical requests wait for that response and receive the same result. This “leader-follower” pattern (coalescing) prevents thundering herd problems. The first request becomes the leader and contacts the observer. All other requests with the same path and query parameters become followers and wait for the leader’s response. Each coalesced group resolves as soon as the leader receives a response. Followers add no additional latency beyond the leader’s round-trip time. Deduplication applies to all GET requests with identical path and query parameters. Deduplication is automatic and requires no configuration. This is useful for high-traffic endpoints like account balances where many clients poll the same address.

Forcing fresh data

To bypass cached data and query the latest state, use these query parameters:

Parameter	Effect
`?onFinalBlock=true`	Query against the latest finalized block (bypasses any stale cache)
`?blockNonce={nonce}`	Query at a specific block height
`?blockHash={hash}`	Query at a specific block hash

These parameters force the Gateway to contact the observer directly, skipping the cache layer.

# Get the latest finalized balance, bypassing cache
curl "https://rust-gateway.xoxno.com/address/erd1.../balance?onFinalBlock=true"

# Query state at a specific block height
curl "https://rust-gateway.xoxno.com/address/erd1.../balance?blockNonce=12345678"

Data availability modes

The Gateway classifies queries into two availability modes based on the parameters you provide:

Recent: any observer can serve these queries, including snapshotless nodes. More observers are available, which means faster responses and better load distribution.
All: only observers with complete history can serve these queries. Fewer observers qualify, but they support historical lookups at arbitrary block heights.

When you include blockNonce, blockHash, or onStartOfEpoch parameters, the Gateway switches to “All” mode and skips snapshotless observers. The Gateway infers the mode from the query parameters. If you only need current state, omit historical parameters. The Gateway will use the larger pool of “Recent” observers, giving you faster responses.

​TTL caching

​In-flight request deduplication

​Forcing fresh data

​Data availability modes

TTL caching

In-flight request deduplication

Forcing fresh data

Data availability modes