MiniChain v0 prototype completion

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Lint
+        run: make lint
+
+      - name: Run tests
+        run: make test

.gitignore

@@ -258,6 +258,17 @@ pythontex-files-*/
 # easy-todo
 *.lod
 
+# MiniChain local planning docs (do not commit)
+issues.md
+architectureProposal.md
+
+# Python caches and virtualenvs
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+
 # xcolor
 *.xcp
 
@@ -324,3 +335,6 @@ TSWLatexianTemp*
 # option is specified. Footnotes are the stored in a file with suffix Notes.bib.
 # Uncomment the next line to have this generated file ignored.
 #*Notes.bib
+
+
+docs/

Makefile

@@ -0,0 +1,21 @@
+PYTHON ?= python3
+
+.PHONY: install dev-install test lint format start-node
+
+install:
+	$(PYTHON) -m pip install .
+
+dev-install:
+	$(PYTHON) -m pip install -e .[dev]
+
+test:
+	$(PYTHON) -m pytest
+
+lint:
+	$(PYTHON) -m ruff check src tests
+
+format:
+	$(PYTHON) -m ruff format src tests
+
+start-node:
+	PYTHONPATH=src $(PYTHON) -m minichain --host 127.0.0.1 --port 7000

doc/implementation.md

@@ -0,0 +1,105 @@
+# MiniChain Implementation Reference
+
+This document summarizes the current MiniChain v0 implementation by subsystem.
+
+## 1) Crypto and Identity (`src/minichain/crypto.py`)
+
+- Ed25519 key generation/sign/verify through PyNaCl.
+- Address derivation from public key digest (20-byte lowercase hex address).
+- Serialization helpers for private/public keys.
+
+## 2) Canonical Serialization (`src/minichain/serialization.py`)
+
+- Deterministic JSON serialization for consensus-critical payloads.
+- Strict field presence/order checks to avoid cross-node divergence.
+
+## 3) Transactions (`src/minichain/transaction.py`)
+
+- Account-model transfer transaction with: sender, recipient, amount, nonce, fee, timestamp.
+- Signature + public key included for validation.
+- Coinbase transaction shape and validation helpers.
+- Deterministic transaction id generation.
+
+## 4) Merkle and Blocks (`src/minichain/merkle.py`, `src/minichain/block.py`)
+
+- Deterministic Merkle root construction for block transaction lists.
+- Block header contains parent hash, height, timestamp, target, nonce, root.
+- Block hash = canonical header hash.
+- Header/body consistency checks for Merkle root.
+
+## 5) Consensus and Mining (`src/minichain/consensus.py`, `src/minichain/mining.py`)
+
+- Proof-of-work target validation and nonce search.
+- Difficulty bounds and retarget policy.
+- Candidate block building from mempool with coinbase reward + fees.
+- Interrupt-capable mining loop support.
+
+## 6) State and Chain Logic (`src/minichain/state.py`, `src/minichain/chain.py`, `src/minichain/genesis.py`)
+
+- Account state tracks balance and nonce per address.
+- Deterministic tx apply rules: nonce progression, amount+fee affordability, signer identity.
+- Canonical chain selection by valid longest chain.
+- Reorg support with state replay and validation.
+- Configurable genesis creation and initial state.
+
+## 7) Mempool (`src/minichain/mempool.py`)
+
+- Signature/identity checks before acceptance.
+- Per-sender nonce queueing (ready vs waiting).
+- Mining selection prioritizes fee while preserving sender nonce order.
+- Eviction by age and capacity.
+
+## 8) Persistence (`src/minichain/storage.py`)
+
+- SQLite storage for blocks, chain metadata, and state snapshots.
+- Canonical head persistence and restart recovery.
+- Replay + snapshot consistency checks on startup.
+
+## 9) Node Orchestration (`src/minichain/node.py`)
+
+- `MiniChainNode` composes chain manager, mempool, and storage.
+- APIs for transaction submission, block acceptance, and mining.
+- Clean startup/shutdown lifecycle with config validation.
+
+## 10) Networking (`src/minichain/network.py`)
+
+- TCP handshake (`hello`) and peer management.
+- Peer discovery via bootstrap and mDNS/local discovery fallback.
+- Gossip protocols:
+  - `/minichain/tx/1.0.0`
+  - `/minichain/block/1.0.0`
+- Sync protocol (`/minichain/sync/1.0.0`) with range requests.
+- Block/tx dedup caches.
+- Automatic reconnect loop to bootstrap/known peers.
+- Transaction gossip returns explicit `tx_result` ack (accepted/reason).
+
+## 11) CLI (`src/minichain/__main__.py`)
+
+Primary command groups:
+
+- `node start`
+- `node run [--peer host:port] [--mine]`
+- `node stop`
+- `wallet generate-key|balance|details|list`
+- `tx submit`
+- `chain info|block|accounts`
+- `mine`
+- `shell`
+
+Current daemon-aware behavior:
+
+- If `node run` is active for the same `--data-dir`, `tx submit` routes over network to the running daemon.
+- `chain info` includes `connected_peers`.
+- Daemon status logging includes `height`, `tip`, `mempool_size`, `connected_peers`.
+
+## 12) Test Coverage (`tests/`)
+
+- Unit tests for core primitives and validation logic.
+- Integration tests for:
+  - peer discovery
+  - tx gossip
+  - block propagation
+  - chain sync/catch-up
+  - fork/reorg and convergence scenarios
+
+MiniChain v0 currently provides a complete educational blockchain node with deterministic behavior, CLI-driven flows, and reproducible local/multi-node testing.

