[Feature] MiniChain v0 - Educational Blockchain Prototype

Minichain_v0/.gitignore

@@ -0,0 +1,10 @@
+# Wallet keys (private keys - never commit!)
+*.key
+
+# Python
+venv/
+__pycache__/
+*.pyc
+
+# Environment
+.env

Minichain_v0/README.md

@@ -0,0 +1,104 @@
+# MiniChain v0 - Educational Blockchain
+
+A minimal, educational blockchain implementation in Python
+
+## Quick Start
+
+```bash
+cd Minichain_v0
+pip install -r requirements.txt
+
+# Using the launcher (recommended)
+./minichain start 8000           # Bootstrap node
+./minichain start 8001 8000      # Connect to port 8000
+./minichain start 8002 8000      # Third node
+
+# Or using Python directly
+python3 main.py --port 8000
+python3 main.py --port 8001 --connect localhost:8000
+```
+
+## Test Scenarios
+
+### 1. Mining for rewards
+```
+mine                # Mine block (earns 50 coins)
+balance             # Check balance
+```
+
+### 2. Distribute from treasury
+```
+treasury            # Check treasury balance
+faucet <addr> 1000
+mine               # Confirm transaction
+```
+
+### 3. Send coins
+```
+address                 # Show your address (copy recipient's)
+send <addr> 100
+mempool                # View mempool
+mine                   # Confirm
+```
+
+## Commands
+
+|---------|----------|-------------|
+| `balance` | `b` | Show your balance |
+| `address` | `a` | Show your wallet address |
+| `send <addr> <amt>` | - | Send coins |
+| `mine` | `m` | Mine block (+50 reward) |
+| `faucet <addr> <amt>` | - | Treasury send |
+| `treasury` | `t` | Show treasury balance |
+| `chain` | `c` | Show blockchain |
+| `peers` | `p` | Show connected peers |
+| `mempool` | `mp` | Show pending transactions |
+| `quit` | `q` | Exit |
+
+
+## File and folder structure
+
+| File | Lines | Description |
+|------|-------|-------------|
+| `config.py` | 19 | Configuration constants |
+| `transaction.py` | 91 | Signed transactions (Ed25519) |
+| `state.py` | 70 | Account balances and nonces |
+| `block.py` | 80 | Block structure |
+| `blockchain.py` | 133 | Chain validation and storage |
+| `mempool.py` | 66 | Pending transaction pool |
+| `consensus.py` | 40 | Proof-of-Work mining |
+| `network.py` | 154 | P2P networking (TCP sockets) |
+| `main.py` | 185 | CLI interface |
+| `minichain` | - | Bash launcher script |
+
+
+## What Users/Dev Learn
+
+1. **Transactions** - Ed25519 digital signatures for authentication
+2. **State** - Account-based ledger (balances + nonces)
+3. **Blocks** - Linking transactions with hashes
+4. **Consensus** - Proof-of-Work mining with rewards
+5. **Networking** - P2P communication with TCP sockets
+
+
+## Architecture
+
+```
+Transaction (signed) → Mempool → Block → Blockchain
+                                   ↑
+                           Consensus (PoW)
+                                   ↓
+                              Network → Peers
+```
+
+
+## Not Included (v0 Simplifications)
+
+- ❌ Merkle trees (optimization)
+- ❌ State snapshots (optimization)
+- ❌ Persistence (in-memory only)
+- ❌ GossipSub (using simpler streams)
+
+## Progression Path
+
+`v0` (currently we are here) → `v1` (optimizations) → `v2` (smart contracts)

Minichain_v0/block.py

@@ -0,0 +1,77 @@
+"""
+block.py - Block structure for MiniChain.
+A block contains transactions and links to the previous block via hash.
+"""
+
+import json
+import hashlib
+import time
+from typing import List
+from transaction import Transaction, create_genesis_tx
+from config import GENESIS_TIMESTAMP, TREASURY_ADDRESS, TREASURY_BALANCE
+
+
+class Block:
+    """A block in the blockchain containing transactions."""
+
+    def __init__(self, index: int, prev_hash: str, transactions: List[Transaction],
+                 timestamp: float = None, nonce: int = 0):
+        self.index = index
+        self.prev_hash = prev_hash
+        self.transactions = transactions
+        self.timestamp = timestamp or time.time()
+        self.nonce = nonce
+        self.hash = self.compute_hash()
+
+    def compute_hash(self) -> str:
+        """Compute SHA-256 hash of block header."""
+        header = {
+            "index": self.index,
+            "prev_hash": self.prev_hash,
+            "tx_hashes": [tx.hash() for tx in self.transactions],
+            "timestamp": self.timestamp,
+            "nonce": self.nonce
+        }
+        header_bytes = json.dumps(header, sort_keys=True).encode()
+        return hashlib.sha256(header_bytes).hexdigest()
+
+    def to_dict(self) -> dict:
+        """Convert block to dictionary for serialization."""
+        return {
+            "index": self.index,
+            "prev_hash": self.prev_hash,
+            "transactions": [tx.to_dict() for tx in self.transactions],
+            "timestamp": self.timestamp,
+            "nonce": self.nonce,
+            "hash": self.hash
+        }
+
+    @staticmethod
+    def from_dict(data: dict) -> "Block":
+        """Create block from dictionary."""
+        txs = [Transaction.from_dict(tx) for tx in data["transactions"]]
+        block = Block(
+            index=data["index"],
+            prev_hash=data["prev_hash"],
+            transactions=txs,
+            timestamp=data["timestamp"],
+            nonce=data["nonce"]
+        )
+        return block
+
+    def __repr__(self):
+        return f"Block(#{self.index}, txs={len(self.transactions)}, hash={self.hash[:8]})"
+
+
+def create_genesis_block() -> Block:
+    """Create the genesis (first) block with treasury funds."""
+    # Genesis funds go to the fixed treasury address
+    genesis_txs = [create_genesis_tx(TREASURY_ADDRESS, TREASURY_BALANCE)]
+
+    return Block(
+        index=0,
+        prev_hash="0" * 64,
+        transactions=genesis_txs,
+        timestamp=GENESIS_TIMESTAMP,
+        nonce=0
+    )

