A decentralized blockchain system built in Rust featuring Merkle-Patricia Tries (MPT) for efficient data storage and cryptographic proofs for data verification. Currently under active development with comprehensive testing and clean architecture.

• Immutable Data Storage: Cryptographic hashing ensures data cannot be modified
• Proof-of-Work Consensus: Adjustable difficulty mining system
• Hash-Linked Blocks: Each block references the previous block's hash
• Merkle-Patricia Trie Storage: Efficient key-value data storage with O(log n) operations
• Cryptographic Proofs: Merkle proofs for data existence and integrity verification
• SQLite Storage Backend: Production-ready persistent storage with atomic transactions

• MPT-Based Storage: Compact, cryptographically verifiable key-value storage
• Custom MPT Serialization: Efficient storage and retrieval of blockchain data
• Merkle Proof Generation: Generate proofs for any data stored in blocks
• Proof Verification: Verify data integrity without downloading entire blockchain
• Efficient Queries: Fast key lookups and range queries
• Data Integrity: Cryptographic guarantees of data authenticity
• Atomic Transactions: Data consistency with automatic rollback on failure

• Decentralized Architecture: Multiple independent nodes maintain blockchain replicas
• Fault Tolerance: Network continues operating if individual nodes fail
• Longest-Chain Consensus: Automatic conflict resolution using longest valid chain
• libp2p P2P Communication: Proper peer-to-peer networking with protocol multiplexing
• Automatic Peer Discovery: mDNS local discovery and DHT-based global discovery
• Network Isolation: Different projects cannot accidentally connect (network ID validation)
• Secure Communication: Noise protocol encryption and identity validation
• Block Propagation: Gossipsub protocol for efficient block broadcasting

• Comprehensive Test Suite: 60+ unit tests covering all components
• Property-Based Testing: Random input validation for robustness
• Clean Code Architecture: Modular design following SOLID principles
• Type Safety: Full Rust type system utilization
• Error Handling: Comprehensive error types and propagation

# vcbc is not published to crates.io - build from source

git clone https://github.com/vestcodes/vcbc.git
cd vcbc
cargo build --release

# Build Docker image
make docker-build

# Or build manually
docker build -t vcbc:latest .

# Run with help
docker run vcbc:latest

# Initialize and start a demo network
docker run vcbc:latest init-chain --network-id demo-net
docker run -v $(pwd)/config:/app/config vcbc:latest start-bootnode --config /app/config.json

# Clone the repository
git clone https://github.com/vestcodes/vcbc.git
cd vcbc

# Quick development setup (installs all required tools)
make setup

# Run full development workflow
make dev

# Or manually:
cargo test
cargo build --release
cargo doc --open

# Development workflow
make dev              # Format, lint, and test
make all              # Full quality check (check + test + clippy + fmt)
make quick            # Fast check (compile + test)

# VCBC blockchain operations
make init-chain       # Initialize new blockchain
make init-authority   # Create network authority
make register-bootnode # Register bootnode with certificate
make start-bootnode   # Start certified bootnode
make start-node       # Start regular node
make demo-network     # Setup complete demo network

# Docker operations
make docker-build     # Build Docker image
make docker-run       # Run in Docker container
make docker-clean     # Clean Docker images

# Quality assurance
make audit            # Security audit dependencies
make coverage         # Generate coverage report
make bench            # Run benchmarks

# Utilities
make lines            # Count lines of code
make tree             # Show project structure
make help             # Show all available targets

# Initialize a new blockchain with custom network ID
cargo run -- init-chain --network-id my-project-net --chain-id 42

# Create network authority for secure bootnode certification
cargo run -- init-authority --name my-project-authority --output authority.json

# Register and certify your bootnode
cargo run -- register-bootnode --node-id primary-bootnode --authority authority.json --config config.json

# Start the certified bootnode
cargo run -- start-bootnode --config config.json

# Initialize regular node pointing to bootnode
cargo run -- init-node --bootstrap-url http://bootnode-host:8080

# Start the regular node
cargo run -- start-node --config config.json

# Initialize a new blockchain network
cargo run -- init-chain --network-id vc-mainnet --chain-id 1 --http-port 8080 --p2p-port 9090

# Initialize a node for an existing blockchain
cargo run -- init-node --bootstrap-url http://bootnode:8080 --http-port 8081 --p2p-port 9091

# Initialize a network authority for bootnode certificates
cargo run -- init-authority --name vc-mainnet-authority --output authority.json

# Register and certify a bootnode
cargo run -- register-bootnode --node-id bootnode-01 --authority authority.json --config config.json

