Improve simulation UX

.github/workflows/rust.yml

@@ -37,6 +37,16 @@ jobs:
     - name: cargo check
       run: cargo check -p round-based --all-features
 
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: Swatinem/rust-cache@v2
+      with:
+        cache-on-failure: "true"
+    - name: cargo test
+      run: cargo test --all-features
+
   check-fmt:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -35,7 +35,12 @@ the documentation of the protocol you're using), but usually they are:
 
 ## Features
 
-* `dev` enables development tools such as protocol simulation
+* `sim` enables protocol execution simulation, see `sim` module
+  * `sim-async` enables protocol execution simulation with tokio runtime, see `sim::async_env`
+    module
+* `state-machine` provides ability to carry out the protocol, defined as async function, via Sync
+   API, see `state_machine` module
+* `derive` is needed to use `ProtocolMessage` proc macro
 * `runtime-tokio` enables tokio-specific implementation of async runtime
 
 ## Join us in Discord!

examples/random-generation-protocol/Cargo.toml

@@ -20,9 +20,8 @@ thiserror = { version = "1", optional = true }
 generic-array = { version = "0.14", features = ["serde"] }
 
 [dev-dependencies]
-round-based = { path = "../../round-based", features = ["derive", "dev", "state-machine"]  }
+round-based = { path = "../../round-based", features = ["derive", "sim", "state-machine"]  }
 tokio = { version = "1.15", features = ["macros", "rt"] }
-futures = "0.3"
 hex = "0.4"
 rand_dev = "0.1"
 rand = "0.8"

examples/random-generation-protocol/src/lib.rs

