PRO-382: tree-availability-service and state-bridge-service-docs

bin/state_bridge_service.rs

@@ -19,7 +19,7 @@ use tracing::info;
 /// The state bridge service propagates roots according to the specified relaying_period by
 /// calling the propagateRoot() method on each specified World ID StateBridge. The state bridge
 /// service will also make sure that it doesn't propagate roots that have already been propagated
-/// and have finalized on the BridgedWorldID side
+/// and have finalized on the BridgedWorldID side.
 #[derive(Parser, Debug)]
 #[clap(
     name = "State Bridge Service",
@@ -60,13 +60,13 @@ struct BridgeConfig {
     bridged_rpc_url: String,
 }
 
-/// The config TOML file defines all the necessary parameters to spawn a state bridge service.
-/// rpc_url - HTTP rpc url for an Ethereum node (string)
-/// private_key - pk to an address that will call the propagateRoot() method on the StateBridge contract (string)
-/// world_id_address - WorldIDIdentityManager contract address (string)
-/// bridge_pair_addresses - List of StateBridge and BridgedWorldID contract address pairs (strings)
-/// bridged_world_id_addresses - List of BridgedWorldID contract addresses (strings)
-/// relaying_period:  propagateRoot() call period time in seconds (u64)
+/// The config TOML file defines all the necessary parameters to spawn a state bridge service. \
+/// rpc_url - HTTP rpc url for an Ethereum node (string) \
+/// private_key - pk to an address that will call the propagateRoot() method on the StateBridge contract (string) \
+/// world_id_address - WorldIDIdentityManager contract address (string) \
+/// bridge_pair_addresses - List of StateBridge and BridgedWorldID contract address pairs (strings) \
+/// bridged_world_id_addresses - List of BridgedWorldID contract addresses (strings) \
+/// relaying_period:  propagateRoot() call period time in seconds (u64) \
 /// block_confirmations - Number of block confirmations required for the propagateRoot call on the StateBridge contract (optional number)
 #[derive(Deserialize, Serialize, Debug, Clone)]
 struct Config {

bin/tree_availability_service.rs

@@ -7,6 +7,7 @@ use futures::stream::FuturesUnordered;
 use futures::StreamExt;
 use tree_availability::TreeAvailabilityService;
 
+/// CLI interface for the Tree Availability Service
 #[derive(Parser, Debug)]
 #[clap(name = "Tree Availability Service", about = "")]
 struct Opts {

crates/state_bridge/src/bridge.rs

@@ -29,14 +29,25 @@ abigen!(
     event_derives(serde::Deserialize, serde::Serialize)
 );
 
+/// The `StateBridge` takes care of listening to roots propagated from the `WorldRoot` and
+/// propagates them periodically every time `relaying_period` elapses and the root was updated.
 pub struct StateBridge<M: Middleware + 'static> {
+    /// Interface for the `StateBridge` contract
     pub state_bridge: IStateBridge<M>,
+    /// Interface for the `BridgedWorldID` contract
     pub bridged_world_id: IBridgedWorldID<M>,
+    /// Time in between `propagateRoot()` calls
     pub relaying_period: Duration,
+    /// The number of blocks before a `propagateRoot()` call is considered finalized
     pub block_confirmations: usize,
 }
 
 impl<M: Middleware> StateBridge<M> {
+    /// Constructor \
+    /// `state_bridge`: `StateBridge` contract interface \
+    /// `bridged_world_id`: `BridgedWorldID` contract interface \
+    /// `relaying_period`: Time in between `propagateRoot()` calls \
+    /// `block_confirmations: The number of blocks before a `propagateRoot()` call is considered finalized
     pub fn new(
         state_bridge: IStateBridge<M>,
         bridged_world_id: IBridgedWorldID<M>,
@@ -51,6 +62,13 @@ impl<M: Middleware> StateBridge<M> {
         })
     }
 
+    /// Constructor with address and middleware \
+    /// `bridge_address`: `StateBridge` contract address \
+    /// `canonical_middleware`: middleware for the chain where the `StateBridge` is deployed \
+    /// `bridged_world_id_address`: `BridgedWorldID` contract address \
+    /// `derived_middleware`: middleware for the chain where the `BridgedWorldID` is deployed \
+    /// `relaying_period`: Time in between `propagateRoot()` calls \
+    /// `block_confirmations: The number of blocks before a `propagateRoot()` call is considered finalized \
     pub fn new_from_parts(
         bridge_address: H160,
         canonical_middleware: Arc<M>,
@@ -75,6 +93,8 @@ impl<M: Middleware> StateBridge<M> {
         })
     }
 
