Cache policies

How it works

Policy matching pipeline. At startup eRPC builds an ordered slice of CachePolicy objects from evmJsonRpcCache.policies. Every request passes through findGetPolicies (reads) or findSetPolicies (writes). Both walk the slice and test each policy's network, method, params, and finality fields against the request.

For reads, finality matching is asymmetric: a finalized request also matches unfinalized policies (a block finalized after write may be stored under the unfinalized policy); a realtime request matches only realtime policies; an unknown-finality request matches all policies. For writes, finality must match exactly. findGetPolicies deduplicates by connector so each connector is probed at most once per request.

Cache key derivation. Every lookup computes a partition key {networkId}:{blockRef} and a range key {method}:{sha256(params)}. The block reference comes from ExtractBlockReferenceFromRequest, which inspects the per-method reqRefs path config. If the block reference resolves to * (a wildcard tag like "latest"), the connector is queried via a reverse index rather than the main index. If the block reference is empty — method not recognized or not cacheable — the whole cache lookup is skipped silently.

Get fan-out. Get spawns one goroutine per matching policy. All goroutines race under a shared fanCtx; the first to find an acceptable non-empty hit calls cancelFan() so peers exit without posting to metrics. Results travel through a buffered channel sized to the number of goroutines so no goroutine ever blocks after fanCtx is done — a slow peer that refuses to honour cancellation never pins user-visible latency. A 30-second backstop context wraps the fan-out when the parent carries no deadline, protecting against FD leaks from misbehaving connectors.

