DTG-BlockFL

DTG-BlockFL is a research codebase for secure federated learning under malicious-client settings. The repository implements a dynamic trust-graph pipeline with anomaly-aware scoring, survivor-aware aggregation, and append-only audit metadata logging. It supports single-run experiments, manifest-based batch execution, and paper-oriented result export utilities.

Scope and fidelity notice

This public repository is intended for research reproducibility and method inspection.

• DTG-BlockFL is implemented directly in this repository.
• The blockchain component is a lightweight pseudo-chain metadata logging prototype for auditability studies, not a production blockchain deployment.
• Several advanced baselines are compact reproduction-style implementations for controlled comparison, not official upstream releases.
• Historical filenames such as paper_full_v13.yaml are retained for compatibility with launcher scripts and previous experiment notes.

Repository layout

run.py                         # main experiment entrypoint
configs/                       # single-run experiment configurations
manifests/                     # batch experiment plans
scripts/                       # setup, diagnosis, launch, summary, plotting
src/                           # attacks, defenses, FL flow, models, utils
launchers/windows/             # one-click Windows launchers
docs/                          # organized documentation hub
data/                          # local-only data placeholders (not tracked)
outputs/                       # runtime outputs (ignored except .gitkeep)

What is included in the public v18 package

• cleaned .gitignore for datasets, caches, checkpoints, and outputs
• MIT license and corrected CITATION.cff
• Windows launchers with no machine-specific Conda path
• documentation hub, contribution files, issue templates, and release notes
• source code, configs, manifests, and helper scripts

What is intentionally not committed

• large or private datasets
• processed dataset caches such as femnist_cache.pt
• local experiment outputs under outputs/
• generated paper tables or logs that should be recreated from real runs

Installation

CPU

conda create -n dtgblockfl python=3.10 -y
conda activate dtgblockfl
pip install -r requirements-cpu-pytorch.txt
pip install -r requirements.txt

CUDA 11.8

conda create -n dtgblockfl_gpu python=3.10 -y
conda activate dtgblockfl_gpu
pip install -r requirements-cu118-pytorch.txt
pip install -r requirements.txt

Windows quick start

1. Double-click WIN_MENU.bat.
2. Create or repair the CPU or GPU environment.
3. Run doctor / gpu_doctor.
4. Start with smoke_femnist_dtg.yaml or a short MNIST run.
5. Move to manifest-based trend or paper-oriented experiments.

The Windows launcher auto-detects Conda from standard locations. You can also set DTG_CONDA_HOME manually before running the menu.

Linux / macOS quick start

bash scripts/setup_env.sh
python scripts/doctor.py
python scripts/validate_project.py
python run.py --config configs/smoke_femnist_dtg.yaml

Data preparation

Public datasets

python scripts/prepare_data.py

FEMNIST

Place LEAF-style FEMNIST JSON files under:

• data/raw/femnist/train/
• data/raw/femnist/test/

Then build the processed cache:

python scripts/prepare_femnist.py

Representative runs

python run.py --config configs/smoke_mnist_fedavg.yaml
python run.py --config configs/smoke_mnist_labelflip.yaml
python run.py --config configs/smoke_femnist_dtg.yaml
python scripts/launch_experiments.py --manifest manifests/trend_baselines_quick.yaml --max_workers 1

Documentation

• docs/README.md — documentation hub
• README_CN.md — Chinese homepage
• docs/03_windows/WINDOWS_FRIENDLY_GUIDE_CN.md — Chinese Windows guide
• docs/02_experiments/EXECUTION_ROADMAP_CN.md — recommended execution order
• docs/05_policy/baseline_fidelity_policy.md — fidelity boundary note

Recommended GitHub publishing flow

git init
git branch -M main
git add .
git commit -m "Initial public release v18"
git remote add origin <your-github-repo-url>
git push -u origin main

After the first push, create a GitHub Release and archive the tagged version to Zenodo if you want a citable software record.

Citation

Use the paper citation for scientific claims, and cite the exact software release for reproducibility. The repository already includes CITATION.cff so GitHub can surface a standard citation block.

License

This repository is released under the MIT License. See LICENSE.