Cache Behavior

NDK's cache persists event data, delivery state, and decrypted payload sidecars used by app-facing reads and writes.

This guide focuses on the behavior you can rely on when building an app with NDK. It does not cover backend implementation details.

What gets cached

At a high level, NDK may persist:

• Nostr events
• event source relays
• pending delivery state for locally created events
• decrypted plaintext sidecars for encrypted events
• convenience projections like metadata, contact lists, and user relay lists

What load-style reads mean

When NDK reads events from cache, it applies these visibility rules:

• expired events are hidden
• author-deleted events are hidden
• for replaceable and addressable events, only the latest visible winner is returned

App-facing reads return the current logical state, not raw historical storage.

Event sources vs delivery targets

These are different concepts:

• Event sources answer: "where did this event come from?"
• Delivery targets answer: "where does this locally created event still need to be sent?"

As an app developer:

• use normal usecases and requests for reading and publishing
• only inspect low-level source relay APIs if your app explicitly needs provenance
• do not assume a source relay is automatically a pending broadcast target

Local-first publishing

When your app broadcasts an event through normal NDK APIs:

• the event can become visible locally before every relay acknowledges it
• relay delivery progress can survive app restarts when the cache backend is persistent
• retries can continue in the background while the app is running
• replaceable events retry only the newest visible version

This lets the UI update from locally persisted state without waiting for every relay to accept the event.

Encrypted payload cache

For encrypted content, NDK can cache decrypted plaintext separately from the original event.

This is useful when:

• the app needs to render the same DM or private list repeatedly
• decryption depends on a slow or remote signer

Important behavior:

• the original event stays encrypted in the canonical event store
• plaintext is cached in a separate sidecar keyed by event and viewer
• different viewers may have different cached plaintext results

Convenience accessors

metadata, follows, and userRelayLists are high-level app APIs backed by the generic event cache.

In practice this means:

• you should keep using the high-level usecases
• you should not maintain a separate storage assumption for metadata/contact lists
• replaceable and deletion semantics are applied consistently across generic event reads and convenience accessors

Cache eviction

Eviction behavior is:

• removing expired events
• removing author-deleted events
• removing superseded replaceable/addressable events
• optionally applying caps to visible events per kind

If background eviction scheduling is enabled, NDK uses the configured values from NdkConfig:

• cacheEvictionEnabled
• cacheEvictionPolicy
• cacheEvictionStartupDelay
• cacheEvictionInterval
• runCacheEvictionOnStartup

If you enable background eviction scheduling, NDK will periodically run the configured eviction policy while the app is alive.

Recommended app usage

• Use a persistent CacheManager in real apps.
• Read through high-level usecases unless you specifically need low-level control.
• Treat local-first publish as locally durable and eventually relay-delivered.
• Configure eviction for long-lived apps with large caches.
• Let NDK manage decrypted payload caching instead of rewriting encrypted event content yourself.