feat: support trace methods in provider (#481)

starknet-providers/src/any.rs

@@ -5,7 +5,8 @@ use starknet_core::types::{
     ContractClass, DeclareTransactionResult, DeployAccountTransactionResult, EventFilter,
     EventsPage, FeeEstimate, FieldElement, FunctionCall, InvokeTransactionResult,
     MaybePendingBlockWithTxHashes, MaybePendingBlockWithTxs, MaybePendingStateUpdate,
-    MaybePendingTransactionReceipt, MsgFromL1, SyncStatusType, Transaction,
+    MaybePendingTransactionReceipt, MsgFromL1, SimulatedTransaction, SimulationFlag,
+    SyncStatusType, Transaction, TransactionTrace, TransactionTraceWithHash,
 };
 
 use crate::{
@@ -551,6 +552,82 @@ impl Provider for AnyProvider {
             ),
         }
     }
+
+    async fn trace_transaction<H>(
+        &self,
+        transaction_hash: H,
+    ) -> Result<TransactionTrace, ProviderError<Self::Error>>
+    where
+        H: AsRef<FieldElement> + Send + Sync,
+    {
+        match self {
+            Self::JsonRpcHttp(inner) => Ok(
+                <JsonRpcClient<HttpTransport> as Provider>::trace_transaction(
+                    inner,
+                    transaction_hash,
+                )
+                .await?,
+            ),
+            Self::SequencerGateway(inner) => Ok(
+                <SequencerGatewayProvider as Provider>::trace_transaction(inner, transaction_hash)
+                    .await?,
+            ),
+        }
+    }
+
+    async fn simulate_transactions<B, T, S>(
+        &self,
+        block_id: B,
+        transactions: T,
+        simulation_flags: S,
+    ) -> Result<Vec<SimulatedTransaction>, ProviderError<Self::Error>>
+    where
+        B: AsRef<BlockId> + Send + Sync,
+        T: AsRef<[BroadcastedTransaction]> + Send + Sync,
+        S: AsRef<[SimulationFlag]> + Send + Sync,
+    {
+        match self {
+            Self::JsonRpcHttp(inner) => Ok(
+                <JsonRpcClient<HttpTransport> as Provider>::simulate_transactions(
+                    inner,
+                    block_id,
+                    transactions,
+                    simulation_flags,
+                )
+                .await?,
+            ),
+            Self::SequencerGateway(inner) => Ok(
+                <SequencerGatewayProvider as Provider>::simulate_transactions(
+                    inner,
+                    block_id,
+                    transactions,
+                    simulation_flags,
+                )
+                .await?,
+            ),
+        }
+    }
+
+    async fn trace_block_transactions<H>(
+        &self,
+        block_hash: H,
+    ) -> Result<Vec<TransactionTraceWithHash>, ProviderError<Self::Error>>
+    where
+        H: AsRef<FieldElement> + Send + Sync,
+    {
+        match self {
+            Self::JsonRpcHttp(inner) => Ok(
+                <JsonRpcClient<HttpTransport> as Provider>::trace_block_transactions(
+                    inner, block_hash,
+                )
+                .await?,
+            ),
+            Self::SequencerGateway(inner) => Ok(
+                <SequencerGatewayProvider as Provider>::trace_block_transactions(inner, block_hash)
+                    .await?,
+            ),
+        }
+    }
 }
 
 impl From<ProviderError<<JsonRpcClient<HttpTransport> as Provider>::Error>>

starknet-providers/src/jsonrpc/mod.rs

@@ -10,7 +10,8 @@ use starknet_core::{
         EventFilterWithPage, EventsPage, FeeEstimate, FieldElement, FunctionCall,
         InvokeTransactionResult, MaybePendingBlockWithTxHashes, MaybePendingBlockWithTxs,
         MaybePendingStateUpdate, MaybePendingTransactionReceipt, MsgFromL1, ResultPageRequest,
-        StarknetError, SyncStatusType, Transaction,
+        SimulatedTransaction, SimulationFlag, StarknetError, SyncStatusType, Transaction,
+        TransactionTrace, TransactionTraceWithHash,
     },
 };
 