Set fan-out. Set fans out using sync.WaitGroup (fire-and-forget per policy). A hard 5-second write timeout is applied per connector, independent of any failsafe configuration. Responses with a JSON-RPC error field are never cached. Empty results for future blocks (beyond the network's confidence head) are never cached regardless of the empty policy setting.

Realtime freshness gate. After a cache hit is retrieved for a realtime request, shouldAcceptCachedResult compares the block's unix timestamp (extracted from the response via ExtractBlockTimestampFromResponse) against the policy TTL. This is block age, not cache-entry wall-clock age: a response cached 5 minutes ago is accepted if its block was produced 3 seconds ago; a response cached 30 seconds ago is rejected if its block is 2 minutes old and TTL is 60 s.

For responses with no block timestamp (eth_blockNumber, eth_gasPrice, eth_getLogs), the gate falls back to the connector's own latest-block timestamp via the CacheHeadReporter interface — currently implemented only by GrpcConnector, which polls every 60 seconds. If neither source is available the gate fails open (accepts the result). When age exceeds TTL the result is reclassified as ttl_rejected and the fan-out loop continues searching peer connectors. Non-realtime data (finalized, unfinalized, unknown) is never age-gated.

Finality buckets. The zero value of the Go DataFinalityState enum is finalized, so omitting finality in YAML silently creates a finalized-only policy.

To cache all traffic types you need at least four policies — one per finality bucket — or the realtime/unfinalized traffic will always bypass the cache and hit upstreams.

Empty-result handling. The empty field controls three modes:

• ignore (default) — empty results are never cached on write; cached empty results are treated as misses on read.
• allow — cache and serve empty results like any other result.
• only — cache and serve only empty results; non-empty responses skip this policy.

A result is "emptyish" if the raw JSON bytes are null, "", "0x", "0x0", 0, [], {}, or a hex string whose non-prefix digits are all zeros.

Skip-cache-read directive. Callers can set the X-ERPC-Skip-Cache-Read HTTP header or skip-cache-read query parameter to bypass specific connectors. The value can be "true" (skip all connectors), "false" (normal), or a glob pattern matched against connector IDs.

Compression. When evmJsonRpcCache.compression.enabled = true (the default — auto-created even when the compression: block is omitted), values are compressed with zstd before storage. Only values whose pre-compression size meets or exceeds threshold (default 1024 bytes) are compressed; smaller values are stored raw. If the compressed output is larger than the original it is also stored raw. Detection on read is by the zstd magic bytes 0x28 0xB5 0x2F 0xFD — no explicit flag needed.

Connector failsafe wrapping. When a connector config lists failsafeForGets or failsafeForSets, the raw connector is wrapped in a FailsafeConnector. Retry, static-delay hedge, and circuit-breaker are supported. Consensus and hedge quantile mode are not supported at this scope.

gRPC connector (BDS read-through). GrpcConnector is a read-only connector backed by BDS gRPC servers. It does not support Set. Supported methods: eth_getBlockByNumber, eth_getBlockByHash, eth_getLogs, eth_getTransactionByHash, eth_getTransactionReceipt, eth_getBlockReceipts, eth_chainId, eth_blockNumber. eth_blockNumber is derived by fetching the latest block internally — there is no native BDS gRPC call for it. The gRPC connector performs a fast-miss check: if the request block number is below the connector's earliest known block, it returns ErrRecordNotFound immediately without a network call.

CacheHash derivation (range key). The range key {method}:{sha256(params)} is computed by JsonRpcRequest.CacheHash (common/json_rpc.go:L1385-L1409). It hashes params positionally using SHA-256 over a recursive type-aware hashValue function, producing a hex string prefixed with the method name. The hash is memoized on the request object — multiple policies referencing the same request compute it only once.

reqRefs and respRefs — block reference extraction. These per-method config fields (networks[*].methods.definitions.<method>.reqRefs / respRefs) tell the block-reference extraction logic where in a JSON-RPC request or response to find a block number, tag, or hash. They determine whether a request is cacheable and what partition key to use.

Built-in path variables in common/defaults.go:

Path format: each selector is an []interface{} where integers index JSON arrays and strings key into JSON objects. An empty path ([]) means the value at that position IS the scalar. A single-element path ["*"] means "arbitrary block" — produces blockRef = "*" which routes to the reverse index.

reqRefs extraction algorithm (architecture/evm/block_ref.go:L277-L310):

1. If reqRefs has exactly one path of length 1 and that element is "*": return blockRef="*" immediately.
2. Otherwise for each path, parse the value as a block parameter (hex number, decimal, or named tag).
3. If multiple paths yield different block references (e.g. eth_getLogs with different fromBlock/toBlock): set blockRef = "*" (composite range).
4. Accumulate the highest block number seen across all paths.
5. If no path resolves: blockRef = "" → cache bypassed entirely, trace attribute cache.skip_reason = "empty_block_ref" set.

respRefs extraction algorithm (architecture/evm/block_ref.go:L343-L368): Called only after a response exists. First non-"*" block ref wins; result supplements or overrides the request-derived ref for the cache key.

Custom reqRefs/respRefs in user config override built-in defaults entirely — there is no merge.

Config schema

All fields are under database.evmJsonRpcCache. Duration values accept Go duration strings or bare integers (milliseconds).

database.evmJsonRpcCache (root)

evmJsonRpcCache.compression

Auto-created even when omitted: CacheConfig.SetDefaults always creates &CompressionConfig{} and calls its SetDefaults() when c.Compression == nil. The only way to opt out is compression.enabled: false.

evmJsonRpcCache.connectors[*]

Connector SetDefaults is called with scope = connectorScopeCache, which sets cache-specific defaults.

evmJsonRpcCache.policies[*]

Worked examples

All patterns below are distilled from real production fleets; comments explain the non-obvious choices.

1. Two-tier memory connectors: fast unfinalized + large finalized pool. Production fleets separate recent reorgable data from immutable historical data because their access patterns and eviction pressures differ. Unfinalized blocks churn quickly; finalized blocks are read far more and rarely evicted:

database:  evmJsonRpcCache:    connectors:      - id: memory-cache-unfinalized        driver: memory        memory:          # High item count for fast-cycling recent blocks and tx receipts          maxItems: 2000000          # Cap at 8GB: recent data is small-ish JSON, 2M items * ~4KB avg          maxTotalSize: 8GB      - id: memory-cache-finalized        driver: memory        memory:          # Lower count: finalized items are large (full blocks, log ranges)          maxItems: 500000          maxTotalSize: 4GB    policies:      - connector: memory-cache-unfinalized        network: "*"        # Only methods this fleet actually indexes — wildcard eth_get* wastes RTTs        # on guaranteed misses for eth_getBalance, eth_getCode, eth_getProof, etc.        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_query*"        finality: unfinalized        # empty: allow — a null receipt means "not indexed yet"; still worth        # caching so rapid polling doesn't hammer upstreams for the same miss        empty: allow        ttl: 0      - connector: memory-cache-unfinalized        network: "*"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_query*"        finality: unknown        empty: allow        ttl: 0      - connector: memory-cache-finalized        network: "*"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_query*"        finality: finalized        empty: allow        # 0 = no expiry: finalized data is reorg-immune and never goes stale        ttl: 0

2. gRPC read-through connector with static-delay hedge and per-call timeout. When the primary cache backend is a remote gRPC server (BDS read-through), add a short static hedge so a slow node doesn't hold up the request — note that quantile mode is rejected at connector scope, so the delay must be static. The 400ms timeout keeps the cache miss path fast enough that going straight to upstreams is always cheaper than waiting on a struggling connector:

database:  evmJsonRpcCache:    connectors:      - id: grpc-cache        driver: grpc        grpc:          # getTimeout: applied when parent context has no deadline or a farther deadline          # 400ms: if the cache read takes longer, skip it and go to upstreams          getTimeout: 400ms          servers:            - https://rpc.example.com:50051          headers:            Authorization: "Bearer ${CACHE_API_TOKEN}"        failsafeForGets:          - matchMethod: "*"            timeout:              # Hard ceiling on a single get call; hedge fires before this              duration: 400ms            hedge:              # Static: quantile mode is not supported at connector scope              delay: 100ms              maxCount: 1            retry:              maxAttempts: 2              # 0: retry immediately — no point waiting for a slow cache node              delay: "0"    policies:      - connector: grpc-cache        network: "evm:1"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt"        finality: unfinalized        empty: allow        # get-only: gRPC connector is read-only, no Set support        appliesTo: get        ttl: 0      - connector: grpc-cache        network: "evm:1"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt"        finality: unknown        empty: allow        appliesTo: get        ttl: 0      - connector: grpc-cache        network: "evm:1"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt"        finality: finalized        empty: allow        appliesTo: get        ttl: 0

3. Chain-specific gRPC reader in front of a wildcard fallback pool. Production fleets often have a high-fidelity per-chain reader colocated in the same cluster alongside a broader pooled connector that covers every chain. The chain-specific connector wins the connector dedup for its network; the wildcard connector catches everything else. Per-chain reader policies come first so their network: "evm:1" entries win before the wildcard network: "*" entry:

database:  evmJsonRpcCache:    connectors:      - id: eth-reader        driver: grpc        grpc:          getTimeout: 400ms          servers:            - grpc://eth-reader-lb.cache.svc.cluster.local:50051        failsafeForGets:          - matchMethod: "*"            retry: { maxAttempts: 2, delay: "0" }            timeout: { duration: 400ms }            hedge: { delay: 100ms, maxCount: 1 }      - id: edge-cache-pool        driver: grpc        grpc:          getTimeout: 400ms          servers:            - https://cache-base.rpc.example.com:50051            - https://cache-arbitrum.rpc.example.com:50051        failsafeForGets:          - matchMethod: "*"            retry: { maxAttempts: 2, delay: "0" }            timeout: { duration: 400ms }            hedge: { delay: 100ms, maxCount: 1 }      - id: memory-cache-finalized        driver: memory        memory: { maxItems: 500000, maxTotalSize: 4GB }    policies:      # Chain-specific per-chain reader policies come first — connector dedup means these      # win the evm:1 slot; the wildcard pool never sees evm:1 requests      - connector: eth-reader        network: "evm:1"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt"        finality: unfinalized        empty: allow        appliesTo: get        ttl: 0      - connector: eth-reader        network: "evm:1"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt"        finality: unknown        empty: allow        appliesTo: get        ttl: 0      - connector: eth-reader        network: "evm:1"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt"        finality: finalized        empty: allow        appliesTo: get        ttl: 0      # Wildcard pool covers all other chains      - connector: edge-cache-pool        network: "*"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_query*"        finality: unfinalized        empty: allow        appliesTo: get        ttl: 0      - connector: edge-cache-pool        network: "*"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_query*"        finality: unknown        empty: allow        appliesTo: get        ttl: 0      - connector: edge-cache-pool        network: "*"        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getBlockReceipts|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_query*"        finality: finalized        empty: allow        appliesTo: get        ttl: 0      # In-memory finalized cache for all chains — written by upstreams, read locally      - connector: memory-cache-finalized        network: "*"        method: "*"        finality: finalized        ttl: 0

4. Intentionally no realtime caching. Some fleets deliberately skip the finality: realtime bucket so eth_blockNumber, eth_getBlockByNumber("latest"), and eth_gasPrice always go to fresh upstreams. This is the right choice when your cache connector doesn't implement CacheHeadReporter (all drivers except gRPC) — without a block timestamp the realtime age gate fails open and you'd serve stale chain-tip data. The three-bucket shape below makes the intent explicit and avoids the silent miss:

database:  evmJsonRpcCache:    connectors:      - id: mem        driver: memory        memory: { maxItems: 500000, maxTotalSize: 4GB }    policies:      # Deliberately no finality: realtime policy — eth_blockNumber and "latest"      # calls always bypass cache and go to upstreams for a fresh head      - connector: mem        network: "*"        method: "*"        finality: finalized        ttl: 0      - connector: mem        network: "*"        method: "*"        finality: unfinalized        # ~2x Ethereum block time; adjust to 2x your slowest chain's block time        ttl: 24s      - connector: mem        network: "*"        method: "*"        finality: unknown        ttl: 0

5. Shadow-write debugging mode. Write cache entries for a new connector without risking stale reads — appliesTo: set means reads always go to upstreams while you verify the connector is populating correctly. Flip to appliesTo: both once you've confirmed hit rates in erpc_cache_set_success_total:

database:  evmJsonRpcCache:    connectors:      - id: new-pg        driver: postgresql        postgresql:          connectionUri: "postgres://${DB_USER}:${DB_PASS}@db-new:5432/erpc"          # table auto-set to "erpc_json_rpc_cache" at cache scope when blank    policies:      - connector: new-pg        finality: finalized        # set only: reads still hit upstreams; verify connector fills correctly        appliesTo: set        ttl: 0

Request/response behavior

• Cache key structure. Partition key: {networkId}:{blockRef}. Range key: {method}:{sha256(params)}. When blockRef = "*" (tag-based or multi-block range), the connector is queried via the reverse index (ConnectorReverseIndex = "idx_reverse"). When blockRef = "", the lookup is bypassed entirely.
• X-ERPC-Skip-Cache-Read header / skip-cache-read query param. Value "true" skips all connectors. A glob pattern (e.g. "mem*") skips matching connectors only. Passing an empty connector ID with a pattern always returns false — patterns are only evaluated per-connector.
• Responses with a JSON-RPC error field are never cached. Neither are empty results for blocks beyond the network's confidence head, regardless of empty policy setting.
• Set has a hard 5-second per-connector write timeout, independent of any configured failsafe. If both are configured, the shorter one fires first.
• Realtime age gate uses block timestamp, not wall-clock cache age. The erpc_cache_get_age_guard_reject_total metric fires when age exceeds TTL; its label is method not category — unique among cache metrics.

Best practices

• Always define four policies (one per finality bucket) when you want to cache all traffic. A single catch-all policy with no explicit finality: silently caches only finalized data. eth_blockNumber, eth_gasPrice, eth_call with "latest", and eth_getBalance with "latest" are all realtime and will miss unless a finality: realtime policy exists.
• Keep realtime TTL between 1 and 3 s. Lower than 1 s means the freshness gate will almost always reject on slower connectors; higher than 3 s risks serving chain-tip data that is multiple blocks stale.
• Set finality: unfinalized TTL at 2× block time. For Ethereum mainnet (~12 s) use 24 s. This gives enough room for the block to finalize without serving stale data for too long.
• Place the fastest connector first in the policy list when sharing a finality bucket. The Get fan-out races all connectors in parallel, but list order determines which connector wins ties and how quickly cancelation propagates. Memory connectors should come before Redis or PostgreSQL.
• Do not set compression.enabled: false unless you have profiled actual CPU overhead. zstd at "fastest" level saves 50–80% storage on typical ABI-encoded JSON-RPC results. The benefit almost always outweighs the CPU cost, and the memory connector would double-compress without it (both layers detect magic bytes and short-circuit, but the extra pass is wasted work only when compression is enabled on both).
• Use minItemSize to avoid caching tiny responses. Responses under 200 B are often null, short errors, or simple scalars. Caching them creates key-count pressure on Ristretto with negligible savings.
• Monitor erpc_cache_get_age_guard_reject_total vs erpc_cache_get_success_hit_total for realtime policies. A high reject ratio means your realtime TTL is too tight relative to connector polling latency or your GrpcConnector head poll interval (60 s). Raise the TTL or switch to a connector with an embedded block timestamp in responses.

Edge cases & gotchas

1. finality: finalized is the zero value — intentionally the safest default. The Go comment at common/data.go:L10-L15 (opens in a new tab) explicitly states finalized gets 0 so that an unspecified finality defaults to the safest sane cache default. Omitting finality means only finalized requests match; realtime, unfinalized, and unknown requests bypass this policy and always hit upstreams.

2. Realtime finality must be stated explicitly — omission silently drops all realtime traffic. Common realtime methods that silently miss without finality: realtime: eth_blockNumber, eth_gasPrice, eth_call with "latest", eth_getBalance with "latest". This is the most common misconfiguration.

3. findGetPolicies deduplicates by connector; findSetPolicies does not. A connector can receive multiple writes for the same request if multiple policies reference it. Source: architecture/evm/json_rpc_cache.go:L926-L978 (opens in a new tab).

4. Emptyish hit under empty=ignore is detected in the fan-out goroutine, not post-fan-out. Without this, the emptyish result would win the race and cancel peers, losing a chance for a peer with empty=allow and non-empty data to win. Source: architecture/evm/json_rpc_cache.go:L343-L351 (opens in a new tab).

5. The realtime age gate checks block timestamp, not cache-entry age. A response cached 5 minutes ago is accepted if its block was produced 3 seconds ago. A response cached 30 seconds ago is rejected if its block is 2 minutes old and TTL is 60 s. Source: architecture/evm/json_rpc_cache.go:L841-L920 (opens in a new tab).

6. eth_blockNumber, eth_gasPrice, and eth_getLogs carry no block timestamp in their response. The realtime age gate falls back to the connector's CacheLatestBlockTimestamp, which is only implemented by GrpcConnector (polls every 60 seconds). For all other connectors the gate fails open (accepts the cached result). Source: architecture/evm/json_rpc_cache.go:L879-L889 (opens in a new tab).

7. Compression threshold has two definitions. The inline code default in NewEvmJsonRpcCache is 512 bytes, but SetDefaults sets it to 1024 bytes. SetDefaults always runs at startup, so the effective default is 1024. The 512 value is only reachable when the cache object is constructed directly without SetDefaults (i.e., in unit tests). Source: common/defaults.go:L597-L599 (opens in a new tab).

8. Set has a hard 5-second timeout per connector in addition to any failsafe timeout. If both are configured, the shorter one fires first. The 5-second fallback protects connectors with no failsafe configured. Source: architecture/evm/json_rpc_cache.go:L768 (opens in a new tab).

9. minItemSize and maxItemSize measure pre-compression result length, not stored blob size. A 4 KB result that compresses to 400 bytes still fails a maxItemSize: 2KB check. The measured value is JsonRpcResponse.ResultLength() — raw JSON result bytes, not the full JSON-RPC envelope. Source: architecture/evm/json_rpc_cache.go:L1067-L1072 (opens in a new tab).

10. Memory connector has independent internal zstd compression. Combined with the EvmJsonRpcCache layer's own compression pass, values stored in the memory connector may be double-compressed. Both layers detect already-compressed data by magic bytes and short-circuit. Source: architecture/evm/json_rpc_cache.go:L1150-L1157 (opens in a new tab).

11. SkipCacheRead accepts both boolean and string values. Both normalized to string on parse: true → "true", false → "false". The directive is accepted from config, the X-ERPC-Skip-Cache-Read HTTP header, and the skip-cache-read query parameter. Passing a glob pattern with an empty connectorId always returns false. Source: common/request.go:L895-914.

12. Policy ordering matters for Get when finality = unknown. All matching policies race in parallel; the fastest connector with data wins. Place the fastest connector first so it most likely wins. For Set, all matching policies receive the write regardless of order.

13. gRPC connector is read-only. It does not support Set. Supported methods: eth_getBlockByNumber, eth_getBlockByHash, eth_getLogs, eth_getTransactionByHash, eth_getTransactionReceipt, eth_getBlockReceipts, eth_chainId, eth_blockNumber. eth_blockNumber is derived by fetching the latest block internally. Source: data/grpc.go:L270-278.

14. appliesTo: "set" without a paired "get" policy writes succeed but reads always miss — useful for shadow-write debugging but rarely the right production shape.

15. reqRefs with multiple conflicting block references collapse to "*". eth_getLogs with different fromBlock/toBlock values routes to the reverse index and the partition key becomes *. Users must cache only finalized data for range-query methods to avoid serving stale reorged data. Source: architecture/evm/block_ref.go:L296-L300 (opens in a new tab).

16. ErrRecordNotFound and ErrEndpointMissingData are semantic misses, not errors. They must not increment erpc_cache_get_error_total. A regression where this happened caused 36k+ spurious errors per 15 minutes. Source: erpc/evm_json_rpc_cache_fanout_test.go (opens in a new tab).

17. database.evmJsonRpcCache: nil completely disables the cache subsystem. The EvmJsonRpcCache object is never created, saving memory and eliminating block-ref extraction overhead on every request. Source: common/defaults.go:L831-836.

18. Compression is auto-enabled — you cannot disable it by omitting the block. CacheConfig.SetDefaults always creates &CompressionConfig{} and calls SetDefaults() on it (sets enabled=true). The only escape is explicitly setting compression.enabled: false. Source: common/defaults.go:L482-488.

19. Cancellation guard uses fanCtx.Err(), not errors.Is(err, context.Canceled). An inner failsafe wrapper can produce an opaque typed error that errors.Is cannot unwind. The fan-out loop trusts fanCtx.Err() as the authoritative cancellation signal so a losing peer's wrapped error never inflates erpc_cache_get_error_total. Source: erpc/evm_json_rpc_cache_fanout_test.go (opens in a new tab).

20. Empty results for future (not-yet-produced) blocks are never cached, regardless of empty policy setting. emptyResultBeyondConfidence compares the requested block number against the network's latest (or finalized) head. If the block hasn't been produced yet, the empty result is silently discarded — preventing the cache from poisoning responses for blocks that simply don't exist yet. Source: architecture/evm/json_rpc_cache.go:L1079-L1082 (opens in a new tab), architecture/evm/common.go:L55-L89 (opens in a new tab).

21. gRPC connector's block-head timestamp is set to zero when timestamp parse fails. This is intentional: storing a stale timestamp from a previous poll would make CacheLatestBlockTimestamp report a dangerously stale age. Storing 0 makes the realtime guard fail-open (accept the cached result) rather than reject based on wrong age data. Source: data/grpc.go:L350-L356 (opens in a new tab).

22. appliesTo: "get" enables independent write/read policies with different TTLs or finality. Setting appliesTo: "get" on a policy means it will never be written to — a separate write-only policy (possibly with a different finality bucket or size limit) can populate the connector while the read-only policy controls what is served. The default "both" means the same policy governs both directions.

Observability

OTel trace spans:

Span attributes on Cache.Get: network.id, request.method, request.finality, cache.policies_matched, cache.hit (bool), cache.miss_reason, cache.miss_connector_id, cache.miss_policy.

Span attributes on Cache.GetForPolicy: cache.policy_summary, cache.connector_id, cache.method, cache.get_outcome (found/miss/ttl_rejected/empty_ignored/error/cancelled), cache.block_ref, cache.group_key, cache.request_key.

Debug log messages

These DEBUG-level log messages appear in eRPC output and are useful for tracing cache behavior:

Source code entry points

• architecture/evm/json_rpc_cache.go:L153-L400 (opens in a new tab) — EvmJsonRpcCache.Get: parallel fan-out, fanCtx, 30-second backstop, winner selection
• architecture/evm/json_rpc_cache.go:L572-L800 (opens in a new tab) — EvmJsonRpcCache.Set: parallel fan-out, 5-second hard write timeout, shouldCacheResponse
• architecture/evm/json_rpc_cache.go:L841-L920 (opens in a new tab) — shouldAcceptCachedResult: realtime age gate, block-timestamp extraction, connector-head fallback, fail-open
• data/cache_policy.go:L1-L200 (opens in a new tab) — CachePolicy struct; MatchesForGet, MatchesForSet, matchParams, MatchesSizeLimits, GetTTL
• architecture/evm/block_ref.go:L277-L368 (opens in a new tab) — ExtractBlockReferenceFromRequest, ExtractBlockReferenceFromResponse: block-ref derivation, reqRefs/respRefs path walking
• common/defaults.go:L474-L650 (opens in a new tab) — CacheConfig.SetDefaults, CachePolicyConfig.SetDefaults, CompressionConfig.SetDefaults
• common/request.go:L895-L914 (opens in a new tab) — ShouldSkipCacheRead: header/query parsing, boolean vs glob logic
• erpc/evm_json_rpc_cache_fanout_test.go (opens in a new tab) — behavior-locking tests: slow-peer non-blocking, miss-as-error classification, cancellation wrapping

Related pages

• Storage connectors — configure the memory, Redis, DynamoDB, PostgreSQL, and gRPC backends referenced by policies.
• Rate limiters — limit how many upstream calls the cache miss path can trigger.
• Failsafe — retry/timeout/circuit-breaker applied per-connector via failsafeForGets/failsafeForSets.
• Reduce RPC costs — the primary use case this feature serves.
• EVM method reference — per-method finality classification and built-in reqRefs/respRefs defaults.