feat: add devnet_getStatus RPC method (#942)

Add a new devnet_getStatus JSON-RPC method that returns:
- block_count, transaction_count, pre_confirmed_tx_count
- chain_id, protocol_version
- is_forked flag and fork_config (url, block) when forking
- impersonated_accounts list and auto_impersonate flag

Includes new helper methods in starknet-devnet-core and
integration tests.

Author: 3alpha

crates/starknet-devnet-core/src/starknet/cheats.rs

@@ -21,4 +21,10 @@ impl Cheats {
     pub(crate) fn set_auto_impersonate(&mut self, auto_impersonation: bool) {
         self.auto_impersonate = auto_impersonation;
     }
+    pub(crate) fn get_impersonated_accounts(&self) -> &HashSet<ContractAddress> {
+        &self.impersonated_accounts
+    }
+    pub(crate) fn is_auto_impersonate(&self) -> bool {
+        self.auto_impersonate
+    }
 }

crates/starknet-devnet-core/src/starknet/mod.rs

@@ -925,6 +925,36 @@ impl Starknet {
         self.config.chain_id
     }
 
+    /// Returns true if devnet is running in forking mode
+    pub fn is_forked(&self) -> bool {
+        self.config.fork_config.url.is_some()
+    }
+
+    /// Returns the total number of accepted blocks
+    pub fn get_block_count(&self) -> usize {
+        self.blocks.num_to_hash.len()
+    }
+
+    /// Returns the total number of transactions across all blocks (including pre_confirmed)
+    pub fn get_transaction_count(&self) -> usize {
+        self.transactions.len()
+    }
+
+    /// Returns the number of transactions in the pre-confirmed block
+    pub fn get_pre_confirmed_tx_count(&self) -> usize {
+        self.blocks.pre_confirmed_block.get_transactions().len()
+    }
+
+    /// Returns addresses of currently impersonated accounts
+    pub fn get_impersonated_accounts(&self) -> Vec<ContractAddress> {
+        self.cheats.get_impersonated_accounts().iter().copied().collect()
+    }
+
+    /// Returns whether auto-impersonate is enabled
+    pub fn is_auto_impersonate(&self) -> bool {
+        self.cheats.is_auto_impersonate()
+    }
+
     pub fn add_deploy_account_transaction(
         &mut self,
         deploy_account_transaction: BroadcastedDeployAccountTransaction,

crates/starknet-devnet-core/src/transactions.rs

@@ -36,6 +36,10 @@ impl StarknetTransactions {
     pub fn remove(&mut self, transaction_hash: &TransactionHash) -> Option<StarknetTransaction> {
         self.0.shift_remove(transaction_hash)
     }
+
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
 }
 
 impl HashIdentifiedMut for StarknetTransactions {

crates/starknet-devnet-server/src/api/endpoints.rs

@@ -24,8 +24,9 @@ use crate::api::account_helpers::{
     get_erc20_fee_unit_address,
 };
 use crate::api::models::{
-    AccountBalanceResponse, AccountBalancesResponse, DevnetResponse, ProveTransactionResponse,
-    SerializableAccount, StarknetExtResponse, StarknetResponse, StorageResult,
+    AccountBalanceResponse, AccountBalancesResponse, DevnetResponse, DevnetStatus, ForkStatus,
+    ProveTransactionResponse, SerializableAccount, StarknetExtResponse, StarknetResponse,
+    StorageResult,
 };
 use crate::api::{JsonRpcHandler, RPC_SPEC_VERSION};
 use crate::config::DevnetConfig;
@@ -856,4 +857,32 @@ impl JsonRpcHandler {
         })
         .into())
     }
+
+    /// devnet_getStatus
+    pub async fn get_devnet_status(&self) -> StrictRpcResult {
+        let starknet = self.api.starknet.lock().await;
+
+        let is_forked = starknet.is_forked();
+        let fork_config = if is_forked {
+            Some(ForkStatus {
+                url: starknet.config.fork_config.url.as_ref().map(|u| u.to_string()),
+                block: starknet.config.fork_config.block_number,
+            })
+        } else {
+            None
+        };
+
+        Ok(DevnetResponse::DevnetStatus(DevnetStatus {
+            block_count: starknet.get_block_count(),
+            transaction_count: starknet.get_transaction_count(),
+            pre_confirmed_tx_count: starknet.get_pre_confirmed_tx_count(),
+            chain_id: starknet.chain_id().to_string(),
+            protocol_version: RPC_SPEC_VERSION.to_string(),
+            is_forked,
+            fork_config,
+            impersonated_accounts: starknet.get_impersonated_accounts(),
+            auto_impersonate: starknet.is_auto_impersonate(),
+        })
+        .into())
+    }
 }

crates/starknet-devnet-server/src/api/json_rpc_handler.rs

@@ -549,6 +549,7 @@ impl JsonRpcHandler {
             DevnetSpecRequest::AccountBalance(data) => self.get_account_balance(data).await,
             DevnetSpecRequest::Mint(data) => self.mint(data).await,
             DevnetSpecRequest::DevnetConfig => self.get_devnet_config().await,
+            DevnetSpecRequest::DevnetStatus => self.get_devnet_status().await,
         }
     }
 

crates/starknet-devnet-server/src/api/models/json_rpc_request.rs

@@ -181,6 +181,8 @@ pub enum DevnetSpecRequest {
     Mint(MintTokensRequest),
     #[serde(rename = "devnet_getConfig", with = "empty_params")]
     DevnetConfig,
+    #[serde(rename = "devnet_getStatus", with = "empty_params")]
+    DevnetStatus,
 }
 
 #[cfg_attr(test, derive(Debug))]
