Skip to main content

Getting Started for Developers

Welcome to OpenMina development! This guide will help you set up your development environment and build OpenMina from source.

Prerequisites​

System Requirements​

  • Operating System: Officially supported platforms (build tested in CI):
    • Ubuntu 22.04 LTS
    • Ubuntu 24.04 LTS (x86_64 and ARM64)
    • macOS (latest)
    • Other Linux distributions may work but are not officially supported
    • Note: While we test compilation on all platforms, the full test suite is only run on ubuntu-22.04 (for GLIBC compatibility with container tests)
  • Memory: At least 8GB RAM (16GB recommended)
  • Storage: At least 20GB free space
  • Network: Stable internet connection for downloading dependencies

Required Tools​

1. Rust Toolchain​

OpenMina requires both stable and nightly Rust toolchains, plus additional tools for development:

# Install rustup (Rust toolchain installer)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# Source cargo environment
source ~/.cargo/env

# Install Rust 1.84 (as specified in rust-toolchain.toml)
rustup install 1.84
rustup default 1.84

# Install nightly toolchain (required for some components)
rustup install nightly

# Add required components for Rust 1.84
rustup component add rustfmt clippy --toolchain 1.84

# Add required components for nightly
rustup component add rustfmt clippy rust-src --toolchain nightly

# Install taplo (TOML formatter, required for `make format`)
cargo install taplo-cli --locked

This installs:

  • Rust 1.84 (stable) and nightly toolchains
  • Required components: rustfmt, clippy, rust-src
  • taplo-cli: TOML formatter required for make format

2. System Dependencies​

sudo apt update
sudo apt install -y \
    build-essential \
    libssl-dev \
    pkg-config \
    protobuf-compiler \
    sqlite3 \
    git \
    curl \
    shellcheck

3. Additional Development Tools​

Node.js (for documentation and frontend):

# Install Node.js (version 18+ recommended)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Docker (optional, for containerized builds):

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Clean up
rm get-docker.sh

4. WASM Tools (for web node development)​

# Install wasm-pack for WebAssembly builds
cargo install wasm-pack

# Install wasm-bindgen CLI tool for generating WebAssembly bindings
cargo install -f wasm-bindgen-cli --version 0.2.99

# Add WebAssembly target
rustup target add wasm32-unknown-unknown

Clone and Build OpenMina​

1. Clone the Repository and Build​

git clone https://github.com/o1-labs/openmina.git
cd openmina

# Download required circuits
echo "Downloading required circuits..."
make download-circuits

# Build in debug mode (faster compilation, slower runtime)
echo "Building OpenMina in debug mode..."
make build

2. Specialized Builds​

For more advanced builds including release mode, WebAssembly, and specialized components:

# Build in release mode (slower compilation, faster runtime)
echo "Building in release mode..."
make build-release

# Build ledger components (requires nightly Rust)
echo "Building ledger components..."
make build-ledger

# Build WebAssembly node for browser
echo "Building WebAssembly node..."
make build-wasm

# Build testing framework with scenario generators
echo "Building testing framework..."
make build-testing

# Build VRF (Verifiable Random Function) components
echo "Building VRF components..."
make build-vrf

3. Run Tests​

You can run a different set of tests. The command make help will give you the whole set of targets. You can also visit the file ci.yaml to explore the targets used for testing in our continuous integration environment.

Development Workflow​

Code Quality and Formatting​

OpenMina maintains strict code quality standards:

# Set up SQLite database for heartbeats processor (required for make check/lint)
echo "Setting up SQLite database for heartbeats processor..."
sqlite3 /tmp/heartbeats.db < tools/heartbeats-processor/schema.sql
export DATABASE_URL="sqlite:///tmp/heartbeats.db"

# Format code (required before commits)
echo "Formatting code..."
make format

# Check formatting
echo "Checking code formatting..."
make check-format

# Run linter (clippy)
echo "Running linter..."
make lint

# Fix trailing whitespaces (mandatory before commits)
echo "Fixing trailing whitespaces..."
make fix-trailing-whitespace

# Check for trailing whitespaces
echo "Checking for trailing whitespaces..."
make check-trailing-whitespace

Working with Makefiles​

The project's Makefile provides many helpful commands. View all available targets:

make help

Common development targets include:

# Basic builds
make build          # Debug build for development
make build-release  # Optimized build for production
make check          # Check code without building

# Testing
make test           # Run test suite
make test-release   # Run tests in release mode

# Code quality
make format         # Format all code
make lint           # Run static analysis
make clean          # Clean build artifacts

Environment Configuration​

Some components require environment variables and database setup:

SQLite Database (Required for make check)​

The heartbeats processor requires an SQLite database to be initialized before running make check:

# Create the SQLite database with required schema
sqlite3 /tmp/heartbeats.db < tools/heartbeats-processor/schema.sql

# Set the database URL environment variable
export DATABASE_URL="sqlite:///tmp/heartbeats.db"

Additional Environment Variables​

# For archive node development
export OPENMINA_ARCHIVE_ADDRESS="http://localhost:3007"
export PG_USER="openmina"
export PG_PW="openminaopenmina"
export PG_DB="openmina_archive"

Architecture Overview​

For detailed information about OpenMina's architecture, Redux-style state machine pattern, and component organization, please see the Architecture Documentation.

Running OpenMina​

Basic Node​

# Run a basic node (after building)
./target/release/openmina node --network devnet

Archive Node​

# Set up PostgreSQL database
make postgres-setup

# Run archive node
make run-archive

Development Server​

For web development with the frontend:

# Build and serve documentation
make docs-serve

# The documentation will be available at http://localhost:3000

Debugging and Development Tools​

Logging​

OpenMina uses structured logging with different levels:

# Set log level
export RUST_LOG=debug

# Run with verbose logging
RUST_LOG=trace ./target/release/openmina node --network devnet

Frontend Development​

The project includes a web-based dashboard:

# Build and run frontend (see frontend/README.md for details)
cd frontend
npm install
npm start

Testing Framework​

OpenMina includes a comprehensive testing framework:

# Build testing binary
make build-testing

# Run specific test scenarios
./target/release/openmina-node-testing --help

Next Steps​

  1. Explore the Codebase: Start with Architecture Documentation
  2. Run Tests: Ensure your setup works by running make test
  3. Join the Community: Connect with other developers on Discord and participate in discussions on the Mina Protocol Forums
  4. Read CLAUDE.md: Check the project-specific development guide in the root directory

Getting Help​

Welcome to the OpenMina development community! 🎉