Skip to main content

​
Crunch Implementation Guide

This example walks you through the entire process of becoming a Coordinator on the Crunch Protocol, from initial setup to running live competitions. We’ll cover everything you need to leverage the collective intelligence of world-class ML engineers for your prediction challenges.

​
What You’ll Learn

We’ll guide you through 5 essential steps to get your Crunch up and running:
1

Prediction Task Definition

Will walk you through the prediction task the Coordinator is trying to solve, which includes the predictive challenge definition, model interfaces and quickstarter models that you can use to test your implementation and will help Crunchers implement their models when the competition starts.
2

Base and Quickstarter Models

Will guide you through creating the Base Model, the model every Cruncher needs to implement to be able to run in the Crunch, and the Quickstarter Models, which are example models that make onboarding easier for Crunchers and can help to set a benchmark for the performance of the submitted models.
3

Coordinator Node Setup

Will give you an overview of how your Coordinator node setup—from data ingestion and transformation to model orchestration and performance evaluation systems.
4

Local Testing

Will help you set up a complete out-of-the-box Crunch testing environment locally. Everything should work seamlessly, giving you confidence before going live.
5

On-Chain Administration

Will guide you through the process of how to administer an ongoing Crunch on-chain, including prize escrow, checkpoint payouts, and final settlement processes.
By the end of this guide, you’ll have a complete, working Crunch implementation! Before we dive into the implementation, let’s first take a look at the project structure and the dataset we will be using.

​
Overview of the Project Structure

The Repository contains the complete Crunch implementation with three main components in examples/iris/:

​
📁 coordinator/ - The Coordinator Node Implementation

Contains the simplest example of a Coordinator node logic that orchestrates the entire Crunch process, implementing the three core responsibilities:
  • Data Management: Load and prepare iris datasets.
  • Model Orchestration: Distributes the different datasets to the registered models for train and infer, using the Model Runner Client (Our Python library for communicating with Crunch Protocol model clusters)
  • Scoring & Rewards: Evaluate model output performance and distribute prizes.

​
📁 cruncher/ - The Model Implementations

Contains example model submissions from Crunchers (ML engineers), including:
  • Model Package: Standard interface all models must implement to be able to run in the Crunch Model Runners and be called by the Coordinator.
  • Quickstarter Models: Pre-trained example models: Neural Network, Random Forest, and SVM implementations. These can be used as a starting point for own models.
  • Utility Scripts: Model training and deployment tools

​
📁 webapp/ - A web application to manage the Crunch

Contains a Nextjs web application to facilitate local testing and Crunch management: It provides an interactive dashboard for coordinating the Crunch workflow, inspecting leaderboard, and simulating complete end-to-end Crunch runs.

​
📁 docker/ - A complete Infrastructure Setup to faciliate local testing

Contains Docker configurations for running the complete Crunch Protocol stack locally:
  • Coordinator web interface: React-based dashboard for running prediction rounds and managing blockchain interactions
  • Model Orchestrator: Central orchestrator to manage model clusters
In the upcoming section we will initially walkthrough the implementation of the Model Package and Quickstarter Models, as it will explain the core prediction task the Coordinator is trying to solve, before then explaining how the Coordinator Node is implemented to facilitate the Crunch!

Prediction Task Definition

In the next section we will walkthrough the implementation of the Model Package and Quickstarter Models, as it will explain the core prediction task the Coordinator is trying to solve.