> ## Documentation Index
> Fetch the complete documentation index at: https://protocol.crunchdao.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coordinator & Crunch Commands

> Manage Coordinators and competition lifecycles using the unified Crunch Protocol CLI (@crunchdao/cli). Includes registration, competition creation, reward management, and checkpoint operations.

## Coordinator Commands

Coordinator commands manage your Coordinator identity on the protocol.

```bash theme={null}
crunch-cli coordinator <command> [options] [arguments]
```

### `coordinator list`

List all registered coordinators.

```bash theme={null}
crunch-cli coordinator list
```

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

***

### `coordinator register`

Register a new Coordinator with the protocol.

```bash theme={null}
crunch-cli coordinator register <name>
```

**Arguments:**

| Argument | Description                     |
| -------- | ------------------------------- |
| `name`   | Unique name for the coordinator |

**Example:**

```bash theme={null}
crunch-cli coordinator register "AI Research Lab"
```

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

**Requirements:**

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

***

### `coordinator get`

Get Coordinator details by owner address.

```bash theme={null}
crunch-cli coordinator get [owner]
```

**Arguments:**

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

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
crunch-cli coordinator cert get [owner]
```

**Arguments:**

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

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
crunch-cli coordinator reset-hotkey
```

***

### `coordinator set-emission-config`

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

```bash theme={null}
crunch-cli coordinator set-emission-config <coordinatorPct> <stakerPct> <crunchFundPct>
```

**Arguments:**

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

**Example:**

```bash theme={null}
crunch-cli coordinator set-emission-config 50 30 20
```

***

## Crunch (Competition) Commands

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

```bash theme={null}
crunch-cli crunch <command> [options] [arguments]
```

### `crunch list`

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

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
crunch-cli crunch start <crunchName>
```

**Example:**

```bash theme={null}
crunch-cli crunch start "iris_classifier"
```

The competition must be in the **created** state.

***

### `crunch get`

Get detailed information about a competition.

```bash theme={null}
crunch-cli crunch get <name>
```

**Example:**

```bash theme={null}
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.

```bash theme={null}
crunch-cli crunch get-cruncher <crunchName> <cruncherWallet>
```

**Arguments:**

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

**Example:**

```bash theme={null}
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.

```bash theme={null}
crunch-cli crunch end <crunchName>
```

The competition must be in the **started** state.

***

### `crunch deposit-reward`

Deposit USDC rewards to a competition's vault.

```bash theme={null}
crunch-cli crunch deposit-reward <crunchName> <amount>
```

**Arguments:**

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

**Example:**

```bash theme={null}
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.

```bash theme={null}
crunch-cli crunch margin <crunchName>
```

***

### `crunch drain`

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

```bash theme={null}
crunch-cli crunch drain <crunchName>
```

***

### `crunch set-fund-config`

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

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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:

```json theme={null}
{ "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.

```bash theme={null}
crunch-cli crunch checkpoint-get-current <crunchName>
```

***

### `crunch checkpoint-get`

Get a specific checkpoint by index.

```bash theme={null}
crunch-cli crunch checkpoint-get <crunchName> <checkpointIndex>
```

***

### `crunch checkpoint-get-address`

Get the Solana address of a specific checkpoint account.

```bash theme={null}
crunch-cli crunch checkpoint-get-address <crunchName> <checkpointIndex>
```

***

## Advanced Crunch Commands

### `crunch sweep-token-accounts`

Sweep tokens from incorrect accounts to the reward vault.

```bash theme={null}
crunch-cli crunch sweep-token-accounts <crunchName>
```

***

### `crunch check-prize-atas`

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

```bash theme={null}
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.

```bash theme={null}
crunch-cli crunch emission-checkpoint-add <emissionFile>
```

***

### `crunch map-cruncher-addresses`

Map cruncher wallets into the coordinator pool address index.

```bash theme={null}
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.

```bash theme={null}
crunch-cli model <command> [options] [arguments]
```

<Note>
  Model commands require the Python CLI companion package. Install with: `pip install crunch-cli`
</Note>

***

### `model list`

List all available simulation scenarios.

```bash theme={null}
crunch-cli model list
```

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

**Example:**

```bash theme={null}
$ 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.

```bash theme={null}
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:**

```bash theme={null}
$ 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.

```bash theme={null}
crunch-cli model validate <scenario>
```

**Arguments:**

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

**Example:**

```bash theme={null}
$ 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

<Steps>
  <Step title="Register">
    Register as a Coordinator:

    ```bash theme={null}
    crunch-cli coordinator register "My Organization"
    ```
  </Step>

  <Step title="Set Certificate">
    Set your TLS certificate for Model Node verification:

    ```bash theme={null}
    crunch-cli coordinator cert set "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
    ```
  </Step>

  <Step title="Create Competition">
    Create a competition:

    ```bash theme={null}
    crunch-cli crunch create "my_competition" 10000 5
    ```
  </Step>

  <Step title="Fund">
    Deposit rewards:

    ```bash theme={null}
    crunch-cli crunch deposit-reward "my_competition" 10000
    ```
  </Step>

  <Step title="Launch">
    Start the competition:

    ```bash theme={null}
    crunch-cli crunch start "my_competition"
    ```
  </Step>

  <Step title="Monitor">
    Check status:

    ```bash theme={null}
    crunch-cli crunch get "my_competition"
    ```
  </Step>

  <Step title="Distribute Rewards">
    Create checkpoints:

    ```bash theme={null}
    crunch-cli crunch checkpoint-create "my_competition" ./prizes.json
    ```
  </Step>

  <Step title="End">
    End the competition:

    ```bash theme={null}
    crunch-cli crunch end "my_competition"
    ```
  </Step>

  <Step title="Cleanup">
    Drain remaining funds:

    ```bash theme={null}
    crunch-cli crunch drain "my_competition"
    ```
  </Step>
</Steps>

## Related

* [Cruncher & Staking Commands](/cli/cruncher-and-staking-commands) — Participant operations, model management, staking
* [Installation & Global Options](/cli/installation-and-global-options) — Configuration and shared options