blockchain-core

Rust workspace implementing a minimal blockchain from scratch. Educational project demonstrating core blockchain concepts with production-quality Rust code.

Architecture

blockchain-core/
├── core/          # Library crate - blockchain primitives
│   └── src/
│       ├── lib.rs          # Re-exports
│       ├── block.rs        # Block + BlockHeader, SHA-256 hashing
│       ├── transaction.rs  # Transaction, signing, verification
│       ├── chain.rs        # Blockchain struct, validation, state
│       ├── wallet.rs       # Ed25519 keypair, address generation
│       ├── mining.rs       # Proof of Work consensus
│       ├── state.rs        # AccountState (balance + nonce)
│       ├── error.rs        # BlockchainError enum (thiserror)
│       ├── config.rs       # Difficulty, block reward constants
│       └── persistence.rs  # JSON save/load
├── node/          # Binary crate - REST API server
│   └── src/
│       ├── main.rs         # Entry point: load chain, start axum
│       ├── state.rs        # AppState: Arc<RwLock<Blockchain>>
│       └── api/
│           ├── mod.rs      # Router setup + CORS
│           ├── blocks.rs   # GET /api/blocks, GET /api/blocks/:hash
│           ├── transactions.rs  # POST /api/transactions
│           ├── wallets.rs  # POST /api/wallets, GET balance
│           ├── mining.rs   # POST /api/mine
│           ├── chain.rs    # GET /api/chain/info
│           └── errors.rs   # API error responses
└── tests/         # Integration tests

Design Decisions

Decision	Choice	Rationale
Transaction model	Account-based	Simpler than UTXO, HashMap<Address, Balance>
Hashing	SHA-256 (sha2)	Bitcoin standard, well documented
Signatures	Ed25519 (ed25519-dalek)	Modern, fast, excellent Rust support
API framework	axum 0.8	Tokio-native, no macros, clean API
Persistence	JSON files	No DB setup needed, human-readable
Amounts	u64 (smallest unit)	No floats, like satoshis in Bitcoin

Data Structures

struct Block {
    header: BlockHeader,  // index, timestamp, prev_hash, hash, nonce, difficulty
    transactions: Vec<Transaction>,
}

struct Transaction {
    id: String,           // UUID
    from: String,         // Hex public key (or "coinbase")
    to: String,           // Hex public key
    amount: u64,          // Smallest unit
    nonce: u64,           // Anti-replay protection
    timestamp: DateTime<Utc>,
    signature: String,    // Ed25519 signature
}

struct Wallet {
    address: String,                     // Hex-encoded public key
    signing_key_bytes: Option<Vec<u8>>,  // Private key (never in API)
}

struct Blockchain {
    blocks: Vec<Block>,
    pending_transactions: Vec<Transaction>,
    accounts: HashMap<String, AccountState>,
    difficulty: u32,
    block_reward: u64,
}

REST API

Method	Path	Description
GET	/api/blocks	List blocks (paginated)
GET	/api/blocks/:hash	Get block by hash
POST	/api/transactions	Submit signed transaction
GET	/api/transactions/pending	View pending transaction pool
POST	/api/wallets	Generate new wallet keypair
GET	/api/wallets/:address/balance	Get balance and nonce
POST	/api/mine	Mine pending transactions into block
GET	/api/mining/status	Difficulty, reward, pending count
GET	/api/chain/info	Chain length, difficulty, latest hash
POST	/api/chain/validate	Full chain validation
GET	/api/health	Node health check

Rust Concepts Demonstrated

• Ownership & Move: blocks pushed into chain Vec
• Borrowing: wallet signing via &self
• Enums + Pattern Matching: BlockchainError, API responses
• Traits (derive): Serialize, Deserialize, Debug, Clone
• Error handling: Result<T, E> with thiserror + ? operator
• Collections: Vec<Block>, HashMap<String, AccountState>
• Iterators: chain validation, transaction filtering
• Async/await: axum handlers, tokio runtime
• Arc<RwLock>: shared state across concurrent API handlers
• Module system: workspace with multiple crates
• Tests: unit + integration

Quick Start

# Build everything
cargo build

# Run tests
cargo test

# Start the node (port 3000)
cargo run -p blockchain-node

# In another terminal, test with curl
curl http://localhost:3000/api/health
curl http://localhost:3000/api/chain/info

Related Repos

• blockchain-cli - Rust CLI tool (communicates via HTTP)
• blockchain-flutter - Flutter mobile/web app (communicates via HTTP)

License

MIT