Skip to content

v0.15.0

Choose a tag to compare

@hdvanegasm hdvanegasm released this 13 Nov 00:11
· 2 commits to main since this release

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-party Protocols 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 any EllipticCurve: the prover shows it knows x with h = g^x in three moves
    (commitment u = g^r, challenge c, response z = r + c·x), and the verifier accepts if and
    only if g^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) and SchnorrPok::verifier(prover, verifier, h);
    both return Error::Input when prover == verifier. Output is Option<bool>: Some(true) or
    Some(false) on the verifier, None on the prover — a rejected proof is an ordinary output, not
    an error. Running a node whose local party does not match its role fails with Error::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_pok example 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), and ForkNetwork::fork creates 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) and parent() 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.
    • Display shows the path only: root for 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 TcpNetwork frame carries only the path, since the root tag is fixed per network instance.
    SessionId is re-exported from the prelude.

  • Display for PartyId, 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 and context. No
    communication is involved. The tag is unique per execution only if context is, 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: one simulate call is one execution, and runs
    cannot exchange messages with each other. simulate keeps 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: the i-th fork of a handle, counting from 0, is on session().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. SimNetwork and TcpNetwork implement the trait.

  • protocol::ForkEnvironment, an Environment whose fork() returns a child environment on
    a forked network handle. GeneralEnvironment implements it when its network implements
    ForkNetwork and its RNG implements SeedableRng. 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 with execute make 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 a Vec of
      their outputs in input order. An empty Vec outputs an empty Vec.

    Both are ordinary Protocols: they nest, and are called with execute. Their environment must
    implement ForkEnvironment. 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, JoinAll and ForkEnvironment are re-exported from the prelude.

    • Every party must run every Join and JoinAll, 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, returns Error::Input on 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 calls fork by 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, and bandwidth_tree_for may return MalformedTrace.
  • Protocol::boxed(map) and protocol::concurrent::BoxedProtocol<E, O>, to run protocols
    of different types in one JoinAll. boxed erases 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's id, so
    its trace scope keeps the inner protocol's name.

  • NetworkError::PeerFailed { peer, reason }: the connection with peer failed, through a
    read error, a frame that does not decode, or a write error; reason is that error's message.
    TcpNetwork returns it from every later send to that peer and receive from it (see Changed),
    so every session learns of the failure, whichever asks first. NetworkError is
    #[non_exhaustive], so no match breaks.

  • SimulationTrace::session(&session) returns the events of one branch: those recorded in
    session or 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_for when a party's protocol scopes do not nest: a
    ProtocolEnd whose protocol is not the one open in its session, or that ends in a session where
    no scope is open. SimulationError is #[non_exhaustive], so no match breaks.

  • 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 model simulate uses, 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 one Join, 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 the Join, and sends the same bytes.

  • Cancel safety is documented for every async method of Network, TcpNetwork,
    SimNetwork, Protocol, Join and JoinAll, under # Cancel safety: the receives and sends
    are cancel safe on both backends; TcpNetwork::recv, TcpNetwork::create and close() 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: TcpNetwork is session-aware, and its wire format changes. Each frame carries the
    session it was sent in: its body is the postcard encoding 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_to returns once the frame is queued for the peer's writer task, not once it is written.
      Dropping a send, as a fail-fast Join does 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 as NetworkError::PeerFailed by 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 the IoError or SerializationError itself. A clean close is still
      ConnectionClosed(Some(peer)).
    • recv_any and recv_any_with_timeout return the packet of the lowest ready sender, as the
      simulator does, instead of following the order of the underlying StreamMap. 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 of HashMap order.
    • After close() on the root handle, receives from every party, this node included, in every
      session, still take what is already queued, then end with ConnectionClosed(Some(party)),
      where a recv_from returned PartyNotFound; sends to every party, this node included, fail
      with ConnectionClosed(Some(party)), where a send to this node returned SendError.
      close() on a forked handle gives up only that handle's session.
    • NetworkError::SendError is no longer returned: it came only from the old loop-back channel.
  • Breaking: protocol::GeneralEnv is renamed GeneralEnvironment, in protocol and in the
    prelude. Its type parameters, fields, new and 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 sha2 0.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: SessionId field
    : 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); under Join or JoinAll, each sub-protocol's events
    carry its own child session. The other variants and the Display of events are unchanged; the
    Display of a trace changes only for runs that fork (see below). Migration: patterns that list
    every field need session or ..; struct
    literals, e.g. in a hand-built trace passed to SimulationTrace::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 in tests/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: simulate always uses
    ConfigDelay, which splits each channel's delay with ChannelConfig::transmission.

    Timings change for code that sends several messages on one link at the same instant. In the
    golden snapshot, 2 receives in bandwidth_flamegraph and 8 in secure_stats_flamegraph arrive
    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: the benches/comparison scenarios 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 a Join's
    branches are attributed to the branch that recorded them.

    • bandwidth_tree_for puts each branch under the Join or JoinAll node with its own bytes,
      e.g. <simulation>;Preprocessing;Join;PassiveRandShr. A branch that a fail-fast combinator dropped
      is closed with the combinator. A ProtocolEnd that 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 Display prints 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
      unmatched ProtocolEnd prints as a plain event line instead of failing. A trace of code that
      never forks renders exactly as before.
  • TcpNetwork::send returns 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 simulate now 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. simulate documents the panic under # Panics.