feat: add finality status from CLI defaulting to AcceptedOnL2

Author: glihm

bin/sozo/src/commands/options/transaction.rs

@@ -1,6 +1,7 @@
 use anyhow::{bail, Result};
 use clap::Args;
 use dojo_utils::{FeeConfig, TxnAction, TxnConfig};
+use starknet::core::types::TransactionFinalityStatus;
 
 #[derive(Debug, Clone, Args, Default)]
 #[command(next_help_heading = "Transaction options")]
@@ -62,6 +63,15 @@ pub struct TransactionOptions {
     #[arg(global = true)]
     #[arg(default_value = "10")]
     pub max_calls: Option<usize>,
+
+    #[arg(long)]
+    #[arg(help = "The finality status to wait for. Since 0.14, the nodes syncing is sometime \
+                  not fast enough to propagate the transaction to the nodes in the \
+                  PRE-CONFIRMED state. The default is ACCEPTED_ON_L2. Available options are: \
+                  PRE-CONFIRMED, ACCEPTED_ON_L2, ACCEPTED_ON_L1.")]
+    #[arg(global = true)]
+    #[arg(default_value = "ACCEPTED_ON_L2")]
+    pub finality_status: Option<String>,
 }
 
 impl TransactionOptions {
@@ -89,6 +99,7 @@ impl TransactionOptions {
                 },
                 walnut: self.walnut,
                 max_calls: self.max_calls,
+                finality_status: parse_finality_status(self.finality_status.clone())?,
             }),
         }
     }
@@ -111,10 +122,33 @@ impl TryFrom<TransactionOptions> for TxnConfig {
                 l2_gas_price: value.l2_gas_price,
             },
             max_calls: value.max_calls,
+            finality_status: parse_finality_status(value.finality_status.clone())?,
         })
     }
 }
 
