# 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

```rust
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<T>>**: shared state across concurrent API handlers
- **Module system**: workspace with multiple crates
- **Tests**: unit + integration

## Quick Start

```bash
# 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](../blockchain-cli) - Rust CLI tool (communicates via HTTP)
- [blockchain-flutter](../blockchain-flutter) - Flutter mobile/web app (communicates via HTTP)

## License

MIT