How snwagh/falcon-public works
1. Falcon is a C++ framework for privacy-preserving deep learning inference/training in a 3-party honest-majority setting. The core design is maliciously secure replicated secret sharing, inherited from SecureNN/ABY3-style protocols, with layer-by-layer modularity instead of a monolithic network protocol.
2. The runtime is centered around three parties that exchange messages over sockets. Networking is handled in src/basicSockets.*, src/connect.*, util/socket.h, and the party orchestration code in src/main.cpp, src/secondary.cpp, src/secondary.h, and src/secCompMultiParty.*. The repository includes hardcoded IP/address files under files/IP_* plus pre-shared keys under files/key*, which are part of the deployment boundary for local/LAN/WAN execution.
3. The secure-computation layer is implemented in src/AESObject.*, util/aes*, util/TedKrovetzAesNiWrapperC.*, and the MIRACL crypto library under util/Miracl/. These pieces support randomness, authenticated/secure computation primitives, and cryptographic utilities needed by the MPC protocol.
4. The neural-network execution layer is built around src/NeuralNetwork.* and the Layer hierarchy. Concrete layer implementations include fully connected, convolution, batch norm, ReLU, and max-pooling in src/FCLayer.*, src/CNNLayer.*, src/BNLayer.*, src/ReLULayer.*, and src/MaxpoolLayer.*. Each layer has a matching config type (*Config.h) so models are assembled from parameterized blocks rather than hardcoded network graphs.
5. Model execution is dataflow-oriented: input tensors are secret-shared, passed through successive layer objects, and intermediate activations remain in the secure representation until final reconstruction. src/Functionalities.*, src/tools.*, and src/globals.h provide shared helpers, tensor operations, and reconstruction/utility logic used across layers and parties.
6. There is an explicit offline/precompute boundary. src/Precompute.* and the files/preload/ tree store pre-generated parameters and example model assets, indicating a split between protocol setup and online inference. The preload files are organized per model family (LeNet, MiniONN, Sarda, SecureML) and contain weights, biases, inputs, and layer outputs used for benchmarking and reproducing known networks.
7. The repository is network-family aware rather than single-model. The README and preload assets show support for MNIST-oriented models such as SecureML, Sarda, MiniONN, and LeNet, with scripts also referencing larger CNN workflows. The scripts/ directory contains Jupyter notebooks for generating or post-processing model artifacts, so model preparation is an external pipeline feeding the C++ runtime.
8. MNIST input handling is separated into its own module under MNIST/, with MNISTParse.cpp/h and run.sh. This looks like a dataset parsing and formatting boundary for feeding secret-sharing inputs into the secure inference pipeline.
9. Performance-critical linear algebra is delegated to vendored Eigen in lib_eigen/, especially matrix multiplication and tensor-style numeric kernels used by the layers. This is a compile-time dependency rather than a service boundary, but it materially affects the architecture because many layer operations are built on Eigen-backed dense math.
10. The build and execution tooling is native and container-friendly. Root makefile, MNIST/makefile, and the Dockerfile define build/run entry points, while god and the shell scripts simplify multi-party launches. The README makes clear that execution modes include localhost, LAN, and WAN variants, so deployment is a distributed three-process application rather than a single binary.
11. Testing and debugging are present but secondary to the runtime. src/unitTests.* provides unit coverage, while the README notes known issues in malicious-mode correctness and memory usage. This suggests the architecture is intended as a research prototype/benchmark harness with clear separation between protocol code, model definitions, and experimental data.
12. Overall data flow: model artifacts and dataset inputs are prepared offline, each party starts with its IP/key and role-specific runtime, the parties secret-share inputs, execute layer-by-layer secure inference via MPC primitives, and finally reconstruct the output. The main diagram should show three synchronized party processes, a secure compute/core layer, layer modules on top of that core, and offline assets/configuration files feeding the runtime.
Main entry points: Layer.h Layer base · NeuralNetwork.cpp Neural network · main.cpp Main process · secCompMultiParty.cpp Party control
Components 22
Distributed runtime
Three-party orchestration, sockets, and process entrypoints.
- Main process · Primary executable that starts a party role and drives the distributed run.
src/main.cpp - Secondary role · Role-specific companion process used in the three-party orchestration.
src/secondary.cpp - Party control · Multi-party coordination and secure-computation execution wrapper.
src/secCompMultiParty.cpp - Socket connect · Connection setup and peer rendezvous logic for the party processes.
src/connect.cpp - Basic sockets · Low-level socket read/write helpers used by the distributed runtime.
src/basicSockets.cpp
Secure compute core
Cryptographic primitives and MPC support used by the protocol.
- AES object · Authenticated/secure computation support object used by MPC operations.
src/AESObject.cpp - Crypto utils · AES, AES-NI wrappers, SHA helpers, and related utility code.
util/aes.h - MIRACL · Vendored public-key and big-number crypto library used by the secure protocol layer.
util/Miracl/miracl.h
Neural execution
Layered model execution and layer-specific implementations.
- Neural network · Top-level model assembly and layer-by-layer execution engine.
src/NeuralNetwork.cpp - Layer base · Common layer abstraction and configuration boundary for model blocks.
src/Layer.h - Fully connected · Dense linear layer implementation used in MNIST-style models.
src/FCLayer.cpp - Convolution · Convolutional layer implementation for CNN-style model families.
src/CNNLayer.cpp - Batch norm · Batch-normalization layer implementation.
src/BNLayer.cpp - ReLU · Nonlinear activation layer implementation.
src/ReLULayer.cpp - Max pool · Max-pooling layer implementation.
src/MaxpoolLayer.cpp - Shared ops · Utility functionality, tensor helpers, and reconstruction logic shared across the runtime.
src/Functionalities.cpp
Offline assets
Deployment files, preload artifacts, dataset parsing, and scripts.
- Precompute · Offline parameter generation and protocol precomputation boundary.
src/Precompute.cpp - MNIST parse · Dataset parsing and formatting module for feeding secret-shared inputs.
MNIST/MNISTParse.cpp - Model scripts · Notebook-based offline pipeline for preparing or post-processing model artifacts.
scripts/MNIST_LeNet.ipynb - Preloaded models · Model-specific preload assets containing weights, biases, inputs, and sample outputs.
files/preload/LeNet - IP and keys · Hardcoded addressing and pre-shared keys for local, LAN, and WAN deployments.
files/IP_localhost
Vendored dependencies
Third-party numeric and cryptographic libraries embedded in the repo.
- Eigen math · Vendored dense and tensor linear-algebra backend used by the layer implementations.
lib_eigen/Eigen/Dense
Connections 24
- Main process → Socket connect: starts · Main process initializes peer connectivity.
- Secondary role → Socket connect: joins · Secondary party process participates in connection setup.
- Socket connect → Basic sockets: uses · Connection logic is built on the socket primitives.
- Main process → Party control: drives · Main executable hands control to the multi-party coordinator.
- Secondary role → Party control: executes · Secondary role runs the secure-computation worker path.
- Party control → AES object: invokes · Multi-party runtime relies on authenticated secure-computation objects.
- AES object → Crypto utils: depends on · Secure-computation primitives use AES and hash utilities.
- Crypto utils → MIRACL: extends · Crypto utilities are complemented by MIRACL big-number and public-key routines.
- Party control → Neural network: runs · The coordinator executes the model runtime inside the MPC protocol.
- Neural network → Layer base: composes · Networks are assembled from layer objects and configs.
- Layer base → Fully connected: specializes · Dense layer is one concrete layer implementation.
- Layer base → Convolution: specializes · Convolution is one concrete layer implementation.
- Layer base → Batch norm: specializes · Batch norm is one concrete layer implementation.
- Layer base → ReLU: specializes · ReLU is one concrete layer implementation.
- Layer base → Max pool: specializes · Max pooling is one concrete layer implementation.
- Neural network → Shared ops: uses · Model execution shares tensor and reconstruction helpers.
- Neural network → Eigen math: computes with · Layer math is backed by Eigen dense and tensor kernels.
- Precompute → Preloaded models: feeds · Offline precomputation produces or consumes preload artifacts.
- Model scripts → Preloaded models: prepares · Notebooks form the offline artifact pipeline for model assets.
- MNIST parse → Main process: feeds inputs · Dataset parsing provides formatted inputs to the runtime.
- IP and keys → Main process: configures · Party addresses and keys configure the distributed run.
- IP and keys → Secondary role: configures · Role-specific deployment files configure peer processes.
- Preloaded models → Neural network: provides model data · Preloaded weights, biases, inputs, and outputs initialize and benchmark networks.
- Precompute → Neural network: supports · Precompute forms the offline boundary for secure model execution.