# Start a certified bootnode
cargo run -- start-bootnode --config config.json

# Start a regular node
cargo run -- start-node --config config.json

Configuration Commands:
  init-chain     Create new blockchain from scratch
  init-node      Initialize node for existing blockchain
  init-authority Initialize network authority for certificates
  register-bootnode Register & certify bootnode with authority

Node Operations:
  start-bootnode Start certified bootnode
  start-node     Start regular blockchain node

# Terminal 1: Start certified bootnode
cargo run -- start-bootnode --config bootnode-config.json

# Terminal 2: Initialize and start regular node
cargo run -- init-node --bootstrap-url http://bootnode:8080
cargo run -- start-node --config node-config.json

# Terminal 3: Add another regular node
cargo run -- init-node --bootstrap-url http://bootnode:8080
cargo run -- start-node --config node2-config.json

# Nodes automatically discover each other through the bootnode

Nodes communicate using structured protocol messages over libp2p:

• handshake - Network identity and compatibility validation
• block_broadcast - New block propagation to peers
• chain_sync - Request missing blocks from peers
• chain_data - Response with block data for synchronization

• proof_request - Request Merkle proof for specific data
• proof_response - Return generated Merkle proof

• Automatic Discovery: mDNS local network discovery
• Identity Validation: Network ID and genesis hash compatibility
• Secure Communication: Noise protocol encryption
• Protocol Multiplexing: Multiple protocols over single connection

# Create network authority for certificate management
cargo run -- init-authority --name vc-mainnet-authority --output authority.json

# Register bootnode with network authority
cargo run -- register-bootnode --node-id bootnode-01 --authority authority.json --config bootnode-config.json

# Start the certified bootnode
cargo run -- start-bootnode --config bootnode-config.json

# Initialize regular node (automatically discovers peers via bootnode)
cargo run -- init-node --bootstrap-url http://bootnode:8080 --config node-config.json
cargo run -- start-node --config node-config.json

# Add more nodes as needed
cargo run -- init-node --bootstrap-url http://bootnode:8080 --config node2-config.json
cargo run -- start-node --config node2-config.json

# All nodes automatically:
# - Connect via P2P networking
# - Synchronize blockchain state
# - Share blocks and transactions
# - Maintain network consensus

# Quick demo network with Docker
make demo-network
make start-bootnode  # Terminal 1
make start-node     # Terminal 2

# Or manually:
# Terminal 1 - Bootnode
docker run vcbc init-authority --name demo-auth
docker run vcbc register-bootnode --node-id demo-boot --authority authority.json
docker run -p 8080:8080 -p 9090:9090 -v $(pwd)/config:/app/config vcbc start-bootnode --config /app/config.json

# Terminal 2 - Regular Node
docker run vcbc init-node --bootstrap-url http://host.docker.internal:8080
docker run -p 8081:8080 -p 9091:9090 -v $(pwd)/node-config:/app/config vcbc start-node --config /app/config.json

vcbc/
├── src/
│   ├── lib.rs              # Library interface and exports
│   ├── error.rs            # Custom error types
│   ├── main.rs             # Application entry point
│   ├── config/             # Configuration management
│   │   ├── mod.rs
│   │   ├── node.rs         # Node configuration & bootnode certs
│   │   ├── authority.rs    # Network authority management
│   │   └── certificate.rs  # Bootnode certificates
│   ├── blockchain/         # Core blockchain logic
│   │   ├── mod.rs
│   │   ├── chain.rs        # Blockchain management
│   │   └── block.rs        # Block implementation
│   ├── mpt/                # Merkle-Patricia Trie
│   │   ├── mod.rs
│   │   ├── trie.rs         # MPT implementation
│   │   ├── node.rs         # MPT node types
│   │   └── hash.rs         # Hashing utilities
│   ├── network/            # P2P networking
│   │   ├── mod.rs
│   │   ├── p2p.rs          # P2P communication
│   │   └── http.rs         # HTTP API
│   ├── storage/            # Persistence layer
│   │   ├── mod.rs
│   │   ├── db.rs           # Storage backends
│   │   └── persistence.rs  # Serialization utilities
│   ├── proof/              # Cryptographic proofs
│   │   ├── mod.rs
│   │   └── core.rs         # Proof implementation
│   └── cli/                # Command-line interface
│       ├── mod.rs
│       ├── commands.rs     # CLI processing
│       └── args.rs         # CLI argument definitions
├── tests/                  # Integration tests
├── benches/                # Performance benchmarks
├── docs/                   # Additional documentation
├── LICENSE                 # GPL-3.0 license
└── README.md              # This file

