Quantum-Blockchain Project • Portal & Runbook

Overview & Structure

This page is your copy-paste guide for local and multi-machine runs, troubleshooting, and next steps.

Quantum-Blockchain-Project/
├── src/
│   ├── models.py
│   ├── p2p.py
│   ├── main_blockchain.py
│   ├── quantum_miner.py
│   └── __init__.py
├── venv/
├── requirements.txt
└── README.html

Prerequisites

Python 3.10+ (3.11+ recommended)
Ports open per node (e.g., 5000, 5001)
Optional (quantum): Qiskit + IBM Runtime + .env

Windows tip: use PowerShell 7 or Windows Terminal; consider py -3.11.

Install & Setup

Clone & venv

git clone <YOUR_REPO_URL> Quantum-Blockchain-Project
cd Quantum-Blockchain-Project

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

pip install -U pip wheel
pip install flask requests ecdsa

# Optional quantum worker deps
# pip install qiskit qiskit-ibm-runtime python-dotenv fastapi uvicorn

Run Locally

Single node @ :5000

python src/main_blockchain.py 5000
# Then try: mine | tx WALLET123 25 | chain | peers | sync | help

Two nodes (same machine)

# terminal 1
python src/main_blockchain.py 5000

# terminal 2
python src/main_blockchain.py 5001 127.0.0.1:5000

Run on Another Machine (LAN/WAN)

Host (Machine A)

python src/main_blockchain.py 5000
# Find LAN IP:
# macOS/Linux: ip addr   (or ifconfig)
# Windows:     ipconfig

Peer (Machine B)

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

Open firewall for TCP port on Machine A:

Windows Defender: add inbound rule for TCP 5000
Linux (ufw): sudo ufw allow 5000/tcp
Router (WAN): port-forward → only if needed

CLI Commands

mine
tx <receiver_address> <amount>
chain
peers
sync
help
quit

HTTP API (curl)

# Get peers
curl -s http://127.0.0.1:5000/peers

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

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

Troubleshooting

Peer connect fails: verify host reachable (curl http://HOST_IP:5000/peers), firewall open, peer arg is HOST:PORT.
CLI “hangs” after broadcast: ensure peer is running and reachable; hit health endpoints.
Chains don’t match: run sync; confirm same difficulty/rules.
Windows venv: run as Admin once: Set-ExecutionPolicy RemoteSigned, then .\venv\Scripts\Activate.ps1.

Next Steps / Roadmap

Wallet & Signatures: add ECDSA (then PQC swap) + encrypted keystore (PBKDF2 + AES-GCM).
Peer Discovery: bootstrap list + gossip.
Consensus: difficulty retarget; cumulative work; orphan handling.
Quantum Miner: integrate worker; embed job_id + resultHash in headers.
Dashboard: minimal web UI polling /status & /chain.
Testing: block validation, chain selection, mempool, P2P broadcast.

Optional: Quantum Worker & .env

# .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 store the proof in your block header.