Chainlink: Empty Account Admission Optimization

[thlorenz]

High-Level Implementation Plan: Empty Account Admission Optimization

Goal

Implement the optimized empty-account policy so that:

• every requested account is still subscribed provisionally before fetch
• found accounts continue to be cloned and durably tracked as needed
• missing accounts are not immediately cloned into the bank
• missing accounts are not immediately promoted into the durable subscription LRU
• only repeated missing accounts within the configured time window are promoted and cloned as empty

This plan assumes:

• transaction behavior does not depend on immediate first-miss empty insertion
• auto-airdrop behavior is fine without immediate empty insertion
• hotness is tracked in one shared counter across read and transaction origins

Proposed Design Direction

Move from the current single-stage subscription/caching model to a two-stage model:

1. Provisional fetch protection
   Every requested pubkey is subscribed before fetch so we do not miss updates during the fetch window.

2. Post-fetch admission
   After the result is known, decide whether the pubkey should become:

   • a durably tracked found account
   • a cold missing entry tracked only in a TTL/hotness structure
   • a hot missing entry promoted into the durable LRU and cloned as an empty placeholder

The core idea is to separate:

• fetch-window correctness
• durable subscription admission
• empty-placeholder bank materialization

Main Workstreams

1. Introduce Empty-Miss Hotness Tracking

Add a dedicated in-memory tracker for missing accounts that records:

• pubkey
• hit count inside a TTL window
• expiry timing / last-seen timing
• optional fetch origin metadata for observability

This tracker becomes the admission gate for empty-placeholder promotion.

High-level outcome:

• first-time and infrequent misses stay out of the bank and out of the durable LRU
• repeated misses cross the threshold and become eligible for empty-placeholder caching

2. Separate Provisional Subscriptions From Durable LRU Admission

Refactor the request-time account fetch flow so that pre-fetch subscriptions for requested pubkeys are treated as provisional, not immediately as durable retained subscriptions.

High-level outcome:

• the system still protects the fetch race window exactly as today
• requested pubkeys are no longer automatically admitted into the durable subscription set just because they were fetched once

This is the architectural core of the optimization.

3. Change Post-Fetch Classification For Missing Requested Accounts

Update the fetch/clone pipeline so that requested pubkeys that resolve as missing are no longer handled uniformly as immediate empty placeholders.

Instead, missing requested pubkeys should split into:

• cold missing

  • increment hotness tracker
  • unsubscribe/drop provisional tracking
  • do not clone into bank

• hot missing

  • promote into durable LRU/subscription set
  • clone empty placeholder into bank

High-level outcome:

• empty placeholders become an admitted cached state, not the default outcome of any miss

4. Preserve Existing Found-Account Semantics

Keep the current correctness model for accounts that are actually found on chain:

• subscribe before fetch
• fetch with subscription override protection
• clone into bank
• retain durable tracking when appropriate

High-level outcome:

• the optimization should reduce waste around missing accounts without weakening correctness for found accounts

5. Apply The Policy Uniformly Across Read And Transaction Origins

Use the same admission model for:

• getAccountInfo
• getMultipleAccounts
• sendTransaction
• simulateTransaction

The difference between origins should be minimized at the policy level unless later testing shows a reason to diverge.

High-level outcome:

• one consistent model for requested missing accounts
• fewer special cases between read and transaction paths

6. Update Observability And Metrics

Add metrics/logging that make the new behavior visible.

At a high level, we want to observe:

• provisional subscriptions opened
• cold misses seen
• hot misses promoted
• empty placeholders cloned after promotion
• cold-miss provisional subscriptions dropped

High-level outcome:

• the rollout can be validated with real traffic patterns
• the chosen threshold can be tuned from data instead of guesswork

7. Update Tests To Match The New Contract

Revise the tests around marked missing accounts so they reflect the new intended behavior:

• first miss: not cloned into bank, not durably subscribed
• repeated/hot miss: cloned as empty and durably tracked
• found accounts: behavior preserved

Add coverage across:

• read-only paths
• transaction paths
• mixed batches for getMultipleAccounts
• threshold crossing behavior

High-level outcome:

• the new contract becomes explicit in tests instead of inferred from current implementation

Rollout Shape

Implement this in layers rather than as one large change:

1. add the hotness tracker and provisional/durable subscription separation
2. switch missing-account post-fetch handling to the new admission policy
3. enable the policy for read and transaction origins
4. add metrics and finalize tests

This keeps the redesign understandable and reduces the risk of mixing policy changes with too many structural changes at once.

Expected Result

After this optimization:

• found accounts still get the same race-safe fetch behavior
• one-off missing accounts no longer consume durable subscription slots
• one-off missing accounts no longer pollute the bank as empty placeholders
• repeated missing accounts still become cached/tracked when there is evidence that caching them is worthwhile

That should reduce:

• LRU churn
• subscription pressure
• empty-account retention noise
• reconnect/resubscribe overhead for low-value misses

while preserving the fetch-window correctness that motivated subscribe-before-fetch in the first place.

Tracker Scope

The hotness tracker is shared across all origins:

• getAccountInfo
• getMultipleAccounts
• sendTransaction
• simulateTransaction

So repeated misses from any mix of those paths contribute to the same promotion decision for a pubkey.