@crunchdao/coordinator-cli

Coordinator CLI Documentation

The Coordinator CLI (@crunchdao/coordinator-cli) provides competition management operations for the CrunchDAO Protocol. This includes coordinator registration, competition lifecycle management (creating, starting, ending competitions), reward distribution, and checkpoint operations.

For participant operations (cruncher registration, model submission, claiming rewards), see @crunchdao/cruncher-cli.

Installation

npm install -g @crunchdao/coordinator-cli

Usage

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

Global Options

All commands support these global options:

• -n, --network <network> - Solana network (localnet, devnet, mainnet)
• -w, --wallet <wallet> - Path to wallet keypair file
• -l, --loglevel <level> - Log level (debug, info, warn, error)
• -m, --multisig <address> - Squads multisig address for coordinator operations

Multisig Operations

When the --multisig parameter is provided, commands will create multisig proposals instead of executing directly. This is the recommended approach for production environments where coordinator operations need approval from multiple parties.

Multisig-Compatible Commands

The following critical operations support multisig proposals:

• register - Register new coordinators
• crunch create - Create new competitions
• crunch start - Start competitions
• crunch end - End competitions
• crunch deposit-reward - Deposit USDC rewards
• crunch drain - Drain remaining USDC

Usage Examples

Direct execution (current behavior):

crunch-coordinator crunch create "AI Competition" 1000 2

Multisig proposal mode:

crunch-coordinator --multisig 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM crunch create "AI Competition" 1000 2

Multisig Workflow

• Create Proposal: Use any multisig-compatible command with --multisig parameter
• Review Proposal: Navigate to the provided Squads dashboard URL
• Approve Proposal: Other multisig members approve the transaction
• Execute: Transaction can be executed when threshold is reached

Coordinator Management Commands

register

Register a new coordinator with the protocol.

Usage:

crunch-coordinator register <name>

Arguments:

• name - Unique name for the coordinator

Example:

crunch-coordinator register "AI Research Lab"

Description: Registers the wallet as a coordinator with the given name. The coordinator must later be approved by protocol admins before they can create competitions.

Requirements:

• Coordinator name must be unique
• Wallet must have sufficient SOL for account creation
• Name should be descriptive and professional

get

Get coordinator details by owner address.

Usage:

crunch-coordinator get [owner]

Arguments:

• owner - Owner address of the coordinator (optional, defaults to current wallet)

Examples:

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

# Get coordinator details for current wallet
crunch-coordinator get

Description: Retrieves detailed information about a coordinator including registration status and metadata.

get-config

Get coordinator configuration from the protocol.

Usage:

crunch-coordinator get-config

Example:

crunch-coordinator get-config

Description: Displays the current coordinator configuration including protocol parameters and settings.

Competition Management Commands

All competition management commands are grouped under the crunch subcommand:

crunch create

Create a new competition (crunch).

Usage:

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

Arguments:

• name - Name of the crunch
• payoutAmount - Payout amount in USDC (default: 10)
• maxModelsPerCruncher - Maximum models per cruncher (default: 2)

Example:

# Direct execution
crunch-coordinator crunch create "Q4 2024 Trading Challenge" 10000 5

# Multisig proposal
crunch-coordinator --multisig <multisig-address> crunch create "Q4 2024 Trading Challenge" 10000 5

Description: Creates a new competition with the specified parameters. The creator must be an approved coordinator.

Requirements:

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

crunch start

Start a competition.

Usage:

crunch-coordinator crunch start <crunchName>

Arguments:

• crunchName - Name of the crunch to start

Example:

crunch-coordinator crunch start "Q4 2024 Trading Challenge"

Description: Transitions a competition from created state to active state, allowing crunchers to register and submit models.

Requirements:

• Competition must be in created state
• Must be the coordinator who created the competition

crunch address

Get the account address for a competition.

Usage:

crunch-coordinator crunch address <crunchName>

Arguments:

• crunchName - Name of the crunch

Example:

crunch-coordinator crunch address "Q4 2024 Trading Challenge"

Description: Returns the Solana public key address of the specified competition account.

crunch get

Get detailed information about a competition.

Usage:

crunch-coordinator crunch get <name>

Arguments:

• name - Name of the crunch

Example:

crunch-coordinator crunch get "Q4 2024 Trading Challenge"

Description: Retrieves comprehensive information about a competition including its state, configuration, participants, and financial details.

crunch end

End a competition.

Usage:

crunch-coordinator crunch end <crunchName>

Arguments:

• crunchName - Name of the crunch to end

Example:

crunch-coordinator crunch end "Q4 2024 Trading Challenge"

Description: Transitions a competition to ended state, preventing new registrations and model submissions.

Requirements:

• Competition must be in active state
• Must be the coordinator who created the competition

Reward and Financial Management

crunch deposit-reward

Deposit reward USDC to a competition.

Usage:

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

Arguments:

• crunchName - Name of the crunch
• amount - Amount in USDC to deposit

Example:

crunch-coordinator crunch deposit-reward "Q4 2024 Trading Challenge" 5000

Description: Deposits USDC tokens to fund the reward pool for the specified competition.

