Struct CoinStateCache 

pub struct CoinStateCache { /* private fields */ }

A light client’s local view of subscribed coin/puzzle-hash state plus the current peak.

Implementations

impl CoinStateCache

pub fn new() -> Self

A fresh, empty cache.

pub fn peak(&self) -> Option<(u32, Bytes32)>

The current peak (height, header_hash), if one has been observed.

pub fn set_peak(&mut self, height: u32, header_hash: Bytes32)

Records a new peak observed from a bare NewPeakWallet message. ADVANCE-ONLY: a stale, out-of-order, or hostile lower peak never regresses a higher one.

pub fn get(&self, coin_id: Bytes32) -> Option<CoinState>

The cached state of coin_id, if the client holds one.

pub fn seed(&mut self, states: impl IntoIterator<Item = CoinState>)

Seeds the cache with the coin states returned by an initial subscribe response.

Routes through cache_coin, so a seeded coin created above the current peak is refused (the invariant is enforced on this path too).

pub fn track_coins(&mut self, coin_ids: impl IntoIterator<Item = Bytes32>)

Records that coin_ids are now subscribed.

pub fn track_puzzle_hashes( &mut self, puzzle_hashes: impl IntoIterator<Item = Bytes32>, )

Records that puzzle_hashes are now subscribed.

pub fn untrack_coins(&mut self, coin_ids: &[Bytes32])

Drops coin_ids from the subscription set (their cached state is retained until overwritten).

pub fn is_subscribed_coin(&self, coin_id: Bytes32) -> bool

Whether coin_id is currently subscribed.

pub fn subscribed_coins(&self) -> Vec<Bytes32>

The set of currently-subscribed coin ids (used to re-arm subscriptions after a reconnect).

pub fn subscribed_puzzle_hashes(&self) -> Vec<Bytes32>

The set of currently-subscribed puzzle hashes (used to re-arm after a reconnect).

pub fn apply_update( &mut self, items: &[CoinState], height: u32, fork_height: u32, peak_hash: Bytes32, )

Applies a CoinStateUpdate from an UNTRUSTED peer: rolls the cache back across the reported fork_height, then inserts the update’s items that belong to the subscribed set (bounded), and advances the peak.

Only items in the subscribed set are accepted: an item whose coin id is a subscribed coin OR whose puzzle hash is a subscribed puzzle hash (the latter preserves puzzle-hash-subscription DISCOVERY — a new coin under a watched puzzle hash is legitimate). An unsolicited item matching neither is DROPPED, so a hostile peer cannot inject coins that later answer a cache-first read. Inserts are further bounded by max_cached_coins so a puzzle-hash subscription cannot be used to exhaust memory.

The peak ADVANCES on a normal update, and is set DOWN ONLY for a GENUINE authoritative reorg — one where the rollback actually changed subscribed state, fork_height is below the current peak, and the update is well-formed (height >= fork_height). An empty/garbage update that rolls back nothing, or one with height < fork_height, cannot lower the peak.

The invariant — no cached coin has created_height > peak_height — is enforced BY CONSTRUCTION, not per-call-site: every add routes through cache_coin (which refuses an above-peak coin), and every peak change runs a sweep via update_peak (which drops any coin now above the peak). So the property holds on all paths — forward, reorg, and seed — regardless of ordering.

See the module docs for the reorg-rollback rules.

Trait Implementations

impl Debug for CoinStateCache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CoinStateCache

fn default() -> CoinStateCache

Returns the “default value” for a type.