DTG-BlockFL: Dynamic Trust Graph-Driven Secure Federated Learning with Blockchain-Based Traceability

A structured research codebase for secure federated learning under poisoning and backdoor attacks, centered on the DTG-BlockFL pipeline: anomaly-aware update modeling, dynamic trust graph construction, temporal trust evolution, trust-weighted aggregation, and append-only audit logging.

This repository is designed as a single, coherent experimental framework for running end-to-end studies across multiple datasets, attack families, baselines, ablations, and auditability analyses.

---

Abstract

Federated learning protects raw data locality, but it remains vulnerable to malicious client updates such as label flipping, model poisoning, model replacement, and stealth backdoor injection. DTG-BlockFL addresses this challenge by combining four tightly coupled components: (1) compact behavioral feature extraction from client updates, (2) malicious-probability estimation and anomaly scoring, (3) dynamic trust graph construction with temporal trust memory, and (4) survivor-aware trust-weighted aggregation with append-only audit metadata logging. The framework is organized to support reproducible experimentation on MNIST, Fashion-MNIST, CIFAR-10, CIFAR-100, and FEMNIST, with both single-run and manifest-based batch execution workflows.

---

Key features

Core DTG-BlockFL pipeline

• update feature extraction from client reports
• anomaly scoring and malicious-probability estimation
• top-k trust graph construction and graph-consistency scoring
• temporal trust update with rolling history
• survivor-aware trust-weighted aggregation
• append-only audit logging for replay and accountability analysis

Attack coverage

• label flip
• Gaussian poisoning
• model replacement
• distributed backdoor
• stealth backdoor
• slow-drift poisoning

Baselines and comparison methods

• FedAvg
• Median / Trimmed Mean / Krum / RFA
• FLTrust-style aggregation
• FLDetector-style filtering
• CONTRA-style consistency weighting
• FLEST-style history-aware trust baseline
• AlignIns-style alignment aggregation
• MARS-style malignity-aware screening
• D-Byz-SGDM-style robust server momentum

Experiment workflow

• YAML-based single-run configuration
• dotted-key runtime override support
• manifest-based batch launching
• result summarization and grouped statistics
• figure generation utilities
• Windows CPU / GPU launcher scripts

---

Repository at a glance

run.py                         # main experiment entrypoint
configs/                       # single-run experiment configurations
manifests/                     # batch experiment plans
scripts/                       # setup, diagnosis, launch, summary, plotting
src/
  attacks/                     # attack implementations
  audit/                       # append-only audit logging
  common/                      # utilities, metrics, hashing, logging
  data/                        # dataset loading and federated partitioning
  defenses/                    # DTG and baseline defenses
  eval/                        # evaluation utilities
  fl/                          # federated server/client/training flow
  models/                      # model definitions and model factory
outputs/                       # metrics, logs, registry, figures, tensorboard

Organized launcher and docs entrypoints:

• WIN_MENU.bat — root Windows launcher entry
• launchers/windows/ — categorized Windows batch launchers
• docs/README.md — documentation index

Detailed Chinese guides:

• README_CN.md
• docs/01_project/PROJECT_OVERVIEW_CN.md
• docs/01_project/CODEBASE_GUIDE_CN.md
• docs/02_experiments/EXPERIMENT_PORTFOLIO_CN.md
• docs/03_windows/WINDOWS_FRIENDLY_GUIDE_CN.md

---

Paper-results packaging note

This repository includes a paper-asset layer used both to organize the completed submission experiment campaign and to package a lightweight source release.

Added in v13:

• paper manifest generation (scripts/build_paper_manifests.py)
• paper coverage audit (scripts/check_paper_coverage.py)
• paper artifact collection (scripts/collect_paper_artifacts.py)
• stricter paper-table export (scripts/export_paper_tables.py)
• baseline fidelity policy (docs/05_policy/baseline_fidelity_policy.md)
• paper-packaging Chinese guides (docs/05_policy/READINESS_GAP_CN.md, docs/02_experiments/EXECUTION_ROADMAP_CN.md)

Current package scope:

• The manuscript is intended to use the completed full experiment archive.
• This lightweight zip may keep only smoke / example outputs in outputs/ and paper_artifacts/outputs/ to keep the package size manageable.
• Before archival release, copy or regenerate the final run_summary, grouped_summary, paper_tables, figures, and coverage JSON in the predefined directories.
• Treat the bundled example outputs as path-validation artifacts only, not as the evidence source for the paper tables.

Important scope note:

• DTG-BlockFL is implemented directly in this repository.
• The audit component is a lightweight pseudo-chain metadata logging prototype for accountability studies.
• Several advanced comparison methods in src/defenses/advanced.py are compact baseline-style reproductions, not official upstream code releases.

For a paper submission or archival release, always generate manuscript tables from actual run outputs via the manifest / summary / export pipeline.

---

Project governance and community files

This repository now includes a standard open-source project layout for public hosting and long-term maintenance:

• LICENSE — repository license
• CONTRIBUTING.md — contribution workflow and coding expectations
• CODE_OF_CONDUCT.md — community participation guidelines
• SECURITY.md — vulnerability disclosure policy
• ROADMAP.md — near-term development priorities
• docs/ — curated documentation index and topic guides
• .github/ISSUE_TEMPLATE/ — issue templates for bugs and feature requests

Windows quick start

CPU environment

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

CUDA 11.8 environment

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

Built-in Windows launchers

The repository includes click-to-run Windows launchers under launchers/windows/ and a root entry file WIN_MENU.bat.

