Chaincraft Rust

A high-performance Rust-based platform for blockchain education and prototyping

Overview

A high-performance Rust-based platform for blockchain education and prototyping. Chaincraft Rust provides a clean, well-documented implementation of core blockchain concepts with a focus on performance, security, and educational value.

Features

• High Performance: Built with Rust for maximum performance and memory safety
• Educational Focus: Well-documented code with clear explanations of blockchain concepts
• Modular Design: Pluggable consensus mechanisms, storage backends, and network protocols
• Cryptographic Primitives: Support for multiple signature schemes (Ed25519, ECDSA/secp256k1)
• Network Protocol: P2P networking with peer discovery and message propagation
• Flexible Storage: Memory and persistent storage options with optional SQLite indexing
• CLI Interface: Easy-to-use command-line interface for node management

Quick Start

Installation

From Crates.io

cargo install chaincraft-rust

From Source

git clone https://github.com/jose-blockchain/chaincraft-rust.git
cd chaincraft-rust
cargo build --release

Running a Node

Start a Chaincraft node with default settings:

chaincraft-cli start

Or with custom configuration:

chaincraft-cli start --port 8080 --max-peers 20 --debug

Generate a Keypair

chaincraft-cli keygen

Usage as a Library

Add Chaincraft Rust to your Cargo.toml:

[dependencies]
chaincraft-rust = "0.2.1"

Basic Example

use chaincraft_rust::{ChaincraftNode, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut node = ChaincraftNode::builder()
        .port(21000)
        .max_peers(10)
        .build()?;

    println!("Starting node {} on port {}", node.id(), node.port());
    
    node.start().await?;
    
    // Your application logic here
    
    node.stop().await?;
    Ok(())
}

Advanced Configuration

use chaincraft_rust::{ChaincraftNode, Result};
use chaincraft_rust::crypto::KeyType;

#[tokio::main]
async fn main() -> Result<()> {
    let mut node = ChaincraftNode::builder()
        .port(21000)
        .max_peers(50)
        .enable_compression()
        .enable_persistent_storage()
        .key_type(KeyType::Ed25519)
        .build()?;

    node.start().await?;
    
    // Node is now running with persistent storage and compression enabled
    
    Ok(())
}

Architecture

Chaincraft Rust is built with a modular architecture:

• Core: Basic blockchain data structures and validation logic
• Consensus: Pluggable consensus mechanisms (Tendermint-style, randomness beacon)
• Network: P2P networking layer with peer discovery
• Storage: Flexible storage backends (memory, persistent, indexed)
• Crypto: Cryptographic primitives and utilities
• CLI: Command-line interface for node management

Network Architecture (Rust Version)

The Rust implementation uses raw UDP sockets (no libp2p) for simplicity and control:

1. Bind: Each node binds a UDP socket to host:port (port 0 = ephemeral).
2. Gossip Loop: A background task periodically rebroadcasts stored message hashes to all known peers.
3. Receive Loop: Incoming datagrams are parsed as JSON SharedMessage, deduplicated, stored, and rebroadcast.
4. Local Discovery: In-process nodes register in a static LOCAL_NODES map for automatic peer discovery within the same process.
5. Message Flow: create_shared_message_with_data() stores a message, processes it through ApplicationObjects, and broadcasts to peers.

Running Multi-Node Demos

Start multiple nodes in separate terminals or use the multi-node script:

# Terminal 1
chaincraft-cli start --port 9001

# Terminal 2
chaincraft-cli start --port 9002 --peer 127.0.0.1:9001

# Terminal 3
chaincraft-cli start --port 9003 --peer 127.0.0.1:9001 --peer 127.0.0.1:9002

Or run the shared objects example (in-process multi-node):

cargo run --example shared_objects_example

Python vs Rust Feature Mapping

Python (chaincraft)	Rust (chaincraft-rust)
node.py	src/node.rs
SharedMessage	shared::SharedMessage
ApplicationObject	shared_object::ApplicationObject
SimpleSharedNumber	shared_object::SimpleSharedNumber
SimpleChainObject	shared_object::MerkelizedChain
Message chain	shared_object::MessageChain
ECDSA ledger	examples::ecdsa_ledger::ECDSALedgerObject
dbm / on-disk storage	sled (feature persistent)
local_discovery	NodeConfig::local_discovery + LOCAL_NODES registry
gossip loop	Gossip task in start_networking()
UDP broadcast	broadcast_bytes() via UdpSocket

Features

Default Features

• compression: Enable message compression for network efficiency

Optional Features

• persistent: Enable persistent storage using sled
• indexing: Enable SQLite-based transaction indexing
• vdf-crypto: Enable VDF (Verifiable Delay Function) support via vdf crate. Requires GMP: apt install libgmp-dev or brew install gmp

Enable features in your Cargo.toml:

[dependencies]
chaincraft-rust = { version = "0.2.1", features = ["persistent", "indexing"] }

Development

Prerequisites

• Rust 1.70 or later
• Git

Building

git clone https://github.com/chaincraft-org/chaincraft-rust.git
cd chaincraft-rust
cargo build

Running Tests

# Run all tests
cargo test

# Run tests with all features enabled
cargo test --all-features

# Run integration tests
cargo test --test integration

Running Benchmarks

cargo bench

Code Coverage

cargo install cargo-tarpaulin
cargo tarpaulin --out Html

API Documentation

Full API documentation is available on docs.rs.

To build documentation locally:

cargo doc --open --all-features

Examples

Check out the examples/ directory for more usage examples:

• basic_node.rs: Simple node setup and operation
• keypair_generation.rs: Cryptographic keypair generation and signing
• chatroom_example.rs: Decentralized chatroom protocol (create rooms, post messages)
• randomness_beacon_example.rs: Verifiable randomness beacon
• shared_objects_example.rs: Multi-node network with shared object propagation
• proof_of_work_example.rs: Proof of Work mining and verification

Run examples with:

cargo run --example basic_node
cargo run --example chatroom_example
cargo run --example shared_objects_example

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass (cargo test --all-features)
6. Run clippy (cargo clippy --all-features)
7. Format your code (cargo fmt)
8. Commit your changes (git commit -am 'Add amazing feature')
9. Push to the branch (git push origin feature/amazing-feature)
10. Open a Pull Request

Performance

Chaincraft Rust is designed for high performance:

• Zero-copy serialization where possible
• Efficient async networking with tokio
• Optimized cryptographic operations
• Configurable resource limits

Security

Security is a top priority:

• Memory-safe Rust implementation
• Cryptographic operations use well-audited libraries
• Network protocol includes message authentication
• Input validation and sanitization throughout

License

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

Acknowledgments

• Built with Tokio for async runtime
• Cryptography powered by RustCrypto
• Custom UDP-based P2P networking (no libp2p dependency)

Roadmap

• Advanced consensus mechanisms (PBFT)
• Smart contract support
• Enhanced monitoring and metrics
• WebAssembly runtime integration

---

For more information, visit our documentation or repository.