+    /// Spawns the `StateBridge` which listens to the `WorldRoot` `TreeChanged` events for new roots to propagate. \
+    /// `root_rx`: The root receiver that listens to the `WorldRoot` root sender
     pub async fn spawn(
         &self,
         mut root_rx: tokio::sync::broadcast::Receiver<Hash>,

crates/state_bridge/src/lib.rs

@@ -8,7 +8,30 @@
 //!
 //! #### CLI
 //!
-//! TODO: specify how to run the state bridge service as a command-line utility
+//! Create a state_bridge_service.toml file which will hold the configuration parameters for the state bridge
+//! service. You can use the example in the test as a template:
+//!
+//! ```toml
+//! rpc_url = "127.0.0.1:8545"
+//! private_key = "4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318"
+//! world_id_address = "0x3f0BF744bb79A0b919f7DED73724ec20c43572B9"
+//! bridge_configs = [
+//!     [
+//!         "Optimism",
+//!         # StateBridge Address
+//!         "0x3f0BF744bb79A0b919f7DED73724ec20c43572B9",
+//!         # BridgedWorldID Address
+//!         "0x4f0BF744bb79A0b919f7DED73724ec20c43572B9",
+//!         "127.0.0.1:8545",
+//!     ]
+//! ]
+//! relaying_period_seconds = 5
+//! ```
+//!
+//! ```bash
+//! cargo build --bin state-bridge-service --release
+//! ./target/release/state-bridge-service --config <CONFIG>
+//! ```
 //!
 //! #### Library
 //! In order to launch a `StateBridgeService` as a library you can use the following example from the [`bridge_service.rs`](https://github.com/worldcoin/identity-sequencer/blob/359f0fe3ec62b18d6f569d8ad31967c048401fa1/crates/state_bridge/tests/bridge_service.rs#L37) test file as a guide.
@@ -101,15 +124,8 @@ impl<M> StateBridgeService<M>
 where
     M: Middleware,
 {
-    /// constructor for the `StateBridgeService`
-    ///
-    /// ### Arguments
-    ///
-    /// `world_tree`:`IWorldID ` - interface to the `WorldIDIdentityManager`
-    ///
-    /// ### Output
-    ///
-    /// `Result<StateBridgeService, StateBridgeError<M>>`
+    /// ### Constructor for the `StateBridgeService` \
+    /// `world_tree`:`IWorldID ` - interface to the `WorldIDIdentityManager` \
     pub async fn new(
         world_tree: IWorldIDIdentityManager<M>,
     ) -> Result<Self, StateBridgeError<M>> {
@@ -120,16 +136,9 @@ where
         })
     }
 
-    /// constructor for the `StateBridgeService`
-    ///
-    /// ### Arguments
-    ///
-    /// `world_tree_address`:`H160` - interface to the `WorldIDIdentityManager`
-    /// `middleware`:`Arc\<M\>` - Middleware provider
-    ///
-    /// ### Output
-    ///
-    /// `Result<StateBridgeService, StateBridgeError<M>>`
+    /// Constructor for the `StateBridgeService` \
+    /// `world_tree_address`:`H160` - interface to the `WorldIDIdentityManager` \
+    /// `middleware`:`Arc\<M\>` - Middleware provider \
     pub async fn new_from_parts(
         world_tree_address: H160,
         middleware: Arc<M>,
@@ -145,30 +154,26 @@ where
     }
 
     /// Adds a state bridge to the list of state bridges the service will use
-    /// to propagate roots on chain to their destination chains
-    ///
-    /// ### Args
-    ///
-    /// `state_bridge`: `StateBridge<M>` - state bridge contract interface with provider
-    ///
+    /// to propagate roots on chain to their destination chains. \
+    /// `state_bridge`: `StateBridge<M>` - state bridge contract interface with provider\
     /// ### Notes
     /// Needs to be called before the spawn function so that the `StateBridgeService`
-    /// knows where to propagate roots to
+    /// knows where to propagate roots to.
     pub fn add_state_bridge(&mut self, state_bridge: StateBridge<M>) {
         self.state_bridges.push(state_bridge);
     }
 
-    /// Spawns the `StateBridgeService`
+    /// Spawns the `StateBridgeService`.
     pub async fn spawn(&mut self) -> Result<(), StateBridgeError<M>> {
         // if no state bridge initialized then there is no point in spawning
-        // the state bridge service as there'd be no receivers for new roots
+        // the state bridge service as there'd be no receivers for new roots.
         if self.state_bridges.is_empty() {
             return Err(StateBridgeError::BridgesNotInitialized);
         }
 
         // We first instantiate the receivers on the state bridges
         // so that the root sender doesn't yield an error when pushing roots
-        // through the channel
+        // through the channel.
         for bridge in self.state_bridges.iter() {
             self.handles.push(
                 bridge.spawn(self.canonical_root.root_tx.subscribe()).await,

crates/state_bridge/src/root.rs

@@ -37,13 +37,8 @@ impl<M> WorldTreeRoot<M>
 where
     M: Middleware,
 {
-    /// `WorldTreeRoot` constructor
-    ///
-    /// ### Args
+    /// `WorldTreeRoot` constructor \
     /// `world_id_identity_manager`:`IWorldIDIdentityManager\<M\>` - `WorldIDIdentityManager` interface
-    ///
-    /// ### Output
-    /// `WorldTreeRoot` Result
     pub async fn new(
         world_id_identity_manager: IWorldIDIdentityManager<M>,
     ) -> Result<Self, StateBridgeError<M>> {
@@ -55,15 +50,10 @@ where
         })
     }
 
-    /// `WorldTreeRoot` constructor from address and middleware
-    ///
-    /// ### Args
-    /// `world_id_identity_manager`:`IWorldIDIdentityManager\<M\>` - `WorldIDIdentityManager` interface
-    /// `world_tree_address`: `H160` - `WorldIDIdentityManager` contract address
-    /// `middleware`: `Arc\<M\>` - Middleware provider (ethers)
-    ///
-    /// ### Output
-    /// `WorldTreeRoot` Result
+    /// `WorldTreeRoot` constructor from address and middleware \
+    /// `world_id_identity_manager`:`IWorldIDIdentityManager\<M\>` - `WorldIDIdentityManager` interface \
+    /// `world_tree_address`: `H160` - `WorldIDIdentityManager` contract address \
+    /// `middleware`: `Arc\<M\>` - Middleware provider (ethers) \
     pub async fn new_from_parts(
         world_tree_address: H160,
         middleware: Arc<M>,

crates/tree_availability/src/error.rs

@@ -4,6 +4,7 @@ use ethers::types::Log;
 use thiserror::Error;
 use tokio::sync::mpsc::error::SendError;
 
+/// Wraps dependency errors and converts them to `TreeAvailabilityError`s
 #[derive(Error, Debug)]
 pub enum TreeAvailabilityError<M>
 where