@@ -385,7 +387,8 @@ impl DevnetSpecRequest {
             | Self::Restart(_)
             | Self::PredeployedAccounts(_)
             | Self::AccountBalance(_)
-            | Self::DevnetConfig => false,
+            | Self::DevnetConfig
+            | Self::DevnetStatus => false,
         }
     }
 
@@ -413,7 +416,8 @@ impl DevnetSpecRequest {
             | Self::Restart(_)
             | Self::PredeployedAccounts(_)
             | Self::AccountBalance(_)
-            | Self::DevnetConfig => false,
+            | Self::DevnetConfig
+            | Self::DevnetStatus => false,
         }
     }
 }

crates/starknet-devnet-server/src/api/models/json_rpc_response.rs

@@ -17,10 +17,10 @@ use starknet_types::starknet_api::block::BlockNumber;
 
 use crate::api::models::{
     AbortedBlocks, AcceptedOnL1Blocks, AccountBalanceResponse, BlockHashAndNumberOutput,
-    CreatedBlock, DeclareTransactionOutput, DeployAccountTransactionOutput, DumpResponseBody,
-    FlushedMessages, IncreaseTimeResponse, MessageHash, MessagingLoadAddress, MintTokensResponse,
-    ProveTransactionResponse, SerializableAccount, SetTimeResponse, StorageResult, SyncingOutput,
-    TransactionHashOutput,
+    CreatedBlock, DeclareTransactionOutput, DeployAccountTransactionOutput, DevnetStatus,
+    DumpResponseBody, FlushedMessages, IncreaseTimeResponse, MessageHash, MessagingLoadAddress,
+    MintTokensResponse, ProveTransactionResponse, SerializableAccount, SetTimeResponse,
+    StorageResult, SyncingOutput, TransactionHashOutput,
 };
 use crate::config::DevnetConfig;
 
@@ -115,6 +115,7 @@ pub enum DevnetResponse {
     MintTokens(MintTokensResponse),
     DevnetConfig(DevnetConfig),
     DevnetDump(DumpResponseBody),
+    DevnetStatus(DevnetStatus),
 }
 
 #[cfg(test)]

crates/starknet-devnet-server/src/api/models/mod.rs

@@ -509,6 +509,20 @@ pub struct ForkStatus {
     pub block: Option<u64>,
 }
 
+#[derive(Serialize)]
+pub struct DevnetStatus {
+    pub block_count: usize,
+    pub transaction_count: usize,
+    pub pre_confirmed_tx_count: usize,
+    pub chain_id: String,
+    pub protocol_version: String,
+    pub is_forked: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fork_config: Option<ForkStatus>,
+    pub impersonated_accounts: Vec<ContractAddress>,
+    pub auto_impersonate: bool,
+}
+
 #[derive(Serialize, Deserialize)]
 pub struct FlushedMessages {
     pub messages_to_l1: Vec<MessageToL1>,

tests/integration/get_devnet_status.rs

@@ -0,0 +1,50 @@
+use serde_json::json;
+
+use crate::common::background_devnet::BackgroundDevnet;
+
+#[tokio::test]
+async fn devnet_get_status_initial_state() {
+    let devnet = BackgroundDevnet::spawn().await.expect("Could not start Devnet");
+
+    let status = devnet.send_custom_rpc("devnet_getStatus", json!({})).await.unwrap();
+
+    // Verify structure and initial values
+    assert_eq!(status["block_count"].as_u64().unwrap(), 1, "Genesis block should be present");
+    assert_eq!(status["transaction_count"].as_u64().unwrap(), 0, "No transactions initially");
+    assert_eq!(status["pre_confirmed_tx_count"].as_u64().unwrap(), 0);
+    assert!(status["chain_id"].as_str().unwrap().contains("SEPOLIA"));
+    assert_eq!(status["protocol_version"].as_str().unwrap(), "0.10.2");
+    assert!(!status["is_forked"].as_bool().unwrap());
+    // fork_config is only present when forking
+    assert!(
+        status.get("fork_config").is_none_or(|v| v.is_null()),
+        "fork_config should be absent/omitted when not forking"
+    );
+    assert!(status["impersonated_accounts"].as_array().unwrap().is_empty());
+    assert!(!status["auto_impersonate"].as_bool().unwrap());
+}
+
+#[tokio::test]
+async fn devnet_get_status_after_interaction() {
+    let devnet = BackgroundDevnet::spawn().await.expect("Could not start Devnet");
+
+    // Create a block to change block count
+    devnet.create_block().await.unwrap();
+
+    let status = devnet.send_custom_rpc("devnet_getStatus", json!({})).await.unwrap();
+    assert!(
+        status["block_count"].as_u64().unwrap() >= 2,
+        "Block count should increase after creating a block"
+    );
+
+    // Mint tokens to generate a transaction
+    let (_, account_address) = devnet.get_first_predeployed_account().await;
+    let mint_amount = 1_000_000u128;
+    devnet.mint(account_address, mint_amount).await;
+
+    let status = devnet.send_custom_rpc("devnet_getStatus", json!({})).await.unwrap();
+    assert!(
+        status["transaction_count"].as_u64().unwrap() >= 1,
+        "Transaction count should increase after minting"
+    );
+}

tests/integration/lib.rs

@@ -23,6 +23,7 @@ mod get_block_txs_count;
 mod get_block_with_txs_and_receipts;
 mod get_class;
 mod get_class_hash_at;
+mod get_devnet_status;
 mod get_events;
 mod get_transaction_by_block_id_and_index;
 mod get_transaction_by_hash;