Contributing

Development setup, test workflow, and contribution guidelines.

Prerequisites

Tool	Version	Purpose
Rust	Nightly 1.93+	Commonware requires nightly features
protoc	3.x+	`tonic-build` codegen
Bun	1.x+	Docs site (Vocs)

Install Rust nightly:

rustup install nightly
rustup default nightly

Install protoc:

# macOS
brew install protobuf
 
# Ubuntu / Debian
sudo apt install protobuf-compiler

Repository structure

Path	Description
src/	Rust library crate — state, consensus, API, validation, message modules
src/bin/node.rs	Full validator node binary
src/bin/cli.rs	CLI client for interacting with a node
proto/makechain.proto	Protobuf service and message definitions
tests/	Integration and unit test suites
docs/	Vocs documentation site
protocol/	Protocol specification (SPECIFICATION.md)

Build and test

Build

cargo build          # Build library + node binary (runs tonic codegen via build.rs)
cargo run --bin node # Start node: gRPC :50051, p2p :50052, Simplex consensus
cargo run --bin cli  # CLI client

Run tests

cargo test           # Run all 520 tests
cargo test <name>    # Run a single test by name

Test distribution

File	Tests	Coverage
tests/state_test.rs	107	State transitions, authorization, 2P semantics, CAS, LWW, archive, fork, storage limits
tests/integration_test.rs	100	End-to-end gRPC submit, mempool, propose, commit, query, streaming, multi-account
tests/validation_test.rs	76	Structural validation for every message type
tests/api_test.rs	53	API query layer: get/list for all resources, pagination, verifications
tests/message_test.rs	10	Signing and verification round-trips
Unit tests (inline)	174	State, consensus, and API module internals

Conventions

TDD workflow

Write tests first, then implement.

Error assertions

Use matches!() for asserting error variants in tests:

let result = apply_message(&mut store, &msg);
assert!(matches!(result, Err(StateError::ProjectNotFound(_))));

Proto changes

When adding new message types or RPCs:

Modify proto/makechain.proto
Run cargo build — Rust types appear automatically via tonic-build
Add structural validation in src/validation.rs
Add state handlers in src/state/handlers/
Add API query functions in src/api/query.rs if needed
Write tests covering the new type

Code style

Rust edition 2024, nightly toolchain
All hash fields are 32 bytes, all signatures are 64 bytes
Proto enum variants use SCREAMING_SNAKE_CASE with a type prefix
State keys use prefix-byte namespacing (see src/state/keys.rs)

Pull requests

Create a feature branch from main
Write tests for your changes
Run cargo test and ensure all 520 tests pass
Run cargo build to verify compilation
Open a pull request with a clear description of the change

Docs contribution

The documentation site uses Vocs with Bun:

cd docs
bun install          # Install dependencies (first time)
bun run dev          # Dev server at http://localhost:5173
bun run build        # Build static site to docs/dist/

Pages are MDX files in docs/pages/. Follow the writing guide for conventions. Deployed to Cloudflare Pages via docs/wrangler.toml.