entry points for:

• CPU environment creation
• CUDA environment creation
• GPU availability check
• doctor / project validation
• smoke runs
• quick MNIST runs
• baseline / attack / CIFAR trend experiments
• result summarization and figure generation

Recommended first-run order:

1. WIN_MENU.bat
2. In the menu, choose Environment and doctor → create CPU env / run CPU doctor
3. Then choose Quick tests → smoke test CPU / MNIST quick CPU
4. Then choose Trend experiments for baseline / attack trend runs

---

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

Sanity 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

Representative DTG experiments

python run.py --config configs/mnist_labelflip.yaml
python run.py --config configs/femnist_labelflip.yaml
python run.py --config configs/cifar10_backdoor.yaml
python run.py --config configs/cifar10_stealth_backdoor.yaml

Batch trends

python scripts/launch_experiments.py --manifest manifests/trend_baselines_quick.yaml --max_workers 1
python scripts/launch_experiments.py --manifest manifests/trend_attacks_quick.yaml --max_workers 1
python scripts/launch_experiments.py --manifest manifests/trend_cifar_quick.yaml --max_workers 1

---

Experiment portfolio

1. Sanity / smoke experiments

Purpose:

• verify data loading
• verify federated training
• verify DTG pipeline execution
• verify audit logging and metric export

Representative files:

• configs/smoke_femnist_dtg.yaml
• configs/smoke_mnist_fedavg.yaml
• configs/smoke_mnist_labelflip.yaml

2. Baseline comparison experiments

Purpose:

• compare DTG-BlockFL against classical robust aggregation and trust-aware baselines

Representative files:

• manifests/trend_baselines_quick.yaml
• manifests/paper_baselines_mnist.yaml

3. Attack trend experiments

Purpose:

• evaluate DTG across different attack families under a unified workflow

Representative files:

• manifests/trend_attacks_quick.yaml
• configs/cifar10_model_replacement.yaml
• configs/cifar10_slow_drift.yaml

4. Strong backdoor-focused experiments

Purpose:

• evaluate DTG against stronger backdoor-oriented methods on CIFAR-style settings

Representative files:

• manifests/trend_cifar_quick.yaml
• manifests/paper_backdoor_subset.yaml
• configs/cifar10_stealth_backdoor.yaml
• configs/cifar100_backdoor.yaml

5. Ablation and sensitivity experiments

Purpose:

• measure the contribution of anomaly detection, graph structure, trust memory, and filtering/weighting strategies

Representative files:

• configs/dtg_ablation.yaml
• manifests/dtg_ablation.yaml
• manifests/paper_ablation_full.yaml

A detailed Chinese experiment map is provided in docs/02_experiments/EXPERIMENT_PORTFOLIO_CN.md.

---

Outputs and reporting

After running experiments, the main outputs are organized as:

• outputs/metrics/ — run-level JSONL metric logs
• outputs/logs/ — detailed logs and audit traces
• outputs/registry/ — batch execution registry
• outputs/figures/ — generated plots
• outputs/tensorboard/ — TensorBoard logs

Summaries

python scripts/summarize_results.py
python scripts/summarize_registry.py

Plotting

python scripts/plot_metrics.py --input outputs/metrics/<run>.jsonl --outdir outputs/figures/<run>
python scripts/plot_compare.py --inputs outputs/metrics/run_a.jsonl outputs/metrics/run_b.jsonl --outdir outputs/figures/compare

---

Reproducibility notes

This repository emphasizes a self-contained and unified experimental workflow. For certain external baselines and advanced attack variants, the implementations are provided as compact in-repository reference variants so that all methods can be launched, logged, summarized, and compared within one codebase. The emphasis of this repository is engineering coherence, experiment portability, and consistent evaluation workflow.

---

Citation

If you use this repository in academic work, please cite the associated DTG-BlockFL study. A citation template is included in CITATION.cff.

@misc{dtgblockfl_framework,
  title={DTG-BlockFL: Dynamic Trust Graph-Driven Secure Federated Learning with Blockchain-Based Traceability},
  author={Anonymous},
  year={2026},
  note={Research codebase and experimental framework}
}

---

Contact and documentation

For project-level understanding and code navigation, see:

• docs/01_project/PROJECT_OVERVIEW_CN.md
• docs/01_project/CODEBASE_GUIDE_CN.md
• docs/02_experiments/EXPERIMENT_PORTFOLIO_CN.md
• docs/03_windows/WINDOWS_FRIENDLY_GUIDE_CN.md

Documentation hub

For a more repository-style documentation experience, start with docs/README.md.

Release-ready repository assets

The repository now includes additional publication and hosting assets:

• docs/04_release/RELEASE_ASSETS_GUIDE.md — what to include in a public release
• docs/04_release/REPOSITORY_PROFILE_SUGGESTIONS.md — suggested description, topics, badges, and social preview messaging
• releases/RELEASE_TEMPLATE_v12.md — release note template
• assets/ — placeholder directory for social preview, architecture overview, and branding materials
• docs/release_readiness.md — release-readiness documentation

Suggested public repository presentation

Recommended repository description:

Dynamic trust graph-driven secure federated learning with poisoning/backdoor defenses, trust-aware aggregation, and append-only auditability.

Recommended repository topics: federated-learning, secure-federated-learning, byzantine-robustness, backdoor-defense, poisoning-defense, trust-graph, anomaly-detection, blockchain-audit, pytorch, reproducibility

Release notes and packaging

Use the files under releases/ as templates when publishing source archives or preparing a formal project release page.