fix(forge): improve error messages for etherscan verification failures

crates/config/src/etherscan.rs

@@ -53,7 +53,11 @@ pub enum EtherscanConfigError {
     #[error(transparent)]
     Unresolved(#[from] UnresolvedEnvVarError),
 
-    #[error("No known Etherscan API URL for config{0} with chain `{1}`. Please specify a `url`")]
+    #[error(
+        "No known Etherscan API URL for chain `{1}`. To fix this, please:\n\
+        1. Specify a `url` {0}\n\
+        2. Verify the chain `{1}` is correct"
+    )]
     UnknownChain(String, Chain),
 
     #[error("At least one of `url` or `chain` must be present{0}")]
@@ -233,7 +237,7 @@ impl EtherscanConfig {
             }),
             (Some(chain), None) => ResolvedEtherscanConfig::create(key, chain, api_version)
                 .ok_or_else(|| {
-                    let msg = alias.map(|a| format!(" `{a}`")).unwrap_or_default();
+                    let msg = alias.map(|a| format!("for `{a}`")).unwrap_or_default();
                     EtherscanConfigError::UnknownChain(msg, chain)
                 }),
             (None, Some(api_url)) => Ok(ResolvedEtherscanConfig {

crates/config/src/lib.rs

@@ -1429,13 +1429,20 @@ impl Config {
 
         // etherscan fallback via API key
         if let Some(key) = self.etherscan_api_key.as_ref() {
-            return Ok(ResolvedEtherscanConfig::create(
+            match ResolvedEtherscanConfig::create(
                 key,
                 chain.or(self.chain).unwrap_or_default(),
                 default_api_version,
-            ));
+            ) {
+                Some(config) => return Ok(Some(config)),
+                None => {
+                    return Err(EtherscanConfigError::UnknownChain(
+                        String::new(),
+                        chain.unwrap_or_default(),
+                    ));
+                }
+            }
         }
-
         Ok(None)
     }
 
@@ -5081,4 +5088,45 @@ mod tests {
             .unwrap();
         assert_eq!(endpoint.url, "https://rpc.sophon.xyz");
     }
+
+    #[test]
+    fn test_get_etherscan_config_with_unknown_chain() {
+        figment::Jail::expect_with(|jail| {
+            jail.create_file(
+                "foundry.toml",
+                r#"
+                [etherscan]
+                mainnet = { chain = 3658348, key = "api-key"}
+            "#,
+            )?;
+            let config = Config::load().unwrap();
+            let unknown_chain = Chain::from_id(3658348);
+            let result = config.get_etherscan_config_with_chain(Some(unknown_chain));
+            assert!(result.is_err());
+            let error_msg = result.unwrap_err().to_string();
+            assert!(error_msg.contains("No known Etherscan API URL for chain `3658348`"));
+            assert!(error_msg.contains("Specify a `url`"));
+            assert!(error_msg.contains("Verify the chain `3658348` is correct"));
+
+            Ok(())
+        });
+    }
+
+    #[test]
+    fn test_get_etherscan_config_with_existing_chain_and_url() {
+        figment::Jail::expect_with(|jail| {
+            jail.create_file(
+                "foundry.toml",
+                r#"
+                [etherscan]
+                mainnet = { chain = 1, key = "api-key" }
+            "#,
+            )?;
+            let config = Config::load().unwrap();
+            let unknown_chain = Chain::from_id(1);
+            let result = config.get_etherscan_config_with_chain(Some(unknown_chain));
+            assert!(result.is_ok());
+            Ok(())
+        });
+    }
 }

crates/verify/src/verify.rs

@@ -320,7 +320,11 @@ impl VerifyArgs {
                     .unwrap_or_default();
 
                 if unique_versions.is_empty() {
-                    eyre::bail!("No matching artifact found for {}", contract.name);
+                    eyre::bail!(
+                        "No matching artifact found for {}. This could be due to:\n\
+                        - Compiler version mismatch - the contract was compiled with a different Solidity version than what's being used for verification",
+                        contract.name
+                    );
                 } else if unique_versions.len() > 1 {
                     warn!(
                         "Ambiguous compiler versions found in cache: {}",
@@ -372,7 +376,12 @@ impl VerifyArgs {
                     .unwrap_or_default();
 
                 if profiles.is_empty() {
-                    eyre::bail!("No matching artifact found for {}", contract.name);
+                    eyre::bail!(
+                        "No matching artifact found for {} with compiler version {}. This could be due to:\n\
+                        - Compiler version mismatch - the contract was compiled with a different Solidity version",
+                        contract.name,
+                        version
+                    );
                 } else if profiles.len() > 1 {
                     eyre::bail!(
                         "Ambiguous compilation profiles found in cache: {}, please specify the profile through `--compilation-profile` flag",