feat(node_framework): Document implementations (#2319)

## What ❔

Provides minimal documentation for the already present framework
implementations.

## Why ❔

Accessibility.

## Checklist

<!-- Check your PR fulfills the following items. -->
<!-- For draft PRs check the boxes as you complete them. -->

- [ ] PR title corresponds to the body of PR (we generate changelog
entries from PRs).
- [ ] Tests for the changes have been added / updated.
- [ ] Documentation comments have been added / updated.
- [ ] Code has been formatted via `zk fmt` and `zk lint`.

core/node/node_framework/src/implementations/layers/batch_status_updater.rs

@@ -11,6 +11,17 @@ use crate::{
     wiring_layer::{WiringError, WiringLayer},
 };
 
+/// Wiring layer for `BatchStatusUpdater`, part of the external node.
+///
+/// ## Requests resources
+///
+/// - `PoolResource<MasterPool>`
+/// - `MainNodeClientResource`
+/// - `AppHealthCheckResource` (adds a health check)
+///
+/// ## Adds tasks
+///
+/// - `BatchStatusUpdater`
 #[derive(Debug)]
 pub struct BatchStatusUpdaterLayer;
 

core/node/node_framework/src/implementations/layers/circuit_breaker_checker.rs

@@ -14,11 +14,13 @@ use crate::{
 /// [`zksync_circuit_breaker::CircuitBreakers`] collection using [`CircuitBreakersResource`].
 /// The added task periodically runs checks for all inserted circuit breakers.
 ///
-/// ## Adds resources
-/// - [`CircuitBreakersResource`]
+/// ## Requests resources
+///
+/// - `CircuitBreakersResource`
 ///
 /// ## Adds tasks
-/// - [`CircuitBreakerCheckerTask`] (as [`UnconstrainedTask`])
+///
+/// - `CircuitBreakerCheckerTask`
 #[derive(Debug)]
 pub struct CircuitBreakerCheckerLayer(pub CircuitBreakerConfig);
 

core/node/node_framework/src/implementations/layers/commitment_generator.rs

@@ -18,11 +18,13 @@ use crate::{
 /// Responsible for initialization and running [`CommitmentGenerator`].
 ///
 /// ## Requests resources
-/// - [`PoolResource`] for [`MasterPool`]
-/// - [`AppHealthCheckResource`] (to add new health check)
+///
+/// - `PoolResource<MasterPool>`
+/// - `AppHealthCheckResource` (adds a health check)
 ///
 /// ## Adds tasks
-/// - [`CommitmentGeneratorTask`] (as [`Task`])
+///
+/// - `CommitmentGeneratorTask`
 #[derive(Debug)]
 pub struct CommitmentGeneratorLayer {
     mode: L1BatchCommitmentMode,

core/node/node_framework/src/implementations/layers/consensus.rs

@@ -24,6 +24,20 @@ pub enum Mode {
     External,
 }
 
+/// Wiring layer for consensus component.
+/// Can work in either "main" or "external" mode.
+///
+/// ## Requests resources
+///
+/// - `PoolResource<MasterPool>`
+/// - `MainNodeClientResource` (if `Mode::External`)
+/// - `SyncStateResource` (if `Mode::External`)
+/// - `ActionQueueSenderResource` (if `Mode::External`)
+///
+/// ## Adds tasks
+///
+/// - `MainNodeConsensusTask` (if `Mode::Main`)
+/// - `FetcherTask` (if `Mode::External`)
 #[derive(Debug)]
 pub struct ConsensusLayer {
     pub mode: Mode,

core/node/node_framework/src/implementations/layers/consistency_checker.rs

@@ -12,6 +12,17 @@ use crate::{
     wiring_layer::{WiringError, WiringLayer},
 };
 
+/// Wiring layer for the `ConsistencyChecker` (used by the external node).
+///
+/// ## Requests resources
+///
+/// - `EthInterfaceResource`
+/// - `PoolResource<MasterPool>`
+/// - `AppHealthCheckResource` (adds a health check)
+///
+/// ## Adds tasks
+///
+/// - `ConsistencyChecker`
 #[derive(Debug)]
 pub struct ConsistencyCheckerLayer {
     diamond_proxy_addr: Address,

core/node/node_framework/src/implementations/layers/contract_verification_api.rs

@@ -13,11 +13,13 @@ use crate::{
 /// Responsible for initialization of the contract verification server.
 ///
 /// ## Requests resources
-/// - [`PoolResource`] for [`MasterPool`]
-/// - [`PoolResource`] for [`ReplicaPool`]
+///
+/// - `PoolResource<MasterPool>`
+/// - `PoolResource<ReplicaPool>`
 ///
 /// ## Adds tasks
-/// - [`ContractVerificationApiTask`] (as [`Task`])
+///
+/// - `ContractVerificationApiTask`
 #[derive(Debug)]
 pub struct ContractVerificationApiLayer(pub ContractVerifierConfig);
 

core/node/node_framework/src/implementations/layers/eth_sender.rs

@@ -24,15 +24,17 @@ use crate::{
 /// of `eth_txs`(such as `CommitBlocks`, `PublishProofBlocksOnchain` or `ExecuteBlock` ) to L1.
 ///
 /// ## Requests resources
-/// - [`PoolResource`] for [`MasterPool`]
-/// - [`PoolResource`] for [`ReplicaPool`]
-/// - [`BoundEthInterfaceResource`]
-/// - [`BoundEthInterfaceForBlobsResource`]
-/// - [`L1TxParamsResource`]
-/// - [`CircuitBreakersResource`] (to add new circuit breaker)
+///
+/// - `PoolResource<MasterPool>`
+/// - `PoolResource<ReplicaPool>`
+/// - `BoundEthInterfaceResource`
+/// - `BoundEthInterfaceForBlobsResource` (optional)
+/// - `L1TxParamsResource`
+/// - `CircuitBreakersResource` (adds a circuit breaker)
 ///
 /// ## Adds tasks
-/// - [`EthTxManagerTask`] (as [`Task`])
+///
+/// - `EthTxManager`
 #[derive(Debug)]
 pub struct EthTxManagerLayer {
     eth_sender_config: EthConfig,
@@ -79,9 +81,7 @@ impl WiringLayer for EthTxManagerLayer {
             eth_client_blobs,
         );
 
-        context.add_task(Box::new(EthTxManagerTask {
-            eth_tx_manager_actor,
-        }));
+        context.add_task(Box::new(eth_tx_manager_actor));
 
         // Insert circuit breaker.
         let CircuitBreakersResource { breakers } = context.get_resource_or_default().await;
@@ -100,15 +100,17 @@ impl WiringLayer for EthTxManagerLayer {
 /// These `eth_txs` will be used as a queue for generating signed txs and will be sent later on L1.
 ///
 /// ## Requests resources
-/// - [`PoolResource`] for [`MasterPool`]
-/// - [`PoolResource`] for [`ReplicaPool`]
-/// - [`BoundEthInterfaceResource`]
-/// - [`BoundEthInterfaceForBlobsResource`]
-/// - [`ObjectStoreResource`]
-/// - [`CircuitBreakersResource`] (to add new circuit breaker)
+///
+/// - `PoolResource<MasterPool>`
+/// - `PoolResource<ReplicaPool>`
+/// - `BoundEthInterfaceResource`
+/// - `BoundEthInterfaceForBlobsResource` (optional)
+/// - `ObjectStoreResource`
+/// - `CircuitBreakersResource` (adds a circuit breaker)
 ///
 /// ## Adds tasks
-/// - [`EthTxAggregatorTask`] (as [`Task`])
+///
+/// - `EthTxAggregator`
 #[derive(Debug)]
 pub struct EthTxAggregatorLayer {
     eth_sender_config: EthConfig,
@@ -183,9 +185,7 @@ impl WiringLayer for EthTxAggregatorLayer {
         )
         .await;
 
-        context.add_task(Box::new(EthTxAggregatorTask {
-            eth_tx_aggregator_actor,
-        }));
+        context.add_task(Box::new(eth_tx_aggregator_actor));
 
         // Insert circuit breaker.
         let CircuitBreakersResource { breakers } = context.get_resource_or_default().await;
@@ -197,34 +197,24 @@ impl WiringLayer for EthTxAggregatorLayer {
     }
 }
 
-#[derive(Debug)]
-struct EthTxAggregatorTask {
-    eth_tx_aggregator_actor: EthTxAggregator,
-}
-
 #[async_trait::async_trait]
-impl Task for EthTxAggregatorTask {
+impl Task for EthTxAggregator {
     fn id(&self) -> TaskId {
         "eth_tx_aggregator".into()
     }
 
     async fn run(self: Box<Self>, stop_receiver: StopReceiver) -> anyhow::Result<()> {
-        self.eth_tx_aggregator_actor.run(stop_receiver.0).await
+        (*self).run(stop_receiver.0).await
     }
 }
 
-#[derive(Debug)]
-struct EthTxManagerTask {
-    eth_tx_manager_actor: EthTxManager,
-}
-
 #[async_trait::async_trait]
-impl Task for EthTxManagerTask {
+impl Task for EthTxManager {
     fn id(&self) -> TaskId {
         "eth_tx_manager".into()
     }
 
     async fn run(self: Box<Self>, stop_receiver: StopReceiver) -> anyhow::Result<()> {
-        self.eth_tx_manager_actor.run(stop_receiver.0).await
+        (*self).run(stop_receiver.0).await
     }
 }

core/node/node_framework/src/implementations/layers/eth_watch.rs

@@ -22,11 +22,13 @@ use crate::{
 /// such as priority operations (aka L1 transactions), protocol upgrades etc.
 ///
 /// ## Requests resources
-/// - [`PoolResource`] for [`MasterPool`]
-/// - [`EthInterfaceResource`]
+///
+/// - `PoolResource<MasterPool>`
+/// - `EthInterfaceResource`
 ///
 /// ## Adds tasks
-/// - [`EthWatchTask`] (as [`Task`])
+///
+/// - `EthWatchTask`
 #[derive(Debug)]
 pub struct EthWatchLayer {
     eth_watch_config: EthWatchConfig,

core/node/node_framework/src/implementations/layers/healtcheck_server.rs

@@ -17,11 +17,13 @@ use crate::{
 /// into [`AppHealthCheck`] aggregating heath using [`AppHealthCheckResource`].
 /// The added task spawns a health check server that only exposes the state provided by other tasks.
 ///
-/// ## Adds resources
-/// - [`AppHealthCheckResource`]
+/// ## Requests resources
+///
+/// - `AppHealthCheckResource`
 ///
 /// ## Adds tasks
-/// - [`HealthCheckTask`] (as [`UnconstrainedTask`])
+///
+/// - `HealthCheckTask`
 #[derive(Debug)]
 pub struct HealthCheckLayer(pub HealthCheckConfig);
 

core/node/node_framework/src/implementations/layers/house_keeper.rs

@@ -20,6 +20,26 @@ use crate::{
     wiring_layer::{WiringError, WiringLayer},
 };
 
+/// Wiring layer for `HouseKeeper` - a component responsible for managing prover jobs
+/// and auxiliary server activities.
+///
+/// ## Requests resources
+///
+/// - `PoolResource<ReplicaPool>`
+/// - `PoolResource<ProverPool>`
+///
+/// ## Adds tasks
+///
+/// - `L1BatchMetricsReporterTask`
+/// - `FriProverJobRetryManagerTask`
+/// - `FriWitnessGeneratorJobRetryManagerTask`
+/// - `WaitingToQueuedFriWitnessJobMoverTask`
+/// - `FriProverJobArchiverTask`
+/// - `FriProverGpuArchiverTask`
+/// - `FriWitnessGeneratorStatsReporterTask`
+/// - `FriProverStatsReporterTask`
+/// - `FriProofCompressorStatsReporterTask`
+/// - `FriProofCompressorJobRetryManagerTask`
 #[derive(Debug)]
 pub struct HouseKeeperLayer {
     house_keeper_config: HouseKeeperConfig,
@@ -54,14 +74,14 @@ impl WiringLayer for HouseKeeperLayer {
     }
 
     async fn wire(self: Box<Self>, mut context: ServiceContext<'_>) -> Result<(), WiringError> {
-        // initialize resources
+        // Initialize resources
         let replica_pool_resource = context.get_resource::<PoolResource<ReplicaPool>>().await?;
         let replica_pool = replica_pool_resource.get().await?;
 
         let prover_pool_resource = context.get_resource::<PoolResource<ProverPool>>().await?;
         let prover_pool = prover_pool_resource.get().await?;
 
-        // initialize and add tasks
+        // Initialize and add tasks
         let l1_batch_metrics_reporter = L1BatchMetricsReporter::new(
             self.house_keeper_config
                 .l1_batch_metrics_reporting_interval_ms,

core/node/node_framework/src/implementations/layers/l1_batch_commitment_mode_validation.rs

@@ -9,6 +9,16 @@ use crate::{
     wiring_layer::{WiringError, WiringLayer},
 };
 
+/// Wiring layer for a prerequisite that checks if the L1 batch commitment mode is valid
+/// against L1.
+///
+/// ## Requests resources
+///
+/// - `EthInterfaceResource`
+///
+/// ## Adds preconditions
+///
+/// - `L1BatchCommitmentModeValidationTask`
 #[derive(Debug)]
 pub struct L1BatchCommitmentModeValidationLayer {
     diamond_proxy_addr: Address,

core/node/node_framework/src/implementations/layers/l1_gas.rs

@@ -18,6 +18,21 @@ use crate::{
     wiring_layer::{WiringError, WiringLayer},
 };
 
+/// Wiring layer for sequencer L1 gas interfaces.
+/// Adds several resources that depend on L1 gas price.
+///
+/// ## Requests resources
+///
+/// - `EthInterfaceResource`
+///
+/// ## Adds resources
+///
+/// - `FeeInputResource`
+/// - `L1TxParamsResource`
+///
+/// ## Adds tasks
+///
+/// - `GasAdjusterTask` (only runs if someone uses the resourced listed above).
 #[derive(Debug)]
 pub struct SequencerL1GasLayer {
     gas_adjuster_config: GasAdjusterConfig,

core/node/node_framework/src/implementations/layers/main_node_client.rs

@@ -13,6 +13,15 @@ use crate::{
     wiring_layer::{WiringError, WiringLayer},
 };
 
+/// Wiring layer for main node client.
+///
+/// ## Requests resources
+///
+/// - `AppHealthCheckResource` (adds a health check)
+///
+/// ## Adds resources
+///
+/// - `MainNodeClientResource`
 #[derive(Debug)]
 pub struct MainNodeClientLayer {
     url: SensitiveUrl,

core/node/node_framework/src/implementations/layers/main_node_fee_params_fetcher.rs

@@ -11,6 +11,20 @@ use crate::{
     wiring_layer::{WiringError, WiringLayer},
 };
 
+/// Wiring layer for main node fee params fetcher -- a fee input resource used on
+/// the external node.
+///
+/// ## Requests resources
+///
+/// - `MainNodeClientResource`
+///
+/// ## Adds resources
+///
+/// - `FeeInputResource`
+///
+/// ## Adds tasks
+///
+/// - `MainNodeFeeParamsFetcherTask`
 #[derive(Debug)]
 pub struct MainNodeFeeParamsFetcherLayer;