pub struct NodeConfig {
    pub node_id: String,
    pub node_type: NodeType,
    pub network_config: NetworkConfig,
    pub storage_path: PathBuf,
}

pub struct BootnodeCertificate {
    pub node_id: String,
    pub public_key: Vec<u8>,
    pub signature: Vec<u8>,
    pub expiry: DateTime<Utc>,
}

• Node configuration management
• Bootnode certificate system for security
• Network authority management
• Configuration-driven architecture

pub struct Blockchain {
    pub chain: Vec<Block>,
    pub network_config: NetworkConfig,
}

pub struct Block {
    pub index: u64,
    pub timestamp: DateTime<Utc>,
    pub data: MerklePatriciaTrie,
    pub previous_hash: String,
    pub hash: String,
    pub nonce: u64,
}

• Core blockchain logic with network isolation
• Block creation, validation, and chain management
• Proof-of-work consensus implementation

pub struct MerklePatriciaTrie {
    root: MPTNode,
}

• Efficient key-value storage with O(log n) operations
• Compact hex prefix encoding
• Cryptographic root hash calculation
• Proof generation for data verification

pub struct MerkleProof {
    pub key: String,
    pub value: Vec<u8>,
    pub block_index: u64,
    pub mpt_root_hash: Vec<u8>,
    pub block_hash: String,
    pub timestamp: String,
}

• Merkle proof generation and verification
• Off-chain data verification
• Timestamped proof creation

pub trait Storage {
    fn save_blockchain(&self, blockchain: &Blockchain) -> Result<()>;
    fn load_blockchain(&self) -> Result<Blockchain>;
    fn blockchain_exists(&self) -> bool;
}

• SQLite Backend: Production-ready persistent storage with ACID compliance
• Custom MPT Serialization: Efficient blockchain data storage and retrieval
• Atomic Transactions: Data consistency with automatic rollback on failure
• Data Integrity Verification: Full blockchain validation on load
• Backup/Restore: Comprehensive persistence utilities

1. Block Mining: Nodes compete to solve proof-of-work puzzles
2. MPT Validation: Verify Merkle root hash integrity
3. Chain Validation: Check hash links and proof-of-work
4. Longest Chain Rule: Accept the longest valid chain
5. Conflict Resolution: Automatic convergence on single chain

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   MPT Ops   │───▶│ Block Mining │───▶│   Network  │
│             │    │              │    │ Broadcast  │
│ • Insert    │    │ • Hash calc  │    │            │
│ • Delete    │    │ • PoW solve  │    │ • Peers    │
│ • Proof gen │    │ • Validation │    │ • Sync     │
└─────────────┘    └─────────────┘    └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Storage    │    │   Chain     │    │   Proofs   │
│             │    │             │    │            │
│ • Persist   │    │ • Immutable │    │ • Verify   │
│ • Backup    │    │ • Linked    │    │ • Merkle   │
│ • Restore   │    │ • Valid     │    │ • Auth     │
└─────────────┘    └─────────────┘    └─────────────┘

# Run all tests
make test
# or: cargo test

# Run specific test modules
make test-specific TEST=mpt        # MPT implementation tests
make test-specific TEST=blockchain # Core blockchain tests
make test-specific TEST=proof      # Cryptographic proof tests
make test-specific TEST=storage    # Persistence layer tests
make test-specific TEST=network    # Multi-node tests

# Development testing workflow
make dev         # Format, lint, and test
make all         # Full quality check
make quick       # Fast compile + test

# Terminal 1: Setup authority and bootnode
cargo run -- init-authority --name test-authority --output authority.json
cargo run -- register-bootnode --node-id test-bootnode --authority authority.json --config bootnode.json
cargo run -- start-bootnode --config bootnode.json

# Terminal 2: Start first regular node
cargo run -- init-node --bootstrap-url http://localhost:8080 --config node1.json
cargo run -- start-node --config node1.json

# Terminal 3: Start second regular node
cargo run -- init-node --bootstrap-url http://localhost:8080 --config node2.json
cargo run -- start-node --config node2.json

# All nodes automatically synchronize via P2P
# HTTP API available on each node for blockchain operations
# Bootnode provides secure peer discovery
# Certificate validation ensures network integrity

• Cryptographic Integrity: SHA-256 hashing prevents data tampering
• MPT Root Verification: Merkle root hash ensures data integrity
• Data Integrity Verification: Full blockchain validation on load from storage
• Merkle Proofs: Cryptographic proof of data existence without full blockchain
• Proof-of-Work: Mining difficulty prevents spam attacks
• Chain Validation: All blocks and MPT roots are cryptographically verified
• Data Immutability: MPT structure prevents unauthorized data modifications
• Tamper Detection: Any data change invalidates Merkle proofs
• Atomic Transactions: Data consistency with automatic rollback on storage failures
• Peer Authentication: Future enhancement for secure peer connections

