Coordinator & Crunch Commands - Crunch Protocol Documentation

Coordinator Commands

Coordinator commands manage your Coordinator identity on the protocol.

crunch-cli coordinator <command> [options] [arguments]

`coordinator list`

List all registered coordinators.

crunch-cli coordinator list

Displays all coordinators in the system with their name, state, owner, and address.

`coordinator register`

crunch-cli coordinator register <name>

Arguments:

Argument	Description
`name`	Unique name for the coordinator

Example:

crunch-cli coordinator register "AI Research Lab"

The Coordinator must be approved by protocol admins before it can create competitions. After registration, the status will be Pending Approval.

Requirements:

Coordinator name must be unique
Wallet must have sufficient SOL for account creation

`coordinator get`

Get Coordinator details by owner address.

crunch-cli coordinator get [owner]

Arguments:

Argument	Description
`owner`	Owner address (optional, defaults to current wallet)

Examples:

# Get your own Coordinator details
crunch-cli coordinator get

# Get details for a specific address
crunch-cli coordinator get 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM

Shows Coordinator info including name, state, pool registration status, emission config percentages, and certificate information (if configured).

`coordinator get-config`

Get Coordinator protocol configuration.

crunch-cli coordinator get-config

Displays protocol-level settings including admin authority, USDC mint, margin percentages, claim expiry, and foundation wallet.

`coordinator cert set`

Set coordinator certificate hash for on-chain authentication.

crunch-cli coordinator cert set <base64-der-pubkey> [--slot <slot>]

Arguments:

Argument	Description
`base64-der-pubkey`	Base64-encoded DER public key from TLS/RSA certificate

Options:

Option	Description	Default
`--slot <slot>`	Certificate slot (0 for primary, 1 for secondary)	`0`

Examples:

# Set primary certificate
crunch-cli coordinator cert set "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

# Set secondary certificate for rotation
crunch-cli coordinator cert set "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..." --slot 1

Stores the SHA-256 hash of your TLS/RSA certificate’s DER-encoded public key on-chain. Model nodes use this to verify your certificate association. Supports primary and secondary slots for seamless certificate rotation. Requirements:

Coordinator must be in Approved state
Certificate hash cannot be all zeros
Slot must be 0 (primary) or 1 (secondary)

`coordinator cert get`

Get coordinator certificate information.

crunch-cli coordinator cert get [owner]

Arguments:

Argument	Description
`owner`	Owner address (optional, defaults to current wallet)

Examples:

# Get certificate info for current wallet
crunch-cli coordinator cert get

# Get certificate info for a specific coordinator
crunch-cli coordinator cert get 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM

Retrieves stored certificate hashes for both primary and secondary slots, along with timestamps. Returns null if no certificate is set.

`coordinator reset-hotkey`

Reset/regenerate the SMP hotkey for the Coordinator.

crunch-cli coordinator reset-hotkey

`coordinator set-emission-config`

Set emission config percentages for the Coordinator. Percentages must sum to 100.

crunch-cli coordinator set-emission-config <coordinatorPct> <stakerPct> <crunchFundPct>

Arguments:

Argument	Description
`coordinatorPct`	Coordinator percentage
`stakerPct`	Staker percentage
`crunchFundPct`	Crunch Fund percentage

Example:

crunch-cli coordinator set-emission-config 50 30 20

Crunch (Competition) Commands

Crunch commands manage competition lifecycles — from creation through checkpointing to draining.

crunch-cli crunch <command> [options] [arguments]

`crunch list`

List crunches for a coordinator, or all crunches system-wide.

# List crunches for current wallet
crunch-cli crunch list

# List crunches for a specific coordinator
crunch-cli crunch list <wallet>

# List all crunches system-wide
crunch-cli crunch list --all

Options:

Option	Description
`--all`	List all crunches system-wide

`crunch create`

Create a new competition.

crunch-cli crunch create <name> <payoutAmount> [maxModelsPerCruncher]

Arguments:

Argument	Description	Default
`name`	Name of the crunch	—
`payoutAmount`	Payout amount in USDC	—
`maxModelsPerCruncher`	Maximum models per cruncher	`2`

Example:

crunch-cli crunch create "iris_classifier" 10000 5

Requirements:

Must be an approved coordinator
Competition name must be unique
Must have sufficient SOL for account creation

`crunch start`

Start a competition, allowing crunchers to register and submit models.

crunch-cli crunch start <crunchName>

Example:

crunch-cli crunch start "iris_classifier"

The competition must be in the created state.

`crunch get`

Get detailed information about a competition.

crunch-cli crunch get <name>

Example:

crunch-cli crunch get "iris_classifier"

Shows state, payout amount, vault balance, max models, checkpoint count, and associated addresses.

`crunch get-cruncher`

Get detailed information about a cruncher registered in a competition.

crunch-cli crunch get-cruncher <crunchName> <cruncherWallet>

Arguments:

