Contributing
Repository Structure
BlockHost is a multi-repo project. The main repo orchestrates submodules:
| Repo | Purpose |
|---|---|
| blockhost | Installer, scripts, ISO builder, admin panel |
| blockhost-engine-evm | EVM blockchain engine |
| blockhost-engine-opnet | OPNet blockchain engine |
| blockhost-provisioner-proxmox | Proxmox provisioner |
| blockhost-provisioner-libvirt | libvirt provisioner |
| blockhost-common | Shared library |
| blockhost-broker | IPv6 broker |
| blockhost-monitor | Host monitor (in development) |
| libpam-web3 | PAM authentication module |
| blockhost-facts | Interface contracts |
Before You Start
- Read the relevant interface contract for the component you're modifying
- Understand the architecture and where your change fits
- Check existing issues and discussions
Guidelines
- Fix the interface, never wrap the mismatch. If two components disagree, the contract is wrong — not the code.
- No
shell=True. All subprocess calls use argument lists. - Validate at the boundary. Trust internal code. Validate external input.
- Keep it simple. Don't add abstractions for one-time operations. Three similar lines are better than a premature helper.
- Test with the ISO. The integration test is booting the ISO and running the wizard end-to-end. Unit tests are good; a working system is better.
Adding a New Engine
See Building an Engine. The interface contract is in facts/ENGINE_INTERFACE.md.
Adding a New Provisioner
See Building a Provisioner. The interface contract is in facts/PROVISIONER_INTERFACE.md.
Security Issues
If you find a security vulnerability, please report it responsibly. See Audit Status for what's been reviewed.