@@ -77,6 +78,12 @@ pub enum JsonRpcMethod {
     AddDeclareTransaction,
     #[serde(rename = "starknet_addDeployAccountTransaction")]
     AddDeployAccountTransaction,
+    #[serde(rename = "starknet_traceTransaction")]
+    TraceTransaction,
+    #[serde(rename = "starknet_simulateTransactions")]
+    SimulateTransactions,
+    #[serde(rename = "starknet_traceBlockTransactions")]
+    TraceBlockTransactions,
 }
 
 #[derive(Debug, Clone)]
@@ -111,6 +118,9 @@ pub enum JsonRpcRequestData {
     AddInvokeTransaction(AddInvokeTransactionRequest),
     AddDeclareTransaction(AddDeclareTransactionRequest),
     AddDeployAccountTransaction(AddDeployAccountTransactionRequest),
+    TraceTransaction(TraceTransactionRequest),
+    SimulateTransactions(SimulateTransactionsRequest),
+    TraceBlockTransactions(TraceBlockTransactionsRequest),
 }
 
 #[derive(Debug, thiserror::Error)]
@@ -601,6 +611,65 @@ where
         )
         .await
     }
+
+    /// For a given executed transaction, return the trace of its execution, including internal
+    /// calls
+    async fn trace_transaction<H>(
+        &self,
+        transaction_hash: H,
+    ) -> Result<TransactionTrace, ProviderError<Self::Error>>
+    where
+        H: AsRef<FieldElement> + Send + Sync,
+    {
+        self.send_request(
+            JsonRpcMethod::TraceTransaction,
+            TraceTransactionRequestRef {
+                transaction_hash: transaction_hash.as_ref(),
+            },
+        )
+        .await
+    }
+
+    /// Simulate a given sequence of transactions on the requested state, and generate the execution
+    /// traces. If one of the transactions is reverted, raises CONTRACT_ERROR.
+    async fn simulate_transactions<B, TX, S>(
+        &self,
+        block_id: B,
+        transactions: TX,
+        simulation_flags: S,
+    ) -> Result<Vec<SimulatedTransaction>, ProviderError<Self::Error>>
+    where
+        B: AsRef<BlockId> + Send + Sync,
+        TX: AsRef<[BroadcastedTransaction]> + Send + Sync,
+        S: AsRef<[SimulationFlag]> + Send + Sync,
+    {
+        self.send_request(
+            JsonRpcMethod::SimulateTransactions,
+            SimulateTransactionsRequestRef {
+                block_id: block_id.as_ref(),
+                transactions: transactions.as_ref(),
+                simulation_flags: simulation_flags.as_ref(),
+            },
+        )
+        .await
+    }
+
+    /// Retrieve traces for all transactions in the given block.
+    async fn trace_block_transactions<H>(
+        &self,
+        block_hash: H,
+    ) -> Result<Vec<TransactionTraceWithHash>, ProviderError<Self::Error>>
+    where
+        H: AsRef<FieldElement> + Send + Sync,
+    {
+        self.send_request(
+            JsonRpcMethod::TraceBlockTransactions,
+            TraceBlockTransactionsRequestRef {
+                block_hash: block_hash.as_ref(),
+            },
+        )
+        .await
+    }
 }
 
 impl<'de> Deserialize<'de> for JsonRpcRequest {
@@ -725,6 +794,18 @@ impl<'de> Deserialize<'de> for JsonRpcRequest {
                     .map_err(error_mapper)?,
                 )
             }
