Binary Reference

This document lists and explains each binary target defined in Cargo.toml, including purpose, usage, options, configuration, and troubleshooting tips.

General tips:

Build & run: cargo run --release --bin <name> [-- <args>]
Discover binaries: check Cargo.toml [[bin]] entries or use shell completion with cargo run --bin <TAB>
Features: Off-chain binaries require the off-chain feature (enabled by default). On-chain binaries or special tools may require --features on-chain.
Configuration: Most binaries read from config/*.{toml,yaml,json} and environment variables with MEV_ prefix via Settings::load() in src/shared/config.rs.

Config overview (see src/shared/config.rs):

Providers: providers.jupiter|orca|meteora.{enabled,base_url,rate_limit_per_second,...}
Arbitrage: arbitrage.{min_profit_threshold,max_slippage_percent,scan_interval_ms,tokens,token_pairs,...}
RPC: rpc.{primary_url,fallback_urls,timeout_ms,max_retries,commitment,websocket_endpoint}
Transaction: transaction.{keypair_path,keypair_env_var,priority_fee_lamports,compute_unit_limit,confirmation_timeout_ms,max_retries}
Safety: safety.{trading_enabled,enable_dry_run,max_position_size_sol, ...}
Monitoring: monitoring.{enable_prometheus,metrics_port,log_level,log_format}

Default keypair env var is SOLANA_KEYPAIR (see TransactionConfig::default()), and all config keys are overridable via env with the MEV_ prefix (e.g., MEV_RPC__PRIMARY_URL).

mev-arbitrage-engine

Path: src/bin/mev_arbitrage_engine.rs
Purpose: Run the off-chain MEV arbitrage engine loop against enabled DEX providers, submit transactions, and expose Prometheus metrics.

Usage:

cargo run --release --bin mev-arbitrage-engine

Command-line options:

None. All behavior is controlled via configuration and env vars.

Configuration requirements:

Uses Settings::load() to load from config/default.*, environment-specific files, and MEV_ env vars.
Ensure at least one provider is enabled: providers.{jupiter,orca,meteora}.enabled = true.
RPC: rpc.primary_url must be reachable.
Safety: safety.trading_enabled and safety.enable_dry_run gate execution.
Monitoring: set monitoring.enable_prometheus = true and monitoring.metrics_port to expose metrics via start_metrics_server().

Troubleshooting:

"No providers enabled": Set one of providers.*.enabled = true.
RPC errors: Verify rpc.primary_url, fallback_urls, network connectivity, and rpc.timeout_ms.
Transaction submit failed: Check wallet balance, priority_fee_lamports, compute_unit_limit, and network congestion.
Immediate shutdown: Fatal errors (config, keypair, insufficient funds) trigger shutdown; check logs.

arbitrage-cli

Path: src/bin/arbitrage_cli.rs
Purpose: Lightweight CLI for one-shot arbitrage search and optional execution. Suitable for scripting and quick experiments.

Usage:

cargo run --release --bin arbitrage-cli -- \
  --wallet ~/.config/solana/id.json \
  --rpc-endpoint https://api.mainnet-beta.solana.com \
  --token-pairs SOL:USDC,SOL:USDT \
  --min-profit 0.001 \
  --max-slippage 1.0 \
  --timeout 30 \
  --max-opportunities 10 \
  --output-format pretty

Command-line options (see parse_args()):

--wallet, -w <KEYPAIR>: Required. Path to keypair file or base58 string.
--rpc-endpoint, -r <URL>: Solana RPC endpoint. Default: https://api.mainnet-beta.solana.com.
--token-pairs, -t <PAIRS>: Comma-separated pairs TOKEN1:TOKEN2[,...]. Default: SOL:USDC.
--min-profit, -p <PERCENTAGE>: Decimal percent threshold (e.g., 0.001 for 0.1%). Default: 0.001.
--max-slippage, -s <PERCENT>: Maximum allowed slippage. Default: 1.0.
--timeout <SECONDS>: Operation timeout. Default: 30.
--dry-run: Analyze without submitting transactions.
--output-format, -o <json|pretty>: Output format. Default: json.
--max-opportunities <COUNT>: Limit opportunities analyzed. Default: 10.

Configuration requirements:

Does not require config files. Providers use defaults; RPC and wallet come from CLI.
Wallet can be a file path (JSON) or base58 secret key string. Public key is derived and validated at runtime.

Troubleshooting:

Wallet loading failed: Ensure file path exists and is a valid Solana keypair, or base58 string is correct.
RPC health check failed: Verify endpoint URL and network; try a different RPC.
No opportunities found: Adjust --min-profit, --max-slippage, or token pairs.

mainnet-mev-system

Path: src/bin/mainnet_mev_system.rs
Purpose: Authentic mainnet MEV detection system with modes for detection-only, observability validation, or full run.

Usage:

cargo run --release --bin mainnet-mev-system -- \
  --mode detection \
  --min-profit 0.001 \
  --max-tps 100

# Enable real execution (DANGER: uses real SOL)
cargo run --release --bin mainnet-mev-system -- --mode full --enable-execution

Command-line options:

--mode <detection|observability|full>: Operation mode. Default: detection.
--enable-execution: Enable real transaction execution (safety countdown shown).
--min-profit <SOL>: Minimum profit in SOL. Default: 0.001.
--max-tps <TPS>: Max transactions per second processed. Default: 100.

Configuration requirements:

Uses Settings::default() internally; external config files are not required for this binary.

Troubleshooting:

Invalid mode: Use one of detection, observability, full.
Long startup: Real execution includes a safety countdown; wait or cancel with Ctrl+C.

production-mev-system

Path: src/bin/production_mev_system.rs
Purpose: Full production orchestrator with safety checks, observability, and graceful shutdown.

Usage:

# Safe (no real execution)
cargo run --release --bin production-mev-system

# Real execution
ENABLE_REAL_EXECUTION=true \
cargo run --release --bin production-mev-system

Command-line options:

None. Behavior is driven by configuration and env.

Environment & configuration:

Loads Settings::load() (config files + MEV_ envs).
Real execution is gated by ENABLE_REAL_EXECUTION=true env var.
Observability initialized via ObservabilityConfig::default().

Troubleshooting:

Init failed: Check config validity with config-test and verify RPC and provider URLs.
Real execution disabled: Set ENABLE_REAL_EXECUTION=true and confirm wallet funding and safety settings.

generate-openapi

This binary has been removed. Use generate_frontend_clients or the Makefile targets instead.

generate-frontend-clients

Path: src/bin/generate_frontend_clients.rs
Purpose: Generate OpenAPI specs into docs/api/ and optionally create frontend API clients using scripts/generate-frontend-clients.sh.

Usage:

# Write only the OpenAPI specs (no client generation)
cargo run --release --bin generate_frontend_clients -- --write-spec-only

# Or use the Makefile target
make openapi-spec

# Generate clients (requires openapi-generator or npx setup)
make clients-generate

Outputs:

docs/api/openapi.json
docs/api/openapi.yaml

Troubleshooting:

Client generation tool missing: Ensure openapi-generator is installed or available via npx.
Cannot write files: Ensure docs/ directory exists and is writable.

config-test

Path: src/bin/config_test.rs
Purpose: Validate loading and schema of a specific config file using Settings::load_from_file().

Usage:

cargo run --release --bin config-test -- ./config/development.yaml

Arguments:

<config_file>: Required. Path to a TOML/YAML/JSON configuration file.

Troubleshooting:

Validation failed: The tool prints detailed errors; fix URLs, numeric ranges, or provider settings.
File not found: Provide a correct path; relative to repo root or absolute.

test-yaml-config

Path: src/bin/test_yaml_config.rs
Purpose: Sanity-check YAML parsing into Settings and validate basic fields.

Usage:

cargo run --release --bin test-yaml-config

Behavior:

Reads test_config.yaml from current working directory.
Parses into Settings, validates, and performs a round-trip YAML serialization test.

Troubleshooting:

Missing file: Ensure test_config.yaml exists in the CWD.

simple-yaml-test

Path: src/bin/simple_yaml_test.rs
Purpose: Minimal serde_yaml round-trip example to verify YAML support.

Usage:

cargo run --release --bin simple-yaml-test

Troubleshooting:

None expected; prints serialized YAML and verifies round-trip integrity.

eidolon-mev-program

Path: src/bin/eidolon_mev_program.rs
Purpose: On-chain Anchor-based MEV program shell for deployment/tests.

Usage:

# Build/run with on-chain features
cargo run --release --features on-chain --bin eidolon-mev-program

Notes:

Without --features on-chain, the program prints a notice and exits.
When enabled, Anchor declare_id! and program entrypoints are compiled.

Feature flags summary

off-chain: Required for most runtime binaries. Enabled by default via features.default in Cargo.toml.
on-chain: Required only for on-chain program binaries.

Environment variables

MEV_*: Override any config key (e.g., MEV_RPC__PRIMARY_URL=https://...).
SOLANA_KEYPAIR: Default keypair env used by transaction signing (if transaction.keypair_path is not set).
ENABLE_REAL_EXECUTION: Enables real execution in production-mev-system.

Common troubleshooting

Provider URL invalid: Fix providers.*.base_url or disable the provider.
Metrics not exposed: Set monitoring.enable_prometheus=true and choose an open monitoring.metrics_port.
Permission denied writing docs: Run make openapi-spec from repo root or adjust file permissions.

PRISM MEV Platform