doc/testing.md

@@ -0,0 +1,207 @@
+# MiniChain End-to-End Testing
+
+This document is the single source for testing MiniChain end-to-end:
+- single-device flow with live logs
+- two-node sync on one machine (multi-device simulation)
+- true multi-device LAN sync
+
+## 1) Prerequisites
+
+```bash
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+Optional clean start:
+
+```bash
+rm -rf .demo-single .demo-a .demo-b
+```
+
+
+## 3) Single-Device End-to-End 
+
+Use two terminals.
+
+### Terminal A: create keys and run node daemon
+
+```bash
+MINER_OUT=$(minichain --data-dir .demo-single wallet generate-key)
+RECIP_OUT=$(minichain --data-dir .demo-single wallet generate-key)
+
+MINER_ADDR=$(echo "$MINER_OUT" | awk -F= '/address/{gsub(/ /,"",$2); print $2; exit}')
+MINER_PK=$(echo "$MINER_OUT" | awk -F= '/private_key/{gsub(/ /,"",$2); print $2; exit}')
+RECIP_ADDR=$(echo "$RECIP_OUT" | awk -F= '/address/{gsub(/ /,"",$2); print $2; exit}')
+
+minichain --data-dir .demo-single --host 127.0.0.1 --port 7000 --miner-address "$MINER_ADDR" \
+  node run --advertise-host 127.0.0.1 --mine --mine-interval-seconds 10 --status-interval-seconds 2 
+```
+
+### Terminal B: verify chain, submit tx, verify balances
+
+
+```bash
+minichain --data-dir .demo-single chain info
+
+minichain --data-dir .demo-single --host 127.0.0.1 --port 7000 tx submit \
+  --private-key "$MINER_PK" \
+  --recipient "$RECIP_ADDR" \
+  --amount 5 \
+  --fee 1 \
+  --no-mine-now
+```
+
+Wait for the next mined block, then:
+
+```bash
+minichain --data-dir .demo-single wallet balance --address "$MINER_ADDR"
+minichain --data-dir .demo-single wallet balance --address "$RECIP_ADDR"
+minichain --data-dir .demo-single chain accounts --limit 20
+```
+
+Stop daemon:
+
+```bash
+minichain --data-dir .demo-single node stop
+```
+
+## 4) Two Nodes on One Machine (Simulate Multi-Device)
+
+Use two terminals.
+
+### Terminal A (miner node)
+
+```bash
+MINER_OUT=$(minichain --data-dir .demo-a wallet generate-key)
+MINER_ADDR=$(echo "$MINER_OUT" | awk -F= '/address/{gsub(/ /,"",$2); print $2; exit}')
+MINER_PK=$(echo "$MINER_OUT" | awk -F= '/private_key/{gsub(/ /,"",$2); print $2; exit}')
+
+minichain --data-dir .demo-a --host 127.0.0.1 --port 7000 --miner-address "$MINER_ADDR" \
+  node run --advertise-host 127.0.0.1 --mine --mine-interval-seconds 15 --status-interval-seconds 2 
+```
+
+### Terminal B (observer node)
+
+```bash
+RECIP_OUT=$(minichain --data-dir .demo-b wallet generate-key)
+RECIP_ADDR=$(echo "$RECIP_OUT" | awk -F= '/address/{gsub(/ /,"",$2); print $2; exit}')
+
+minichain --data-dir .demo-b --host 127.0.0.1 --port 7001 \
+  node run --advertise-host 127.0.0.1 --peer 127.0.0.1:7000 --status-interval-seconds 2 
+```
+
+### Terminal C (tx submit)
+
+
+
+Submit tx to node A:
+
+```bash
+minichain --data-dir .demo-a --host 127.0.0.1 --port 7000 tx submit \
+  --private-key "$MINER_PK" \
+  --recipient "$RECIP_ADDR" \
+  --amount 7 \
+  --fee 1 \
+  --no-mine-now
+```
+
+After next mined block on A, verify sync:
+
+```bash
+minichain --data-dir .demo-a chain info
+minichain --data-dir .demo-b chain info
+minichain --data-dir .demo-a wallet balance --address "$MINER_ADDR"
+minichain --data-dir .demo-a wallet balance --address "$RECIP_ADDR"
+minichain --data-dir .demo-b wallet balance --address "$MINER_ADDR"
+minichain --data-dir .demo-b wallet balance --address "$RECIP_ADDR"
+```
+
+Stop:
+
+```bash
+minichain --data-dir .demo-a node stop
+minichain --data-dir .demo-b node stop
+```
+
+## 5) True Multi-Device LAN Test
+
+Assume:
+- Device A IP: `<A_IP>`
+- Device B IP: `<B_IP>`
+
+### Device A (miner)
+
+```bash
+minichain --data-dir .demo-a --host 0.0.0.0 --port 7000 --miner-address "$MINER_ADDR" \
+  node run --advertise-host <A_IP> --mine --mine-interval-seconds 15 --status-interval-seconds 2 
+```
+
+### Device B (observer)
+
+```bash
+minichain --data-dir .demo-b --host 0.0.0.0 --port 7001 \
+  node run --advertise-host <B_IP> --peer <A_IP>:7000 --status-interval-seconds 2 
+```
+
+## 6) Complete CLI Command Reference
+
+Top-level:
+
+```bash
+minichain [--host HOST] [--port PORT] [--data-dir DATA_DIR] [--miner-address MINER_ADDRESS] <command>
+```
+
+Commands:
+
+```bash
+minichain node start
+minichain node run [--peer HOST:PORT] [--advertise-host HOST] [--node-id ID] [--mdns] [--mine] [--mine-interval-seconds N] [--sync-batch-size N] [--status-interval-seconds N]
+minichain node stop [--timeout-seconds N] [--force]
+
+minichain wallet generate-key
+minichain wallet balance --address <20-byte-lowercase-hex>
+minichain wallet details --address <20-byte-lowercase-hex>
+minichain wallet list [--limit N]
+
+minichain tx submit --private-key <hex-ed25519-key> --recipient <20-byte-lowercase-hex> --amount N [--fee N] [--nonce N] [--mine-now|--no-mine-now]
+
+minichain chain info
+minichain chain block (--height N | --hash <block-hash-hex>)
+minichain chain accounts [--limit N]
+
+minichain mine [--count N] [--max-transactions N]
+minichain shell
+```
+
+Useful help commands:
+
+```bash
+minichain --help
+minichain node --help
+minichain node run --help
+minichain node stop --help
+minichain wallet --help
+minichain wallet balance --help
+minichain wallet details --help
+minichain wallet list --help
+minichain tx --help
+minichain tx submit --help
+minichain chain --help
+minichain chain block --help
+minichain chain accounts --help
+minichain mine --help
+```
+
+Legacy aliases (still accepted and auto-remapped):
+
+```bash
+start
+generate-key
+balance
+submit-tx
+chain-info
+block
+```
+
+
+