Skip to main content

​
Installation Guide

Minichain is written entirely in Rust and requires Rust 1.70 or later. This guide will walk you through installing Rust and building Minichain from source.

​
Prerequisites

​
Install Rust

Minichain requires Rust 1.70+. If you don’t have Rust installed, use rustup: 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
After installation, verify Rust is installed: 
rustc --version
You should see output like: 
rustc 1.70.0 (or later)
If rustc is not found, restart your terminal or run:
source $HOME/.cargo/env

​
System Requirements

Minichain has minimal system requirements:
  • OS: Linux, macOS, or Windows
  • RAM: 512MB minimum
  • Disk: 50MB for the binary + space for blockchain data
  • CPU: Any modern processor

​
Build from Source

1

Clone the Repository

Clone the Minichain repository from GitHub:
git clone https://github.com/jayendra-info/minichain.git
cd minichain
Replace the repository URL with your fork if you’re contributing to Minichain.
2

Build the Project

Build the project in release mode for optimal performance:
cargo build --release
This will:
  • Download and compile all dependencies
  • Compile all 7 crates in the workspace
  • Create an optimized binary
  • Take 2-5 minutes depending on your system
You’ll see output like:
   Compiling minichain-core v0.1.0
   Compiling minichain-storage v0.1.0
   Compiling minichain-vm v0.1.0
   Compiling minichain-assembler v0.1.0
   Compiling minichain-consensus v0.1.0
   Compiling minichain-chain v0.1.0
   Compiling minichain-cli v0.1.0
    Finished release [optimized] target(s)
3

Locate the Binary

The compiled binary is located at:
target/release/minichain
You can run it directly:
./target/release/minichain --help
Or use cargo run:
cargo run --release -- --help
4

Install Globally (Optional)

To install the binary to your system PATH:
cargo install --path crates/cli
This installs minichain to ~/.cargo/bin/, which should be in your PATH.Now you can run:
minichain --help
from any directory.

​
Verify Installation

Test that Minichain is working correctly: 
# Using the binary directly
./target/release/minichain --version

# Or with cargo run
cargo run --release -- --version

# Or if installed globally
minichain --version
You should see: 
minichain 0.1.0
View available commands: 
minichain --help
Output: 
A minimal toy blockchain implementation in Rust

Usage: minichain <COMMAND>

Commands:
  init     Initialize a new blockchain
  account  Account management
  tx       Transaction operations
  deploy   Deploy a smart contract
  call     Call a smart contract
  block    Block operations
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

​
Development Setup

If you plan to contribute or modify Minichain, here are useful development tools:

​
Run Tests

Minichain includes 26+ unit and integration tests: 
# Run all tests across all crates
cargo test --all
All tests should pass: 
running 26 tests
test tests::test_hash ... ok
test tests::test_keypair ... ok
test tests::test_vm_add ... ok
...
test result: ok. 26 passed; 0 failed

​
Code Quality Tools

# Check if code compiles without building
cargo check

​
Watch Mode

Install cargo-watch for automatic rebuilds: 
cargo install cargo-watch

# Auto-rebuild on file changes
cargo watch -x build

# Auto-test on file changes
cargo watch -x test

​
Project Structure

Once built, your workspace contains: 
minichain/
├── Cargo.toml                 # Workspace configuration
├── Cargo.lock                 # Dependency lock file
├── target/                    # Build artifacts
│   └── release/
│       └── minichain          # Compiled binary
├── crates/                    # Source code
│   ├── core/                  # Blockchain primitives
│   ├── storage/               # Persistent storage
│   ├── vm/                    # Virtual machine
│   ├── assembler/             # Assembly compiler
│   ├── consensus/             # PoA consensus
│   ├── chain/                 # Blockchain orchestration
│   └── cli/                   # Command-line interface
├── contracts/                 # Example contracts
│   ├── counter.asm
│   ├── storage_test.asm
│   └── token.asm
├── tests/                     # Integration tests
└── docs/                      # Documentation

​
Workspace Dependencies

Minichain uses the following key dependencies:

​
Cryptography

  • blake3 (1.5): Fast hashing for blocks and transactions
  • ed25519-dalek (2.1): Digital signatures for transaction signing
  • rand (0.8): Cryptographic randomness for key generation

​
Storage

  • sled (0.34): Embedded database for persistent blockchain state

​
Serialization

  • serde (1.0): Serialization framework
  • serde_json (1.0): JSON serialization for configuration
  • bincode (1.3): Binary serialization for blockchain data

​
CLI

  • clap (4.4): Command-line argument parsing
  • colored (2.1): Terminal color output

​
Utilities

  • thiserror (1.0): Error handling
  • anyhow (1.0): Error context
  • hex (0.4): Hexadecimal encoding/decoding
  • chrono (0.4): Timestamp handling

​
Assembler

  • logos (0.14): Lexer generator for assembly language

​
Logging

  • tracing (0.1): Structured logging
  • tracing-subscriber (0.3): Log output formatting
All dependencies are managed in Cargo.toml and automatically downloaded during build.

​
Troubleshooting

​
Compilation Errors

Issue: error: linker 'cc' not found 
sudo apt-get install build-essential

​
Outdated Rust Version

Issue: error: package requires rustc 1.70 or newer 
rustup update stable

​
Cargo Command Not Found

Issue: bash: cargo: command not found Restart your terminal or manually add to PATH: 
source $HOME/.cargo/env

​
Build Takes Too Long

Issue: First build is slow (5+ minutes) This is normal! Subsequent builds are much faster due to caching. Use cargo build (without --release) for faster debug builds during development.

​
Disk Space Issues

Issue: error: no space left on device Clean old build artifacts: 
cargo clean

​
Next Steps

Now that Minichain is installed:
  1. Run the Quickstart: Follow the Quickstart Guide to initialize your first blockchain
  2. Learn the Basics: Read Core Concepts to understand the architecture
  3. Write Contracts: Study the Assembly Language guide

Quickstart

Get your blockchain running in 5 minutes

Core Concepts

Learn about accounts, transactions, and blocks
Minichain is for educational purposes only. Do not use in production environments.

Build docs developers (and LLMs) love

Get started for freeTalk to us