chore: improve error message for 'dfx cycles convert'.

CHANGELOG.md

@@ -37,6 +37,17 @@ This affects the following commands:
 - `dfx canister update-settings`
 - `dfx ledger fabricate-cycles`
 
+### chore: improve `dfx cycles convert` messages.
+
+If users run `dfx cycles convert` without enough ICP tokens, show additional messages to indicate what to do next.
+```
+Error explanation:
+Insufficient ICP balance to finish the transfer transaction.
+How to resolve the error:
+Please top up your ICP balance.
+Please run 'dfx ledger account-id' to get the address for receiving ICP tokens.
+```
+
 # 0.24.3
 
 ### feat: Bitcoin support in PocketIC

e2e/tests-dfx/cycles-ledger.bash

@@ -885,6 +885,10 @@ current_time_nanoseconds() {
 
   deploy_cycles_ledger
 
+  # Test failed to convert ICP to cycles without enough ICP.
+  assert_command_fail dfx cycles convert --amount 12.5 --identity alice
+  assert_contains "Insufficient ICP balance to finish the transfer transaction."
+
   assert_command dfx --identity cycle-giver ledger transfer --memo 1234 --amount 100 "$(dfx ledger account-id --of-principal "$ALICE")"
   assert_command dfx --identity cycle-giver ledger transfer --memo 1234 --amount 100 "$(dfx ledger account-id --of-principal "$ALICE" --subaccount "$ALICE_SUBACCT1")"
 

src/dfx/src/lib/diagnosis.rs

@@ -1,4 +1,5 @@
 use crate::lib::error_code;
+use crate::lib::ledger_types::TransferError as ICPTransferError;
 use anyhow::Error as AnyhowError;
 use dfx_core::error::root_key::FetchRootKeyError;
 use ic_agent::agent::{RejectCode, RejectResponse};
@@ -72,6 +73,12 @@ pub fn diagnose(err: &AnyhowError) -> Diagnosis {
         }
     }
 
+    if let Some(transfer_error) = err.downcast_ref::<ICPTransferError>() {
+        if insufficient_icp(transfer_error) {
+            return diagnose_insufficient_icp();
+        }
+    }
+
     NULL_DIAGNOSIS
 }
 
@@ -262,3 +269,14 @@ fn diagnose_ledger_not_found() -> Diagnosis {
 
     (Some(explanation.to_string()), Some(suggestion.to_string()))
 }
+
+fn insufficient_icp(err: &ICPTransferError) -> bool {
+    matches!(err, ICPTransferError::InsufficientFunds { balance: _ })
+}
+
+fn diagnose_insufficient_icp() -> Diagnosis {
+    let explanation = "Insufficient ICP balance to finish the transfer transaction.";
+    let suggestion = "Please top up your ICP balance.
+Please run 'dfx ledger account-id' to get the address for receiving ICP tokens.";
+    (Some(explanation.to_string()), Some(suggestion.to_string()))
+}