Technical Architecture

The Validator History Program employs technical architecture designed for efficient on-chain storage and retrieval of historical validator data.

Core Account Structure

Config Account

The Config account defines the global configuration of validator history program.

• Admin Management: Tracks administrative authorities
• Oracle Permissions: Manages data upload permissions
• Program Integration: Links to tip distribution program
• Counter Tracking: Monitors total ValidatorHistory accounts

ValidatorHistory Account

The ValidatorHistory account serves as the primary data container for each validator.

Key Components:

• Size: 65,848 bytes per validator account
• Storage Capacity: Up to 512 epochs of historical data
• Zero-Copy Design: Implements bytemuck::{Pod, Zeroable} traits for efficient memory management
• Unique Identifier: Each account is indexed and linked to a specific vote account

Circular Buffer Implementation

At the heart of each ValidatorHistory account lies the CircBuf - a circular buffer that efficiently manages historical data storage:

Buffer Characteristics:

• Fixed Size: 512 entries maximum (MAX_ITEMS = 512)
• Wrap-Around Behavior: Automatically overwrites oldest data when capacity is reached
• Index Tracking: Maintains current position with idx pointer
• Empty State Management: Tracks buffer state to handle initialization

Memory Efficiency: The circular buffer prevents account bloat by maintaining a constant size regardless of how much historical data has been collected. When new epochs are added beyond the 512-entry limit, the oldest entries are automatically overwritten.

Data Structure Design

ValidatorHistoryEntry

Each epoch's data is stored in a ValidatorHistoryEntry struct (128 bytes) containing:

Performance Metrics:

pub epoch_credits: u32,          // Vote credits earned
pub commission: u8,              // Validator commission percentage
pub mev_commission: u16,         // MEV commission in basis points
pub mev_earned: u32,             // MEV rewards (stored as 1/100th SOL)

Validator Information:

pub ip: [u8; 4],                 // IPv4 address
pub version: ClientVersion,      // Software version (major.minor.patch)
pub client_type: u8,             // Client type

Stake Data:

pub activated_stake_lamports: u64, // Total active stake
pub rank: u32,                     // Validator rank by stake
pub is_superminority: u8,          // Superminority status (0/1)

Metadata:

pub epoch: u16,                           // Epoch number
pub vote_account_last_update_slot: u64,   // Last update slot

ClusterHistory Account

The ClusterHistory account serves as the primary data for cluster.

• Network Metrics: Stores cluster-wide statistics
• Block Production: Tracks total blocks per epoch
• Timestamp Data: Records epoch start times
• Same Architecture: Uses identical circular buffer design

Data Structure Design

ClusterHistoryEntry

Each epoch's data is stored in a ClusterHistoryEntry struct containing:

Cluster Information

pub total_blocks: u32,              // Total blocks
pub epoch: u16,                     // Epoch number
pub epoch_start_timestamp: u64      // Timestamp number

Memory and Performance Optimizations

Zero-Copy Architecture: Eliminates runtime memory allocation overhead by using fixed-size structures that can be directly mapped to account data.

Efficient Storage Layout: C-style struct alignment ensures optimal memory usage and prevents compiler-added padding.

Batch Operations: Support for bulk updates of historical data without individual transaction overhead.

Normalized Data Access: Built-in handling for network changes like Timely Vote Credits (TVC) activation.

This architecture enables the Validator History Program to provide comprehensive historical data access while maintaining the performance and cost-efficiency required for on-chain operations.