secure-fl 2026.2.22.dev1__tar.gz → 2026.3.16.dev1__tar.gz

{secure_fl-2026.2.22.dev1 → secure_fl-2026.3.16.dev1}/.gitignore

@@ -102,12 +102,15 @@ dmypy.json
 # ===========================
 # Runtime logs and results
 logs/
-results/
+results/*
+!results/gpu_convergence_mnist/
+!results/gpu_convergence_cifar10/
+!results/gpu_convergence_synthetic_small/
+!results/gpu_convergence_medmnist_resnet18/
 results_bak/
 *.log
 
 # Data directories
-data/
 datasets/
 
 # ZKP artifacts
@@ -123,6 +126,13 @@ proofs/compiled/
 *.vkey
 *.zkey
 
+# pysnark debug/trace output files
+pysnark_eqs
+pysnark_eqs_main
+pysnark_schedule
+pysnark_values
+pysnark_wires
+
 # Temporary files
 temp/
 tmp/
@@ -171,9 +181,6 @@ Thumbs.db
 # Ruff cache
 .ruff_cache/
 
-# Benchmarking results
-benchmarks/
-performance_results/
 
 # Docker
 .dockerignore

{secure_fl-2026.2.22.dev1 → secure_fl-2026.3.16.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-fl
-Version: 2026.2.22.dev1
+Version: 2026.3.16.dev1
 Summary: Dual-Verifiable Framework for Federated Learning using Zero-Knowledge Proofs
 Project-URL: Homepage, https://github.com/krishantt/secure-fl
 Project-URL: Bug Reports, https://github.com/krishantt/secure-fl/issues

secure_fl-2026.3.16.dev1/docs/research paper/README.md

@@ -0,0 +1,13 @@
+# Research Paper Draft
+
+This folder contains a publication-style consolidation of the current project results.
+
+- Source: `main.tex`
+- References: `refs.bib`
+- Output: `main.pdf`
+
+Compile with Docker:
+
+```bash
+docker run --rm -v "$(pwd)":/work -w /work texlive/texlive latexmk -pdf main.tex
+```

secure_fl-2026.3.16.dev1/src/secure_fl/.build_number

@@ -0,0 +1 @@
+2026.03.16:1

{secure_fl-2026.2.22.dev1 → secure_fl-2026.3.16.dev1}/src/secure_fl/__init__.py

@@ -115,13 +115,12 @@ from .federation import StabilityMonitor
 from .federation import create_client
 from .federation import create_server_strategy
 from .federation import start_client
-from .models import CIFAR10Model
-from .models import FlexibleMLP
-from .models import MNISTModel
-from .models import ResNetBlock
+from .models import MNISTCNN
+from .models import ResNet18Model
 
 # Models
 from .models import SimpleModel
+from .models import model_fn
 from .utils import AuditLogger
 from .utils import PerformanceLogger
 from .utils import SecureFlLogger
@@ -305,10 +304,9 @@ __all__ = [
     "validate_proof_rigor",
     # Models
     "SimpleModel",
-    "MNISTModel",
-    "CIFAR10Model",
-    "FlexibleMLP",
-    "ResNetBlock",
+    "MNISTCNN",
+    "ResNet18Model",
+    "model_fn",
 ]
 
 
@@ -317,20 +315,23 @@ def get_default_config_dict() -> dict[str, Any]:
     return get_default_config().to_dict()
 
 
-def print_system_info() -> None:
-    """Print system information and component status."""
-    print(f"Secure FL v{__version__}")
-    print(f"Description: {__description__}")
-    print(f"Authors: {__author__}")
-    print()
+def _command_available(command: list[str], timeout: int = 5) -> bool:
+    import subprocess
 
-    # Check component availability
+    try:
+        result = subprocess.run(command, capture_output=True, timeout=timeout)
+        return result.returncode == 0
+    except (subprocess.SubprocessError, OSError, FileNotFoundError):
+        return False
+
+
+def _get_component_status() -> dict[str, bool]:
     components = {
-        "Flower": True,  # Always available if imported
-        "PyTorch": True,
-        "Cairo": False,  # Would need to check installation
-        "Circom": False,  # Would need to check installation
-        "SnarkJS": False,  # Would need to check installation
+        "Flower": False,
+        "PyTorch": False,
+        "Cairo": _command_available(["cairo-compile", "--version"]),
+        "Circom": _command_available(["circom", "--version"]),
+        "SnarkJS": _command_available(["snarkjs", "help"]),
     }
 
     try:
@@ -338,37 +339,26 @@ def print_system_info() -> None:
 
         components["PyTorch"] = True
     except ImportError:
-        components["PyTorch"] = False
+        pass
 
     try:
         import flwr  # noqa: F401
 
         components["Flower"] = True
     except ImportError:
-        components["Flower"] = False
+        pass
 
-    # Check external tools
-    import subprocess
+    return components
 
-    try:
-        result = subprocess.run(
-            ["cairo-compile", "--version"], capture_output=True, timeout=5
-        )
-        components["Cairo"] = result.returncode == 0
-    except (subprocess.SubprocessError, OSError, FileNotFoundError):
-        pass
 
-    try:
-        result = subprocess.run(["circom", "--version"], capture_output=True, timeout=5)
-        components["Circom"] = result.returncode == 0
-    except (subprocess.SubprocessError, OSError, FileNotFoundError):
-        pass
+def print_system_info() -> None:
+    """Print system information and component status."""
+    print(f"Secure FL v{__version__}")
+    print(f"Description: {__description__}")
+    print(f"Authors: {__author__}")
+    print()
 
-    try:
-        result = subprocess.run(["snarkjs", "help"], capture_output=True, timeout=5)
-        components["SnarkJS"] = result.returncode == 0
-    except (subprocess.SubprocessError, OSError, FileNotFoundError):
-        pass
+    components = _get_component_status()
 
     print("Component Status:")
     for component, available in components.items():
@@ -447,7 +437,6 @@ def create_secure_fl_setup(
                     if isinstance(client_config.proof_rigor, ProofRigor)
                     else client_config.proof_rigor
                 ),
-                quantize_weights=client_config.quantize_weights,
                 quantization_bits=(
                     client_config.quantization_bits.value
                     if isinstance(client_config.quantization_bits, QuantizationBits)

secure_fl-2026.3.16.dev1/src/secure_fl/benchmarks/__init__.py

@@ -0,0 +1,30 @@
+"""Benchmark orchestration helpers for experiment entrypoints."""
+
+from secure_fl.data.benchmark_data import SUPPORTED_DATASETS
+from secure_fl.data.benchmark_data import load_dataset
+from secure_fl.data.benchmark_data import maybe_subsample_dataset
+from secure_fl.data.benchmark_data import normalize_datasets
+from secure_fl.data.benchmark_data import partition_dataset
+from secure_fl.models.factory import model_fn
+
+from .defaults import PAPER_DEFAULT_ROUNDS
+from .defaults import resolve_num_rounds
+from .execution import run_training_rounds
+from .pipeline import run_single
+from .reporting import build_tradeoff_report
+from .reporting import summarize_repeats
+
+__all__ = [
+    "PAPER_DEFAULT_ROUNDS",
+    "resolve_num_rounds",
+    "SUPPORTED_DATASETS",
+    "normalize_datasets",
+    "load_dataset",
+    "partition_dataset",
+    "maybe_subsample_dataset",
+    "model_fn",
+    "run_single",
+    "run_training_rounds",
+    "summarize_repeats",
+    "build_tradeoff_report",
+]

secure_fl-2026.3.16.dev1/src/secure_fl/benchmarks/defaults.py

@@ -0,0 +1,15 @@
+"""Default benchmark profiles used by publication-oriented experiments."""
+
+PAPER_DEFAULT_ROUNDS = {
+    "mnist": 100,
+    "cifar10": 150,
+    "medmnist": 120,
+    "synthetic_small": 100,
+}
+
+
+def resolve_num_rounds(dataset: str, requested_num_rounds: int) -> int:
+    """Resolve round count using paper defaults when request is 0."""
+    if requested_num_rounds > 0:
+        return requested_num_rounds
+    return int(PAPER_DEFAULT_ROUNDS.get(dataset, 100))

secure_fl-2026.3.16.dev1/src/secure_fl/benchmarks/execution.py

@@ -0,0 +1,383 @@
+"""Round-execution utilities shared by benchmark entrypoints."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+import numpy as np
+import torch
+from torch.utils.data import DataLoader
+
+from secure_fl.federation.stability_monitor import StabilityMonitor
+from secure_fl.zkp.proof_manager import ServerProofManager
+
+
+def evaluate_global(
+    model_fn: Any,
+    params: list[np.ndarray],
+    test_set: torch.utils.data.Dataset,
+    batch_size: int,
+) -> dict[str, float]:
+    """Evaluate current global model on the provided test set."""
+    from secure_fl import ndarrays_to_torch
+
+    model = model_fn()
+    ndarrays_to_torch(model, params)
+    model.eval()
+    loader = DataLoader(test_set, batch_size=batch_size, shuffle=False)
+    criterion = torch.nn.CrossEntropyLoss()
+
+    correct = 0
+    total = 0
+    total_loss = 0.0
+    with torch.no_grad():
+        for x, y in loader:
+            if isinstance(y, torch.Tensor) and y.ndim > 1:
+                y = y.view(-1)
+            out = model(x)
+            loss = criterion(out, y)
+            total_loss += float(loss.item()) * x.size(0)
+            pred = out.argmax(dim=1)
+            correct += int((pred == y).sum().item())
+            total += int(y.size(0))
+
+    return {
+        "accuracy": (correct / total) if total else 0.0,
+        "loss": (total_loss / total) if total else 0.0,
+    }
+
+
+def run_training_rounds(
+    *,
+    clients: list[Any],
+    config: dict[str, Any],
+    model_fn: Any,
+    global_params: list[np.ndarray],
+    aggregator: Any,
+    test_set: torch.utils.data.Dataset,
+    num_rounds: int,
+    clients_per_round: int,
+    local_epochs: int,
+    batch_size: int,
+    require_real_proofs: bool,
+    min_proof_coverage: float,
+    dataset: str,
+) -> dict[str, Any]:
+    """Execute FL rounds and return round-level and summary benchmark metrics."""
+    is_dynamic = config["proof_rigor"] == "dynamic"
+    stability_monitor: StabilityMonitor | None = (
+        StabilityMonitor() if is_dynamic else None
+    )
+    current_rigor = "high" if is_dynamic else config["proof_rigor"]
+    server_proof_manager = ServerProofManager() if config["enable_zkp"] else None
+
+    rounds: list[dict[str, Any]] = []
+    proof_coverage_values: list[float] = []
+
+    for round_idx in range(num_rounds):
+        round_start = time.perf_counter()
+        old_global_params = [p.copy() for p in global_params]
+        model_payload_bytes = float(_ndarrays_nbytes(old_global_params))
+        updates: list[list[np.ndarray]] = []
+        weights: list[int] = []
+        client_proof_times: list[float] = []
+        client_verification_times: list[float] = []
+        proof_payload_count = 0
+        verified_client_count = 0
+        losses: list[float] = []
+        total_client_upload_bytes = 0.0
+        total_client_update_bytes = 0.0
+        total_client_proof_bytes = 0.0
+
+        sampled_count = min(max(1, clients_per_round), len(clients))
+        sampled_clients = list(
+            np.random.choice(clients, size=sampled_count, replace=False)
+        )
+
+        for client in sampled_clients:
+            updated_params, num_examples, metrics = client.fit(
+                global_params,
+                {
+                    "server_round": round_idx + 1,
+                    "local_epochs": local_epochs,
+                    "learning_rate": 0.01,
+                    "proof_rigor": current_rigor,
+                    "enable_zkp": config["enable_zkp"],
+                },
+            )
+
+            client_proof_times.append(float(metrics.get("proof_time", 0.0)))
+            raw_proof = metrics.get("zkp_proof")
+            update_bytes = float(_ndarrays_nbytes(updated_params))
+            proof_bytes = float(_serialized_size_bytes(raw_proof))
+            total_client_update_bytes += update_bytes
+            total_client_proof_bytes += proof_bytes
+            total_client_upload_bytes += update_bytes + proof_bytes
+            has_real_proof = _has_real_proof(raw_proof)
+            if has_real_proof:
+                proof_payload_count += 1
+
+            is_verified = True
+            if config["enable_zkp"]:
+                is_verified = False
+                if has_real_proof and server_proof_manager is not None:
+                    verify_start = time.perf_counter()
+                    is_verified = server_proof_manager.verify_client_proof(
+                        raw_proof,
+                        updated_parameters=updated_params,
+                        old_global_params=old_global_params,
+                    )
+                    client_verification_times.append(time.perf_counter() - verify_start)
+
+            if is_verified:
+                updates.append(updated_params)
+                weights.append(num_examples)
+                losses.append(float(metrics.get("train_loss", 0.0)))
+                verified_client_count += 1
+
+        if not updates or not weights:
+            raise RuntimeError(
+                f"No verified client updates available for {dataset}/{config['name']} "
+                f"round {round_idx + 1}."
+            )
+
+        weight_sum = sum(weights)
+        norm_weights = [w / weight_sum for w in weights]
+        global_params = aggregator.aggregate(
+            updates, norm_weights, round_idx + 1, global_params
+        )
+
+        server_proof_time = 0.0
+        server_proof_generated = 0.0
+        server_proof_payload_bytes = 0.0
+        rigor_this_round = current_rigor
+        if (
+            config["enable_zkp"]
+            and server_proof_manager is not None
+            and should_generate_server_proof(rigor_this_round, round_idx + 1)
+        ):
+            proof_start = time.perf_counter()
+            server_proof = server_proof_manager.generate_server_proof(
+                client_updates=updates,
+                client_weights=norm_weights,
+                aggregated_params=global_params,
+                old_params=old_global_params,
+                momentum=aggregator.server_momentum
+                if aggregator.server_momentum is not None
+                else [np.zeros_like(p) for p in global_params],
+                momentum_coeff=aggregator.momentum,
+            )
+            server_proof_time = float(time.perf_counter() - proof_start)
+            server_proof_generated = 1.0 if server_proof else 0.0
+            server_proof_payload_bytes = float(_serialized_size_bytes(server_proof))
+
+        if stability_monitor is not None:
+            client_metrics_agg: dict[str, Any] = {}
+            if losses:
+                client_metrics_agg["train_loss"] = float(np.mean(losses))
+            if client_proof_times:
+                client_metrics_agg["proof_time"] = float(np.mean(client_proof_times))
+            stability_monitor.update(
+                global_params, round_idx + 1, client_metrics_agg or None
+            )
+            current_rigor = stability_monitor.get_recommended_rigor()
+
+        proof_coverage = (
+            proof_payload_count / len(sampled_clients) if sampled_clients else 0.0
+        )
+        proof_coverage_values.append(proof_coverage)
+
+        if (
+            config["enable_zkp"]
+            and require_real_proofs
+            and proof_coverage < min_proof_coverage
+        ):
+            raise RuntimeError(
+                "Real proof requirement failed for "
+                f"{dataset}/{config['name']} round {round_idx + 1}: "
+                f"coverage={proof_coverage:.3f}, expected>={min_proof_coverage:.3f}. "
+                "Check Circom/SnarkJS/PySNARK setup before benchmarking."
+            )
+
+        eval_metrics = evaluate_global(model_fn, global_params, test_set, batch_size)
+        server_model_broadcast_bytes = float(len(sampled_clients)) * model_payload_bytes
+        server_proof_broadcast_bytes = (
+            float(len(sampled_clients)) * server_proof_payload_bytes
+        )
+        total_round_communication_bytes = (
+            total_client_upload_bytes
+            + server_model_broadcast_bytes
+            + server_proof_broadcast_bytes
+        )
+        rounds.append(
+            {
+                "round": float(round_idx + 1),
+                "round_time_sec": float(time.perf_counter() - round_start),
+                "avg_client_proof_time_sec": float(
+                    np.mean(client_proof_times) if client_proof_times else 0.0
+                ),
+                "avg_client_verification_time_sec": float(
+                    np.mean(client_verification_times)
+                    if client_verification_times
+                    else 0.0
+                ),
+                "server_proof_time_sec": float(server_proof_time),
+                "server_proof_generated": float(server_proof_generated),
+                "proof_payload_coverage": float(proof_coverage),
+                "verified_clients": float(verified_client_count),
+                "submitted_clients": float(len(sampled_clients)),
+                "client_upload_bytes": float(total_client_upload_bytes),
+                "client_update_bytes": float(total_client_update_bytes),
+                "client_proof_payload_bytes": float(total_client_proof_bytes),
+                "avg_client_upload_bytes": float(total_client_upload_bytes)
+                / float(len(sampled_clients) if sampled_clients else 1),
+                "server_model_broadcast_bytes": float(server_model_broadcast_bytes),
+                "server_proof_payload_bytes": float(server_proof_payload_bytes),
+                "server_proof_broadcast_bytes": float(server_proof_broadcast_bytes),
+                "total_communication_bytes": float(total_round_communication_bytes),
+                "avg_train_loss": float(np.mean(losses) if losses else 0.0),
+                "accuracy": eval_metrics["accuracy"],
+                "eval_loss": eval_metrics["loss"],
+                "proof_rigor": rigor_this_round,
+            }
+        )
+
+    return {
+        "global_params": global_params,
+        "rounds": rounds,
+        "summary": {
+            "final_accuracy": rounds[-1]["accuracy"] if rounds else 0.0,
+            "final_eval_loss": rounds[-1]["eval_loss"] if rounds else 0.0,
+            "mean_round_time_sec": float(np.mean([r["round_time_sec"] for r in rounds]))
+            if rounds
+            else 0.0,
+            "mean_client_proof_time_sec": float(
+                np.mean([r["avg_client_proof_time_sec"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_client_verification_time_sec": float(
+                np.mean([r["avg_client_verification_time_sec"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_server_proof_time_sec": float(
+                np.mean([r["server_proof_time_sec"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "server_proof_generation_rate": float(
+                np.mean([r["server_proof_generated"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_total_proof_time_sec": float(
+                np.mean(
+                    [
+                        r["avg_client_proof_time_sec"] + r["server_proof_time_sec"]
+                        for r in rounds
+                    ]
+                )
+            )
+            if rounds
+            else 0.0,
+            "mean_proof_payload_coverage": float(np.mean(proof_coverage_values))
+            if proof_coverage_values
+            else 0.0,
+            "mean_client_upload_bytes": float(
+                np.mean([r["client_upload_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_client_update_bytes": float(
+                np.mean([r["client_update_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_client_proof_payload_bytes": float(
+                np.mean([r["client_proof_payload_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_avg_client_upload_bytes": float(
+                np.mean([r["avg_client_upload_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_server_model_broadcast_bytes": float(
+                np.mean([r["server_model_broadcast_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_server_proof_payload_bytes": float(
+                np.mean([r["server_proof_payload_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_server_proof_broadcast_bytes": float(
+                np.mean([r["server_proof_broadcast_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+            "mean_total_communication_bytes": float(
+                np.mean([r["total_communication_bytes"] for r in rounds])
+            )
+            if rounds
+            else 0.0,
+        },
+    }
+
+
+def should_generate_server_proof(rigor: str, server_round: int) -> bool:
+    """Match server strategy cadence for server proof generation."""
+    if rigor == "high":
+        return True
+    if rigor == "medium":
+        return server_round % 2 == 0
+    if rigor == "low":
+        return server_round % 5 == 0
+    return False
+
+
+def _has_real_proof(raw_proof: Any) -> bool:
+    if not raw_proof:
+        return False
+
+    proof_obj: dict[str, Any] | None = None
+    if isinstance(raw_proof, str):
+        try:
+            parsed = json.loads(raw_proof)
+            if isinstance(parsed, dict):
+                proof_obj = parsed
+        except json.JSONDecodeError:
+            return False
+    elif isinstance(raw_proof, dict):
+        proof_obj = raw_proof
+
+    if not proof_obj:
+        return False
+
+    pysnark = proof_obj.get("pysnark")
+    if isinstance(pysnark, dict):
+        return bool(pysnark.get("enabled", False)) and "error" not in pysnark
+
+    return False
+
+
+def _ndarrays_nbytes(arrays: list[np.ndarray]) -> int:
+    return int(sum(int(arr.nbytes) for arr in arrays))
+
+
+def _serialized_size_bytes(payload: Any) -> int:
+    if payload is None:
+        return 0
+    if isinstance(payload, bytes):
+        return len(payload)
+    if isinstance(payload, str):
+        return len(payload.encode("utf-8"))
+    try:
+        return len(json.dumps(payload, sort_keys=True).encode("utf-8"))
+    except Exception:
+        return 0