Struct StakesHandle 

pub struct StakesHandle {
    pub pending: StakeCache,
    pub history: StakeHistory,
    pub needs_refresh: Arc<AtomicBool>,
}

Handle for builtin programs to access stake cache data and freeze stakes.

This handle provides:

• Read/write access to the pending (next epoch) stake cache data
• The ability to freeze the pending stakes into history via freeze_and_get_validator_stakes()

Epoch Semantics

Important: The pending field contains data for the NEXT epoch (i.e., changes being accumulated that will take effect after FreezeStakes). To get the CURRENT epoch’s frozen data for lookups, use history.back() instead.

The handle is cached at block level for performance. When freeze_and_get_validator_stakes() is called, it sets needs_refresh to signal that subsequent transactions should recreate the handle to see the updated epoch.

Thread Safety

Both StakeCache and StakeHistory wrap their data in Arc<RwLock<...>> internally, allowing safe concurrent access from builtin programs during transaction execution. Mutations to pending are immediately visible to the owning Bank since they share the same Arc.

Fields

pending: StakeCache

Stake cache data for the NEXT epoch (pending/accumulating changes).

This is a mutable working copy that accumulates stake and validator account modifications throughout the epoch. These changes will become effective after the next FreezeStakes call. For current epoch lookups (the frozen effective state), use history.back() instead.

The StakeCache wrapper contains Arc<RwLock<...>> internally, allowing builtin programs to mutate the pending stake data during transaction execution, with changes visible to the Bank.

history: StakeHistory

Target history to push frozen snapshots to.

The StakeHistory wrapper contains Arc<RwLock<...>> internally.

needs_refresh: Arc<AtomicBool>

Flag to signal that the cache needs to be refreshed after FreezeStakes. Set to true by freeze_and_get_validator_stakes().

Implementations

impl StakesHandle

pub fn new(pending: StakeCacheData, history: StakeHistory) -> Self

Create a new stakes handle with fresh data.

This creates new Arc<RwLock<...>> wrappers for the provided data. Note: This creates NEW Arcs, so changes won’t be visible to the original data. Use new_shared instead when you want to share Arcs with the Bank.

pub fn new_shared(pending: StakeCache, history: StakeHistory) -> Self

Create a new stakes handle with shared references.

This shares the same Arc<RwLock<...>> with the Bank, so mutations to pending by builtin programs are immediately visible to the Bank.

pub fn needs_refresh(&self) -> bool

Check if this handle needs to be refreshed (was invalidated by FreezeStakes).

pub fn freeze_and_get_validator_stakes(&self) -> Vec<(Pubkey, u64)>

Freeze the pending stake cache data and return validator stakes.

This performs an O(1) clone of the pending stake cache data (via ImHashMap structural sharing) and pushes it to the back of the stake history queue. This is typically called by the ValidatorRegistry program’s FreezeStakes instruction to capture the validator set at a specific point. It then extracts and returns a vector of (Pubkey, stake) pairs for all validators in the frozen snapshot.

Important: This sets needs_refresh to true, signaling that subsequent transactions should recreate their StakesHandle to see the updated epoch.

Returns the validator stakes list, sorted by pubkey for determinism.

Trait Implementations

impl Clone for StakesHandle

fn clone(&self) -> StakesHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StakesHandle

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

Formats the value using the given formatter.

impl Default for StakesHandle

fn default() -> Self

Returns the “default value” for a type.