How quantumfusion-network/qf-solochain works
Project type and purpose
• Quantum Fusion is a Substrate-based blockchain “solo chain” with both a standalone node and a parachain node.
• It provides on-chain smart-contract execution via a custom RISC-V-based VM (PolkaVM), plus toolchains for compiling and testing VM programs.
File structure to extract components
• Top-level crates:
– client/consensus-spin: a custom consensus engine crate
– node/: the main full-node binary (CLI, service, RPC, chain spec)
– parachain/node/: a Substrate parachain binary
– runtimes/: two runtime crates (solo chain & parachain), each bundling pallets into WASM-executable state transition functions
• Pallets/: on-chain modules (Substrate FRAME pallets), notably:
– qf-polkavm: implements the PolkaVM pallet, including compiler, interpreter, sandbox, etc.
– faucet, spin, spin-polkadot, qf-polkavm-dev: auxiliary on-chain functionality
• pvm_prog/: example Rust programs compiled to .polkavm blobs
• qf-test-runner/ & pvm-test-runner/: host-side tools to run VM blobs against the node via RPC
• docker/: Dockerfiles and scripts to package the node and runtimes into containers
• CI/CD: .github/workflows/*.yml for build, test, and release pipelines
README for runtime and tooling insights
• Two executables: qf-solochain (full node) and parachain node
• Smart-contract toolchain: make pvm-prog-<progname> → compiles .polkavm, then upload & execute via extrinsics
• Test frameworks: Zombienet integration, qf-test-runner for headless VM tests
a. Main components
1. Node Layer
• Full-node CLI (node/)
• Parachain CLI (parachain/node/)
2. Consensus Layer
• consensus-spin (client/consensus-spin & primitives/consensus-spin)
3. Runtime Layer (WASM)
• runtimes/qf-runtime & runtimes/parachain
• FRAME pallets (pallets/*) including qf-polkavm
4. Smart-Contract VM Toolchain
• PolkaVM compiler & interpreter inside pallet
• pvm_prog example programs
• Host-side runners (qf-test-runner, pvm-test-runner)
5. Storage & Networking
• RocksDB/ParityDB (config in runtime weights)
• libp2p networking via Substrate service
6. Deployment & CI/CD
• Docker images & scripts
• GitHub Actions
b. Relationships and data flows
• User CLI → Node binary → Service API → Consensus → Runtime WASM → FRAME pallets
• qf-polkavm pallet extrinsic “upload(programBlob)” → stores program in pallet state → “execute(a,b,op)” → invokes interpreter
• pvm-test-runner / qf-test-runner → RPC to node → submit extrinsics & query results
• Docker container wraps Node binary + runtime WASM + config → exposed P2P and RPC endpoints
c. Architectural patterns & design principles
• Layered architecture: CLI/Service → Consensus → Runtime → Pallets → VM
• Modular design: independent crates for consensus, pallets, runtimes, test-runners
• Host vs. on-chain split: heavy VM logic lives in pallet but uses generic traits for no-std vs std via mutex_no_std / mutex_std
d. Key technologies & frameworks
• Rust + Cargo workspaces
• Substrate FRAME (pallets, runtimes)
• RISC-V PolkaVM — custom VM inside a pallet
• Docker for containerization
• Zombienet for network emulation
• GitHub Actions for CI