Feat/offline election prediction tool #1189

Ipsa11 · 2025-11-13T09:55:08Z

This PR introduces the Offline Election Prediction Tool, which allows users to simulate and predict staking election results without relying on a live network connection.

The tool supports custom parameters such as election algorithm, snapshot block, and chain state, and produces detailed outputs showing validator–nominator allocations and corresponding stake amounts. It defaults to the on-chain Phragmén algorithm and can use the latest chain state if no snapshot block is provided.

cla-bot-2021 · 2025-11-13T09:55:20Z

User @karanvir12, please sign the CLA here.

User @pushkar1262, please sign the CLA here.

src/commands/types.rs

src/prelude.rs

kianenigma · 2025-11-14T09:34:43Z

src/utils.rs

+}
+
+/// Convert Plancks to tokens (divide by 10^decimals) and format with token symbol
+pub fn planck_to_token(planck: u128, decimals: u8, symbol: &str) -> String {


Have you seen this crate? it can likely simplify this code a bit for you: https://github.com/paritytech/ss58-registry

src/commands/types.rs

Ipsa11 · 2025-11-14T12:18:41Z

Hey @kianenigma
Thank you for the review we have made the suggested changes.Please have a look into it.

sigurpol · 2025-11-18T08:42:06Z

Hi @Ipsa11 , can you please rebase vs latest main and address the issues raised by CI (format / clippy)?
I would recommend you to use nightly-2025-06-27 for both fmt and clippy so you get everything fixed for free CI wise. Once pushed, I will make sure to run the workflow again

sigurpol

I have left quite a few comments, some cosmetic and some more substantial.

Most critical ones:

remove duplicate election execution and call mine_solution only once
remove duplication. Imho, The prediction command should reuse:
- fetch_missing_snapshots() for snapshot data
- mine_solution() for election computation
- Snapshot
- All existing type infrastructure monitor already relies on

It might be beneficial to create a single data fetching layer that both monitor and predict can reuse. Something that 1. try to fetch snapshot 2.optional fallback: fetch from staking pallet and convert to snapshot format

I would like to have predict_command something like this (very high level)

  pub async fn predict_cmd(...) -> Result<(), Error> {
      // this get_election_data() is the same method to fetch data that monitor will use too.
     // For predict, we will enable fallback in case snapshot is not available
      let (targets, voters) = get_election_data(...).await?;
      // same mine_solution that monitor relies on, SDK does the whole work
      let solution = mine_solution(targets, voters, ...).await?;

      // Extract prediction from solution.solution_pages
      let predictions = build_predictions_from_solution(&solution, ...);
      write_output(predictions)?;
      Ok(())

What do you think?

sigurpol · 2025-11-18T08:49:14Z

scripts/generate_changelog.sh

Why are we removing this file?

sigurpol · 2025-11-18T08:54:32Z

README.md

+```json
+{
+  "metadata": {
+    "ss58Prefix": 42


Why do we need to specify ss58Prefix? Isn't it redundant since we specify the chain via --uri ?

@Ipsa11 can you reply to the open comments in this file from previous round of review?

@sigurpol
We have removed this ss58Prefix.

@Ipsa11 it's still referenced in multiple places in tests/predict.rs e.g. when you create a temp custom file and still in this README...

README.md

Cargo.toml

.gitignore

src/commands/predict.rs

src/dynamic/staking.rs

Ipsa11 · 2025-11-19T05:35:58Z

I have left quite a few comments, some cosmetic and some more substantial.

Most critical ones:

remove duplicate election execution and call mine_solution only once

remove duplication. Imho, The prediction command should reuse:

fetch_missing_snapshots() for snapshot data

mine_solution() for election computation

Snapshot

All existing type infrastructure monitor already relies on

It might be beneficial to create a single data fetching layer that both monitor and predict can reuse. Something that 1. try to fetch snapshot 2.optional fallback: fetch from staking pallet and convert to snapshot format

I would like to have predict_command something like this (very high level)
  pub async fn predict_cmd(...) -> Result<(), Error> {
      // this get_election_data() is the same method to fetch data that monitor will use too.
     // For predict, we will enable fallback in case snapshot is not available
      let (targets, voters) = get_election_data(...).await?;
      // same mine_solution that monitor relies on, SDK does the whole work
      let solution = mine_solution(targets, voters, ...).await?;

      // Extract prediction from solution.solution_pages
      let predictions = build_predictions_from_solution(&solution, ...);
      write_output(predictions)?;
      Ok(())
What do you think?

Hey @sigurpol,
The mine_solution function returns a very minimal output — it doesn’t include details like account IDs or stake amounts. Because of this, the required output format won’t match what the function produces, so we can’t use mine_solution directly in this case.So therefore there is duplication of code to produce the required output.

sigurpol · 2025-11-19T09:00:12Z

Hey @sigurpol, The mine_solution function returns a very minimal output — it doesn’t include details like account IDs or stake amounts. Because of this, the required output format won’t match what the function produces, so we can’t use mine_solution directly in this case.So therefore there is duplication of code to produce the required output.

Hi @Ipsa11 , I believe the mine_solution output can be converted to the required format with full account IDs and stake distribution.

An example in the SDK where this is done is here.

I believe the miner could just use
use polkadot_sdk::pallet_election_provider_multi_block::verifier::feasibility_check_page_inner_with_snapshot;
and do something like this after calling mine_solution:

// after calling mine_solution()
for solution_page in paged_raw_solution.solution_pages {
    let supports = feasibility_check_page_inner_with_snapshot::<MinerConfig>(
        solution_page,
        &snapshot_voters,
        &snapshot_targets,
        desired_targets,
    )?;
    // `supports` now contains full validator support with AccountIds and stakes

…b.com/antiers-solutions/polkadot-staking-miner into feat/offline-election-prediction-tool

…tool

cla-bot-2021 · 2025-11-24T05:31:23Z

User @Ipsa11, please sign the CLA here.

src/dynamic/election_data.rs

sigurpol · 2025-12-11T08:12:40Z

Looks good (to be properly tested by @michalisFr still 😅 ). @Ipsa11 can we please do a final round of cleanup and address some small easy pending comments to reduce the scope of the PR:

do not change permission of changelog.sh
revert all changes in Dockerfile, Dockerfile.README.md and remove .dockerignore

So we can have just changes specific to the predict command, thanks.

Ipsa11 · 2025-12-11T09:40:08Z

Hey @sigurpol
I have revert the changes in changelog.sh, the Docker-related files, and remove .dockerignore so that the PR only contains updates related to the predict command.

sigurpol · 2025-12-11T10:03:38Z

Hey @sigurpol I have revert the changes in changelog.sh, the Docker-related files, and remove .dockerignore so that the PR only contains updates related to the predict command.

Thank you @Ipsa11 ! Can you also reset the permission of changelog.sh to 100755 ?

…minators with their allocated stake

…tool

sigurpol · 2026-01-28T09:43:25Z

src/commands/predict.rs

+				.map_err(|e| {
+					Error::Other(format!("Failed to fetch Desired Targets from chain: {e}"))
+				})?
+				.expect("Error in fetching desired validators from chain")


I would return an error here instead of panic here replacing expect with ok_or_else() or similar

sigurpol · 2026-01-28T09:50:05Z

src/client.rs


-			let backend: ChainHeadBackend<Config> =
-				ChainHeadBackendBuilder::default().build_with_background_driver(reconnecting_rpc);
+			let backend = LegacyBackend::builder().build(reconnecting_rpc.clone());


[IMPORTANT] This is a breaking change vs current monitor command. For monitor cmd - which is expect to run 24/7 we want and need to use the new ChainHeadBackend API and not the legacy one. I would suggest to revert this change.

Hey @sigurpol
If we use ChainHeadBackend instead of LegacyBackend, we are unable to access older blocks, which effectively renders the block-number option meaningless. As a result, we can no longer run election predictions on blocks that have snapshots.
We would appreciate your guidance on how to address this issue. For reference, below is the error we encounter when attempting to access older blocks using ChainHeadBackend. Based on our testing, it only allows access to approximately the most recent 15 blocks.
Error:

Subxt(Rpc(ClientError(User(UserError { code: -32801, message: "Invalid block hash", data: None }))))

I have experienced something similar while playing with a PR to add support for Smoldot (temporarily parked, went for RPC pool support as stop gap solution until I have time to address it better). Unless @jsdw has better idea here, I would suggest to use two path: let monitor command rely on ChainHeadBackend as today so no change for the main monitor cmd we want to run 24/7 to submit solutions. And let the predict command use the LegacyBackend. Does it make sense for you?

src/commands/predict.rs

sigurpol · 2026-01-28T10:16:04Z

src/dynamic/election_data.rs

+			// validator has only self-vote if:
+			// 1. They are a validator (in active_set)
+			// 2. Their only target is themselves
+			// NOTE: Reverted to your original logic as requested, assuming you want strictly this


Is NOTE a leftover? There is a misalignment between what comment says and what code does.
The comment says AND, the code does OR, right?

Suggestion:

remove NOTE

check what SDK does, look at get_npos_voters Logic (in staking-async)

align comment and code

I believe the current logic is not aligned with what SDK does IIRC - meaning that if eg Alice is a validator and nominates Bob and Charlie, then it should count as valid nominator. Maybe targets.len() == 1 && targets[0] == *nominator would be a more correct check. Can you double-check?

@sigurpol
Yes, you are correct the Note shouldn't be there. But let us explain that the condition active_set.contains(nominator) || (targets.len() == 1 && targets[0] == *nominator)is for filtering the validators with only self stake after the mining of the solution, so that the nominators_results.json do not contain any validators with self stakes. Please have a look at the comment: [https://github.com/w3f/Grant-Milestone-Delivery/pull/1288#issuecomment-3586979252](w3f/Grant-Milestone-Delivery#1288 (comment))

we believe the current implementation focuses only on not including any validators in the nominators' result so both:
targets.len() == 1 && targets[0] == *nominator and
active_set.contains(nominator) || (targets.len() == 1 && targets[0] == *nominator)
seem to be equivalent. If there is any other query we're all ears. Thank you

thanks for the explanation so basically you want validators in one file, nominators in another file. If this is intent then the logic is fine and name could be better maybe (E.g. from validators_with_only_self_vote to validators_to_exclude_from_nominator_output or something like this. But that's just a cosmetic suggestion

sigurpol · 2026-01-28T10:18:40Z

src/commands/predict.rs

+	let validators_output = output_dir.join("validators_prediction.json");
+	let nominators_output = output_dir.join("nominators_prediction.json");
+	// Save validators prediction
+	write_data_to_json_file(&validators_prediction, validators_output.to_str().unwrap()).await?;


probably no need to panic here, can we return an error instead?

sigurpol · 2026-01-28T10:18:46Z

src/commands/predict.rs

+	);
+
+	// Save nominators prediction
+	write_data_to_json_file(&nominators_prediction, nominators_output.to_str().unwrap()).await?;


probably no need to panic here, can we return an error instead?

karanvir12 and others added 13 commits October 10, 2025 18:47

feat: initialize offline election prediction tool structure

38269b8

chore:added prediction types

531191f

chore: add module for fetching and preprocessing election data

b9abed4

chore: add command-line interface for offline election prediction tool

57a25c0

chore: implement core prediction logic

4648815

chore: run election predictions and generate output files

342d700

test: add unit and integration tests for election prediction tool

7e16bce

chore:code restructured

f51f470

chore:added readme

932e913

fix:fixed snapshot fetching logic

4d370fd

chore: Implemented suggested changes and improvements

bc8c325

fix(predict): custom file handling logic

7f80138

chore:docker image updated

f60a578

Ipsa11 mentioned this pull request Nov 13, 2025

Milestone 1 and 2 for Offline Election Prediction Tool w3f/Grant-Milestone-Delivery#1288

Merged

5 tasks

kianenigma reviewed Nov 14, 2025

View reviewed changes

src/commands/types.rs Show resolved Hide resolved

kianenigma reviewed Nov 14, 2025

View reviewed changes

src/prelude.rs Outdated Show resolved Hide resolved

kianenigma reviewed Nov 14, 2025

View reviewed changes

src/commands/types.rs Outdated Show resolved Hide resolved

chore: apply minor codebase improvements and cleanup

5a5b6f3

sigurpol reviewed Nov 18, 2025

View reviewed changes

karanvir12 and others added 4 commits November 19, 2025 15:54

chore:docker file updated

d5995ca

Merge branch 'feat/offline-election-prediction-tool' of https://githu…

16ad14b

…b.com/antiers-solutions/polkadot-staking-miner into feat/offline-election-prediction-tool

chore:rust version updated

d13195d

Merge branch 'paritytech:main' into feat/offline-election-prediction-…

22a40eb

…tool

chore:docker file updated

aaeb8f5

sigurpol reviewed Dec 3, 2025

View reviewed changes

src/dynamic/election_data.rs Outdated Show resolved Hide resolved

fix(predict): used bags and voterlist for fetching staking data

cbf661d

fix: restored dockerfile and removed dockerignore

f34cbf0

pushkar1262 and others added 19 commits December 11, 2025 16:00

Changed permissions of generate_changelog.sh

7e626e1

feat: added cli options for do_reduce and block number

ab9cdfd

chore: updated README

55e1502

fix(predict): fixed voter data fetch and ordering

2202fd6

chore: added number of nominators per validator and the individual no…

fc798f6

…minators with their allocated stake

refactor: fixed custom data file reading and some refactoring

6a957d6

Merge branch 'main' into feat/offline-election-prediction-tool

74bcabb

refactor: simplify backend initialization in Client

5a69b41

test(utils): add unit tests and misc cleanups

a8c53fc

Merge branch 'paritytech:main' into feat/offline-election-prediction-…

c1a4756

…tool

fix: fixed snapshot creation

b351c77

Merge branch 'paritytech:main' into feat/offline-election-prediction-…

22ab2e4

…tool

fixed empty validator prediction

a9a6670

Merge branch 'main' into feat/offline-election-prediction-tool

c887d92

Added overrides option| removed custom-data option

485db87

Added support for PhragMMS

3b5a346

Merge branch 'main' into feat/offline-election-prediction-tool

fb2333f

fix: address breaking changes from client.rs updates

76ebc86

improve logging hierarchy and used dynamic solver for kusama

8415e40

sigurpol reviewed Jan 28, 2026

View reviewed changes

implemented separate clients for monitor and predict | some refactoring

c3ba626

sigurpol approved these changes Jan 29, 2026

View reviewed changes

sigurpol merged commit b0335fa into paritytech:main Jan 29, 2026
10 checks passed

Feat/offline election prediction tool #1189

Feat/offline election prediction tool #1189

Uh oh!

Conversation

Ipsa11 commented Nov 13, 2025

Uh oh!

cla-bot-2021 bot commented Nov 13, 2025

User @karanvir12, please sign the CLA here.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Ipsa11 commented Nov 14, 2025

Uh oh!

sigurpol commented Nov 18, 2025

Uh oh!

sigurpol left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sigurpol Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ipsa11 commented Nov 19, 2025

Uh oh!

sigurpol commented Nov 19, 2025

Uh oh!

cla-bot-2021 bot commented Nov 24, 2025

Uh oh!

Uh oh!

sigurpol commented Dec 11, 2025

Uh oh!

Ipsa11 commented Dec 11, 2025

Uh oh!

sigurpol commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

sigurpol left a comment •

edited

Loading

sigurpol Nov 27, 2025 •

edited

Loading