Permissionless Cranker

Overview

The Tip Router Keeper is a critical component of the Jito Tip Router system that manages epoch-based operations for validators, operators, and vaults. It orchestrates the complete lifecycle of an epoch, from updating vaults, weight setting to reward distribution, ensuring proper consensus and state transitions.

Architecture

Core Components

1. KeeperState - Manages the state of the keeper across epochs
2. Epoch Management - Handles epoch progression and state transitions

Key Data Structures

KeeperState

The KeeperState struct maintains all essential addresses and state information:

pub struct KeeperState {
    pub epoch: u64,
    pub ncn: Pubkey,
    pub vaults: Vec<Pubkey>,
    pub operators: Vec<Pubkey>,
    pub tip_router_config_address: Pubkey,
    pub vault_registry_address: Pubkey,
    pub epoch_state_address: Pubkey,
    // ... additional addresses and state
}

Epoch Lifecycle

The keeper follows state machine for each epoch:

State Progression

1. SetWeight - Establishes vault weights for the epoch
2. Snapshot - Captures operator and vault snapshots
3. Vote - Operators vote on the merkle root
4. PostVoteCooldown - Waiting period after voting
5. Distribute - Distributes rewards to participants
6. Close - Closes epoch accounts and finalizes

Epoch Progression Logic

The keeper uses the progress_epoch function to determine when to advance:

• New Epoch Detection: Automatically progresses when a new epoch begins
• Completion Handling: Resets to starting epoch when current epoch is complete
• Stall Recovery: Advances to next epoch when stalls are detected

Main Loop Operations

A. Progress Epoch

Determines which epoch the keeper should work on based on:

• Current epoch
• Completion status of epochs
• Stall detection

B. Emit NCN Metrics

Collects and emits comprehensive metrics including:

• Validator information
• Epoch statistics
• Ticket states
• Account balances

C. Register Vaults

Ensures all vaults are properly registered with the Global Vault Registry before processing begins.

D. Fetch Keeper State

Updates the internal state with current epoch information and account data.

E. Update Epoch State

Synchronizes with on-chain epoch state accounts to maintain consistency.

F. Create or Complete State

• Creates new epoch state if none exists
• Detects and handles completed epochs

G. Crank State Operations

Executes state-specific operations based on current epoch state:

match current_state {
    State::SetWeight => crank_set_weight(handler, state.epoch).await,
    State::Snapshot => crank_snapshot(handler, state.epoch).await,
    State::Vote => crank_vote(handler, state.epoch, test_vote).await,
    State::PostVoteCooldown => crank_post_vote_cooldown(handler, state.epoch).await,
    State::Distribute => crank_distribute(handler, state.epoch).await,
    State::Close => crank_close_epoch_accounts(handler, state.epoch).await,
}

H. Emit Epoch Metrics

Provides detailed metrics for the current epoch state and progress.

I. Detect Stall

Identifies when the epoch is stuck and needs to progress:

• Voting completion
• Insufficient rewards for distribution
• Other blocking conditions

Configuration and Deployment

Operating Modes

The keeper supports several operating modes:

• Full Operations (run_operations = true): Complete epoch management
• Metrics Only (metrics_only = true): Only emit metrics without state changes
• Migration Mode (run_migration = true): Special migration operations

Stall Detection

The keeper implements sophisticated stall detection:

Stall Conditions

1. Voting States: During Vote and PostVoteCooldown states
2. Low Rewards: When rewards are below distribution threshold (< 10,000 lamports)
3. Account Dependencies: When required accounts are not ready

Stall Recovery

When stalls are detected:

• The keeper logs the stall condition
• Progresses to the next epoch after timeout
• Continues monitoring for resolution