Caching and provenance

Every read goes through a cache, and every result knows where it came from. Understanding both is what lets you tune an application’s RPC traffic without guessing.

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 everywhere unless a specific call overrides it. 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?”

Snapshots carry read metadata: the strategy that produced them, the slot, and the commitment. So “is this fresh?” and “was this served from cache?” are always answerable rather than inferred.

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 an intentionally separate cache partition. That is deliberate, not a leak — but it does mean definitions should be treated as stable singletons rather than rebuilt per call.

Reference

• client — context, cache, and provenance exports
• How the SDK thinks — the short version