+/// Parses the finality status from a string.
+/// If no status is provided, the default is ACCEPTED_ON_L2.
+/// # Arguments
+///
+/// * `status` - The finality status to parse.
+///
+/// # Returns
+///
+/// The parsed finality status.
+fn parse_finality_status(status: Option<String>) -> Result<TransactionFinalityStatus> {
+    if let Some(status) = status {
+        match status.to_uppercase().as_str() {
+            "PRE_CONFIRMED" => Ok(TransactionFinalityStatus::PreConfirmed),
+            "ACCEPTED_ON_L2" => Ok(TransactionFinalityStatus::AcceptedOnL2),
+            "ACCEPTED_ON_L1" => Ok(TransactionFinalityStatus::AcceptedOnL1),
+            _ => bail!("Invalid finality status: {}", status),
+        }
+    } else {
+        Ok(TransactionFinalityStatus::AcceptedOnL2)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use anyhow::Result;
@@ -134,6 +168,7 @@ mod tests {
             l2_gas_price: Some(1_000),
             walnut: false,
             max_calls: Some(10),
+            finality_status: Some("PRE_CONFIRMED".to_string()),
         };
 
         let config: TxnConfig = opts.try_into()?;
@@ -150,6 +185,32 @@ mod tests {
         assert_eq!(config.fee_config.l2_gas, Some(10_000));
         assert_eq!(config.fee_config.l2_gas_price, Some(1_000));
 
+        assert_eq!(config.finality_status, TransactionFinalityStatus::PreConfirmed);
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_parse_finality_status() -> Result<()> {
+        matches!(
+            parse_finality_status(Some("PRE_CONFIRMED".to_string())),
+            Ok(TransactionFinalityStatus::PreConfirmed)
+        );
+
+        matches!(
+            parse_finality_status(Some("ACCEPTED_ON_L2".to_string())),
+            Ok(TransactionFinalityStatus::AcceptedOnL2)
+        );
+
+        matches!(
+            parse_finality_status(Some("ACCEPTED_ON_L1".to_string())),
+            Ok(TransactionFinalityStatus::AcceptedOnL1)
+        );
+
+        matches!(parse_finality_status(None), Ok(TransactionFinalityStatus::AcceptedOnL2));
+
+        assert!(parse_finality_status(Some("INVALID".to_string())).is_err());
+
         Ok(())
     }
 }

crates/dojo/utils/src/tx/deployer.rs

@@ -88,8 +88,9 @@ where
         );
 
         if self.txn_config.wait {
-            let receipt =
-                TransactionWaiter::new(transaction_hash, &self.account.provider()).await?;
+            let receipt = TransactionWaiter::new(transaction_hash, &self.account.provider())
+                .with_tx_status(self.txn_config.finality_status)
+                .await?;
 
             if self.txn_config.receipt {
                 return Ok((

crates/dojo/utils/src/tx/invoker.rs

@@ -65,8 +65,9 @@ where
         trace!(transaction_hash = format!("{:#066x}", tx.transaction_hash), "Invoke contract.");
 
         if self.txn_config.wait {
-            let receipt =
-                TransactionWaiter::new(tx.transaction_hash, &self.account.provider()).await?;
+            let receipt = TransactionWaiter::new(tx.transaction_hash, &self.account.provider())
+                .with_tx_status(self.txn_config.finality_status)
+                .await?;
 
             if self.txn_config.receipt {
                 return Ok(TransactionResult::HashReceipt(tx.transaction_hash, Box::new(receipt)));
@@ -114,6 +115,7 @@ where
                 if self.txn_config.wait {
                     let receipt =
                         TransactionWaiter::new(tx.transaction_hash, &self.account.provider())
+                            .with_tx_status(self.txn_config.finality_status)
                             .await?;
 
                     if self.txn_config.receipt {
@@ -141,8 +143,9 @@ where
             );
 
             if self.txn_config.wait {
-                let receipt =
-                    TransactionWaiter::new(tx.transaction_hash, &self.account.provider()).await?;
+                let receipt = TransactionWaiter::new(tx.transaction_hash, &self.account.provider())
+                    .with_tx_status(self.txn_config.finality_status)
+                    .await?;
 
                 if self.txn_config.receipt {
                     return Ok(vec![TransactionResult::HashReceipt(

crates/dojo/utils/src/tx/mod.rs

@@ -15,7 +15,7 @@ use starknet::accounts::{
 };
 use starknet::core::types::{
     BlockId, BlockTag, DeclareTransactionResult, DeployAccountTransactionResult, Felt,
-    InvokeTransactionResult, TransactionReceiptWithBlockInfo,
+    InvokeTransactionResult, TransactionFinalityStatus, TransactionReceiptWithBlockInfo,
 };
 use starknet::providers::jsonrpc::HttpTransport;
 use starknet::providers::{AnyProvider, JsonRpcClient, Provider};
@@ -38,7 +38,7 @@ pub struct FeeConfig {
 }
 
 /// The transaction configuration to use when sending a transaction.
-#[derive(Debug, Copy, Clone, Default)]
+#[derive(Debug, Copy, Clone)]
 pub struct TxnConfig {
     /// Whether to wait for the transaction to be accepted or reverted on L2.
     pub wait: bool,
@@ -52,6 +52,24 @@ pub struct TxnConfig {
     /// This number could vary depending on the calls content, and is mostly
     /// here to ensure the migration is not stuck if too much resources have to be registered.
     pub max_calls: Option<usize>,
+    /// The finality status to wait for.
+    /// Since 0.14, the nodes syncing is sometime not fast enough to propagate the transaction to
+    /// the nodes in the PRE-CONFIRMED state. Exposing the finality status allows to wait for
+    /// the transaction to be accepted on L2 when a more robust migration is needed.
+    pub finality_status: TransactionFinalityStatus,
+}
+
+impl Default for TxnConfig {
+    fn default() -> Self {
+        Self {
+            wait: true,
+            receipt: false,
+            walnut: false,
+            fee_config: FeeConfig::default(),
+            max_calls: None,
+            finality_status: TransactionFinalityStatus::AcceptedOnL2,
+        }
+    }
 }
 
 #[derive(Debug, Clone)]
@@ -62,6 +80,7 @@ pub enum TxnAction {
         fee_config: FeeConfig,
         walnut: bool,
         max_calls: Option<usize>,
+        finality_status: TransactionFinalityStatus,
     },
     Estimate,
     Simulate,