Steward API

Events Endpoint

This endpoint allows you to retrieve various events related to the Steward program. Events are emitted by the Steward program when certain actions occur, such as when a validator is scored, or when rebalancing takes place.

Endpoint

GET https://kobe.mainnet.jito.network/api/v1/steward_events

Parameters

Parameter	Type	Required	Description
vote_account	String	No	Filter events by validator vote account public key
epoch	Integer	No	Filter events by epoch number
event_type	String	No	Filter events by type (see Valid Event Types below)
page	Integer	No	Page number for pagination (default: 1)
limit	Integer	No	Number of events per page (default: 100, max: 1000)

Valid Event Types

Most relevant to validators:

ScoreComponentsV4: Validator scoring details using the 4-tier hierarchical scoring system. Emitted once every 10 epochs
InstantUnstakeComponentsV3: Information about instant unstaking events
RebalanceEvent: Details about stake rebalancing operations

Updates to overall state:

StateTransition: Changes in the Steward program's state machine
DecreaseComponents: Included in RebalanceEvent, provides specifics on stake decreases
AutoRemoveValidatorEvent: Automatic removal of offline validators from the pool
AutoAddValidatorEvent: Automatic addition of new validators to the pool
EpochMaintenanceEvent: Epoch maintenance operations

Example Request: Get a validator's scores

GET https://kobe.mainnet.jito.network/api/v1/steward_events?vote_account=J1to3PQfXidUUhprQWgdKkQAMWPJAEqSJ7amkBDE9qhF&event_type=ScoreComponentsV4

{
  "events": [
    {
      "signature": "5N3hVRpuqsiXCiChrm3GuaWRfi2zZMYAkx6jnM3YTocAC5RBTsrukk4ghFHeCyZawC7Ca72i7fo8TNg2MsG1zXP7",
      "event_type": "ScoreComponentsV4",
      "vote_account": "J1to3PQfXidUUhprQWgdKkQAMWPJAEqSJ7amkBDE9qhF",
      "timestamp": "2024-08-20T06:18:46Z",
      "data": {
        "score": 7260571231234567890,
        "raw_score": 7260571231234567890,
        "commission_max": 5,
        "mev_commission_avg": 800,
        "validator_age": 1250,
        "vote_credits_avg": 9650000,
        "mev_commission_score": 1,
        "blacklisted_score": 1,
        "superminority_score": 1,
        "delinquency_score": 1,
        "running_jito_score": 1,
        "commission_score": 1,
        "historical_commission_score": 1,
        "merkle_root_upload_authority_score": 1,
        "priority_fee_commission_score": 1,
        "priority_fee_merkle_root_upload_authority_score": 1,
        "details": {
          "max_mev_commission": 1000,
          "max_mev_commission_epoch": 658,
          "superminority_epoch": 65535,
          "delinquency_ratio": 0.98,
          "delinquency_epoch": 65535,
          "max_commission": 5,
          "max_commission_epoch": 659,
          "max_historical_commission": 10,
          "max_historical_commission_epoch": 520,
          "avg_priority_fee_commission": 450,
          "max_priority_fee_commission_epoch": 658
        }
      },
      "epoch": 659
    },
    ...
  ]
}

ScoreComponentsV4 Fields:

score: Final score (u64). If 0, validator is ineligible. Otherwise, equals raw_score
raw_score: 4-tier encoded score before binary filters applied
commission_max: Maximum inflation commission observed (0-100, Tier 1 component)
mev_commission_avg: Average MEV commission in basis points (0-10000, Tier 2 component)
validator_age: Number of epochs with non-zero vote credits (Tier 3 component)
vote_credits_avg: Scaled vote credits ratio (Tier 4 component)
Binary eligibility scores (1 = pass, 0 = fail):
- mev_commission_score: MEV commission check
- commission_score: Recent commission check
- historical_commission_score: Historical commission check
- blacklisted_score: Blacklist check
- superminority_score: Superminority check
- delinquency_score: Voting delinquency check
- running_jito_score: Running Jito MEV client check
- merkle_root_upload_authority_score: Tip distribution authority check
- priority_fee_commission_score: Priority fee commission check
- priority_fee_merkle_root_upload_authority_score: Priority fee authority check
details: Additional scoring details for debugging and transparency

Example Request: See stake movements by epoch

GET https://kobe.mainnet.jito.network/api/v1/steward_events?event_type=RebalanceEvent&epoch=657&limit=2000

{
  "events": [
    {
      "signature": "64GGjM2QtrKw4SPocR5hmw17Kenf9qBdRRM5KrrM9gkr8XUgyyjXNQkuzfxq3ZhDJgHU8jvhUKxaAfMnnGp85Uss",
      "event_type": "RebalanceEvent",
      "vote_account": "7emL18Bnve7wbYE9Az7vYJjikxN6YPU81igf6rVU5FN8",
      "timestamp": "2024-08-17T20:20:57Z",
      "data": {
        "rebalance_type_tag": "Increase",
        "increase_lamports": 2762842586176,
          "decrease_components": {
          "scoring_unstake_lamports": 0,
          "instant_unstake_lamports": 0,
          "stake_deposit_unstake_lamports": 0,
          "total_unstake_lamports": 0
        }
      },
      "epoch": 657
    },
    ...
  ]
}