Minichain_v0/blockchain.py

@@ -0,0 +1,133 @@
+"""
+blockchain.py - Chain management for MiniChain.
+Stores blocks, validates new blocks, and handles longest-chain rule.
+"""
+
+from typing import List
+from block import Block, create_genesis_block
+from state import State, apply_tx
+from config import DIFFICULTY
+
+
+class Blockchain:
+    """The blockchain: a list of validated blocks."""
+
+    def __init__(self):
+        genesis = create_genesis_block()
+        self.chain: List[Block] = [genesis]
+        self.difficulty = DIFFICULTY
+
+    @property
+    def latest_block(self) -> Block:
+        """Get the most recent block."""
+        return self.chain[-1]
+
+    @property
+    def height(self) -> int:
+        """Get chain length."""
+        return len(self.chain)
+
+    def get_state(self) -> State:
+        """Recompute current state by replaying all transactions from genesis."""
+        state = State()
+        for block in self.chain:
+            for tx in block.transactions:
+                state = apply_tx(state, tx)
+        return state
+
+    def validate_block(self, block: Block, prev_block: Block) -> bool:
+        """Check if a block is valid (structure, PoW, transactions)."""
+        # Check index is sequential
+        if block.index != prev_block.index + 1:
+            print(f"Invalid index: expected {prev_block.index + 1}, got {block.index}")
+            return False
+
+        # Check previous hash links correctly
+        if block.prev_hash != prev_block.hash:
+            print("Invalid previous hash")
+            return False
+
+        # Check hash is correct
+        if block.hash != block.compute_hash():
+            print("Invalid hash")
+            return False
+
+        # Check proof-of-work
+        if not block.hash.startswith("0" * self.difficulty):
+            print("Hash does not meet difficulty")
+            return False
+
+        return True
+
+    def validate_block_transactions(self, block: Block, state: State) -> bool:
+        """Validate all transactions in block against given state."""
+        try:
+            for tx in block.transactions:
+                state = apply_tx(state, tx)
+            return True
+        except ValueError as e:
+            print(f"Transaction validation failed: {e}")
+            return False
+
+    def add_block(self, block: Block) -> bool:
+        """Add a new block to the chain if valid."""
+        # Validate block structure and PoW
+        if not self.validate_block(block, self.latest_block):
+            return False
+
+        # Validate transactions against current state
+        current_state = self.get_state()
+        if not self.validate_block_transactions(block, current_state):
+            return False
+
+        self.chain.append(block)
+        return True
+
+    def is_valid_chain(self, chain: List[Block]) -> bool:
+        """Validate an entire chain from genesis."""
+        if not chain:
+            return False
+
+        # Check genesis block matches expected
+        expected_genesis = create_genesis_block()
+        if chain[0].hash != expected_genesis.hash:
+            return False
+
+        # Validate each block
+        state = State()
+        for i, block in enumerate(chain):
+            # Apply transactions
+            try:
+                for tx in block.transactions:
+                    state = apply_tx(state, tx)
+            except ValueError:
+                return False
+
+            # Validate structure (skip genesis)
+            if i > 0 and not self.validate_block(block, chain[i - 1]):
+                return False
+
+        return True
+
+    def replace_chain(self, new_chain: List[Block]) -> bool:
+        """Replace chain if new one is longer and valid (longest-chain rule)."""
+        if len(new_chain) <= len(self.chain):
+            print("New chain is not longer")
+            return False
+
+        if not self.is_valid_chain(new_chain):
+            print("New chain is invalid")
+            return False
+
+        self.chain = new_chain
+        print(f"Chain replaced with {len(new_chain)} blocks")
+        return True
+
+    def to_dict(self) -> List[dict]:
+        """Serialize chain for network transmission."""
+        return [block.to_dict() for block in self.chain]
+
+    @staticmethod
+    def from_dict(data: List[dict]) -> List[Block]:
+        """Deserialize chain from network."""
+        return [Block.from_dict(b) for b in data]

Minichain_v0/config.py

@@ -0,0 +1,31 @@
+"""
+config.py - MiniChain configuration constants.
+Simple settings for the blockchain.
+"""
+
+# Proof-of-Work difficulty (number of leading zeros required)
+DIFFICULTY = 4
+
+# Genesis block timestamp (fixed for reproducibility)
+GENESIS_TIMESTAMP = 1704067200.0
+
+# Initial treasury balance (distributed via faucet to nodes)
+TREASURY_BALANCE = 10000000
+
+# Mining reward per block
+MINING_REWARD = 50
+
+# Maximum transactions per block
+MAX_TXS_PER_BLOCK = 100
+
+# Network protocol ID
+PROTOCOL_ID = "/minichain/1.0.0"
+
+# Special addresses
+COINBASE_SENDER = "0" * 64  # Mining rewards come from "nowhere"
+
+# Pre-generated treasury keypair (Ed25519, hex-encoded)
+# This is a FIXED keypair for educational/testing purposes
+# In production, this would be securely managed
+TREASURY_PRIVATE_KEY = "b705c5f56f218a2003f940f3d7d825ee7369c504ba3ad5fda8a2303f4b3c5e26"
+TREASURY_ADDRESS = "6b97d4ed320c6a8d1400dc034e183fd4678c4aa3f6301edf92e1cb4bd6337f44"