From aab8446b59f46014d04e79289eda6ca3dc76e1b7 Mon Sep 17 00:00:00 2001 From: Denis Varlakov Date: Wed, 27 Nov 2024 15:48:31 +0100 Subject: [PATCH] Update docs Signed-off-by: Denis Varlakov --- round-based/src/simulation/async_env.rs | 3 +-- round-based/src/simulation/mod.rs | 30 +++++++++++++++++++------ 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/round-based/src/simulation/async_env.rs b/round-based/src/simulation/async_env.rs index 5b9336b..6f28282 100644 --- a/round-based/src/simulation/async_env.rs +++ b/round-based/src/simulation/async_env.rs @@ -3,8 +3,7 @@ //! Simulation provided in a [parent module](super) should be used in most cases. It works //! by converting all parties (defined as async functions) into [state machines](crate::state_machine), //! which has certain limitations. In particular, the protocol cannot await on any futures that -//! aren't provided by [`MpcParty`](crate::MpcParty), for instance, awaiting on the timer will -//! cause a simulation error. +//! aren't provided by [`MpcParty`], for instance, awaiting on the timer will cause a simulation error. //! //! We suggest to avoid awaiting on the futures that aren't provided by `MpcParty` in the MPC protocol //! implementation as it likely makes it runtime-dependent. However, if you do ultimately need to diff --git a/round-based/src/simulation/mod.rs b/round-based/src/simulation/mod.rs index 582ee50..0d44001 100644 --- a/round-based/src/simulation/mod.rs +++ b/round-based/src/simulation/mod.rs @@ -1,17 +1,33 @@ //! Multiparty protocol simulation //! //! Simulator is an essential developer tool for testing the multiparty protocol locally. -//! It covers most of the boilerplate by mocking networking. +//! It covers most of the boilerplate of emulating MPC protocol execution. //! //! The entry point is either [`run`] or [`run_with_setup`] functions. They take a protocol //! defined as an async function, provide simulated networking, carry out the simulation, //! and return the result. //! -//! If you need more control over execution, you can use [`Network`] to simulate the networking -//! and carry out the protocol manually. +//! If you need more control over execution, you can use [`Simulation`]. For instance, it allows +//! creating a simulation that has parties defined by different functions, which is helpful, for +//! instance, in simulation in presence of an adversary (e.g. one set of parties can be defined +//! with a regular function/protocol implementation, when the other set of parties may be defined +//! by other function which emulates adversary behavior). //! -//! When `state-machine` feature is enabled, [`SimulationSync`] is available which can carry out -//! protocols defined as a state machine. +//! ## Limitations +//! [`Simulation`] works by converting each party (defined as an async function) into the +//! [state machine](crate::state_machine). That should work without problems in most cases, providing +//! better UX, without requiring an async runtime (simulation is entirely sync). +//! +//! However, a protocol wrapped into a state machine cannot poll any futures except provided within +//! [`MpcParty`](crate::MpcParty) (so it can only await on sending/receiving messages and yielding). +//! For instance, if the protocol implementation makes use of tokio timers, it will result into an +//! execution error. +//! +//! In general, we do not recommend awaiting on the futures that aren't provided by `MpcParty` in +//! the MPC protocol implementation, to keep the protocol implementation runtime-agnostic. +//! +//! If you do really need to make use of unsupported futures, you can use [`async_env`] instead, +//! which provides a simulation on tokio runtime, but has its own limitations. //! //! ## Example //! ```rust,no_run @@ -308,7 +324,7 @@ where } } -/// Error returned by [`SimulationSync::run`] +/// Error indicating that simulation failed #[derive(Debug, thiserror::Error)] #[error(transparent)] pub struct SimError(#[from] Reason); @@ -385,7 +401,7 @@ impl MessagesQueue { /// Simulates execution of the protocol /// /// Takes amount of participants, and a function that carries out the protocol for -/// one party. The function takes as input: index of the party, and [`MpcParty`] +/// one party. The function takes as input: index of the party, and [`MpcParty`](crate::MpcParty) /// that can be used to communicate with others. /// /// ## Example