Requirements:

• Must have sufficient USDC balance
• Competition must exist

crunch margin

Execute margin payout for a competition.

Usage:

crunch-coordinator crunch margin <crunchName>

Arguments:

• crunchName - Name of the crunch

Example:

crunch-coordinator crunch margin "Q4 2024 Trading Challenge"

Description: Processes margin-based payouts for competition participants based on their performance.

crunch drain

Drain USDC from a competition.

Usage:

crunch-coordinator crunch drain <crunchName> [--show-solscan]

Arguments:

• crunchName - Name of the crunch

Options:

• --show-solscan - Show Solscan links for transactions

Example:

crunch-coordinator crunch drain "Q4 2024 Trading Challenge" --show-solscan

Description: Withdraws remaining USDC from a competition's reward pool back to the coordinator.

Checkpoint Management

crunch checkpoint-create

Create a checkpoint for payout distribution.

Usage:

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

Arguments:

• crunchName - Name of the crunch
• prizeFileName - Path to prize JSON file containing payout distribution

Options:

• --dryrun - Perform a dry run without executing transactions

Example:

crunch-coordinator crunch checkpoint-create "Q4 2024 Trading Challenge" "./prizes.json"

Prize File Format:

{"timestamp": 1840417288969, "model": "model_1", "prize": 456.78}
{"timestamp": 1840417288969, "model": "model_2", "prize": 412.34}
{"timestamp": 1840417288969, "model": "model_3", "prize": 130.88}

Description: Creates a new checkpoint with specified prize distribution, enabling participants to claim their rewards.

crunch checkpoint-get-current

Get the current checkpoint information.

Usage:

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

Arguments:

• crunchName - Name of the crunch

Example:

crunch-coordinator crunch checkpoint-get-current "Q4 2024 Trading Challenge"

Description: Retrieves information about the current active checkpoint including total amount and distribution details.

crunch checkpoint-get-address

Get the address of a specific checkpoint.

Usage:

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

Arguments:

• crunchName - Name of the crunch
• checkpointIndex - Index of the checkpoint

Example:

crunch-coordinator crunch checkpoint-get-address "Q4 2024 Trading Challenge" 1

Description: Returns the Solana public key address of the specified checkpoint account.

Configuration

The CLI uses a configuration system for managing settings. Use the config commands to manage your configuration:

# Set configuration values
crunch-coordinator config set <key> <value>

# Show current configuration
crunch-coordinator config show

# Use a specific profile
crunch-coordinator config use-profile <profile>

Configuration Options

• network (string) - Solana network (localnet, devnet, mainnet)
• wallet (string) - Path to wallet keypair file
• loglevel (string) - Log level (debug, info, warn, error)

Default Configuration

{
  "network": "localnet",
  "wallet": "./accounts/coordinator.json",
  "loglevel": "info"
}

Command Reference Summary

Category	Command	Description
Coordinator Management	register	Register as a coordinator
	get	Get coordinator details
	get-config	Get coordinator configuration
Competition Lifecycle	crunch create	Create a new competition
	crunch start	Start a competition
	crunch address	Get competition address
	crunch get	Get competition details
	crunch end	End a competition
Financial Management	crunch deposit-reward	Deposit USDC rewards
	crunch margin	Execute margin payout
	crunch drain	Withdraw remaining USDC
Checkpoint Management	crunch checkpoint-create	Create reward checkpoint
	crunch checkpoint-get-current	Get current checkpoint
	crunch checkpoint-get-address	Get checkpoint address
Configuration	config	Configuration management

Competition Workflow

• Setup: Register as coordinator using register
• Create: Create competition using crunch create
• Fund: Deposit rewards using crunch deposit-reward
• Launch: Start competition using crunch start
• Monitor: Check status using crunch get
• Distribute: Create checkpoints using crunch checkpoint-create
• Complete: End competition using crunch end
• Cleanup: Drain remaining funds using crunch drain

Related Packages

• @crunchdao/cruncher-cli - Participant operations (cruncher registration, model submission, claiming rewards)
• @crunchdao/admin-cli - Administrative operations

Production Recommendations

Security Best Practices

• Multisig Required: For production deployments, always use multisig protection for critical operations:

  crunch-coordinator --multisig <multisig-address> crunch create "Production Competition" 50000 3
  

• Test First: Always test operations on devnet before executing on mainnet:

  crunch-coordinator --network devnet crunch create "Test Competition" 100 2
  

• Validate Parameters: Double-check competition parameters before creation, especially payout amounts

Operational Workflow

• Development: Test operations with direct execution on devnet
• Staging: Validate operations with multisig on devnet
• Production: Execute operations with multisig on mainnet

Example Production Commands

# Register coordinator via multisig
crunch-coordinator --multisig <multisig-address> register "Production Coordinator"

# Create competition via multisig
crunch-coordinator --multisig <multisig-address> crunch create "Monthly AI Challenge" 25000 5

# Start competition via multisig
crunch-coordinator --multisig <multisig-address> crunch start "Monthly AI Challenge"

Support

For issues and questions, please refer to the main repository documentation or create an issue in the project repository.