Argument	Description
`crunchName`	Name of the crunch
`cruncherWallet`	Cruncher wallet address

Example:

crunch-cli crunch get-cruncher "iris_classifier" 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM

Shows cruncher index, PDA address, registered models, and prize history across checkpoints.

`crunch end`

End a competition, preventing new registrations and model submissions.

crunch-cli crunch end <crunchName>

The competition must be in the started state.

`crunch deposit-reward`

Deposit USDC rewards to a competition’s vault.

crunch-cli crunch deposit-reward <crunchName> <amount>

Arguments:

Argument	Description
`crunchName`	Name of the crunch
`amount`	Amount in USDC

Example:

crunch-cli crunch deposit-reward "iris_classifier" 5000

Requirements:

Must have sufficient USDC balance
Must have a USDC Associated Token Account

`crunch margin`

Execute margin payout for a competition.

crunch-cli crunch margin <crunchName>

`crunch drain`

Drain remaining USDC from a competition’s reward pool back to the coordinator.

crunch-cli crunch drain <crunchName>

`crunch set-fund-config`

Set crunch fund configuration percentages. Percentages must sum to 100.

crunch-cli crunch set-fund-config <crunchName> <cruncherPct> <dataproviderPct> <computeProviderPct>

Arguments:

Argument	Description
`crunchName`	Name of the crunch
`cruncherPct`	Cruncher percentage
`dataproviderPct`	Data provider percentage
`computeProviderPct`	Compute provider percentage

Example:

crunch-cli crunch set-fund-config "iris_classifier" 60 20 20

Checkpoint Commands

Checkpoints handle reward distribution to crunchers.

`crunch checkpoint-create`

Create a checkpoint for payout distribution.

crunch-cli crunch checkpoint-create <crunchName> <prizeFileName> [--dryrun]

Arguments:

Argument	Description
`crunchName`	Name of the crunch
`prizeFileName`	Path to prize JSON file

Options:

Option	Description
`--dryrun`	Preview without executing transactions

Example:

crunch-cli crunch checkpoint-create "iris_classifier" ./prizes.json
crunch-cli crunch checkpoint-create "iris_classifier" ./prizes.json --dryrun

Prize File Format: Each line in the JSON file should follow this structure:

{ "timestamp": 1840417288969, "model": "model_3", "prize": 130870000 }

Field	Description	Required
`timestamp`	Unix timestamp in milliseconds	Yes
`model`	Model identifier receiving the prize	Yes
`prize`	Prize amount in micro USDC (amount × 10^6)	Yes
`prizeId`	Unique identifier for the prize	No

`crunch checkpoint-get-current`

Get the current active checkpoint for a competition.

crunch-cli crunch checkpoint-get-current <crunchName>

`crunch checkpoint-get`

Get a specific checkpoint by index.

crunch-cli crunch checkpoint-get <crunchName> <checkpointIndex>

`crunch checkpoint-get-address`

Get the Solana address of a specific checkpoint account.

crunch-cli crunch checkpoint-get-address <crunchName> <checkpointIndex>

Advanced Crunch Commands

`crunch sweep-token-accounts`

Sweep tokens from incorrect accounts to the reward vault.

crunch-cli crunch sweep-token-accounts <crunchName>

`crunch check-prize-atas`

Check if crunchers in a prize file have USDC Associated Token Accounts.

crunch-cli crunch check-prize-atas <crunchName> <prizeFileName> [-c|--create]

Options:

Option	Description
`-c, --create`	Create missing USDC Associated Token Accounts

`crunch emission-checkpoint-add`

Add an emission checkpoint to the coordinator pool.

crunch-cli crunch emission-checkpoint-add <emissionFile>

`crunch map-cruncher-addresses`

Map cruncher wallets into the coordinator pool address index.

crunch-cli crunch map-cruncher-addresses <crunchAddress> <wallets...>

Arguments:

Argument	Description
`crunchAddress`	Crunch address (Pubkey)
`wallets...`	Cruncher wallet addresses in mapping order

Model Commands

Model commands enable running simulations and managing scenario files using the Python CLI integration.

crunch-cli model <command> [options] [arguments]

Model commands require the Python CLI companion package. Install with: pip install crunch-cli

`model list`

List all available simulation scenarios.

crunch-cli model list

Displays a table of available scenarios with their names and corresponding files. Example:

$ crunch-cli model list
                             Available Scenarios                              
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                              ┃ File                                   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ high_demand_5_coordinators        │ high_demand_5_coordinators.yaml        │
│ single_coordinator_2year_baseline │ single_coordinator_2year_baseline.yaml │
│ ...                               │ ...                                    │
└───────────────────────────────────┴────────────────────────────────────────┘

`model run <scenario>`

Run a simulation using the specified scenario.

crunch-cli model run <scenario> [--output <path>]

Arguments:

Argument	Description
`scenario`	Name or file path of the scenario

Options:

