# encryptogroup/motion architecture

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

- Interactive diagram: https://gitdiagram.com/encryptogroup/motion
- Repository: https://github.com/encryptogroup/motion

## Overview

1. MOTION is a C++20 framework for mixed-protocol secure multi-party computation. The core deliverable is a reusable library under `src/motioncore`, with optional example executables under `src/examples` and tests under `src/test`.

2. The highest-level runtime boundary is the “party” abstraction: each participant runs a local `Party`/`Backend` instance, loads a protocol configuration, and participates in distributed computation through a communication layer. The framework is designed for multiple parties executing the same circuit/protocol logic with secret-shared or garbled values.

3. Communication is isolated in `src/motioncore/communication`. It provides a transport-agnostic message system plus concrete transports:
   - `tcp_transport` for real network communication
   - `dummy_transport` for local or test execution
   - message classes such as hello and garbled-circuit messages
   FlatBuffers definitions live in `fbs/`, so serialized messages are a distinct boundary from protocol logic.

4. Protocol execution is centered around the generic `gate`, `wire`, `share`, and `share_wrapper` abstractions. Concrete protocol families implement these interfaces in subdirectories under `src/motioncore/protocols`, which is the main architectural partition of the computation layer.

5. The supported protocol families include boolean GMW, arithmetic GMW, BMR, garbled circuits, Astra, and constant shares. This means the framework can represent the same application at different abstraction levels and switch between protocols or mix them within one computation. Conversions between domains are handled explicitly in `protocols/conversion`, while `protocols/data_management` provides SIMD-style packing/unpacking and subset selection.

6. The garbled-circuit path is a major subsystem. It has its own provider, gate, share, wire, and constants, and it connects to dedicated message types in communication. This indicates a full end-to-end offline/online flow for garbled computation rather than a thin wrapper over another protocol.

7. Oblivious transfer is a separate foundational layer in `src/motioncore/oblivious_transfer`. It includes base OT providers and KK13-style 1-out-of-n OT flavors/providers. These primitives feed other protocol layers, especially garbled circuits and OT-based extensions.

8. Multiplication triples and Beaver-style randomness are another core service layer in `src/motioncore/multiplication_triple`. Providers for different share types supply preprocessed correlated randomness to arithmetic-style protocols. This preprocessing layer is structurally separate from online gate execution.

9. Cryptographic and randomness primitives are centralized in `src/motioncore/primitives`. This includes AES-NI helpers, BLAKE2b, Curve25519 code, PRGs, and RNG backends such as OpenSSL and AES-CTR. These primitives support OT, preprocessing, and protocol-specific randomness generation.

10. Application code is intentionally separated from the core framework. The examples in `src/examples` show how to build end-user MPC programs such as AES-128, SHA-256, the millionaires’ problem, benchmarking apps, and tutorial workloads like inner product and cross-tabs. This makes the repo both a library and a collection of reference deployments.

11. The `circuits/` directory contains Bristol-format circuit descriptions and metadata for integer, float, and advanced functions like AES and SHA. These are externalized circuit assets consumed by protocol implementations, especially garbled-circuit-based ones, and they serve as the bridge between high-level applications and low-level gate networks.

12. Supporting infrastructure is substantial but secondary to the computation stack: `utility/` contains threading/fiber pools, queues, logging, bit containers, and runtime helpers; `statistics/` collects runtime measurements; `data_storage/` holds OT extension state. This separation shows that MOTION’s architecture is layered around distributed protocol execution, with shared infrastructure reused across protocols and applications.

13. Build and portability are managed with CMake, optional bundled dependencies in `extern/`, and Docker for a reproducible environment. The repo also uses GoogleTest for validation and Benchmarks for performance experiments, reinforcing that this is a research/experimental MPC platform rather than an application-specific product.

