Persist --hd-path on plain seed-phrase keys.

Author: fnando

FULL_HELP_DOCS.md

@@ -1138,7 +1138,7 @@ Add a new identity (keypair, ledger, OS specific secure store)
 
 - `--public-key <PUBLIC_KEY>` — Add a public key, ed25519, or muxed account, e.g. G1.., M2..
 - `--overwrite` — Overwrite existing identity if it already exists. When combined with --secure-store, also replaces the existing Secure Store entry
-- `--hd-path <HD_PATH>` — When importing a seed phrase into the Secure Store, which `hd_path` to derive the key at
+- `--hd-path <HD_PATH>` — When importing a seed phrase, which `hd_path` to derive the key at. Persisted on the identity (or its Secure Store entry) so later commands derive the same account without re-passing the flag. Not valid with `--public-key` or a raw secret key
 
 ###### **Options (Global):**
 
@@ -1207,7 +1207,7 @@ Generate a new identity using a 24-word seed phrase The seed phrase can be store
 
   On Mac this uses Keychain, on Windows it is Secure Store Service, and on \*nix platforms it uses a combination of the kernel keyutils and DBus-based Secret Service.
 
-- `--hd-path <HD_PATH>` — With `--as-secret` or `--secure-store`, which `hd_path` to derive the key at from the seed phrase
+- `--hd-path <HD_PATH>` — Which `hd_path` to derive the key at from the seed phrase. Honored across all storage modes: with `--as-secret` it picks which derived key is stored, with `--secure-store` or plain seed-phrase storage it is persisted on the identity so later commands derive the same account without re-passing the flag
 - `--fund` — Fund generated key pair
 
   Default value: `false`

cmd/crates/soroban-test/tests/it/util.rs