Option	Description
`--output <path>`	Directory to save simulation results

Example:

$ crunch-cli model run baseline --output ./results
Running simulation: baseline
  Epochs: 104
  Coordinators: 1
✓ Completed 104 epochs
✓ Results saved to ./results

`model validate <scenario>`

Validate a scenario file to check for configuration errors.

crunch-cli model validate <scenario>

Arguments:

Argument	Description
`scenario`	Name or file path of the scenario

Example:

$ crunch-cli model validate high_demand_scenario.yaml
✓ Scenario file is valid

Command Reference Summary

Category	Command	Description
Coordinator	`coordinator list`	List all coordinators
	`coordinator register`	Register as a Coordinator
	`coordinator get`	Get Coordinator details
	`coordinator get-config`	Get protocol configuration
	`coordinator reset-hotkey`	Reset SMP hotkey
	`coordinator set-emission-config`	Set emission percentages
Certificate Management	`coordinator cert set`	Set certificate hash on-chain
	`coordinator cert get`	Get certificate info
Competition Lifecycle	`crunch create`	Create a new competition
	`crunch start`	Start a competition
	`crunch get`	Get competition details
	`crunch get-cruncher`	Get cruncher details in competition
	`crunch list`	List crunches
	`crunch end`	End a competition
Financial Management	`crunch deposit-reward`	Deposit USDC rewards
	`crunch margin`	Execute margin payout
	`crunch drain`	Withdraw remaining USDC
	`crunch set-fund-config`	Set fund split percentages
Checkpoint Management	`crunch checkpoint-create`	Create reward checkpoint
	`crunch checkpoint-get-current`	Get current checkpoint
	`crunch checkpoint-get`	Get checkpoint by index
	`crunch checkpoint-get-address`	Get checkpoint address
Model Management	`model list`	List available simulation scenarios
	`model run`	Run a simulation scenario
	`model validate`	Validate a scenario file
Advanced	`crunch sweep-token-accounts`	Sweep tokens to reward vault
	`crunch check-prize-atas`	Check/create prize ATAs
	`crunch emission-checkpoint-add`	Add emission checkpoint
	`crunch map-cruncher-addresses`	Map cruncher addresses

Competition Workflow

crunch-cli coordinator register "My Organization"

Set Certificate

Set your TLS certificate for Model Node verification:

crunch-cli coordinator cert set "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

Create Competition

Create a competition:

crunch-cli crunch create "my_competition" 10000 5

Fund

Deposit rewards:

crunch-cli crunch deposit-reward "my_competition" 10000

Launch

Start the competition:

crunch-cli crunch start "my_competition"

Monitor

Check status:

crunch-cli crunch get "my_competition"

Distribute Rewards

Create checkpoints:

crunch-cli crunch checkpoint-create "my_competition" ./prizes.json

End

End the competition:

crunch-cli crunch end "my_competition"

Cleanup

Drain remaining funds:

crunch-cli crunch drain "my_competition"

Cruncher & Staking Commands — Participant operations, model management, staking
Installation & Global Options — Configuration and shared options

​Coordinator Commands

​coordinator list

​coordinator register

​coordinator get

​coordinator get-config

​coordinator cert set

​coordinator cert get

​coordinator reset-hotkey

​coordinator set-emission-config

​Crunch (Competition) Commands

​crunch list

​crunch create

​crunch start

​crunch get

​crunch get-cruncher

​crunch end

​crunch deposit-reward

​crunch margin

​crunch drain

​crunch set-fund-config

​Checkpoint Commands

​crunch checkpoint-create

​crunch checkpoint-get-current

​crunch checkpoint-get

​crunch checkpoint-get-address

​Advanced Crunch Commands

​crunch sweep-token-accounts

​crunch check-prize-atas

​crunch emission-checkpoint-add

​crunch map-cruncher-addresses

​Model Commands

​model list

​model run <scenario>

​model validate <scenario>

​Command Reference Summary

​Competition Workflow

​Related

Coordinator Commands

`coordinator list`

`coordinator register`

`coordinator get`

`coordinator get-config`

`coordinator cert set`

`coordinator cert get`

`coordinator reset-hotkey`

`coordinator set-emission-config`

Crunch (Competition) Commands

`crunch list`

`crunch create`

`crunch start`

`crunch get`

`crunch get-cruncher`

`crunch end`

`crunch deposit-reward`

`crunch margin`

`crunch drain`

`crunch set-fund-config`

Checkpoint Commands

`crunch checkpoint-create`

`crunch checkpoint-get-current`

`crunch checkpoint-get`

`crunch checkpoint-get-address`

Advanced Crunch Commands

`crunch sweep-token-accounts`

`crunch check-prize-atas`

`crunch emission-checkpoint-add`

`crunch map-cruncher-addresses`

Model Commands

`model list`

`model run <scenario>`

`model validate <scenario>`

Command Reference Summary

Competition Workflow

Related