# snwagh/falcon-public architecture

> Architecture diagram of the GitHub repository snwagh/falcon-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snwagh/falcon-public
- Repository: https://github.com/snwagh/falcon-public

## Overview

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: [`src/Layer.h`](https://github.com/snwagh/falcon-public/blob/master/src/Layer.h) (Layer base), [`src/NeuralNetwork.cpp`](https://github.com/snwagh/falcon-public/blob/master/src/NeuralNetwork.cpp) (Neural network), [`src/main.cpp`](https://github.com/snwagh/falcon-public/blob/master/src/main.cpp) (Main process), [`src/secCompMultiParty.cpp`](https://github.com/snwagh/falcon-public/blob/master/src/secCompMultiParty.cpp) (Party control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Distributed runtime"]
  node_node_main["Main process<br/>party entrypoint<br/>[main.cpp]"]
  node_node_secondary["Secondary role<br/>party worker<br/>[secondary.cpp]"]
  node_node_multiparty["Party control<br/>orchestration"]
  node_node_connect["Socket connect<br/>network setup<br/>[connect.cpp]"]
  node_node_sockets["Basic sockets<br/>socket I/O<br/>[basicSockets.cpp]"]
end

subgraph group_group_mpc["Secure compute core"]
  node_node_secobj["AES object<br/>crypto primitive<br/>[AESObject.cpp]"]
  node_node_crypto["Crypto utils<br/>aes+hash<br/>[aes.h]"]
  node_node_miracl["MIRACL<br/>crypto library<br/>[miracl.h]"]
end

subgraph group_group_nn["Neural execution"]
  node_node_nn["Neural network<br/>model runtime<br/>[NeuralNetwork.cpp]"]
  node_node_layer["Layer base<br/>layer interface<br/>[Layer.h]"]
  node_node_fc["Fully connected<br/>dense layer<br/>[FCLayer.cpp]"]
  node_node_cnn["Convolution<br/>conv layer<br/>[CNNLayer.cpp]"]
  node_node_bn["Batch norm<br/>norm layer<br/>[BNLayer.cpp]"]
  node_node_relu["ReLU<br/>activation<br/>[ReLULayer.cpp]"]
  node_node_pool["Max pool<br/>pooling layer<br/>[MaxpoolLayer.cpp]"]
  node_node_funcs["Shared ops<br/>tensor helpers"]
end

subgraph group_group_data["Offline assets"]
  node_node_precompute["Precompute<br/>offline setup<br/>[Precompute.cpp]"]
  node_node_mnist["MNIST parse<br/>dataset adapter<br/>[MNISTParse.cpp]"]
  node_node_scripts["Model scripts<br/>artifact pipeline<br/>[MNIST_LeNet.ipynb]"]
  node_node_preload[("Preloaded models<br/>benchmark assets")]
  node_node_ipkeys["IP and keys<br/>deployment config"]
end

subgraph group_group_deps["Vendored dependencies"]
  node_node_eigen["Eigen math<br/>numeric dependency"]
end

node_node_main -->|"starts"| node_node_connect
node_node_secondary -->|"joins"| node_node_connect
node_node_connect -->|"uses"| node_node_sockets
node_node_main -->|"drives"| node_node_multiparty
node_node_secondary -->|"executes"| node_node_multiparty
node_node_multiparty -->|"invokes"| node_node_secobj
node_node_secobj -->|"depends on"| node_node_crypto
node_node_crypto -.->|"extends"| node_node_miracl
node_node_multiparty -->|"runs"| node_node_nn
node_node_nn -->|"composes"| node_node_layer
node_node_layer -->|"specializes"| node_node_fc
node_node_layer -->|"specializes"| node_node_cnn
node_node_layer -->|"specializes"| node_node_bn
node_node_layer -->|"specializes"| node_node_relu
node_node_layer -->|"specializes"| node_node_pool
node_node_nn -->|"uses"| node_node_funcs
node_node_nn -->|"computes with"| node_node_eigen
node_node_precompute -->|"feeds"| node_node_preload
node_node_scripts -.->|"prepares"| node_node_preload
node_node_mnist -->|"feeds inputs"| node_node_main
node_node_ipkeys -->|"configures"| node_node_main
node_node_ipkeys -->|"configures"| node_node_secondary
node_node_preload -->|"provides model data"| node_node_nn
node_node_precompute -->|"supports"| node_node_nn

click node_node_main "https://github.com/snwagh/falcon-public/blob/master/src/main.cpp"
click node_node_secondary "https://github.com/snwagh/falcon-public/blob/master/src/secondary.cpp"
click node_node_multiparty "https://github.com/snwagh/falcon-public/blob/master/src/secCompMultiParty.cpp"
click node_node_connect "https://github.com/snwagh/falcon-public/blob/master/src/connect.cpp"
click node_node_sockets "https://github.com/snwagh/falcon-public/blob/master/src/basicSockets.cpp"
click node_node_secobj "https://github.com/snwagh/falcon-public/blob/master/src/AESObject.cpp"
click node_node_crypto "https://github.com/snwagh/falcon-public/blob/master/util/aes.h"
click node_node_miracl "https://github.com/snwagh/falcon-public/blob/master/util/Miracl/miracl.h"
click node_node_nn "https://github.com/snwagh/falcon-public/blob/master/src/NeuralNetwork.cpp"
click node_node_layer "https://github.com/snwagh/falcon-public/blob/master/src/Layer.h"
click node_node_fc "https://github.com/snwagh/falcon-public/blob/master/src/FCLayer.cpp"
click node_node_cnn "https://github.com/snwagh/falcon-public/blob/master/src/CNNLayer.cpp"
click node_node_bn "https://github.com/snwagh/falcon-public/blob/master/src/BNLayer.cpp"
click node_node_relu "https://github.com/snwagh/falcon-public/blob/master/src/ReLULayer.cpp"
click node_node_pool "https://github.com/snwagh/falcon-public/blob/master/src/MaxpoolLayer.cpp"
click node_node_funcs "https://github.com/snwagh/falcon-public/blob/master/src/Functionalities.cpp"
click node_node_precompute "https://github.com/snwagh/falcon-public/blob/master/src/Precompute.cpp"
click node_node_mnist "https://github.com/snwagh/falcon-public/blob/master/MNIST/MNISTParse.cpp"
click node_node_scripts "https://github.com/snwagh/falcon-public/blob/master/scripts/MNIST_LeNet.ipynb"
click node_node_preload "https://github.com/snwagh/falcon-public/tree/master/files/preload/LeNet"
click node_node_ipkeys "https://github.com/snwagh/falcon-public/tree/master/files/IP_localhost"
click node_node_eigen "https://github.com/snwagh/falcon-public/tree/master/lib_eigen/Eigen/Dense"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_secondary,node_node_multiparty,node_node_connect,node_node_sockets toneBlue
class node_node_secobj,node_node_crypto,node_node_miracl toneAmber
class node_node_nn,node_node_layer,node_node_fc,node_node_cnn,node_node_bn,node_node_relu,node_node_pool,node_node_funcs toneMint
class node_node_precompute,node_node_mnist,node_node_scripts,node_node_preload,node_node_ipkeys toneRose
class node_node_eigen toneIndigo
```

## Components

### Distributed runtime

Three-party orchestration, sockets, and process entrypoints.

- [Main process](https://github.com/snwagh/falcon-public/blob/master/src/main.cpp): party entrypoint · Primary executable that starts a party role and drives the distributed run. · `src/main.cpp`
- [Secondary role](https://github.com/snwagh/falcon-public/blob/master/src/secondary.cpp): party worker · Role-specific companion process used in the three-party orchestration. · `src/secondary.cpp`
- [Party control](https://github.com/snwagh/falcon-public/blob/master/src/secCompMultiParty.cpp): orchestration · Multi-party coordination and secure-computation execution wrapper. · `src/secCompMultiParty.cpp`
- [Socket connect](https://github.com/snwagh/falcon-public/blob/master/src/connect.cpp): network setup · Connection setup and peer rendezvous logic for the party processes. · `src/connect.cpp`
- [Basic sockets](https://github.com/snwagh/falcon-public/blob/master/src/basicSockets.cpp): socket I/O · 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](https://github.com/snwagh/falcon-public/blob/master/src/AESObject.cpp): crypto primitive · Authenticated/secure computation support object used by MPC operations. · `src/AESObject.cpp`
- [Crypto utils](https://github.com/snwagh/falcon-public/blob/master/util/aes.h): aes+hash · AES, AES-NI wrappers, SHA helpers, and related utility code. · `util/aes.h`
- [MIRACL](https://github.com/snwagh/falcon-public/blob/master/util/Miracl/miracl.h): crypto library · 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](https://github.com/snwagh/falcon-public/blob/master/src/NeuralNetwork.cpp): model runtime · Top-level model assembly and layer-by-layer execution engine. · `src/NeuralNetwork.cpp`
- [Layer base](https://github.com/snwagh/falcon-public/blob/master/src/Layer.h): layer interface · Common layer abstraction and configuration boundary for model blocks. · `src/Layer.h`
- [Fully connected](https://github.com/snwagh/falcon-public/blob/master/src/FCLayer.cpp): dense layer · Dense linear layer implementation used in MNIST-style models. · `src/FCLayer.cpp`
- [Convolution](https://github.com/snwagh/falcon-public/blob/master/src/CNNLayer.cpp): conv layer · Convolutional layer implementation for CNN-style model families. · `src/CNNLayer.cpp`
- [Batch norm](https://github.com/snwagh/falcon-public/blob/master/src/BNLayer.cpp): norm layer · Batch-normalization layer implementation. · `src/BNLayer.cpp`
- [ReLU](https://github.com/snwagh/falcon-public/blob/master/src/ReLULayer.cpp): activation · Nonlinear activation layer implementation. · `src/ReLULayer.cpp`
- [Max pool](https://github.com/snwagh/falcon-public/blob/master/src/MaxpoolLayer.cpp): pooling layer · Max-pooling layer implementation. · `src/MaxpoolLayer.cpp`
- [Shared ops](https://github.com/snwagh/falcon-public/blob/master/src/Functionalities.cpp): tensor helpers · 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](https://github.com/snwagh/falcon-public/blob/master/src/Precompute.cpp): offline setup · Offline parameter generation and protocol precomputation boundary. · `src/Precompute.cpp`
- [MNIST parse](https://github.com/snwagh/falcon-public/blob/master/MNIST/MNISTParse.cpp): dataset adapter · Dataset parsing and formatting module for feeding secret-shared inputs. · `MNIST/MNISTParse.cpp`
- [Model scripts](https://github.com/snwagh/falcon-public/blob/master/scripts/MNIST_LeNet.ipynb): artifact pipeline · Notebook-based offline pipeline for preparing or post-processing model artifacts. · `scripts/MNIST_LeNet.ipynb`
- [Preloaded models](https://github.com/snwagh/falcon-public/tree/master/files/preload/LeNet): benchmark assets · Model-specific preload assets containing weights, biases, inputs, and sample outputs. · `files/preload/LeNet`
- [IP and keys](https://github.com/snwagh/falcon-public/tree/master/files/IP_localhost): deployment config · 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](https://github.com/snwagh/falcon-public/tree/master/lib_eigen/Eigen/Dense): numeric dependency · Vendored dense and tensor linear-algebra backend used by the layer implementations. · `lib_eigen/Eigen/Dense`

## Connections

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