libdpf/doc/pages/network_and_mpc.md

# Network, parties, and MPC around the keys {#network_and_mpc}

\htmlonly
<div class="eli5"><b>ELI5.</b> The library is about DPFs first. The same headers also wire the parties together, schedule rounds, multiply and garble leaf shares, write leveled run logs, and emit paper-cost statistics — so a PIR or Duoram sketch does not start from bare sockets.</div>
\endhtmlonly

Keys and evaluation are the core story. This page is the map of everything
that sits *around* those keys when you run a real protocol: links, party
roles, composition, arithmetic and boolean MPC on leaf shares, logging, and
cost instrumentation. Open a linked page for the details; the [call index](@ref api_reference)
lists the headers.

## Network and party mesh

| Piece | Role |
| --- | --- |
| [party_session](@ref dpf/net/party_session.hpp) | One role joins a mesh: dial/accept, lanes, reconnect, dealer link |
| [trio](@ref dpf/net/trio.hpp) | Convenience `(2+1)` mesh (`p0`, `p1`, dealer `p2`) |
| [TLS 1.3](@ref dpf/net/tls.hpp) / [security](@ref dpf/net/security.hpp) | Default on peer links; `--encryption=off` for plaintext benches |
| [RoundSink](@ref dpf/net/round_sink.hpp) / [edge_mesh](@ref dpf/net/edge_mesh.hpp) | Batched exchange rounds on star / clique / dealer topologies |
| [stream arrays](@ref dpf/net/stream_array.hpp) | Sync or async TCP (and optional SCTP) byte lanes |

Processes may start in any order: lower ids accept, higher ids connect and
retry. After connect (or TLS handshake) both ends exchange a fixed hello so
mismatched party id, epoch, transport, or lane count fail at join time.

```cpp
// Conceptual shape — see party_session / trio headers for the full API.
dpf::net::session_options opt;           // TLS on by default
dpf::net::party_session session(/*role*/, opt);
session.join(/*host:port table*/);       // or in-process rendezvous
auto & sink = session.round_sink(/*peer*/);
```

**Go deeper:** [trio.hpp](@ref dpf/net/trio.hpp),
[party_session.hpp](@ref dpf/net/party_session.hpp),
[secure_channel.hpp](@ref dpf/net/secure_channel.hpp),
examples under `examples/protocol/`.

## Protocol composition

[dpf::protocol::composer](@ref protocol_compose) records FSS walks, Beaver
opens, and reshares as one RoundSink plan. Share domains are tagged
(`fss`, `a`, `b`, `rss`, `y`); party-count changes are explicit `reshare`.
Independent opens share a wave; dependency chains become successive waves.

Drive with `drive` / `drive_via_schedule`, or party helpers
`util::drive_composed` / `util::drive_composed_trio`. Named application
skeletons (PIR upload/answer, SUBLEQ, hushmap, …) live in
[app_plans.hpp](@ref dpf/app_plans.hpp).

**Go deeper:** [Protocol composition](@ref protocol_compose).

## MPC on leaf shares

The DPF answers the secret index. What you do *with* the opened (or still
shared) leaf is ordinary MPC in the same library:

| Tool | When you reach for it |
| --- | --- |
| [Beaver triples](@ref beaver_triples) | Products, dots, polynomials, optional MACs (ABY2.0) |
| [Arithmetic share runtime](@ref arith_runtime) | edaBits, truncate, share compare, matmul, hidden shuffle |
| [Yao on a leaf](@ref yao_leaf) | A boolean circuit the key does not contain; half-gates |
| [Dealer-free keygen](@ref dealer_free) | Doerner–Shelat / IKNP when nobody deals the pads |
| [Multiparty & 3-server](@ref multiparty) | `(2,3)` Shamir spines or IT three-server tables |

**Go deeper:** those capability pages, then the [guided tour](@ref guided_tour)
sections on Beaver, Yao, and running protocols.

## Logging and statistics

Observability is first-class, not an afterthought:

| Facility | Role |
| --- | --- |
| [Run log](@ref run_log) (`log.hpp` / `run_log.hpp`) | Leveled `key=value` lines to stderr, syslog, or a file; provenance banner (build, host, argv, env, config); link and trial events |
| [Statistics & CSVs](@ref statistics) (`experiment.hpp`) | Replayable master seeds, per-party streams, wire bytes, rounds, wall/CPU, symmetric-key blocks by purpose×primitive |
| [`prg::count`](@ref dpf/prg_count.hpp) | Thread-local expand / hash / harness counters (AES, ChaCha, LowMC) |
| [`thread_work`](@ref dpf/thread_work.hpp) | Charge compute-pool kernels back to the owning party |

In-tree `party/` drivers and `run_parties` / `app::run` / `app::run_measured`
call `app::start_logging` and drive the mesh end-to-end. Before any party
starts its clock, all parties wait at a start gate.

**Go deeper:** [Logging, statistics, and experiments](@ref experiment_costs),
[compose.hpp](@ref dpf/compose.hpp),
[experiment.hpp](@ref dpf/experiment.hpp),
[log.hpp](@ref dpf/log.hpp).

\htmlonly
<div class="tldr"><b>TL;DR.</b> Start with make_dpf and eval. When you need live parties, party_session / trio give TLS links and RoundSink rounds; the composer schedules FSS next to Beaver and Yao; start_logging and experiment stamp the run log and paper CSVs. The keys stay the product — the net, MPC, logging, and statistics stack is how you run and measure them.</div>
\endhtmlonly