@@ -173,56 +173,43 @@ pub struct Blame {
 
 #[cfg(test)]
 mod tests {
-    use alloc::{vec, vec::Vec};
-
     use rand::Rng;
-    use round_based::simulation::Simulation;
     use sha2::{Digest, Sha256};
 
-    use super::{protocol_of_random_generation, Msg};
+    use super::protocol_of_random_generation;
 
-    #[tokio::test]
-    async fn simulation_async() {
+    #[test]
+    fn simulation() {
         let mut rng = rand_dev::DevRng::new();
 
         let n: u16 = 5;
 
-        let mut simulation = Simulation::<Msg>::new();
-        let mut party_output = vec![];
-
-        for i in 0..n {
-            let party = simulation.add_party();
-            let output = protocol_of_random_generation(party, i, n, rng.fork());
-            party_output.push(output);
-        }
-
-        let output = futures::future::try_join_all(party_output).await.unwrap();
-
-        // Assert that all parties outputed the same randomness
-        for i in 1..n {
-            assert_eq!(output[0], output[usize::from(i)]);
-        }
+        let randomness = round_based::sim::run_with_setup(
+            core::iter::repeat_with(|| rng.fork()).take(n.into()),
+            |i, party, rng| protocol_of_random_generation(party, i, n, rng),
+        )
+        .unwrap()
+        .expect_ok()
+        .expect_eq();
 
-        std::println!("Output randomness: {}", hex::encode(output[0]));
+        std::println!("Output randomness: {}", hex::encode(randomness));
     }
 
-    #[test]
-    fn simulation_sync() {
+    #[tokio::test]
+    async fn simulation_async() {
         let mut rng = rand_dev::DevRng::new();
 
-        let simulation = round_based::simulation::SimulationSync::from_async_fn(5, |i, party| {
-            protocol_of_random_generation(party, i, 5, rng.fork())
-        });
+        let n: u16 = 5;
 
-        let outputs = simulation
-            .run()
-            .unwrap()
-            .into_iter()
-            .collect::<Result<Vec<_>, _>>()
-            .unwrap();
-        for output_i in &outputs {
-            assert_eq!(*output_i, outputs[0]);
-        }
+        let randomness = round_based::sim::async_env::run_with_setup(
+            core::iter::repeat_with(|| rng.fork()).take(n.into()),
+            |i, party, rng| protocol_of_random_generation(party, i, n, rng),
+        )
+        .await
+        .expect_ok()
+        .expect_eq();
+
+        std::println!("Output randomness: {}", hex::encode(randomness));
     }
 
     // Emulate the protocol using the state machine interface

round-based/CHANGELOG.md

@@ -1,3 +1,29 @@
+## v0.4.0
+* Improve ergonomics of protocol simulation, which is used for writing tests [#14]
+  * Remove `dev` feature, it's replaced with `sim` and `sim-async`
+  * `round_based::simulation` module is renamed into `round_based::sim`
+  * `round_based::simulation::Simulation` is renamed and moved to `round_based::sim::async_env::Network`
+  * Other async simulated network related types are moved to `round_based::sim::async_env`
+  * Added convenient `round_based::sim::{run, run_with_setup}` which make simulation very ergonomic
+  * Simulation outputs `round_based::sim::SimResult`, which has convenient most-common methods:
+    * `.expect_ok()` that unwraps all results, and if any party returned an error, panics with a verbose
+      error message
+    * `.expect_eq()` that checks that all outputs are equally the same
+  * When `sim-async` feature is enabled, you can use `round_based::sim::async_env::{run, run_with_setup, ...}`,
+    but typically you don't want to use them
+  * `round_based::simulation::SimulationSync` has been renamed to `round_based::sim::Simulation`
+
+Migration guidelines:
+* Replace `dev` feature with `sim`
+* Instead of using `round_based::simulation::Simulation` from previous version, use
+  `round_based::simulation::{run, run_with_setup}`
+* Take advantage of `SimResult::{expect_ok, expect_eq}` to reduce amount of the code
+  in your tests
+
+Other than simulation, there are no breaking changes in this release.
+
+[#14]: https://github.com/LFDT-Lockness/round-based/pull/14
+
 ## v0.3.2
 * Update links in crate settings, update readme [#11]
 

round-based/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "round-based"
-version = "0.3.2"
+version = "0.4.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 description = "Driver for MPC protocols"
@@ -32,11 +32,18 @@ trybuild = "1"
 matches = "0.1"
 futures = { version = "0.3", default-features = false }
 tokio = { version = "1", features = ["macros"] }
+hex = "0.4"
+
+rand = "0.8"
+rand_dev = "0.1"
+
+anyhow = "1"
 
 [features]
 default = ["std"]
 state-machine = []
-dev = ["std", "tokio/sync", "tokio-stream"]
+sim = ["std", "state-machine"]
+sim-async = ["sim", "tokio/sync", "tokio-stream", "futures-util/alloc"]
 derive = ["round-based-derive"]
 runtime-tokio = ["tokio"]
 std = ["thiserror"]

round-based/src/lib.rs

@@ -35,7 +35,12 @@
 //!
 //! ## Features
 //!
-//! * `dev` enables development tools such as [protocol simulation](simulation)
+//! * `sim` enables protocol execution simulation, see [`sim`] module
+//!   * `sim-async` enables protocol execution simulation with tokio runtime, see [`sim::async_env`]
+//!     module
+//! * `state-machine` provides ability to carry out the protocol, defined as async function, via Sync
+//!    API, see [`state_machine`] module
+//! * `derive` is needed to use [`ProtocolMessage`](macro@ProtocolMessage) proc macro
 //! * `runtime-tokio` enables [tokio]-specific implementation of [async runtime](runtime)
 //!
 //! ## Join us in Discord!
@@ -53,11 +58,14 @@ extern crate alloc;
 #[doc(no_inline)]
 pub use futures_util::{Sink, SinkExt, Stream, StreamExt};
 
-/// Fixes false-positive of `unused_crate_dependencies` lint that only occure in the tests
+/// Fixes false-positive of `unused_crate_dependencies` lint that only occur in the tests
 #[cfg(test)]
 mod false_positives {
+    use anyhow as _;
     use futures as _;
     use trybuild as _;
+
+    use {hex as _, rand as _, rand_dev as _};
 }
 
 mod delivery;
@@ -67,8 +75,8 @@ pub mod runtime;
 #[cfg(feature = "state-machine")]
 pub mod state_machine;
 
-#[cfg(feature = "dev")]
-pub mod simulation;
+#[cfg(feature = "sim")]
+pub mod sim;
 
 pub use self::delivery::*;
 #[doc(no_inline)]