Skip to content

Latest commit

 

History

History
194 lines (131 loc) · 5.19 KB

CONTRIBUTING_CODE.md

File metadata and controls

194 lines (131 loc) · 5.19 KB

Contributing to Malachite

Thank you for your interest in contributing to Malachite, a Byzantine Fault Tolerant (BFT) consensus engine written in Rust.

This document provides guidelines and instructions to help you set up your development environment and contribute to the project.

Table of Contents

Setup

Prerequisites

To build and test Malachite, you need the following tools:

  • Rust: Install the latest stable Rust toolchain using rustup
  • Protocol Buffers Compiler (protoc): Required for Protobuf message serialization
  • Node.js: Required for running Quint
  • Quint: A formal specification language used for our model-based tests
  • cargo-nextest: An improved test runner for Rust

Environment Setup

  1. Install Rust:

    Via rustup.rs:

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

  2. Install the Protocol Buffers Compiler:

    protoc is needed for compiling Protobuf definitions used in the test applications to Rust code.

    For Ubuntu/Debian:

    sudo apt-get install protobuf-compiler

    For macOS:

    brew install protobuf

    Please ensure that the version of protoc is at least v29.0.

  3. Install Node.js: (only required for running model-based tests)

    Follow the instructions at nodejs.org or use a version manager:

    # Using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 21
nvm use 21

  4. Install Quint: (only required for running model-based tests)

    npm install -g @informalsystems/quint

  5. Install cargo-nextest:

    cargo install cargo-nextest

  6. Fork and clone the repository:

    git clone https://github.com/USERNAME/malachite.git
cd malachite/code

Note

If you do not intend to contribute code and just want to play around with the codebase, you can just clone the repository directly: git clone https://github.com/informalsystems/malachite.git

Building the Project

To build the project, run:

cargo build

Running Tests

We have several categories of tests that help ensure the quality and correctness of our code.

Unit and Integration Tests

cargo all-tests

Or run specific integration tests:

  1. Discovery:

    cargo nextest run -p informalsystems-malachitebft-discovery-test

  2. Starknet app:

    cargo nextest run -p informalsystems-malachitebft-starknet-test

  3. Test app:

    cargo nextest run -p informalsystems-malachitebft-test

Important

For the integration tests to run successfully it is important to ensure that only one integration test is running at a time, by supplying the --test-threads=1 flag to cargo-nextest. This is done automatically via the code/.config/nextest.toml configuration file, but can be overridden from the command line if needed.

Tip

If you are on a Linux-based system, you can use cargo-maelstrom to run each test in isolation, concurrently.

cargo install cargo-maelstrom
cargo maelstrom --slots 16

Model-Based Tests (MBT)

Model-based tests use formal specifications to generate test scenarios and validate system behavior against them.

To run model-based tests:

cargo mbt

Code Style and Guidelines

We follow Rust's official style guidelines. Before submitting your code, please ensure:

  1. Format your code using rustfmt:

    cargo fmt

  2. Run Clippy to catch common mistakes and ensure code quality:

    cargo lint

Pull Request Process

  1. Fork the repository and create your branch from main.
  2. Make your changes and ensure all tests pass.
  3. Update documentation as needed.
  4. Submit a pull request with a clear description of the changes and any relevant issue numbers.
  5. Address any feedback from code reviewers.

When submitting a PR, our CI will automatically run all tests, Clippy checks, and formatting verification.

Continuous Integration

We use GitHub Actions for continuous integration. The following checks run on every PR:

  • Unit Tests: Ensures individual components work correctly.
  • Integration Tests: Validates component interactions.
  • Model-Based Tests: Checks against formal specifications.
  • Clippy: Catches common Rust mistakes and enforces best practices.
  • Formatting: Ensures consistent code style with rustfmt.

Thank you for contributing to Malachite! If you have any questions, feel free to open an issue or ask the maintainers.