+            JsonRpcMethod::TraceTransaction => JsonRpcRequestData::TraceTransaction(
+                serde_json::from_value::<TraceTransactionRequest>(raw_request.params)
+                    .map_err(error_mapper)?,
+            ),
+            JsonRpcMethod::SimulateTransactions => JsonRpcRequestData::SimulateTransactions(
+                serde_json::from_value::<SimulateTransactionsRequest>(raw_request.params)
+                    .map_err(error_mapper)?,
+            ),
+            JsonRpcMethod::TraceBlockTransactions => JsonRpcRequestData::TraceBlockTransactions(
+                serde_json::from_value::<TraceBlockTransactionsRequest>(raw_request.params)
+                    .map_err(error_mapper)?,
+            ),
         };
 
         Ok(Self {

starknet-providers/src/provider.rs

@@ -6,7 +6,8 @@ use starknet_core::types::{
     ContractClass, DeclareTransactionResult, DeployAccountTransactionResult, EventFilter,
     EventsPage, FeeEstimate, FieldElement, FunctionCall, InvokeTransactionResult,
     MaybePendingBlockWithTxHashes, MaybePendingBlockWithTxs, MaybePendingStateUpdate,
-    MaybePendingTransactionReceipt, MsgFromL1, StarknetError, SyncStatusType, Transaction,
+    MaybePendingTransactionReceipt, MsgFromL1, SimulatedTransaction, SimulationFlag, StarknetError,
+    SyncStatusType, Transaction, TransactionTrace, TransactionTraceWithHash,
 };
 use std::error::Error;
 
@@ -202,6 +203,36 @@ pub trait Provider {
     where
         D: AsRef<BroadcastedDeployAccountTransaction> + Send + Sync;
 
+    /// For a given executed transaction, return the trace of its execution, including internal
+    /// calls
+    async fn trace_transaction<H>(
+        &self,
+        transaction_hash: H,
+    ) -> Result<TransactionTrace, ProviderError<Self::Error>>
+    where
+        H: AsRef<FieldElement> + Send + Sync;
+
+    /// Simulate a given sequence of transactions on the requested state, and generate the execution
+    /// traces. If one of the transactions is reverted, raises CONTRACT_ERROR.
+    async fn simulate_transactions<B, T, S>(
+        &self,
+        block_id: B,
+        transactions: T,
+        simulation_flags: S,
+    ) -> Result<Vec<SimulatedTransaction>, ProviderError<Self::Error>>
+    where
+        B: AsRef<BlockId> + Send + Sync,
+        T: AsRef<[BroadcastedTransaction]> + Send + Sync,
+        S: AsRef<[SimulationFlag]> + Send + Sync;
+
+    /// Retrieve traces for all transactions in the given block.
+    async fn trace_block_transactions<H>(
+        &self,
+        block_hash: H,
+    ) -> Result<Vec<TransactionTraceWithHash>, ProviderError<Self::Error>>
+    where
+        H: AsRef<FieldElement> + Send + Sync;
+
     /// Same as [estimate_fee], but only with one estimate.
     async fn estimate_fee_single<R, B>(
         &self,
@@ -223,6 +254,34 @@ pub trait Provider {
             Err(ProviderError::ArrayLengthMismatch)
         }
     }
+
+    /// Same as [simulate_transactions], but only with one simulation.
+    async fn simulate_transaction<B, T, S>(
+        &self,
+        block_id: B,
+        transaction: T,
+        simulation_flags: S,
+    ) -> Result<SimulatedTransaction, ProviderError<Self::Error>>
+    where
+        B: AsRef<BlockId> + Send + Sync,
+        T: AsRef<BroadcastedTransaction> + Send + Sync,
+        S: AsRef<[SimulationFlag]> + Send + Sync,
+    {
+        let mut result = self
+            .simulate_transactions(
+                block_id,
+                [transaction.as_ref().to_owned()],
+                simulation_flags,
+            )
+            .await?;
+
+        if result.len() == 1 {
+            // Unwrapping here is safe becuase we already checked length
+            Ok(result.pop().unwrap())
+        } else {
+            Err(ProviderError::ArrayLengthMismatch)
+        }
+    }
 }
 
 #[derive(Debug, thiserror::Error)]

starknet-providers/src/sequencer/mod.rs

@@ -48,6 +48,12 @@ pub enum GatewayClientError {
     /// Model conversion error (only when using as [Provider])
     #[error("unable to convert gateway models to jsonrpc types")]
     ModelConversionError,
+    /// Simulating multiple transactions is not supported (only when using as [Provider])
+    #[error("simulating multiple transactions not supported")]
+    BulkSimulationNotSupported,
+    /// At least one of the simulation flags is not supported (only when using as [Provider])
+    #[error("unsupported simulation flag")]
+    UnsupportedSimulationFlag,
 }
 
 #[derive(Debug, thiserror::Error, Deserialize)]