# quantumfusion-network/qf-solochain architecture

> Architecture diagram of the GitHub repository quantumfusion-network/qf-solochain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quantumfusion-network/qf-solochain
- Repository: https://github.com/quantumfusion-network/qf-solochain

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Off-Chain Tooling"
    Make["Makefiles & Toolchain"]:::offchain
    Prog["pvm_prog Examples"]:::offchain
    QR["qf-test-runner"]:::offchain
    PR["pvm-test-runner"]:::offchain
  end

  subgraph "Node Layer"
    FN["Full-Node CLI & Service"]:::exec
    PN["Parachain CLI & Service"]:::exec
  end

  subgraph "Consensus Layer"
    Spin["Spin Consensus Engine"]:::core
  end

  subgraph "Runtime Layer (WASM)"
    QRt["qf-runtime"]:::onchain
    PRt["parachain runtime"]:::onchain
  end

  subgraph "FRAME Pallets"
    Pallets["FRAME Pallets"]:::onchain
    QVM["qf-polkavm Pallet"]:::onchain
  end

  subgraph "PolkaVM VM" as VM
    Comp["Compiler"]:::vm
    Int["Interpreter"]:::vm
  end

  Storage["RocksDB/ParityDB"]:::storage
  Net["libp2p Network"]:::external
  Docker["Docker & Scripts"]:::external
  CI["GitHub Actions CI/CD"]:::external

  Make --> Prog
  Prog -->|"upload(programBlob)"| QVM
  QR -->|"RPC calls"| FN
  PR -->|"RPC calls"| FN
  FN -->|"start service"| Spin
  PN -->|"start service"| Spin
  Spin -->|"state transition"| QRt
  Spin -->|"state transition"| PRt
  QRt -->|"includes pallets"| Pallets
  PRt -->|"includes pallets"| Pallets
  Pallets -->|"invoke"| QVM
  QVM -->|"compile"| Comp
  QVM -->|"execute(args)"| Int
  FN -->|"read/write"| Storage
  PN -->|"read/write"| Storage
  FN -->|"peer<>peer"| Net
  PN -->|"peer<>peer"| Net
  Docker --> FN
  Docker --> PN
  CI --> Docker

  click FN "https://github.com/quantumfusion-network/qf-solochain/tree/main/node/"
  click PN "https://github.com/quantumfusion-network/qf-solochain/tree/main/parachain/node/"
  click Spin "https://github.com/quantumfusion-network/qf-solochain/tree/main/client/consensus-spin/"
  click QRt "https://github.com/quantumfusion-network/qf-solochain/tree/main/runtimes/qf-runtime/"
  click PRt "https://github.com/quantumfusion-network/qf-solochain/tree/main/runtimes/parachain/"
  click QVM "https://github.com/quantumfusion-network/qf-solochain/tree/main/pallets/qf-polkavm/"
  click Prog "https://github.com/quantumfusion-network/qf-solochain/tree/main/pvm_prog/"
  click QR "https://github.com/quantumfusion-network/qf-solochain/tree/main/qf-test-runner/"
  click PR "https://github.com/quantumfusion-network/qf-solochain/tree/main/pvm-test-runner/"
  click Docker "https://github.com/quantumfusion-network/qf-solochain/tree/main/docker/"
  click CI "https://github.com/quantumfusion-network/qf-solochain/tree/main/.github/workflows/"
  click VM "https://github.com/quantumfusion-network/qf-solochain/tree/main/pallets/qf-polkavm/src/polkavm/"

  classDef exec fill:#D6E8FF,stroke:#000;
  classDef onchain fill:#E2F0D9,stroke:#000;
  classDef offchain fill:#FFE6CC,stroke:#000;
  classDef core fill:#FFF2CC,stroke:#000;
  classDef vm fill:#FDE9D9,stroke:#000;
  classDef storage fill:#E8E8E8,stroke:#000;
  classDef external fill:#F2F2F2,stroke:#000;
```
