Contributing

Development setup, test workflow, and contribution guidelines.

Prerequisites

Tool	Version	Purpose
Rust	Stable 1.95+	Workspace toolchain
protoc	3.x+	`tonic-build` codegen
Bun	1.x+	Docs site (Vocs)

Install the pinned Rust toolchain:

rustup toolchain install 1.95.0

Install protoc:

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

Repository structure

Path	Description
crates/	Rust workspace crates (proto, crypto, state, consensus, api, sync, client)
src/bin/node.rs	Full validator node binary
src/bin/cli.rs	CLI client for interacting with a node
src/bin/tui/	Interactive terminal UI (dashboard, submit, wallet)
src/bin/indexer.rs	gRPC chain indexer writing to Postgres (feature: `indexer`)
src/bin/event_processor.rs	Event-driven query table builder consuming Redis streams (feature: `event-processor`)
proto/makechain.proto	Protobuf service and message definitions
tests/	Integration and unit test suites
apps/docs/	Vocs documentation site
contracts/	Foundry project for the `StorageRelay` settlement contract and deployment artifacts
protocol/	Protocol specification git submodule (officialunofficial/protocol)

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
cargo run --bin tui  # Interactive terminal UI (--dev for embedded devnet)
 
# Feature-gated binaries (require Postgres / Redis)
cargo build --bin indexer --features indexer           # Chain indexer
cargo build --bin event-processor --features event-processor # Query table event processor

Run tests

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

Test distribution

File	Tests	Coverage
crates/makechain-state/tests/state_test.rs	226	State transitions, authorization, 2P semantics, CAS, LWW, archive, fork, storage limits
tests/integration_test.rs	219	End-to-end gRPC submit, mempool, propose, commit, query, streaming, multi-account
tests/consensus_e2e_test.rs	19	In-process multi-validator proposer/verifier harness
tests/conformance_test.rs	20	Commonware-conformance encoding stability tests
crates/makechain-state/tests/validation_test.rs	181	Structural validation for every message type
crates/makechain-api/tests/api_test.rs	86	API query layer: get/list for all resources, pagination, verifications, links, reactions
crates/makechain-crypto/tests/message_test.rs	47	Signing and verification round-trips, envelope validation
tests/event_processor_test.rs	17	Event processor logic, event routing, idempotent semantics (feature: `event-processor`)
Unit tests (inline)	~1000	State, consensus, sync, API, client, and node binary 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 crates/makechain-state/src/validation.rs
Add state handlers in crates/makechain-state/src/handlers/
Add API query functions in crates/makechain-api/src/query.rs if needed
Write tests covering the new type

Code style

Rust edition 2024, stable toolchain 1.95+
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 crates/makechain-state/src/keys.rs)

Pull requests

Create a feature branch from main
Write tests for your changes
Run cargo test and ensure all 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 apps/docs
bun install          # Install dependencies (first time)
bun run dev          # Dev server at http://localhost:5173
bun run build        # Build static site to apps/docs/dist/

Pages are MDX files in apps/docs/src/pages/. Follow the writing guide for conventions. Deployed to Cloudflare Pages.

Edit this page on GitHub