MiniChain — Proof of Stake Blockchain for Seminars

A fully functional blockchain built in Python for live classroom demonstrations. Students run nodes, connect to a relay, stake vibe (Vibe), produce blocks, and fix bugs — all in real-time.

Architecture

minichain/           Node code (what students run)
  crypto/              SHA-256, ECDSA (secp256k1), Merkle trees
  consensus/pos.py     Proof of Stake: epochs, leader schedule, staking
  core/                Transaction, Block, Blockchain (PoS chain management)
  vm/stack_vm.py       26-opcode stack VM with gas metering
  storage/             SQLite persistence (WAL mode, ACID)
  network/             WebSocket relay client
  api/                 REST API (10 endpoints)
  mempool.py           Fee-ordered transaction pool
  node.py              Node orchestrator (block production + relay)

relay/               Relay server (instructor runs)
  server.py            WebSocket broker + REST API
  frontend/            React dashboard (scoreboard, topology, chain state)

vibecli/             CLI tool (like `cast` from Foundry)
vibecc/              Compiler: simple language → VM bytecode
examples/            Sample contracts (.vc files)

Concepts Demonstrated

Concept	Where	Details
Cryptography	crypto/	SHA-256, ECDSA (secp256k1), Merkle trees with proofs
Consensus	consensus/pos.py	PoS with 2-min epochs, 500ms slots, weighted leader election
Virtual Machines	vm/stack_vm.py	26 opcodes, gas metering, persistent contract storage
Databases	storage/	SQLite with WAL, ACID transactions, indexed tables
Distributed Systems	core/blockchain.py	Fork choice, state sync, chain validation
Networking	network/	WebSocket relay, gossip protocol, peer discovery
Concurrency	node.py	Async block production + networking on event loop
Game Theory	mempool.py, pos.py	Fee markets, staking rewards, validator incentives

Quick Start

1. Install

pip install ecdsa aiohttp

2. Generate Genesis

python generate_genesis.py --students 50 --output genesis.json

This creates 1 master key (10M vibe) + 50 student keys (10K vibe each).

3. Start the Relay (instructor)

python -m relay.run_relay --port 9000 --genesis genesis.json

Open http://localhost:9000 for the dashboard.

4. Start a Node (students)

# Using a key from genesis.json
python run_node.py --relay http://<relay-ip>:9000 --private-key <key> --name "Alice"

# Or generate a new wallet
python run_node.py --relay http://<relay-ip>:9000 --name "Bob"

5. Stake and Produce Blocks

# Stake 500 vibe to become a validator
python -m vibecli.cli stake --amount 500 --name "Alice" --wallet wallet.json

# Check the scoreboard
python -m vibecli.cli validators

6. Deploy a Smart Contract

# Compile a contract
python -m vibecc.compiler examples/counter.vc -o counter.vbc

# Deploy it
python -m vibecli.cli deploy --code-file counter.vbc --wallet wallet.json

Docker (Students)

docker build -t minichain .
docker run -e RELAY_URL=http://<relay-ip>:9000 minichain \
  --relay http://<relay-ip>:9000 --private-key <key> --name "Alice"

CLI Reference

vibecli keygen                              # Generate new wallet
vibecli balance <address>                   # Check balance
vibecli send --to <addr> --amount 10        # Transfer vibe
vibecli stake --amount 500 --name "Alice"   # Stake to validate
vibecli unstake --amount 200                # Unstake
vibecli deploy --code-file contract.vbc     # Deploy contract
vibecli call --contract <addr> --code "..." # Call contract
vibecli chain                               # View recent blocks
vibecli validators                          # View validator scores
vibecli info                                # Node info
vibecli debug gossip --relay ws://...       # Monitor gossip

Compiler (VibeCC)

Simple language that compiles to VM bytecode:

// counter.vc
let count = load("count");
count = count + 1;
store("count", count);
log(count);

python -m vibecc.compiler counter.vc                # Compile
python -m vibecc.compiler counter.vc --optimize     # With optimizer (has a bug!)
python -m vibecc.compiler counter.vc --ast          # Show AST

PoS Parameters

Parameter	Value
Epoch duration	120 seconds (2 minutes)
Slot duration	500ms
Slots per epoch	240
Block reward	10 vibe
Minimum stake	100 vibe
Leader selection	Weighted random by stake

REST API

Endpoint	Method	Description
/info	GET	Node status
/blocks	GET	All blocks
/blocks/{index}	GET	Block by height
/block/{hash}	GET	Block by hash
/tx/{hash}	GET	Transaction
/balance/{address}	GET	Account balance, nonce, stake
/state	GET	Full world state
/mempool	GET	Pending transactions
/validators	GET	Validator scoreboard
/schedule/{epoch}	GET	Leader schedule
/tx	POST	Submit transaction

Seminar Flow

1. Setup: Instructor starts relay, generates genesis, distributes keys
2. Connect: Students start nodes, connect to relay, see each other on dashboard
3. Stake: Students stake vibe, their slots appear in the leader schedule
4. Run: Nodes produce blocks, scoreboard updates in real-time
5. Bugs: Introduce bugs one at a time; students fix, restart, and rejoin
6. Win: Student with most accumulated rewards wins a prize

Students must time restarts carefully — if their node is down during their scheduled slots, they miss block rewards!