• ✅ Merkle-Patricia Trie: Efficient key-value storage with O(log n) operations
• ✅ Cryptographic Proofs: Merkle proofs for data verification and integrity
• ✅ SQLite Storage Backend: Production-ready persistent storage with atomic transactions
• ✅ Custom MPT Serialization: Efficient blockchain data storage and retrieval
• ✅ Data Integrity Verification: Full blockchain validation on load
• ✅ libp2p P2P Networking: Proper decentralized peer-to-peer communication
• ✅ Network Isolation: Automatic prevention of cross-project contamination
• ✅ Bootnode Security System: Certificate-based bootnode authentication
• ✅ HTTP API-First Architecture: RESTful API for blockchain operations
• ✅ Automatic Peer Discovery: Bootnode-based network formation
• ✅ Secure Communication: Noise protocol encryption and identity validation
• ✅ Configuration-Driven: JSON-based node configuration system
• ✅ Modular Architecture: Single responsibility principle across 13 modules
• ✅ Comprehensive Testing: 155+ unit tests with high coverage
• ✅ Clean Architecture: SOLID principles with type safety and error handling
• ✅ Docker Support: Containerized deployment with multi-stage builds
• ✅ Development Tools: Complete Makefile with 30+ automation targets

• Peer Discovery: Automatic network formation with gossip protocol
• WebSocket Support: Real-time block propagation
• Fork Resolution: Advanced conflict resolution mechanisms
• Network Partitioning: Handling network splits and merges
• Incentive Mechanisms: Mining rewards and transaction fees
• Smart Contracts: Turing-complete contract execution
• Zero-Knowledge Proofs: Enhanced privacy features
• Sharding: Horizontal scaling for high-throughput networks

Check node status and blockchain statistics:

cargo run -- info

View connected P2P peers:

cargo run -- peers

Monitor blockchain state:

# Get blockchain length and stats
cargo run -- list
cargo run -- info

# Get MPT data from specific blocks
cargo run -- get --index 1
cargo run -- query --block 1 --key "user"

# Generate and verify Merkle proofs
cargo run -- proof --block-index 1 --key "user"

# Run complete test suite
make test
# or: cargo test

# Generate coverage report
make coverage

# Test coverage: 155+ tests across 13 modules
# - MPT Implementation: 15 tests + property-based testing
# - Blockchain Core: 30 comprehensive tests (network identity, isolation)
# - Configuration: 15 node and certificate tests
# - P2P Networking: 15 protocol and peer management tests
# - Cryptographic Proofs: 15 security tests
# - Storage Layer: 20 persistence tests (SQLite production-ready)
# - CLI Interface: 15 integration tests
# - Error Handling: 5 validation tests
# - Network Compatibility: 35+ cross-network validation tests

• Zero Compilation Errors: Clean, type-safe Rust code
• Modular Architecture: 13 well-separated modules with single responsibility
• Comprehensive Error Handling: Custom error types throughout
• Documentation: Full API documentation with examples
• Testing: High code coverage with edge case handling
• Security: Bootnode certificate system for network integrity

We welcome contributions! This project follows a collaborative development process.

1. Fork and Clone

   git clone https://github.com/vestcodes/vcbc.git
   cd vcbc

2. Development Dependencies

   # Install Rust toolchain
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
   # Install additional tools
   rustup component add clippy rustfmt
   cargo install cargo-audit cargo-tarpaulin cargo-watch

3. Run Tests and Checks

   # Full development workflow
   make dev
   
   # Or run individual checks:
   make test         # Run all tests
   make clippy       # Run clippy linter
   make fmt-check    # Check code formatting
   make audit        # Security audit
   make coverage     # Generate coverage report
   
   # Run benchmarks
   make bench

This blockchain implementation follows clean code principles with a modular architecture:

• config/: Node configuration, certificates, and network authorities
• blockchain/: Core blockchain logic with network isolation
• mpt/: Merkle-Patricia Trie for efficient key-value storage
• proof/: Cryptographic proof generation and verification
• network/: P2P networking and HTTP API
• storage/: Persistence layer with backup/restore
• cli/: Command-line interface for configuration and node management
• error.rs: Comprehensive error handling types

