Quantum-Blockchain Project — HTML README & Runbook

2) Prerequisites

• Python 3.10+ (3.11+ recommended)
• Pip & venv: python -m venv venv
• Ports open per node (default: 5000, 5001, 5002...)
• Optional (quantum): IBM Qiskit & credentials (.env)

OS Notes

• Linux/macOS: Use your system Python or pyenv.
• Windows 10/11: Use PowerShell 7 or Windows Terminal. Consider py -3.11.
• Android/Termux: pkg install python clang git; paths like /data/data/com.termux/files/home.

3) Install & Setup

Copy
# 1) Clone your repo
git clone <YOUR_REPO_URL> Quantum-Blockchain-Project
cd Quantum-Blockchain-Project

# 2) Create & activate venv
python -m venv venv
# macOS/Linux
source venv/bin/activate
# Windows PowerShell
# .\venv\Scripts\Activate.ps1

# 3) Install deps (Flask, requests, etc.)
pip install -U pip wheel
pip install flask requests ecdsa

# 4) (Optional) For quantum worker later
# pip install qiskit qiskit-ibm-runtime python-dotenv fastapi uvicorn
    

4) Run Locally (single & multi-node on one machine)

Single node @ :5000

Copy
# from project root
python src/main_blockchain.py 5000
# CLI appears; try commands: mine, tx, chain, peers, sync, help
    

Two nodes (same machine)

Open a second terminal:

Copy
# terminal 1
python src/main_blockchain.py 5000

# terminal 2 (connect to node1 as peer)
python src/main_blockchain.py 5001 127.0.0.1:5000
    

After mining on one node, run sync on the other; hashes should match.

5) Run on Another Machine (LAN/WAN)

1. On Machine A (host), pick a port (e.g., 5000) and run:

   Copypython src/main_blockchain.py 5000

2. Find Machine A’s LAN IP:

   Copy
   # macOS/Linux:
   ip addr  # or: ifconfig
   # Windows:
   ipconfig
           

3. On Machine B, connect to A using its IP:

   Copy
   # Example: Machine A is 192.168.1.50
   python src/main_blockchain.py 5001 192.168.1.50:5000
           

4. Firewall/NAT: allow the chosen port on Machine A.
   • Windows Defender Firewall: “Allow an app”, or add inbound rule for TCP 5000.
   • Linux (ufw): sudo ufw allow 5000/tcp
   • Router (WAN): Port-forward external port → Machine A :5000 (only if you really need internet peers).

6) Node CLI Commands

• mine Mine a new block (adds coinbase reward to local wallet or placeholder address).
• tx <receiver_address> <amount> Create + broadcast a transaction.
• chain Print current chain (height, last hash).
• peers List connected peers.
• sync Fetch & resolve longest valid chain from peers.
• help Show available commands.
• quit Exit.

7) HTTP API (quick curl)

Most nodes expose simple JSON endpoints via Flask. From another terminal:

Copy
# Get peers
curl -s http://127.0.0.1:5000/peers | jq .

# Get chain summary
curl -s http://127.0.0.1:5000/chain | jq .

# Broadcast a transaction (example payload)
curl -s -X POST http://127.0.0.1:5000/tx \
  -H "Content-Type: application/json" \
  -d '{"to":"ADDR_ABC123","amount":5.0}' | jq .
    

8) Troubleshooting

Node starts but peer connect fails

• Confirm host IP/port is reachable from the other machine: curl http://HOST_IP:5000/peers
• Open firewall for TCP port (see section 5).
• Ensure you passed peer as HOST_IP:PORT (no protocol prefix).

CLI commands “hang” after broadcast

• Check peer is actually running and not blocked by firewall.
• Open a separate terminal and hit health endpoints (above) to verify liveness.

Chains don’t match after mining

• Run sync on the out-of-date node.
• Check that both nodes run the same difficulty and validation rules.

Windows: Activate venv issues

• Open PowerShell as Admin once: Set-ExecutionPolicy RemoteSigned
• Then: .\venv\Scripts\Activate.ps1

9) Next Steps / Roadmap (if current stage is successful)

1. Wallet & Signatures: add ECDSA (or PQC later) to sign transactions. Store keys in an encrypted keystore (PBKDF2 + AES-GCM).
2. Better Peer Discovery: simple bootstrap URL (known_peers.json) + periodic gossip.
3. Consensus Hardening: difficulty retargeting; honest longest-chain w/ cumulative work; orphan handling.
4. Re-integrate Quantum Miner:
   • Expose quantum_miner.mine(target) that can call IBM Q via your quantum-worker FastAPI.
   • Return a verifiable proof (job_id + result hash) embedded in block header.
5. PQC Migration Plan: swap ECDSA → CRYSTALS-Dilithium (via oqs-python) for post-quantum signatures.
6. Web Dashboard (optional): minimal Firebase/Next.js page polling each node’s /status & /chain to visualize height, peers, and last hash.
7. Testing: vitest/pytest suites for block validation, chain selection, tx mempool, P2P broadcast.

10) Optional: Quantum Worker & .env

If/when you connect IBM Quantum, run your quantum-worker FastAPI separately and set credentials via .env:

Copy
# .env (example)
IBM_QUANTUM_API_KEY=YOUR_IBM_TOKEN
IBM_QUANTUM_INSTANCE=ibm-q/open/main
QWORKER_URL=http://127.0.0.1:8000

# run the worker
uvicorn quantum-worker.main:app --host 0.0.0.0 --port 8000 --reload
    

In quantum_miner.py, post to ${QWORKER_URL}/qrng or /poq/start and embed job_id + resultHash in your block header for on-chain verification.