!5279odin/query-height-cache → developf08ee5b0e6

Node-local per-height response cache for external queries

AI-generatedEverything on this page was written by an AI agent from the diff: the summaries, the narration, the diagrams, the flags and the glossary. It can be wrong or incomplete, so check it against the code before you rely on it.

5commits
10files
1.3klines changed
601lines to read
128 MiBdefault cap
0consensus changes

Where the diff is

Where the cache sits

Two external entrypoints share one per-height cache; the state machine bypasses it.

abci_query / RESTCometBFT RPCgRPC / gatewayexternal clientsApp.QueryABCI entrypointabciParityServergRPC entrypointquery cacheLRU · singleflightmissBaseApp handlerstore at heightCommit hookmark ready, sweepwasm in a txrouter direct, no cache
newchanged

3-minute explainer

What changed

Why

~26% of a query node's CPU recomputed identical answers.

Two entrypoints

ABCI Query and the gRPC registration; the state machine bypasses both.

abci_querygRPC→ cache

wasm in a tx → GRPCQueryRouter, never cached

Height in the key

Latest resolves to the ready height; a new block means new keys.

kindheightmethodrequestcommit → old “latest” entries swept

Singleflight + byte cap

One fill per key; errors never stored or shared; 128 MiB LRU.

  • concurrent callers share one fill
  • errors: each waiter re-runs
  • entry ≤ ¼ of cap

Wire bytes

gRPC hits decode a fresh message per caller.

missMarshalstore bzUnmarshal per hit

What is cached

Six services; Block, Export, keysign/keygen excluded; quotes only while fresh.

typeswasmbankauthdenomscheduler

quotes: latest height, blockTime ≥ now − max_lag

Config + evidence

On by default; perf guard shows identical regression outputs.

State + upgrade

Config (off-chain)

  • newthor.api.query_cache.enabledtrue
  • newthor.api.query_cache.max_bytes128 MiB

Line by line · every changed logic line, narrated

8:22runtime
15code chapters
100%logic lines narrated (453/453)
5flagged spots
speed

Chapters

What to check

Ask an AI about this change

Chat assistantClaude, ChatGPT, … (reads a link)

Coding agentClaude Code, Cursor, … (reads the repo)

The context file is context.md. Use Copy with context for an AI that can't open links; it pastes the whole file in.

Glossary

ABCI query
CometBFT's abci_query RPC; the node's BaseApp.Query answers it, and here THORChainApp.Query wraps it with the cache. app/query_cache.go ↗
abciParityServer
Wrapper around the app's gRPC server registration that translates errors like the ABCI path; it now also routes cacheable methods through the cache. app/grpc_query_errors.go ↗
LRU
Least recently used eviction: the cache drops the entries touched longest ago once its byte cap is exceeded.
max_lag
thor.api.quote.max_lag: quotes refuse to answer when the latest block is older than this; the cache serves quotes only within it. config/default.yaml ↗
PrepareCheckStater
Cosmos SDK hook run at the end of Commit with the new check state; here it marks the committed height ready for the cache. app/app.go ↗
Ready height
The last height whose Commit hook has run; requests without a height resolve to it, and nothing above it is cached.
Singleflight
Go library that runs one call per key while concurrent callers wait for its result. x/sync/singleflight ↗
Stargate query
CosmWasm's way for contracts to call chain gRPC queries in a tx; it uses the router directly, not the cached entrypoints.
Wire bytes
The protobuf-encoded response; gRPC entries are stored this way and decoded per caller.