cli: improve RPC error detection (#720)

* cli: improve RPC error detection

* add rpc error handling to sui & solana + extend error message for evm chains

Author: evgeniko

cli/src/error.ts

@@ -0,0 +1,81 @@
+import chalk from "chalk";
+import type { Chain, Network } from "@wormhole-foundation/sdk";
+import { chainToPlatform } from "@wormhole-foundation/sdk-base";
+
+/**
+ * Handles RPC-related errors and provides helpful error messages with suggestions.
+ * 
+ * @param error - The error that occurred
+ * @param chain - The chain being deployed to
+ * @param network - The network (Mainnet, Testnet, Devnet)
+ * @param rpc - The RPC endpoint URL that failed
+ */
+export function handleRpcError(
+  error: any,
+  chain: Chain,
+  network: Network,
+  rpc: string
+): never {
+  const errorMessage = error?.message || String(error);
+  const errorStack = error?.stack || "";
+  
+  // Check if this is an RPC-related error by looking for common RPC error indicators
+  const isRpcError =
+    errorMessage.toLowerCase().includes("jsonrpc") ||
+    errorStack.toLowerCase().includes("jsonrpc") ||
+    errorMessage.toLowerCase().includes("rpc") ||
+    errorMessage.toLowerCase().includes("connection") ||
+    errorMessage.toLowerCase().includes("network error");
+
+  if (isRpcError) {
+    console.error(chalk.red(`RPC connection error for ${chain} on ${network}\n`));
+    console.error(chalk.yellow("RPC endpoint:"), chalk.white(rpc));
+    console.error(chalk.yellow("Error:"), errorMessage);
+    console.error();
+    console.error(
+      chalk.yellow(
+        "This error usually means the RPC endpoint is missing, invalid, or unreachable."
+      )
+    );
+    console.error(
+      chalk.yellow(
+        "You can specify a private RPC endpoint by creating an overrides.json file.\n"
+      )
+    );
+    console.error(chalk.cyan("Create a file named ") + chalk.white("overrides.json") + chalk.cyan(" in your project root:"));
+    console.error(chalk.white(`
+{
+  "chains": {
+    "${chain}": {
+      "rpc": "https://your-private-rpc-endpoint"
+    }
+  }
+}
+`));
+    
+    // Show chainlist.org only for EVM chains
+    try {
+      const platform = chainToPlatform(chain as any);
+      if (platform === "Evm") {
+        console.error(
+          chalk.cyan(
+            `Find RPC endpoints for ${chain}: https://chainlist.org`
+          )
+        );
+      }
+    } catch (e) {
+      // If chainToPlatform fails, just skip the platform-specific message
+    }
+    
+    console.error(
+      chalk.cyan(
+        `For more information about overrides.json:\n` +
+          `  • https://wormhole.com/docs/products/token-transfers/native-token-transfers/faqs/#how-can-i-specify-a-custom-rpc-for-ntt`
+      )
+    );
+  } else {
+    console.error(chalk.red("\n Error during deployment:"));
+    console.error(errorMessage);
+  }
+  process.exit(1);
+}

cli/src/index.ts

@@ -70,6 +70,7 @@ import { type SuiChains } from "@wormhole-foundation/sdk-sui";
 
 import { colorizeDiff, diffObjects } from "./diff";
 import { forgeSignerArgs, getSigner, type SignerType } from "./getSigner";
+import { handleRpcError } from "./error";
 
 // Configuration fields that should be excluded from diff operations
 // These are local-only configurations that don't have on-chain representations
@@ -3032,6 +3033,7 @@ async function deployEvm<N extends Network, C extends Chain>(
   }
 
   const rpc = ch.config.rpc;
+
   // TODO: how to make specialRelayer configurable??
   let specialRelayer: string;
   if (ch.chain === "Avalanche") {
@@ -3042,10 +3044,17 @@ async function deployEvm<N extends Network, C extends Chain>(
     specialRelayer = "0x63BE47835c7D66c4aA5B2C688Dc6ed9771c94C74";
   }
 
-  const provider = new ethers.JsonRpcProvider(rpc);
-  const abi = ["function decimals() external view returns (uint8)"];
-  const tokenContract = new ethers.Contract(token, abi, provider);
-  const decimals: number = await tokenContract.decimals();
+  let provider: ethers.JsonRpcProvider;
+  let decimals: number;
+
+  try {
+    provider = new ethers.JsonRpcProvider(rpc);
+    const abi = ["function decimals() external view returns (uint8)"];
+    const tokenContract = new ethers.Contract(token, abi, provider);
+    decimals = await tokenContract.decimals();
+  } catch (error) {
+    handleRpcError(error, ch.chain, ch.network, rpc);
+  }
 
   // TODO: should actually make these ENV variables.
   const sig = "run(address,address,address,address,uint8,uint8)";
@@ -3279,7 +3288,12 @@ async function deploySolana<N extends Network, C extends SolanaChains>(
   // get the mint authority of 'token'
   const tokenMint = new PublicKey(token);
   const connection: Connection = await ch.getRpc();
-  const mintInfo = await connection.getAccountInfo(tokenMint);
+  let mintInfo;
+  try {
+    mintInfo = await connection.getAccountInfo(tokenMint);
+  } catch (error) {
+    handleRpcError(error, ch.chain, ch.network, ch.config.rpc);
+  }
   if (!mintInfo) {
     console.error(`Mint ${token} not found on ${ch.chain} ${ch.network}`);
     process.exit(1);
@@ -4092,7 +4106,7 @@ async function deploySui<N extends Network, C extends Chain>(
     } catch (deploymentError) {
       // Restore original Move.toml files if deployment fails
       restore();
-      throw deploymentError;
+      handleRpcError(deploymentError, ch.chain, ch.network, ch.config.rpc);
     }
   });
 }