Skip to content

DEVELOPER.md

Latest commit

 

History

History
304 lines (223 loc) · 7.39 KB

DEVELOPER.md

File metadata and controls

304 lines (223 loc) · 7.39 KB
Raw

Developer Guide

Native development setup for the Rust workspace.

This repository is built with Cargo, Docker, and system packages only.

The formal-verification gates need more tools. See Formal Verification Tooling in the repository README for the Java runtime, the pinned TLC jar, opam, and the Rocq prover.

Required Tooling

macOS

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

brew install protobuf openssl pkg-config lmdb just grpcurl ruby jq

Optional:

cargo install cross

Ubuntu Or Debian

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

sudo apt-get update
sudo apt-get install -y \
  protobuf-compiler \
  libprotobuf-dev \
  pkg-config \
  libssl-dev \
  liblmdb-dev \
  build-essential \
  gcc \
  ruby \
  jq

cargo install just

Optional:

cargo install cross

Fedora Or RHEL

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

sudo dnf install -y \
  protobuf-compiler \
  protobuf-devel \
  pkg-config \
  openssl-devel \
  lmdb-devel \
  gcc \
  ruby \
  jq

cargo install just

Git Hooks

Install nextest and the hooks after cloning:

cargo install cargo-nextest --locked
./scripts/setup-hooks.sh

This sets core.hooksPath to .githooks/, which provides:

Hook Runs Checks
pre-commit On every commit cargo fmt --check, cargo clippy -D warnings
pre-push On every push CI script tests, cargo clippy, cargo nextest run --release

Both hooks skip automatically in CI environments. The pre-push hook gives Casper tests 1800 seconds and gives other commands 600 seconds.

The pre-push hook uses nextest by default and prints each crate duration. This initial experiment excludes doctests.

Hook Options

# Commit with skips
SKIP_FMT=1 git commit -m "wip"
SKIP_CLIPPY=1 git commit -m "wip"

# Push with skips
QUICK=1 git push                           # Debug-mode tests (faster compile)
SKIP_TESTS=1 git push                      # Skip Rust tests
SKIP_CI_TESTS=1 git push                   # Skip CI script tests
TEST_CRATES="casper rholang" git push      # Test specific crates only
TEST_RUNNER=cargo git push                 # Use cargo test for A/B comparison
TEST_TIMEOUT=900 git push                  # Adjust the general timeout
CASPER_TEST_TIMEOUT=2400 git push          # Adjust the Casper timeout

# Bypass entirely (not recommended)
git commit --no-verify
git push --no-verify

Hook Management

./scripts/setup-hooks.sh --status   # Show current configuration
./scripts/setup-hooks.sh --copy     # Alternative: copy to .git/hooks/
./scripts/setup-hooks.sh --remove   # Remove hooks

Toolchain

The workspace is pinned in rust-toolchain.toml:

rustup toolchain install nightly-2026-02-09
rustup show

Environment Notes

If the build cannot find protoc or OpenSSL:

export PROTOC=$(which protoc)
export OPENSSL_INCLUDE_DIR=$(brew --prefix openssl)/include
export OPENSSL_LIB_DIR=$(brew --prefix openssl)/lib

The workspace already sets:

  • RUST_MIN_STACK=8388608 in .cargo/config.toml
  • -C target-cpu=native for local builds

If you are cross-compiling, review .cargo/config.toml and Cross.toml before reusing those defaults.

Common Workflows

Build

cargo build
cargo build --release
cargo build -p node
just build
just build-debug

Format And Lint

cargo fmt --all
cargo clippy --workspace --all-targets

Test

cargo nextest run
cargo nextest run --release
cargo test
cargo test --release
cargo test -p casper
cargo test -p rholang
./scripts/run_rust_tests.sh

# Unit-test line coverage (requires cargo-llvm-cov, nextest, llvm-tools-preview)
# Src-shipped test scaffolding (test_utils dirs, block-storage/src/rust/test)
# is excluded from the measured denominator; see scripts/coverage.sh.
just coverage            # enforce 80% for every crate and the workspace
just coverage casper     # enforce 80% for one crate

Run A Standalone Node (without Docker)

Requires just — a command runner installed with the tooling above.

just run-standalone           # Build release binary + run standalone node
just run-standalone-debug     # Debug build (faster compile, slower runtime)
just clean-standalone         # Reset node data to genesis
just help                     # Show node CLI help
just run-help                 # Show `run` subcommand options

The node listens on ports 40400-40405 (protocol, gRPC external/internal, HTTP API, discovery, admin). Configuration and genesis data live in run-local/.

Without just:

mkdir -p run-local/data/standalone/genesis
cp run-local/genesis/standalone/bonds.txt run-local/data/standalone/genesis/
cp run-local/genesis/standalone/wallets.txt run-local/data/standalone/genesis/

cargo run --release -p node -- run -s \
  --config-file=run-local/conf/standalone.conf \
  --validator-private-key=5f668a7ee96d944a4494cc947e4005e172d7ab3461ee5538f1f2a45a835e9657 \
  --host=localhost \
  --no-upnp

Build And Run Docker Images

# Build a local image
./node/docker-commands.sh build-local

# Standalone (single node, instant finalization)
docker compose -f docker/standalone.yml up

# Multi-validator shard (bootstrap + 3 validators + observer + monitoring)
docker compose -f docker/shard.yml up

# Use a locally built image instead of the published one
F1R3FLY_IMAGE=f1r3fly-rust:local docker compose -f docker/standalone.yml up

# Reset to genesis
docker compose -f docker/standalone.yml down -v

See docker/README.md for the full port map, validator setup, and monitoring.

Workspace Layout

f1r3node-rust/
├── Cargo.toml
├── rust-toolchain.toml
├── rustfmt.toml
├── .cargo/config.toml
├── .githooks/          # pre-commit (fmt+clippy), pre-push (tests)
├── Justfile
├── node/
├── casper/
├── comm/
├── crypto/
├── models/
├── rholang/
├── rspace++/
├── block-storage/
├── shared/
├── graphz/
├── docker/
├── run-local/
├── scripts/
└── docs/

Generated Artifacts

  • node/build.rs generates bindings for repl.proto and lsp.proto
  • models/build.rs generates bindings for the core protocol and API schemas
  • comm/build.rs generates the Kademlia RPC bindings

The generated code is rebuilt automatically when the corresponding .proto files change.

Troubleshooting

protoc Not Found

which protoc
export PROTOC=$(which protoc)

OpenSSL Not Found On macOS

export OPENSSL_INCLUDE_DIR=$(brew --prefix openssl)/include
export OPENSSL_LIB_DIR=$(brew --prefix openssl)/lib

Stack Overflow In Debug Tests

The workspace already raises stack size for test threads. If a specific test still overflows:

RUST_MIN_STACK=16777216 cargo test -p rholang

LMDB Lock Or Leftover Test Data

find . -name "*.mdb" -delete

Slow Full Workspace Rebuilds

Build or test a smaller target first:

cargo build -p node
cargo test -p casper