From a8893d80261b3a7867f56523f3b6306b72dbee7c Mon Sep 17 00:00:00 2001 From: zoopx founder Date: Fri, 28 Nov 2025 03:20:54 +0530 Subject: [PATCH] feat: add Offline Election Tool grant application (Predifi Labs) --- applications/offline-election-tool.md | 261 ++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 applications/offline-election-tool.md diff --git a/applications/offline-election-tool.md b/applications/offline-election-tool.md new file mode 100644 index 00000000000..ab6179bb5aa --- /dev/null +++ b/applications/offline-election-tool.md @@ -0,0 +1,261 @@ +# Offline Election Tool + +- **Team Name:** Predifi Labs +- **Payment Details:** + - **DOT**: 14B4RC9uUzh73C5RmHMU5VgevNPccmMTnvgYPp2Y8xeUtwZY (50% vested over 2 years) + - **Payment**: 14B4RC9uUzh73C5RmHMU5VgevNPccmMTnvgYPp2Y8xeUtwZY (USDC on Polkadot AssetHub) +- **[Level](https://grants.web3.foundation/docs/Introduction/levels):** 1 + +> **This application is in response to the [Offline Election Tool RFP](https://github.com/w3f/Grants-Program/blob/master/docs/RFPs/Open/offline-election-tool.md) by @michalisFr.** + +## Project Overview :page_facing_up: + +### Overview + +**Tagline:** A modern Rust-based tool for accurately simulating Polkadot's NPoS election mechanism offline. + +The Offline Election Tool aims to accurately simulate Polkadot's Nominated Proof-of-Stake (NPoS) election mechanism that determines active validators and nomination distribution. It replaces the legacy election simulator with a modern, flexible, and accurate Rust-based implementation. The tool supports both on-chain and synthetic data, exposes a CLI and HTTP API, and allows custom parameters and "what-if" scenarios for staking providers and the Decentralized Nodes program. + +**Integration with Polkadot:** This tool directly interfaces with Polkadot's staking pallets and uses the same election algorithms (via `sp-npos-elections`) that run on-chain. It enables validators, nominators, and staking providers to predict election outcomes without executing actual on-chain elections. + +**Motivation:** Accurate election simulation helps staking providers and decentralized node operators plan nomination strategies, forecast validator inclusion probabilities, and test stake distributions without triggering on-chain elections. The old script is outdated and lacks API support, custom account simulation, and algorithm flexibility. This project addresses these gaps by providing a production-ready, well-documented, and actively maintained tool. + +### Project Details + +**Technology Stack:** +- **Language:** Rust +- **Core Libraries:** `sp-npos-elections`, `sp-runtime`, `frame-election-provider-support`, `parity-scale-codec` +- **API Framework:** Axum (lightweight async HTTP server) +- **RPC Client:** `subxt` or `jsonrpsee` for on-chain data fetching +- **CLI Framework:** `clap` for command-line interface + +**Architecture Overview:** + +1. **Data Ingestion Layer:** + - Fetch on-chain state from Polkadot/Kusama via RPC at specific block heights + - Accept JSON input files for offline or synthetic scenarios + - Support custom accounts (unbonded or non-existent voters/candidates) + +2. **Election Simulation Engine:** + - Use Substrate's `sp-npos-elections` crate for precise NPoS election logic + - Support configurable parameters: + - Maximum active validators + - Maximum nominators per validator + - Minimum nomination threshold + - Commission rates + - Execute phragmén or phragmms algorithms as configured + +3. **Output & API Layer:** + - **CLI Mode:** Run simulations via command-line with results output to stdout or files + - **HTTP API:** + - `POST /simulate`: Submit election data and parameters, receive predicted results + - `GET /params`: Retrieve current configuration + - `GET /health`: Health check endpoint + - Output includes: + - Active validator set + - Nomination distribution per validator + - Score/backing for each validator + - Edge assignments (nominator → validator) + +**What This Project Will NOT Include:** +- Token economics modeling or financial projections +- Deployment hosting or cloud infrastructure +- Marketing, events, or business development activities +- Auditing services (though code will be production-ready and tested) + +**Validation Approach:** +- Cross-check simulation results against 20+ historical eras from Polkadot mainnet +- Target >95% parity in active validator set composition +- Target >95% accuracy in nomination distribution patterns +- Automated integration tests comparing tool output vs. actual on-chain results + +### Ecosystem Fit + +**Where does this project fit?** +This tool serves the Polkadot staking ecosystem by providing essential infrastructure for: +- Validator operators planning their nomination strategies +- Staking-as-a-Service providers optimizing delegation +- The Decentralized Nodes program for simulating nomination scenarios +- Researchers studying NPoS fairness, decentralization, and game theory + +**Target Audience:** +- Staking providers (e.g., Stakefish, P2P Validator, Chorus One) +- Individual validators and nominators +- Decentralized Nodes program participants +- Polkadot governance contributors analyzing staking dynamics +- Academic researchers studying NPoS mechanisms + +**Needs Met:** +- **Predictability:** Simulate election outcomes before committing stake +- **Strategy Testing:** Test "what-if" scenarios with custom parameters +- **Transparency:** Understand why specific validators are elected or excluded +- **Automation:** Integrate election prediction into automated staking workflows via API + +**Evidence of Need:** +- The RFP itself indicates demand from the Web3 Foundation and Decentralized Nodes program +- Community discussions on [Polkadot Forum](https://forum.polkadot.network/) frequently mention the need for better staking tools +- Existing legacy script is rarely updated and lacks modern features (API, custom scenarios) + +**Similar Projects:** +- **Legacy Election Simulator:** Outdated Python/JavaScript script; lacks API, extensibility, and maintenance +- **Polkadot Staking Dashboard:** Focuses on UI/UX for nominators but doesn't provide programmatic election simulation +- **This Project's Differentiation:** + - Built in Rust using official Substrate crates (same logic as on-chain) + - Provides both CLI and HTTP API for integration + - Supports custom/synthetic accounts for forward-looking scenarios + - Actively maintained with comprehensive documentation and tests + +**Related Ecosystems:** +- Ethereum staking tools focus on validator rotation and rewards, but NPoS is unique to Polkadot +- Cosmos staking is simpler (top-N validators); NPoS election logic is more complex and novel + +## Team :busts_in_silhouette: + +### Team members + +- **Team Leader:** Devendra Tanwar +- **AI Engineering Support:** GPT-5 (technical assistant for algorithm design and Substrate integration) + +### Contact + +- **Contact Name:** Devendra Tanwar +- **Contact Email:** dev@predifi.com +- **Website:** https://predifi.com + +### Legal Structure + +- **Registered Address:** To be provided during KYC/KYB process +- **Registered Legal Entity:** Predifi Labs (registration details to be confirmed in KYC) + +### Team's experience + +**Devendra Tanwar** is a full-stack engineer with extensive experience in: +- Backend systems development (Rust, Go, Python) +- DeFi protocol integration and smart contract interactions +- Substrate/Polkadot ecosystem contributions +- Building developer tooling and APIs for blockchain applications + +Prior work includes contributions to DeFi protocols, staking infrastructure, and data analytics pipelines for on-chain activity. + +**GPT-5 AI Support:** Used for algorithm design, Substrate crate integration, and technical documentation to accelerate development while maintaining high code quality. + +### Team Code Repos + +- https://github.com/Predifi-com/offline-election-tool (to be created) +- https://github.com/Predifi-com + +Team member GitHub: +- https://github.com/devendra-tanwar (or actual handle) + +### Team LinkedIn Profiles + +- https://www.linkedin.com/in/devendra-tanwar (placeholder - replace with actual) + +## Development Status :open_book: + +This application is in direct response to the **[Offline Election Tool RFP](https://github.com/w3f/Grants-Program/blob/master/docs/RFPs/Open/offline-election-tool.md)** published by @michalisFr. + +**Research and Preparation:** +- Reviewed the legacy election simulator and identified its limitations +- Analyzed Substrate's `sp-npos-elections` crate and election-provider pallets +- Studied Polkadot's staking mechanics via runtime code and on-chain data +- Reviewed community discussions on staking strategy and tooling needs +- Defined API specifications and data models for the HTTP interface + +**References:** +- [Polkadot NPoS Research](https://research.web3.foundation/Polkadot/protocols/NPoS) +- [sp-npos-elections documentation](https://paritytech.github.io/substrate/master/sp_npos_elections/) +- [Decentralized Nodes Program](https://wiki.polkadot.network/docs/thousand-validators) + +## Development Roadmap :nut_and_bolt: + +### Overview + +- **Total Estimated Duration:** 4 weeks +- **Full-Time Equivalent (FTE):** 1 +- **Total Costs:** 5,000 USD +- **DOT %:** 50% (vested over 2 years) + +### Milestone 1 — Update Original Script & Accurate Prediction + +- **Estimated duration:** 2 weeks +- **FTE:** 1 +- **Costs:** 2,500 USD + +| Number | Deliverable | Specification | +| -----: | ----------- | ------------- | +| **0a.** | License | Apache 2.0 | +| **0b.** | Documentation | Inline documentation for all modules, plus a comprehensive README with setup instructions, usage examples, and architecture overview. | +| **0c.** | Testing and Testing Guide | Unit tests for core election logic, integration tests comparing results against historical on-chain elections. Guide will explain how to run tests locally. | +| **0d.** | Docker | Dockerfile for building and running the tool in a containerized environment. | +| 1. | Core Election Engine | Implement Rust-based election simulation using `sp-npos-elections` with support for phragmén/phragmms algorithms. | +| 2. | On-Chain Data Fetching | Integrate RPC client to fetch staking state (validators, nominators, stakes, commissions) at specific block heights. | +| 3. | JSON Input Support | Accept offline JSON files with custom staking data for simulation. | +| 4. | Result Output | Generate detailed output: active validator set, nomination distribution, scores, and edge assignments. | +| 5. | Validation Suite | Automated tests comparing tool output against 20+ historical Polkadot eras to ensure >95% accuracy. | + +### Milestone 2 — Support Non-Existent Voters and Candidates + +- **Estimated Duration:** 1 week +- **FTE:** 1 +- **Costs:** 1,250 USD + +| Number | Deliverable | Specification | +| -----: | ----------- | ------------- | +| **0a.** | License | Apache 2.0 | +| **0b.** | Documentation | Updated README and inline docs explaining how to add synthetic accounts (unbonded or non-existent voters/candidates). | +| **0c.** | Testing and Testing Guide | Unit tests for synthetic account handling, integration tests for "what-if" scenarios. | +| **0d.** | Docker | Updated Dockerfile including new features. | +| 1. | Synthetic Account Injection | Allow users to specify custom voters and candidates (not present on-chain or unbonded) via JSON input. | +| 2. | What-If Scenarios | Enable testing of hypothetical stake distributions and candidate additions without altering on-chain data. | +| 3. | Validation | Ensure synthetic accounts integrate correctly with election logic and produce valid results. | + +### Milestone 3 — API Development (CLI + HTTP) + +- **Estimated Duration:** 1 week +- **FTE:** 1 +- **Costs:** 1,250 USD + +| Number | Deliverable | Specification | +| -----: | ----------- | ------------- | +| **0a.** | License | Apache 2.0 | +| **0b.** | Documentation | API reference documentation (OpenAPI/Swagger spec), CLI usage guide, and integration examples. | +| **0c.** | Testing and Testing Guide | API endpoint tests, CLI integration tests, and performance benchmarks. | +| **0d.** | Docker | Production-ready Docker image for running HTTP API server. | +| **0e.** | Article | Publish a Medium/blog post explaining the tool's features, use cases, and how it benefits the Polkadot staking ecosystem. | +| 1. | CLI Interface | Command-line tool with subcommands for running simulations, fetching on-chain data, and managing configurations. Uses `clap` for argument parsing. | +| 2. | HTTP API | Axum-based REST API with endpoints: `POST /simulate`, `GET /params`, `GET /health`. JSON request/response format. | +| 3. | API Documentation | OpenAPI 3.0 spec and interactive Swagger UI for API testing. | +| 4. | Integration Guide | Step-by-step tutorial for integrating the tool into staking workflows (e.g., via curl, Postman, or automated scripts). | +| 5. | Performance Optimization | Ensure simulations complete within reasonable time (<10s for typical Polkadot election size). | + +## Future Plans + +**Short-Term (0-6 months):** +- Promote the tool within the Polkadot community via forum posts, Twitter, and developer workshops +- Gather feedback from staking providers and iterate on features +- Add support for Kusama and other Substrate-based chains + +**Long-Term Maintenance:** +- Monitor Substrate/Polkadot runtime upgrades and update the tool accordingly +- Accept community contributions via GitHub (issues, PRs, feature requests) +- Potential future grant for advanced features (e.g., historical analysis dashboard, gas-optimized smart contract integration) + +**Sustainability:** +- Tool will remain open-source and community-maintained +- Predifi Labs will provide ongoing support as part of our Polkadot ecosystem contributions +- Consider offering premium hosted API service for enterprise staking providers (self-funded) + +## Additional Information :heavy_plus_sign: + +**How did you hear about the Grants Program?** +Web3 Foundation Website and the RFP announcement in the Grants-Program repository. + +**Additional Context:** +- This tool directly supports the **Decentralized Nodes program** by enabling offline validator selection prediction and nomination planning. +- Benefits extend to staking providers, community validators, and researchers studying NPoS fairness and decentralization. +- We are committed to delivering a production-ready, well-documented, and actively maintained tool that becomes a standard resource in the Polkadot staking ecosystem. + +**Previous Work:** +- No previous Web3 Foundation grants applied for by Predifi Labs. +- Team has prior experience contributing to DeFi protocols and blockchain developer tooling in the Polkadot ecosystem.