move consts and add documentation comments to the retry module

Author: maximopalopoli

aggregation_mode/proof_aggregator/src/backend/mod.rs

@@ -10,15 +10,14 @@ use crate::{
     aggregators::{AlignedProof, ProofAggregationError, ZKVMEngine},
     backend::{
         db::{Db, DbError},
-        retry::{retry_function, RetryError},
+        retry::{
+            retry_function, RetryError, ETHEREUM_CALL_BACKOFF_FACTOR, ETHEREUM_CALL_MAX_RETRIES,
+            ETHEREUM_CALL_MAX_RETRY_DELAY, ETHEREUM_CALL_MIN_RETRY_DELAY,
+        },
         types::{AlignedProofAggregationService, AlignedProofAggregationServiceContract},
     },
 };
 
-use aligned_sdk::common::constants::{
-    ETHEREUM_CALL_BACKOFF_FACTOR, ETHEREUM_CALL_MAX_RETRIES, ETHEREUM_CALL_MAX_RETRY_DELAY,
-    ETHEREUM_CALL_MIN_RETRY_DELAY,
-};
 use alloy::{
     consensus::{BlobTransactionSidecar, EnvKzgSettings, EthereumTxEnvelope, TxEip4844WithSidecar},
     eips::{eip4844::BYTES_PER_BLOB, eip7594::BlobTransactionSidecarEip7594, Encodable2718},

aggregation_mode/proof_aggregator/src/backend/retry.rs

@@ -1,6 +1,57 @@
 use std::future::Future;
 use std::time::Duration;
 
+/// Retry/backoff behavior summary:
+///
+/// This module retries transient failures using exponential backoff, but permanent failures stop immediately.
+///
+/// Backoff algorithm:
+/// - Starts with `delay = ETHEREUM_CALL_MIN_RETRY_DELAY`
+/// - After each transient failure, sleeps for `delay` and then updates it following the next formula:
+///     delay = min(delay * ETHEREUM_CALL_BACKOFF_FACTOR, ETHEREUM_CALL_MAX_RETRY_DELAY)
+/// - Stops retrying when the number of attempts exceed the `ETHEREUM_CALL_MAX_RETRIES` constant
+///
+/// About the retries limit: In the current implementation `attempt` starts at 0 and we stop when
+///   `attempt >= max_times`, incrementing `attempt` after sleeping. That means the code can perform
+/// max_times + 1 sleeps/retries. With the current constant value (10), that is 11 backoff intervals.
+///
+/// Delay schedule with current config
+/// (start = 500ms, factor = 2.0, max delay = 60s, max_times = 10):
+///
+///   retry  1: 0.5s
+///   retry  2: 1.0s
+///   retry  3: 2.0s
+///   retry  4: 4.0s
+///   retry  5: 8.0s
+///   retry  6: 16.0s
+///   retry  7: 32.0s
+///   retry  8: 60.0s  (capped)
+///   retry  9: 60.0s
+///   retry 10: 60.0s
+///   retry 11: 60.0s  (due to the max_times + 1 behavior described above)
+///
+/// Worst-case total sleep time across all retries:
+///   0.5 + 1 + 2 + 4 + 8 + 16 + 32 + 60 + 60 + 60 + 60
+/// = 303.5 seconds (~5m 3.5s),
+/// plus the execution time of each Ethereum call attempt.
+
+/// Minimum delay value (the one on first iteration)
+pub const ETHEREUM_CALL_MIN_RETRY_DELAY: u64 = 500; // milliseconds
+
+/// Maximum number of retry attempts.
+///
+/// Note: With the current retry loop logic this behaves as "max_times + 1"
+/// backoff intervals.
+pub const ETHEREUM_CALL_MAX_RETRIES: usize = 10;
+
+/// Exponential backoff multiplier applied to the delay after each transient failure.
+///
+/// Note: This value should be at least 1.0, otherwise will be clamped so the backoff never shrinks.
+pub const ETHEREUM_CALL_BACKOFF_FACTOR: f32 = 2.0;
+
+/// Maximum delay between retries (seconds). Delays are capped to this value.
+pub const ETHEREUM_CALL_MAX_RETRY_DELAY: u64 = 60; // seconds
+
 #[derive(Debug)]
 pub enum RetryError<E> {
     Transient(E),
@@ -54,7 +105,10 @@ where
                     return Err(RetryError::Transient(e));
                 }
 
-                tracing::warn!("Retryable function failed: {e}");
+                tracing::warn!(
+                    "Retryable function failed, retrying in {} seconds",
+                    delay.as_secs()
+                );
 
                 tokio::time::sleep(delay).await;