StillHammer
64ea897cdc
- Workspace: core/ (blockchain library) + node/ (REST API) - Core: block, chain, wallet, transaction, mining, persistence, state - Node: axum 0.8 REST API with full endpoint set - SHA-256 hashing, Ed25519 signatures, account-based model - Unit tests for all core modules
134 lines
4.8 KiB
Markdown
134 lines
4.8 KiB
Markdown
# 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
|