Main entry points: [`src/motioncore/base/backend.h`](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/base/backend.h) (Backend), [`src/motioncore/communication/communication_layer.h`](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/communication_layer.h) (Comm layer), [`src/motioncore/protocols/boolean_gmw/boolean_gmw_gate.h`](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/boolean_gmw/boolean_gmw_gate.h) (GMW / BMR / Astra), [`src/motioncore/communication/transport.h`](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/transport.h) (Transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_party["Party<br/>runtime entry<br/>[party.h]"]
  node_backend["Backend<br/>runtime core<br/>[backend.h]"]
  node_configuration["Config<br/>setup<br/>[configuration.h]"]
  node_executor["Gate exec<br/>scheduler<br/>[gate_executor.h]"]
end

subgraph group_comm["Communication"]
  node_comm_layer["Comm layer<br/>messaging hub"]
  node_transport["Transport<br/>abstraction<br/>[transport.h]"]
  node_tcp_transport["TCP<br/>network transport<br/>[tcp_transport.h]"]
  node_dummy_transport["Dummy<br/>test transport<br/>[dummy_transport.h]"]
  node_message_mgr["Message mgr<br/>dispatch<br/>[message_manager.h]"]
  node_fbs["FlatBuffers<br/>wire format<br/>[message.fbs]"]
end

subgraph group_protocols["Protocols"]
  node_gate["Gate<br/>protocol primitive<br/>[gate.h]"]
  node_wire(("Wire<br/>value carrier<br/>[wire.h]"))
  node_share(("Share<br/>secret value<br/>[share.h]"))
  node_share_wrapper(("Share wrap<br/>adapter<br/>[share_wrapper.h]"))
  node_gc["Garbled circuits<br/>protocol family"]
  node_gmw["GMW / BMR / Astra<br/>protocol families<br/>[boolean_gmw_gate.h]"]
  node_conversion["Conversions<br/>domain bridge<br/>[conversion_gate.h]"]
  node_data_mgmt["Data mgmt<br/>packing<br/>[simdify_gate.h]"]
end

subgraph group_crypto["Crypto primitives"]
  node_ot["Oblivious transfer<br/>primitive layer<br/>[ot_provider.h]"]
  node_primitives["Crypto primitives<br/>crypto core"]
end

subgraph group_infra["Infrastructure"]
  node_mt["Mul triples<br/>preprocessing<br/>[mt_provider.h]"]
  node_utility["Utility<br/>runtime support<br/>[helpers.h]"]
  node_stats["Statistics<br/>measurement"]
  node_storage[("OT storage<br/>state store")]
end

subgraph group_apps["Applications"]
  node_examples["Examples<br/>apps<br/>[CMakeLists.txt]"]
  node_bench["Benchmarks<br/>apps<br/>[CMakeLists.txt]"]
end

subgraph group_assets["Assets"]
  node_circuits["Circuits<br/>assets<br/>[aes_128.bristol]"]
end

node_party -->|"loads"| node_configuration
node_party -->|"owns"| node_backend
node_backend -->|"uses"| node_comm_layer
node_backend -->|"drives"| node_executor
node_comm_layer -->|"abstracts"| node_transport
node_transport -->|"implements"| node_tcp_transport
node_transport -->|"implements"| node_dummy_transport
node_comm_layer -->|"routes"| node_message_mgr
node_message_mgr -->|"serializes"| node_fbs
node_gate -->|"operates on"| node_wire
node_wire -->|"backing"| node_share
node_share -->|"adapts"| node_share_wrapper
node_gmw -->|"implements"| node_gate
node_gmw -->|"implements"| node_share
node_gmw -->|"implements"| node_wire
node_gc -->|"exchanges"| node_comm_layer
node_gc -->|"depends on"| node_ot
node_conversion -->|"converts"| node_share_wrapper
node_data_mgmt -->|"packs"| node_share_wrapper
node_ot -->|"uses"| node_primitives
node_mt -->|"uses"| node_primitives
node_mt -->|"persists"| node_storage
node_primitives -->|"supports"| node_utility
node_stats -->|"integrates"| node_utility
node_examples -->|"uses"| node_backend
node_examples -->|"consumes"| node_circuits
node_bench -->|"measures"| node_executor
node_circuits -->|"feeds"| node_gc

click node_party "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/base/party.h"
click node_backend "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/base/backend.h"
click node_configuration "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/base/configuration.h"
click node_executor "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/executor/gate_executor.h"
click node_comm_layer "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/communication_layer.h"
click node_transport "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/transport.h"
click node_tcp_transport "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/tcp_transport.h"
click node_dummy_transport "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/dummy_transport.h"
click node_message_mgr "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/message_manager.h"
click node_fbs "https://github.com/encryptogroup/motion/blob/dev/fbs/message.fbs"
click node_gate "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/gate.h"
click node_wire "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/wire.h"
click node_share "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/share.h"
click node_share_wrapper "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/share_wrapper.h"
click node_gc "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/garbled_circuit/garbled_circuit_provider.h"
click node_gmw "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/boolean_gmw/boolean_gmw_gate.h"
click node_conversion "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/conversion/conversion_gate.h"
click node_data_mgmt "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/data_management/simdify_gate.h"
click node_ot "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/oblivious_transfer/ot_provider.h"
click node_mt "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/multiplication_triple/mt_provider.h"
click node_primitives "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/primitives/pseudo_random_generator.h"
click node_utility "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/utility/helpers.h"
click node_stats "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/statistics/run_time_statistics.h"
click node_storage "https://github.com/encryptogroup/motion/blob/dev/src/motioncore/data_storage/ot_extension_data.h"
click node_examples "https://github.com/encryptogroup/motion/blob/dev/src/examples/CMakeLists.txt"
click node_bench "https://github.com/encryptogroup/motion/blob/dev/src/benchmark/CMakeLists.txt"
click node_circuits "https://github.com/encryptogroup/motion/blob/dev/circuits/advanced/aes_128.bristol"

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_party,node_backend,node_configuration,node_executor,node_circuits toneBlue
class node_comm_layer,node_transport,node_tcp_transport,node_dummy_transport,node_message_mgr,node_fbs toneAmber
class node_gate,node_wire,node_share,node_share_wrapper,node_gc,node_gmw,node_conversion,node_data_mgmt toneMint
class node_ot,node_primitives toneRose
class node_mt,node_utility,node_stats,node_storage toneIndigo
class node_examples,node_bench toneTeal
```

## Components

### Core runtime

Party lifecycle, backend orchestration, and execution scheduling.

- [Party](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/base/party.h): runtime entry · Represents one participant in a distributed MPC run. · `src/motioncore/base/party.h`
- [Backend](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/base/backend.h): runtime core · Coordinates protocol setup and local execution for a party. · `src/motioncore/base/backend.h`
- [Config](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/base/configuration.h): setup · Loads and holds protocol and runtime configuration. · `src/motioncore/base/configuration.h`
- [Gate exec](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/executor/gate_executor.h): scheduler · Executes protocol gates and drives computation order. · `src/motioncore/executor/gate_executor.h`

### Communication

Transport-agnostic messaging and concrete network backends.

- [Comm layer](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/communication_layer.h): messaging hub · Routes messages between protocol logic and transports. · `src/motioncore/communication/communication_layer.h`
- [Transport](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/transport.h): abstraction · Abstract transport interface for message delivery. · `src/motioncore/communication/transport.h`
- [TCP](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/tcp_transport.h): network transport · Concrete network transport for real multi-party communication. · `src/motioncore/communication/tcp_transport.h`
- [Dummy](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/dummy_transport.h): test transport · Local transport for testing and single-process execution. · `src/motioncore/communication/dummy_transport.h`
- [Message mgr](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/communication/message_manager.h): dispatch · Creates, parses, and dispatches typed protocol messages. · `src/motioncore/communication/message_manager.h`
- [FlatBuffers](https://github.com/encryptogroup/motion/blob/dev/fbs/message.fbs): wire format · Serialized message definitions for communication payloads. · `fbs/message.fbs`

### Protocols

Generic MPC abstractions and concrete protocol families.

- [Gate](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/gate.h): protocol primitive · Common computation unit across protocol families. · `src/motioncore/protocols/gate.h`
- [Wire](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/wire.h): value carrier · Represents protocol-specific wire state flowing through gates. · `src/motioncore/protocols/wire.h`
- [Share](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/share.h): secret value · Base abstraction for secret-shared or garbled values. · `src/motioncore/protocols/share.h`
- [Share wrap](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/share_wrapper.h): adapter · Wraps shares for type-safe protocol use and conversions. · `src/motioncore/protocols/share_wrapper.h`
- [Garbled circuits](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/garbled_circuit/garbled_circuit_provider.h): protocol family · Full garbled-circuit stack with provider, gates, shares, wires, and constants. · `src/motioncore/protocols/garbled_circuit/garbled_circuit_provider.h`
- [GMW / BMR / Astra](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/boolean_gmw/boolean_gmw_gate.h): protocol families · Boolean and arithmetic secret-sharing families plus BMR and Astra implementations. · `src/motioncore/protocols/boolean_gmw/boolean_gmw_gate.h`
- [Conversions](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/conversion/conversion_gate.h): domain bridge · Explicit conversions between share domains and protocol types. · `src/motioncore/protocols/conversion/conversion_gate.h`
- [Data mgmt](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/protocols/data_management/simdify_gate.h): packing · SIMD packing, unpacking, and subset selection utilities. · `src/motioncore/protocols/data_management/simdify_gate.h`

### Crypto primitives

Randomness and cryptographic building blocks used across the stack.

- [Oblivious transfer](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/oblivious_transfer/ot_provider.h): primitive layer · Base OT and KK13-style OT providers used by higher-level protocols. · `src/motioncore/oblivious_transfer/ot_provider.h`
- [Crypto primitives](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/primitives/pseudo_random_generator.h): crypto core · AES, hashes, curves, PRGs, and RNG backends supporting OT and preprocessing. · `src/motioncore/primitives/pseudo_random_generator.h`

### Infrastructure

Shared runtime utilities, preprocessing storage, and statistics.

- [Mul triples](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/multiplication_triple/mt_provider.h): preprocessing · Beaver-style correlated randomness providers for arithmetic protocols. · `src/motioncore/multiplication_triple/mt_provider.h`
- [Utility](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/utility/helpers.h): runtime support · Threads, fibers, queues, logging, bit containers, and helpers. · `src/motioncore/utility/helpers.h`
- [Statistics](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/statistics/run_time_statistics.h): measurement · Runtime measurement and analysis collection. · `src/motioncore/statistics/run_time_statistics.h`
- [OT storage](https://github.com/encryptogroup/motion/blob/dev/src/motioncore/data_storage/ot_extension_data.h): state store · Persistent state for OT extension and related preprocessing. · `src/motioncore/data_storage/ot_extension_data.h`

### Applications

Example programs and benchmarks built on top of the library.

- [Examples](https://github.com/encryptogroup/motion/blob/dev/src/examples/CMakeLists.txt): apps · Reference MPC applications and tutorials built on the framework. · `src/examples/CMakeLists.txt`
- [Benchmarks](https://github.com/encryptogroup/motion/blob/dev/src/benchmark/CMakeLists.txt): apps · Microbenchmarks for protocol and runtime performance. · `src/benchmark/CMakeLists.txt`

### Assets

External circuit descriptions consumed by protocol implementations.

- [Circuits](https://github.com/encryptogroup/motion/blob/dev/circuits/advanced/aes_128.bristol): assets · Bristol-format circuit assets for arithmetic, float, and advanced functions. · `circuits/advanced/aes_128.bristol`

## Connections

- Party → Config: loads · A party uses configuration to initialize its runtime.
- Party → Backend: owns · The backend is the local execution context for one party.
- Backend → Comm layer: uses · Backend coordinates distributed message exchange through the communication layer.
- Backend → Gate exec: drives · Backend delegates local gate execution to the scheduler.
- Comm layer → Transport: abstracts · Communication layer hides the underlying transport.
- Transport → TCP: implements · TCP transport provides the real network backend.
- Transport → Dummy: implements · Dummy transport supports local and test execution.
- Comm layer → Message mgr: routes · Message manager handles typed message lifecycle and dispatch.
- Message mgr → FlatBuffers: serializes · FlatBuffers defines the wire format for messages.
- Gate → Wire: operates on · Gates consume and produce wire state.
- Wire → Share: backing · Shares and wires represent protocol-specific value state.
- Share → Share wrap: adapts · Wrapper provides typed access and conversion helpers.
- GMW / BMR / Astra → Gate: implements · Boolean GMW, arithmetic GMW, BMR, and Astra specialize the core gate model.
- GMW / BMR / Astra → Share: implements · Protocol families define share types.
- GMW / BMR / Astra → Wire: implements · Protocol families define wire types.
- Garbled circuits → Comm layer: exchanges · Garbled circuit execution uses dedicated messages through communication.
- Garbled circuits → Oblivious transfer: depends on · Garbled circuits use OT for key transfer and input handling.
- Conversions → Share wrap: converts · Conversion gates bridge between share domains.
- Data mgmt → Share wrap: packs · SIMD-style packing and subset selection work on wrapped shares.
- Oblivious transfer → Crypto primitives: uses · OT relies on cryptographic primitives and randomness generation.
- Mul triples → Crypto primitives: uses · Preprocessing randomness is built on cryptographic primitives.
- Mul triples → OT storage: persists · OT and preprocessing state is stored separately from online execution.
- Crypto primitives → Utility: supports · Primitive code relies on common low-level utilities and runtime helpers.
- Statistics → Utility: integrates · Statistics collection is part of the shared runtime infrastructure.
- Examples → Backend: uses · Examples build end-user MPC programs on the core backend.
- Examples → Circuits: consumes · Some examples rely on external circuit assets and metadata.
- Benchmarks → Gate exec: measures · Benchmarks exercise the executor and protocol layers.
- Circuits → Garbled circuits: feeds · Circuit assets are consumed by garbled-circuit-based protocols.