Crate rialo_stake_cache_interface 

Shared types for the Stake Cache.

This crate provides types that are shared between svm-execution and rialo-s-program-runtime, allowing builtin programs to access and manipulate stake cache data during transaction execution.

Reward Distribution Flow

The reward distribution follows a specific flow:

1. FreezeStakes: At epoch boundary, push pending to frozen (creates epoch snapshot)
2. DistributeRewards: Creates EpochRewards account (initially inactive/queued)
3. Activation: When EpochRewards becomes active:
   • pop_front_and_merge_to_baseline() is called
   • frozen.front() is merged into baseline
   • Rewards are calculated from baseline only
4. Distribution: Rewards distributed across partitions
5. Completion: EpochRewards marked inactive

Reward Eligibility

Stakes are eligible for rewards based on the following checks:

• activation_requested.is_some() → stake was activated
• deactivation not yet effective (timestamp-based check against epoch boundary)
• validator.is_some() → stake is delegated to a validator

Lookup Methods

Different lookup methods for different use cases:

• From Pending (get_*_from_pending): Includes next epoch changes
• From Last Frozen (get_*_from_last_frozen): Current epoch’s effective state
• From First Frozen (get_*_from_first_frozen): Oldest pending rewards epoch
• From Baseline (get_*_from_baseline): Post-merge state for reward calculation

Modules

pda

PDA derivation helpers for self-bond accounts. Self-bond PDA helpers.

Structs

EpochRewardsInitRequest

Request data for epoch rewards initialization. Used to pass information from DistributeRewards instruction to Bank.

StakeAccount

Represents a stake account with its data.

StakeCache

A cache of stake and validator accounts.

StakeCacheData

Data structure holding the cached stake and validator accounts.

StakeHistory

A history of frozen stake cache snapshots across epochs.

StakesHandle

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

StakesView

Read-only view of the stake cache for external consumers (e.g., RPC handlers).

ValidatorAccount

Represents a validator account with its data.

ValidatorInfo

Data structure for the validator information account. This data structure is meant to hold all information about a validator, such that we can leverage it in Epoch negotiation and create a proper Authority object on Epoch change.

Constants

SELF_BOND_SEED

Seed prefix for self-bond PDAs.

Functions

derive_self_bond_address

Derives the self-bond stake account address from a validator’s info account.

derive_self_bond_address_with_bump

Derives the self-bond address with bump seed (for PDA signing).