Caching and provenance

Account snapshots use an address-keyed cache. Game definition catalogs use a separate context-owned registry with sequence-based generations. Understanding that distinction lets you tune RPC traffic without assuming the same freshness policy for both. See Definition catalogs for preload and optional persistence.

The cache key is an identity, not a call

Two reads of the same account through the same context return the same immutable snapshot — not an equal copy, the same object — until it expires.

The key is: cluster identity, program address, account type, account address, and the stable identity of the account definition used to decode it.

That last part matters more than it looks. Two decoders can never consume or overwrite one another’s data, because a different definition means a different cache slot. It is why the SDK can hold several typed views of the same bytes without them interfering.

The practical consequence: reading a fleet through character.fleets.all() and reading the same fleet directly hits the same entry. You do not need to hoard results yourself to avoid duplicate fetches.

Freshness is a per-read decision

const sage = createSageClient({
  cluster: 'zink-ptr',
  rpc,
  defaultMaxAgeMs: 10_000,
});

That default applies to account reads unless a specific call overrides it. It is not a refresh timer for retained Game definition catalogs. Raising it cuts RPC traffic; lowering it costs requests. There is no universally right value, because it depends on what you are reading — see the note on market data in markets.

Commitment levels can coexist

Each typed slot may hold one snapshot per commitment level, so a lagging stronger view and a newer weaker view can both be cached without fighting. A read at a given commitment gets the snapshot for that commitment.

Provenance answers “where did this come from?”

Use readMeta() to inspect available read metadata, including discovery strategy and source slot/commitment. An observed slot records where a value came from; it does not prove that the account has not changed since. Use the read API’s freshness controls when a current observation is needed.

Preloaded definition sections have their own per-section metadata. Restored sections can explicitly report unavailable source provenance; there is no single slot for a preload spanning several observations.

The interactive examples make this visible — running two examples on one page, the second completes in a fraction of the time because it reuses what the first fetched.

Contexts are isolated

Two contexts are genuinely independent: separate caches, separate endpoints. That is what makes it safe to run several in one process, and why creating a context does no network work.

Reconstructing an equivalent account definition creates a separate cache partition. Treat definitions as stable singletons instead of rebuilding them for each call.

Reference

• client — context, cache, and provenance exports
• How Atlas Kit reads the game — the short version