A self-organizing distributed system for parallel hash computation. Nodes automatically discover each other, elect a leader, and distribute cryptographic work across the swarm. Features Bitcoin-style block mining with automatic task generation and dynamic work redistribution.
- Dynamic Discovery: Nodes find each other via UDP broadcast - no configuration needed
- Leader Election: LCR (LeLann-Chang-Roberts) ring-based algorithm
- Fault Tolerance: Heartbeat-based failure detection with automatic re-election
- FIFO Multicast: Reliable ordered message delivery with sequence numbers
- Parallel Hashing: Distributed SHA-256 nonce search with configurable difficulty
- Bitcoin-Style Mining: Auto-generated block headers with previous_hash, merkle_root, timestamp
- Dynamic Work Pool: Automatic work redistribution on node failure/join
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"python -m crypto_swarmThe node will:
- Broadcast its presence
- Wait for other nodes (5 seconds)
- Become leader (if alone)
- Enter ACTIVE state
Open 3 terminals and run:
# Terminal 1
python -m crypto_swarm --port 5973
# Terminal 2
python -m crypto_swarm --port 5974
# Terminal 3
python -m crypto_swarm --port 5975All nodes will discover each other and elect the one with the highest UID as leader.
From the leader node (or any node - it will forward to leader):
python -m crypto_swarm --port 5973 --submit-task "find my hash" --difficulty easypython -m crypto_swarm [OPTIONS]
Options:
--port PORT Unicast port (default: 5973)
--config FILE Custom config file
--difficulty LEVEL simple|easy|medium|hard|extreme
--submit-task DATA Submit a hash task
--debug Enable debug logging
--dry-run Validate config and exit| Level | Prefix | Expected Time |
|---|---|---|
| simple | 0 |
Instant |
| easy | 00 |
~1 second |
| medium | 000 |
~15 seconds |
| hard | 0000 |
~2-5 minutes |
| extreme | 00000 |
~30+ minutes |
network:
discovery:
broadcast_port: 5972
unicast_port: 5973
timeout_seconds: 5.0
heartbeat:
interval_seconds: 1.0
timeout_seconds: 3.0
crypto:
difficulty_preset: medium
# Auto-task generation (Bitcoin-style mining)
auto_task:
enabled: true
interval_seconds: 15.0
block_simulation:
genesis_hash: "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
version: 1┌─────────────────────────────────────────────────────────────┐
│ Node │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Discovery │ │ Election │ │ Heartbeat │ │
│ │ (Process) │ │ (LCR) │ │ (Failure Detect) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Ring │ │ Multicast │ │ Task Manager │ │
│ │ (Topology) │ │ (FIFO) │ │ (Work Distribution)│ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
See docs/ARCHITECTURE.md for detailed documentation.
# Run all tests
pytest
# Run with verbose output
pytest -v
# Run only unit tests
pytest tests/unit/
# Run integration tests
pytest tests/integration/# Terminal 1 - Start first node
python -m crypto_swarm --port 5973
# Terminal 2 - Start second node
python -m crypto_swarm --port 5974
# Terminal 3 - Start third node
python -m crypto_swarm --port 5975Watch the logs show:
Mining block #1...- Leader generates Bitcoin-style block headers[FIFO-SEND] seq=1/[FIFO-DELIVER] seq=1- FIFO multicast in actionTask COMPLETED- Distributed proof-of-work foundBlock mined. New chain head: abc123...- Chain progresses
# Start 3 nodes as above, wait for mining to begin
# Kill Terminal 3 (Ctrl+C)
# Watch logs show:
# Node failure detected
# Reassigned 4 units from failed node back to poolFailed node's work is automatically redistributed to remaining workers.
# Start 2 nodes, let mining begin
# Start Terminal 3 (new node joins mid-task)
# Watch logs show:
# New node joined: abc12345...
# Assigned 4 units to new node abc12345...New nodes immediately receive work from the pool.
# Terminal 1 - Start first node (highest UID becomes leader)
python -m crypto_swarm --port 5973
# Terminal 2 - Start second node
python -m crypto_swarm --port 5974
# Wait for election: "Node state: ACTIVE (I am the leader)"
# Kill Terminal 1 (Ctrl+C)
# Watch Terminal 2 detect failure and become the new leadercrypto_swarm/
├── crypto_swarm/ # Main package
│ ├── core/ # Core algorithms
│ │ ├── discovery.py # UDP broadcast discovery
│ │ ├── election.py # LCR leader election
│ │ ├── ring.py # Ring topology
│ │ ├── heartbeat.py # Failure detection
│ │ ├── multicast.py # FIFO reliable multicast
│ │ └── membership.py # Group view management
│ ├── task/ # Task distribution
│ │ ├── task_manager.py
│ │ ├── crypto_worker.py
│ │ └── work_unit.py
│ ├── network/ # Network layer
│ │ ├── message.py # Message serialization
│ │ └── protocol.py # Constants
│ ├── node.py # Main orchestrator
│ └── cli.py # Command-line interface
├── tests/ # Unit and integration tests
├── docs/ # Documentation
└── config/ # Configuration files
- Python 3.9+
- PyYAML
MIT License - Group 41