• Testing: All new features require comprehensive unit tests
• Documentation: Public APIs must be fully documented with examples
• Error Handling: Use custom error types, avoid generic errors
• Clean Code: Follow SOLID principles and single responsibility
• Type Safety: Leverage Rust's type system for correctness
• Performance: Consider algorithmic complexity and memory usage

1. Create Feature Branch

   git checkout -b feature/your-feature-name

2. Write Tests First

   #[test]
   fn test_your_new_feature() {
       // Test implementation
   }

3. Implement Feature

   • Follow existing code patterns
   • Add comprehensive error handling
   • Update documentation

4. Run Quality Checks

   cargo test
   cargo clippy
   cargo fmt --check

5. Submit PR

   • Clear description of changes
   • Reference any related issues
   • Include test results

• Performance Optimization: MPT operations, network communication
• Additional Consensus: Proof-of-Stake, Byzantine fault tolerance
• New Features: Smart contracts, token standards, privacy features
• Documentation: API docs, tutorials, examples
• Testing: Property-based testing, fuzzing, integration tests
• Tooling: Development tools, CI/CD improvements

cargo bench --bench mpt_benchmark

• Block Propagation: < 100ms for local network
• Proof Verification: O(log n) for MPT depth
• Storage Operations: Optimized JSON serialization

• MPT Node: ~64 bytes average
• Block Storage: Variable based on MPT size
• Network Buffer: Configurable connection pooling

• Cryptographic Primitives: SHA-256 for hashing, secure random generation
• Input Validation: Comprehensive bounds checking and sanitization
• DoS Protection: Rate limiting on network endpoints
• Data Privacy: MPT provides cryptographic integrity without revealing data
• Key Management: No private keys stored in memory

VCBC uses automated releases with conventional commits, semantic versioning, and beautiful changelogs.

• main: Production branch - stable releases and hotfixes
• development: Development branch - feature development with automated pre-releases

# Switch to main branch
git checkout main
git pull origin main

# Create production release
make release-patch    # Patch: 1.0.0 -> 1.0.1
make release-minor    # Minor: 1.0.0 -> 1.1.0
make release-major    # Major: 1.0.0 -> 2.0.0

# Or manual tag creation
git tag v1.0.1
git push origin v1.0.1

# Switch to development branch
git checkout development
git pull origin development

# Automated development release (triggers after CI passes)
# Push commits → CI runs → If CI passes, release analysis runs → Release created
# CI automatically analyzes commits and creates releases when:
# - Features are added (MINOR version bump)
# - Fixes are made (PATCH version bump)
# - Breaking changes detected (MAJOR version bump)

# Or manual workflow dispatch in GitHub Actions for forced releases

The development CI automatically analyzes the last 10 commits to determine release type:

• feat: commits → MINOR release (new features)
• fix: commits → PATCH release (bug fixes)
• perf: commits → PATCH release (performance)
• refactor: commits → PATCH release (code improvements)
• Breaking changes → MAJOR release (marked with ! or BREAKING)

Only conventional commits trigger automated releases.

# Test release process without executing
make release-dry-run

• Trigger: Tag push (v*.*.*)
• Actions:
  • Updates CHANGELOG.md
  • Creates stable GitHub release
  • Builds and pushes Docker images to Docker Hub
  • Publishes to package registries

• Trigger: After CI workflow completes successfully + commit analysis
• Actions:
  • Analyzes conventional commits for release determination
  • Creates version bump and tag based on commit types
  • Updates CHANGELOG.md with git-cliff
  • Creates pre-release on GitHub
  • Builds development Docker images

Follow Conventional Commits for automatic changelog generation:

feat: add new blockchain feature
fix: resolve MPT serialization bug
docs: update API documentation
refactor: improve error handling
test: add unit tests for networking
chore: update dependencies

• release.toml: cargo-release configuration
• cliff.toml: git-cliff changelog configuration
• .github/workflows/release.yml: Production release workflow
• .github/workflows/dev-release.yml: Development release workflow (depends on CI success)

development branch
       ↓
   Push commits
       ↓
   CI Pipeline
   (tests, lint, build, security)
       ↓
   CI Success ✓
       ↓
Commit Analysis Script
   (analyzes conventional commits)
       ↓
Determines Release Type
   (patch/minor/major)
       ↓
cargo-release + git-cliff
       ↓
GitHub Pre-release + Docker Images

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

• Ethereum: Inspiration for MPT implementation
• Bitcoin: Proof-of-work consensus foundation
• Rust Community: Excellent tooling and ecosystem
• Open Source Contributors: Building upon collective knowledge

Made with ❤️ by vestcodes in Rust

For questions or support, please open an issue or join our discussions.