One door for the balance cache

A change of scale: after whole subsystems, here's a single 150-line file. But it's worth a lesson because it solves a bug class you'll meet anywhere there's a cache — corruption that spreads because the cache trusts whatever it's handed — and the fix is a pattern worth internalizing: make one invariant un-bypassable by making the package the only door.

1 · The bug class: sticky cache corruption

The hot cache balance:{chain}:{token}:{holder} in Redis speeds up balance lookups. Before this package, any writer could put anything in it — and several did: a pre-floor-fix indexer path, a reconciler that piped through a quirky RPC return, a genesis rebuild that propagated already-corrupt Neo4j quantity_raw. Each wrote a 2^256 − X garbage string. Then the corruption became sticky:

garbage write  →  next batch reads it as a SEED  →  re-writes ON TOP  →  garbage persists

The cache had no notion of "valid," so once garbage was in, it propagated forward and survived every cycle. (Observed on stage, 2026-05-19.) That's the failure this package exists to close.

2 · The fix: one typed gateway, one invariant

pkg/balancecache is the single typed gateway for that Redis key. Every read and write goes through it, and it enforces one predicate — IsPlausible:

func IsPlausible(v *big.Int) bool {
    return v != nil && v.Sign() >= 0 && v.BitLen() <= MaxBalanceBits   // non-nil, non-negative, ≤ 240 bits
}

3 · The threshold: calibrate for safe-side margin

Why MaxBalanceBits = 240 specifically? A small calibration story worth keeping:

4 · Two smaller choices

• No TTL — durable by design. Set writes with no expiry (SET key val 0). Balances don't "go stale and vanish"; they're refreshed by being overwritten with fresh reads (recall L26's price-dirty recompute). Eviction is the operator's job via Redis maxmemory policy, not a per-key TTL.
• Mandatory source on writes. Set requires a non-empty source string, logged on rejection — so when an implausible value is caught, the WARN names which writer produced it, pointing straight at the upstream bug. Provenance for debugging, the same instinct as the healers' source stamps (L30).

What you can now do

• Explain why a trusting cache turns one bad write into sticky, self-propagating corruption.
• State the plausibility invariant (non-nil, non-negative, ≤ 240 bits) and why those shapes can't be real balances.
• Explain the single-typed-gateway pattern and how the import graph makes the invariant un-bypassable.
• Explain read-as-miss vs write-as-reject sharing one predicate, and the threshold's safe-side-margin calibration.
• Explain the no-TTL durability choice and the mandatory source for rejection provenance.