@@ -18,6 +18,7 @@ pub fn add_key(dir: &Path, name: &str, kind: SecretKind, data: &str) {
     let secret = match kind {
         SecretKind::Seed => Secret::SeedPhrase {
             seed_phrase: data.to_string(),
+            hd_path: None,
         },
         SecretKind::Key => Secret::SecretKey {
             secret_key: data.to_string(),

cmd/soroban-cli/src/commands/keys/add.rs

@@ -39,6 +39,12 @@ pub enum Error {
          unset STELLAR_SECRET_KEY or provide a seed phrase instead"
     )]
     SecureStoreRequiresSeedPhrase,
+
+    #[error("--hd-path is not valid with a secret key; secret keys cannot be derived")]
+    HdPathNotSupportedForSecretKey,
+
+    #[error("--hd-path is not valid with --public-key; public keys cannot be derived")]
+    HdPathNotSupportedForPublicKey,
 }
 
 #[derive(Debug, clap::Parser, Clone)]
@@ -62,7 +68,9 @@ pub struct Cmd {
     #[arg(long)]
     pub overwrite: bool,
 
-    /// When importing a seed phrase into the Secure Store, which `hd_path` to derive the key at.
+    /// When importing a seed phrase, which `hd_path` to derive the key at. Persisted on
+    /// the identity (or its Secure Store entry) so later commands derive the same account
+    /// without re-passing the flag. Not valid with `--public-key` or a raw secret key.
     #[arg(long)]
     pub hd_path: Option<usize>,
 }
@@ -71,6 +79,10 @@ impl Cmd {
     pub fn run(&self, global_args: &global::Args) -> Result<(), Error> {
         let print = Print::new(global_args.quiet);
 
+        if self.public_key.is_some() && self.hd_path.is_some() {
+            return Err(Error::HdPathNotSupportedForPublicKey);
+        }
+
         if self.config_locator.read_identity(&self.name).is_ok() {
             if !self.overwrite {
                 return Err(Error::IdentityAlreadyExists(self.name.to_string()));
@@ -98,7 +110,7 @@ impl Cmd {
                 return Err(Error::SecureStoreRequiresSeedPhrase);
             }
         } else if let Ok(secret_key) = std::env::var("STELLAR_SECRET_KEY") {
-            return Ok(secret_key.parse()?);
+            return build_secret(&secret_key, self.hd_path);
         }
 
         if self.secrets.secure_store {
@@ -123,8 +135,8 @@ impl Cmd {
         } else {
             let prompt = "Type a secret key or 12/24 word seed phrase:";
             let secret_key = read_password(print, prompt)?;
-            let secret = secret_key.parse()?;
-            if let Secret::SeedPhrase { seed_phrase } = &secret {
+            let secret = build_secret(&secret_key, self.hd_path)?;
+            if let Secret::SeedPhrase { seed_phrase, .. } = &secret {
                 if seed_phrase.split_whitespace().count() < 24 {
                     print.warnln("The provided seed phrase lacks sufficient entropy and should be avoided. Using a 24-word seed phrase is a safer option.".to_string());
                     print.warnln(
@@ -138,6 +150,18 @@ impl Cmd {
     }
 }
 
+fn build_secret(input: &str, hd_path: Option<usize>) -> Result<Secret, Error> {
+    let secret: Secret = input.parse()?;
+    match (secret, hd_path) {
+        (Secret::SecretKey { .. }, Some(_)) => Err(Error::HdPathNotSupportedForSecretKey),
+        (Secret::SeedPhrase { seed_phrase, .. }, hd_path) => Ok(Secret::SeedPhrase {
+            seed_phrase,
+            hd_path,
+        }),
+        (secret, _) => Ok(secret),
+    }
+}
+
 fn read_password(print: &Print, prompt: &str) -> Result<String, Error> {
     if std::io::stdin().is_terminal() {
         // Interactive: prompt and read from TTY
@@ -157,3 +181,89 @@ fn read_password(print: &Print, prompt: &str) -> Result<String, Error> {
         Ok(input)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::address::KeyName;
+
+    const TEST_PUBLIC_KEY: &str = "GAREAZZQWHOCBJS236KIE3AWYBVFLSBK7E5UW3ICI3TCRWQKT5LNLCEZ";
+    const TEST_SECRET_KEY: &str = "SBF5HLRREHMS36XZNTUSKZ6FTXDZGNXOHF4EXKUL5UCWZLPBX3NGJ4BH";
+    const TEST_SEED_PHRASE: &str =
+        "depth decade power loud smile spatial sign movie judge february rate broccoli";
+
+    #[test]
+    fn test_build_secret_persists_hd_path_on_seed_phrase() {
+        let secret = build_secret(TEST_SEED_PHRASE, Some(5)).unwrap();
+        match secret {
+            Secret::SeedPhrase {
+                seed_phrase,
+                hd_path,
+            } => {
+                assert_eq!(seed_phrase, TEST_SEED_PHRASE);
+                assert_eq!(hd_path, Some(5));
+            }
+            other => panic!("expected SeedPhrase variant, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_build_secret_seed_phrase_without_hd_path() {
+        let secret = build_secret(TEST_SEED_PHRASE, None).unwrap();
+        match secret {
+            Secret::SeedPhrase { hd_path, .. } => assert_eq!(hd_path, None),
+            other => panic!("expected SeedPhrase variant, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_build_secret_rejects_hd_path_with_secret_key() {
+        let result = build_secret(TEST_SECRET_KEY, Some(5));
+        assert!(matches!(result, Err(Error::HdPathNotSupportedForSecretKey)));
+    }
+
+    #[test]
+    fn test_build_secret_secret_key_without_hd_path() {
+        let secret = build_secret(TEST_SECRET_KEY, None).unwrap();
+        assert!(matches!(secret, Secret::SecretKey { .. }));
+    }
+
+    fn cmd_with_public_key(public_key: &str, hd_path: Option<usize>) -> Cmd {
+        let temp_dir = tempfile::tempdir().unwrap();
+        Cmd {
+            name: KeyName("test_name".to_string()),
+            secrets: secret::Args {
+                secret_key: false,
+                seed_phrase: false,
+                secure_store: false,
+            },
+            config_locator: locator::Args {
+                config_dir: Some(temp_dir.path().to_path_buf()),
+            },
+            public_key: Some(public_key.to_string()),
+            overwrite: false,
+            hd_path,
+        }
+    }
+
+    #[test]
+    fn test_run_rejects_hd_path_with_public_key() {
+        let cmd = cmd_with_public_key(TEST_PUBLIC_KEY, Some(3));
+        let global_args = global::Args {
+            quiet: true,
+            ..Default::default()
+        };
+        let result = cmd.run(&global_args);
+        assert!(matches!(result, Err(Error::HdPathNotSupportedForPublicKey)));
+    }
+
+    #[test]
+    fn test_run_accepts_public_key_without_hd_path() {
+        let cmd = cmd_with_public_key(TEST_PUBLIC_KEY, None);
+        let global_args = global::Args {
+            quiet: true,
+            ..Default::default()
+        };
+        assert!(cmd.run(&global_args).is_ok());
+    }
+}

cmd/soroban-cli/src/commands/keys/generate.rs

@@ -50,7 +50,10 @@ pub struct Cmd {
     #[command(flatten)]
     pub config_locator: locator::Args,
 
-    /// With `--as-secret` or `--secure-store`, which `hd_path` to derive the key at from the seed phrase.
+    /// Which `hd_path` to derive the key at from the seed phrase. Honored across all
+    /// storage modes: with `--as-secret` it picks which derived key is stored, with
+    /// `--secure-store` or plain seed-phrase storage it is persisted on the identity
+    /// so later commands derive the same account without re-passing the flag.
     #[arg(long)]
     pub hd_path: Option<usize>,
 
@@ -127,7 +130,10 @@ impl Cmd {
             let secret: Secret = seed_phrase.into();
             Ok(secret.private_key(self.hd_path)?.into())
         } else {
-            Ok(seed_phrase.into())
+            Ok(Secret::SeedPhrase {
+                seed_phrase: seed_phrase.seed_phrase.into_phrase(),
+                hd_path: self.hd_path,
+            })
         }
     }
 
@@ -179,6 +185,23 @@ mod tests {
         assert!(matches!(identity, Key::Secret(Secret::SeedPhrase { .. })));
     }
 
+    #[tokio::test]
+    async fn test_generate_seed_phrase_persists_hd_path() {
+        let (test_locator, mut cmd) = set_up_test();
+        cmd.hd_path = Some(7);
+        let global_args = global_args();
+
+        cmd.run(&global_args).await.unwrap();
+
+        let identity = test_locator.read_identity("test_name").unwrap();
+        match identity {
+            Key::Secret(Secret::SeedPhrase { hd_path, .. }) => {
+                assert_eq!(hd_path, Some(7));
+            }
+            other => panic!("expected SeedPhrase variant, got {other:?}"),
+        }
+    }
+
     #[tokio::test]
     async fn test_storing_secret_as_a_secret_key() {
         let (test_locator, mut cmd) = set_up_test();

cmd/soroban-cli/src/commands/keys/secret.rs

@@ -49,7 +49,7 @@ impl Cmd {
     pub fn seed_phrase(&self) -> Result<String, Error> {
         let key = self.locator.read_identity(&self.name)?;
 
-        if let Key::Secret(Secret::SeedPhrase { seed_phrase }) = key {
+        if let Key::Secret(Secret::SeedPhrase { seed_phrase, .. }) = key {
             Ok(seed_phrase)
         } else {
             Err(Error::UnknownSeedPhrase)

cmd/soroban-cli/src/config/key.rs

@@ -176,7 +176,10 @@ mod test {
     #[test]
     fn secret_seed_phrase() {
         let seed_phrase = "singer swing mango apple singer swing mango apple singer swing mango apple singer swing mango apple".to_string();
-        let secret = Secret::SeedPhrase { seed_phrase };
+        let secret = Secret::SeedPhrase {
+            seed_phrase,
+            hd_path: None,
+        };
         let key = Key::Secret(secret);
         round_trip(&key);
     }

cmd/soroban-cli/src/config/secret.rs

@@ -62,6 +62,12 @@ pub enum Secret {
     },
     SeedPhrase {
         seed_phrase: String,
+        // Persisted derivation index. Lets `--hd-path` set on `keys generate` /
+        // `keys add` travel with the identity, so later commands derive the
+        // intended account without re-passing the flag. Optional for backwards
+        // compatibility with files written before this field existed.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        hd_path: Option<usize>,
     },
     Ledger,
     SecureStore {
@@ -87,6 +93,7 @@ impl FromStr for Secret {
         } else if sep5::SeedPhrase::from_str(s).is_ok() {
             Ok(Secret::SeedPhrase {
                 seed_phrase: s.to_string(),
+                hd_path: None,
             })
         } else if s == "ledger" {
             Ok(Secret::Ledger)
@@ -120,6 +127,7 @@ impl From<SeedPhrase> for Secret {
     fn from(value: SeedPhrase) -> Self {
         Secret::SeedPhrase {
             seed_phrase: value.seed_phrase.into_phrase(),
+            hd_path: None,
         }
     }
 }
@@ -128,9 +136,12 @@ impl Secret {
     pub fn private_key(&self, index: Option<usize>) -> Result<PrivateKey, Error> {
         Ok(match self {
             Secret::SecretKey { secret_key } => PrivateKey::from_string(secret_key)?,
-            Secret::SeedPhrase { seed_phrase } => PrivateKey::from_payload(
+            Secret::SeedPhrase {
+                seed_phrase,
+                hd_path,
+            } => PrivateKey::from_payload(
                 &sep5::SeedPhrase::from_str(seed_phrase)?
-                    .from_path_index(index.unwrap_or_default(), None)?
+                    .from_path_index(index.or(*hd_path).unwrap_or_default(), None)?
                     .private()
                     .0,
             )?,
@@ -347,4 +358,62 @@ mod tests {
         assert!(cached_public_key(Some("not-a-public-key"), None, None).is_none());
         assert!(cached_public_key(Some(""), None, None).is_none());
     }
+
+    #[test]
+    fn test_seed_phrase_toml_round_trip_with_hd_path() {
+        let secret = Secret::SeedPhrase {
+            seed_phrase: TEST_SEED_PHRASE.to_string(),
+            hd_path: Some(5),
+        };
+        let serialized = toml::to_string(&secret).unwrap();
+        assert!(
+            serialized.contains("hd_path"),
+            "expected hd_path field in TOML, got: {serialized}"
+        );
+        let parsed: Secret = toml::from_str(&serialized).unwrap();
+        assert_eq!(secret, parsed);
+    }
+
+    #[test]
+    fn test_seed_phrase_legacy_toml_parses_with_none_hd_path() {
+        // Identity files written before this feature only contain seed_phrase.
+        // They must still parse, with hd_path defaulting to None.
+        let toml_str = format!("seed_phrase = \"{TEST_SEED_PHRASE}\"\n");
+        let secret: Secret = toml::from_str(&toml_str).unwrap();
+        match secret {
+            Secret::SeedPhrase {
+                seed_phrase,
+                hd_path,
+            } => {
+                assert_eq!(seed_phrase, TEST_SEED_PHRASE);
+                assert_eq!(hd_path, None);
+            }
+            other => panic!("expected SeedPhrase variant, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_seed_phrase_uses_persisted_hd_path_when_caller_passes_none() {
+        // When the caller passes None, the persisted hd_path should drive derivation.
+        let secret = Secret::SeedPhrase {
+            seed_phrase: TEST_SEED_PHRASE.to_string(),
+            hd_path: Some(1),
+        };
+        let pk_at_0 = secret.public_key(Some(0)).unwrap();
+        let pk_default = secret.public_key(None).unwrap();
+        assert_ne!(pk_at_0.to_string(), pk_default.to_string());
+    }
+
+    #[test]
+    fn test_seed_phrase_caller_hd_path_overrides_persisted() {
+        // Caller's explicit hd_path argument always wins over the persisted value.
+        let secret = Secret::SeedPhrase {
+            seed_phrase: TEST_SEED_PHRASE.to_string(),
+            hd_path: Some(1),
+        };
+        let pk = secret.public_key(Some(0)).unwrap();
+        let sk = secret.private_key(Some(0)).unwrap();
+        assert_eq!(pk.to_string(), TEST_PUBLIC_KEY);
+        assert_eq!(sk.to_string(), TEST_SECRET_KEY);
+    }
 }