Repository navigation
v0.15.0
Adds concurrent composition: independent sub-protocols, of the same or different types, run at the
same time within one party, so the party waits for the slowest of them instead of for all of them
in turn. The Join and JoinAll combinators of protocol::concurrent fork the environment into
child sessions; every message carries its session, both backends keep sessions apart, and traces
and bandwidth trees follow them. On TcpNetwork, each connection now has a reader and a writer
task. The simulator also models link occupancy, so messages sent at once on one link share its
bandwidth. Also new: Schnorr's interactive proof of knowledge, in protocol::zk. Breaking: Event
gains a session field; the TcpNetwork wire format changes and create takes a required root
tag; GeneralEnv is renamed GeneralEnvironment; the MSRV rises to 1.88; and simulated timings
change where one link carries several messages at once. Changed lists each break and, where code
has to change, how to migrate.
Added
-
protocol::zk, a new module for zero-knowledge proofs run as two-partyProtocols between
a prover and a verifier. The verifier's output is its verdict; the prover has no output. -
protocol::zk::schnorr::SchnorrPok, Schnorr's interactive proof of knowledge of a discrete
logarithm over anyEllipticCurve: the prover shows it knowsxwithh = g^xin three moves
(commitmentu = g^r, challengec, responsez = r + c·x), and the verifier accepts if and
only ifg^z = u · h^c. It is zero-knowledge against an honest verifier only, and interactive —
no Fiat–Shamir transform is applied.The prover and the verifier are named by
PartyId, so the proof runs between any two distinct
parties of a larger network, for example as a sub-protocol of an MPC protocol; the other parties
do not run it and exchange no messages with it. Build the two nodes with
SchnorrPok::prover(prover, verifier, x, h)andSchnorrPok::verifier(prover, verifier, h);
both returnError::Inputwhenprover == verifier.OutputisOption<bool>:Some(true)or
Some(false)on the verifier,Noneon the prover — a rejected proof is an ordinary output, not
an error. Running a node whose local party does not match its role fails withError::Input
before any message is sent: the local party is neither the prover nor the verifier, the prover
lacks the witness, or the verifier was given one.The
schnorr_pokexample keeps its own self-contained copy of the protocol, restricted to a
two-party network, and does not use this type. -
net::session::SessionId, the identifier of a session, for concurrent composition. The
simulator uses it to keep sessions apart and
to tag trace events (see Changed), andForkNetwork::forkcreates handles on child sessions
(see below). A session is two things: a 32-byte root tag, which identifies one execution
and must be equal at every party of it and distinct across executions; and a path of fork
indices from that execution's root session.SessionId::root(tag)builds the root session.with_child(index)andparent()move down and up the tree;depth(),root_tag()and
path()read it.digest()returns a domain-separated SHA-256 commitment to the root tag and the path, to bind
a session into transcripts and commitments.Displayshows the path only:rootfor the root session, otherwise the fork indices joined
by dots, e.g.0,1.0,0.3.1. The root tag is not shown.
A
TcpNetworkframe carries only the path, since the root tag is fixed per network instance.
SessionIdis re-exported from the prelude. -
DisplayforPartyId, which shows the bare index, e.g.2. Width, fill and alignment
apply as for an integer. -
net::session::derive_root_tag(context)derives a root tag from public context that every
party of an execution knows: SHA-256 over a domain-separation prefix andcontext. No
communication is involved. The tag is unique per execution only ifcontextis, e.g. the
protocol name and version, the party set, the parameters, and an epoch counter that is never
reused. -
net::simulation::simulator::SIMULATION_ROOT_TAG, the fixed root tag of every simulated
execution. A fixed tag is safe in the simulator: onesimulatecall is one execution, and runs
cannot exchange messages with each other.simulatekeeps its signature. -
net::ForkNetwork, a network handle that can be split into handles on child sessions, so
that independent sub-protocols can run at the same time within one party without mixing their
messages.fork()returns a handle on the next child session of the handle's own session, and
session()returns that session. Child sessions are numbered by the order of the forks, with no
communication: thei-th fork of a handle, counting from 0, is onsession().with_child(i), and
a child handle starts its own count at 0. So the parties agree on a session only if they fork
alike: within a session, every party must make the same forks in the same order. After one
skipped fork, every later fork in that session gets a different index on the party that skipped
it.SimNetworkandTcpNetworkimplement the trait. -
protocol::ForkEnvironment, anEnvironmentwhosefork()returns a child environment on
a forked network handle.GeneralEnvironmentimplements it when its network implements
ForkNetworkand its RNG implementsSeedableRng. The child's RNG is seeded from the parent's
RNG, so a run with seeded RNGs stays reproducible. Forking draws from the parent's RNG, though,
so running sub-protocols under a combinator instead of one after another changes the values they
sample. -
protocol::concurrent, combinators that run independent sub-protocols concurrently within
one party. Sub-protocols called one after another withexecutemake a party wait for the sum
of their latencies; under a combinator, it waits for the slowest one.Join((p0, p1, …))runs 2 to 6 protocols of possibly different types, and outputs the tuple
of their outputs.JoinAll(vec![p0, p1, …])runs any number of protocols of one type, and outputs aVecof
their outputs in input order. An emptyVecoutputs an emptyVec.
Both are ordinary
Protocols: they nest, and are called withexecute. Their environment must
implementForkEnvironment. A combinator forks the environment once per sub-protocol, in order
and before any of them starts, and runs each sub-protocol in its own child session, so messages
of different sub-protocols never mix, even over the same links. No task or thread is spawned:
the concurrency stays within the party's task, adds no CPU parallelism, and is deterministic on
the simulator.Join,JoinAllandForkEnvironmentare re-exported from the prelude.- Every party must run every
JoinandJoinAll, with the same number of sub-protocols,
including a party that takes no part in some of them; its sub-protocol there returns at once.
A protocol that rejects non-participants cannot be that sub-protocol:SchnorrPok, for
example, returnsError::Inputon them. On the simulator, a violation ends in the deadlock
panic; on a real network, the receives hang until they time out. - Combinators fail fast: they return the first error any sub-protocol returns, and drop the
others unfinished. The messages those already sent are never received, and the matching
sub-protocols at the other parties may wait until their own timeout or error. - Fork only through the combinators. A combinator runs nothing in its own session while its
sub-protocols run, and simulation traces rely on that to place each sub-protocol's scope (a
trace records no fork). Code that callsforkby hand must do the same: run nothing else in
its own session until the protocols on the child have returned or been dropped. Otherwise
outputs and timings stay correct, but the trace places the child's scope inside the wrong
protocol, andbandwidth_tree_formay returnMalformedTrace.
-
Protocol::boxed(map)andprotocol::concurrent::BoxedProtocol<E, O>, to run protocols
of different types in oneJoinAll.boxederases the protocol's type and maps its output to
O, for example into an enum of the caller's:
JoinAll(vec![a.boxed(Pre::Shares), b.boxed(Pre::Doubles)]). The protocol and the map must be
'static; the environment need not be. A boxed protocol reports the inner protocol'sid, so
its trace scope keeps the inner protocol's name. -
NetworkError::PeerFailed { peer, reason }: the connection withpeerfailed, through a
read error, a frame that does not decode, or a write error;reasonis that error's message.
TcpNetworkreturns it from every later send to that peer and receive from it (see Changed),
so every session learns of the failure, whichever asks first.NetworkErroris
#[non_exhaustive], so nomatchbreaks. -
SimulationTrace::session(&session)returns the events of one branch: those recorded in
sessionor in a session below it. Events that carry no session (Start,Output,Stop, …)
are left out. -
SimulationError::MalformedTrace { event_idx, reason }, returned by
SimulationOutcome::bandwidth_tree_forwhen a party's protocol scopes do not nest: a
ProtocolEndwhose protocol is not the one open in its session, or that ends in a session where
no scope is open.SimulationErroris#[non_exhaustive], so nomatchbreaks. -
Delay::transmission(link, size_bytes), which splits a message's delay into the time it
holds the link and the time it then travels, returned as the new
net::simulation::switchboard::TransmissionTime(new,serialization(),
propagation()). It is a provided method, whose default has no serialization time.
ConfigDelay, the delay modelsimulateuses, overrides it with the new
ChannelConfig::transmission(n_bytes), whose two parts always add up to
message_delay(n_bytes)exactly. See link occupancy under Changed. -
examples/concurrent_preprocessing.rs: the preprocessing of a Beaver multiplication run
one step after another and with its five independent steps in oneJoin, on the WAN preset,
with the two runs' metrics side by side. A party other than the king takes 400 ms one after
another and 200 ms under theJoin, and sends the same bytes. -
Cancel safety is documented for every async method of
Network,TcpNetwork,
SimNetwork,Protocol,JoinandJoinAll, under# Cancel safety: the receives and sends
are cancel safe on both backends;TcpNetwork::recv,TcpNetwork::createandclose()on a
TcpNetwork's root handle are not; a protocol is not, and is made safe to drop by running it in
a forked session.
Changed
-
Breaking:
TcpNetwork::create(id, config, root_tag)takes the execution's root tag as a
third, required parameter. Every party must pass the same tag, and a tag must not be reused for
another execution on the same parties. There is deliberately no default, because a silently
reused tag is the failure the parameter exists to prevent. Migration: derive one with
derive_root_tag, e.g.
TcpNetwork::create(id, config, derive_root_tag(b"my-protocol/v1 run=1")). The tag is the root
of every session of the network, and is never sent: a frame carries only its session's path, and
each party rebuilds the session from its own tag. -
Breaking:
TcpNetworkis session-aware, and its wire format changes. Each frame carries the
session it was sent in: its body is thepostcardencoding of the session's path and the packet,
where it was the packet alone, so a party on 0.14.x and a party on this version cannot talk to
each other. Each connection now has a reader task and a writer task. The reader files every
frame under its session and sender, and a receive takes only from its own session; a frame for a
session this party has not forked yet waits until it does, and frames for a session whose handle
was dropped or closed are discarded. For code that never forks, the following also changes:send_toreturns once the frame is queued for the peer's writer task, not once it is written.
Dropping a send, as a fail-fastJoindoes to a sibling, can no longer leave part of a frame
on the stream.- A failed connection with a peer (a read error, a frame that does not decode, or a write error)
is reported asNetworkError::PeerFailedby every later send to that peer and, once the
packets already received from it are taken, by every later receive from it, in every session.
0.14.x returned theIoErrororSerializationErroritself. A clean close is still
ConnectionClosed(Some(peer)). recv_anyandrecv_any_with_timeoutreturn the packet of the lowest ready sender, as the
simulator does, instead of following the order of the underlyingStreamMap. They no longer
return a single peer's error: they wait while any peer is open, and return
ConnectionClosed(None)once none is and nothing is left to take in the session.party_ids()returns the parties in ascending order, instead ofHashMaporder.- After
close()on the root handle, receives from every party, this node included, in every
session, still take what is already queued, then end withConnectionClosed(Some(party)),
where arecv_fromreturnedPartyNotFound; sends to every party, this node included, fail
withConnectionClosed(Some(party)), where a send to this node returnedSendError.
close()on a forked handle gives up only that handle's session. NetworkError::SendErroris no longer returned: it came only from the old loop-back channel.
-
Breaking:
protocol::GeneralEnvis renamedGeneralEnvironment, inprotocoland in the
prelude. Its type parameters, fields,newand trait impls are unchanged. Migration: rename the
imports and uses, e.g.GeneralEnvironment::new(network, rng). -
MSRV raised from 1.85.1 to 1.88, because the new
sha20.11.1 dependency (used by
SessionId::digest) requires it. The CI MSRV job builds on 1.88. -
Breaking:
Event::{SendData, ReceiveData, ProtocolBegin, ProtocolEnd}gain a
session: SessionIdfield: the session the packet was sent or received in, or the protocol
ran in. In code that never forks, it is always the root session,
SessionId::root(SIMULATION_ROOT_TAG); underJoinorJoinAll, each sub-protocol's events
carry its own child session. The other variants and theDisplayof events are unchanged; the
Displayof a trace changes only for runs that fork (see below). Migration: patterns that list
every field needsessionor..; struct
literals, e.g. in a hand-built trace passed toSimulationTrace::new, need
session: SessionId::root(SIMULATION_ROOT_TAG). -
The simulator keeps sessions apart. Its mailboxes, waiting receives and scheduled
deliveries are keyed by link and session, so a receive takes only packets sent in its own
session, and a delivery wakes only receives waiting in that session. Delivery on a link stays
first-in, first-out across sessions, as on one TCP stream. For code that does not fork sessions,
this routing changes nothing: with it alone, the golden snapshot intests/golden.rs(traces,
exact event timestamps, bandwidth trees and metrics) was unchanged. Link occupancy (below) does
change some timings. -
Simulated links now carry one message at a time (link occupancy). A message holds its link
for its serialization time (its size over the channel's throughput), and a message sent on the
same link meanwhile starts once the link is free; the propagation time, half the RTT, is added
after and holds nothing. Before, every message got the link's whole bandwidth, so messages sent
at once on one link arrived together, which underestimated latency whenever a link carried more
than one message at a time, as concurrent sessions do. A message sent alone arrives exactly when
it did before. Messages on different links still do not share bandwidth (an uplink shared across
links is not modelled). Occupancy applies to every simulation:simulatealways uses
ConfigDelay, which splits each channel's delay withChannelConfig::transmission.Timings change for code that sends several messages on one link at the same instant. In the
golden snapshot, 2 receives inbandwidth_flamegraphand 8 insecure_stats_flamegrapharrive
0.4 ms later;secure_covariance, which sends many packets on one link at once, finishes at
0.863 s instead of 0.859 s, with receives up to 4.4 ms later. The order of events, the bandwidth
trees and the byte counts are unchanged. Occupancy has not been checked against real concurrent
transfers: thebenches/comparisonscenarios keep one message in flight. -
Traces and bandwidth trees follow sessions. Both are now read off one tree of protocol
scopes, built with a stack of open scopes per session, so the interleaved events of aJoin's
branches are attributed to the branch that recorded them.bandwidth_tree_forputs each branch under theJoinorJoinAllnode with its own bytes,
e.g.<simulation>;Preprocessing;Join;PassiveRandShr. A branch that a fail-fast combinator dropped
is closed with the combinator. AProtocolEndthat does not match the scope open in its
session is now an error,MalformedTrace, where the old parser closed the innermost scope.- A trace's
Displayprints each branch as its own block, labelled with its session, e.g.
PassiveRandShr [session 0.2] {; a scope that never ended closes with} (not finished); an
unmatchedProtocolEndprints as a plain event line instead of failing. A trace of code that
never forks renders exactly as before.
-
TcpNetwork::sendreturns the total payload bytes it sent: one packet's size per party,
this node included. 0.14.x returned the size of the packet sent to the last party, i.e. one
packet's size. -
A deadlock in
simulatenow says what is stuck. The panic message keeps its first line,
scheduler: N task(s) parked, nothing to deliver (deadlock), and adds a report: each receive
still waiting, and each packet that reached its recipient but was never received, together
with what that recipient is doing. For example, a recipient waiting in the same session for a
different sender usually means the protocol receives from the wrong party. The report is
sorted, so it is the same in every run. Tests that match the first line with
#[should_panic(expected = …)]still pass.simulatedocuments the panic under# Panics.