Merge remote-tracking branch 'origin/main' into ledger-entry-get

Author: elizabethengelman

FULL_HELP_DOCS.md

@@ -1107,6 +1107,7 @@ Add a new identity (keypair, ledger, OS specific secure store)
 * `--global` — ⚠️ Deprecated: global config is always on
 * `--config-dir <CONFIG_DIR>` — Location of config directory. By default, it uses `$XDG_CONFIG_HOME/stellar` if set, falling back to `~/.config/stellar` otherwise. Contains configuration files, aliases, and other persistent settings
 * `--public-key <PUBLIC_KEY>` — Add a public key, ed25519, or muxed account, e.g. G1.., M2..
+* `--overwrite` — Overwrite existing identity if it already exists
 
 
 
@@ -4007,7 +4008,6 @@ Fetch ledger entries. This command supports all types of ledger entries supporte
 
 * `account` — Fetch account entry by public key or alias
 * `contract-data` — Fetch contract ledger entry by address or alias and storage key
-* `config` — Fetch the current network config by `ConfigSettingId`. All config settings are returned if no id is provided
 * `claimable-balance` — Fetch a claimable balance ledger entry by id
 * `liquidity-pool` — Fetch a liquidity pool ledger entry by id
 * `contract-code` — Fetch a Contract's WASM bytecode by WASM hash
@@ -4021,14 +4021,11 @@ Fetch ledger entries. This command supports all types of ledger entries supporte
 
 Fetch account entry by public key or alias
 
-**Usage:** `stellar ledger entry fetch account [OPTIONS] <ACCOUNT>`
-
-###### **Arguments:**
-
-* `<ACCOUNT>` — Account alias or address to lookup
+**Usage:** `stellar ledger entry fetch account [OPTIONS] --account <ACCOUNT>`
 
 ###### **Options:**
 
+* `--account <ACCOUNT>` — Account alias or address to lookup
 * `--rpc-url <RPC_URL>` — RPC server endpoint
 * `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
 * `--network-passphrase <NETWORK_PASSPHRASE>` — Network passphrase to sign the transaction sent to the rpc server
@@ -4047,7 +4044,6 @@ Fetch account entry by public key or alias
   - `xdr`:
     Original RPC output (containing XDRs)
 
-* `--hide-account` — Hide the account ledger entry from the output
 * `--hd-path <HD_PATH>` — If identity is a seed phrase use this hd path, default is 0
 
 
@@ -4056,14 +4052,11 @@ Fetch account entry by public key or alias
 
 Fetch contract ledger entry by address or alias and storage key
 
-**Usage:** `stellar ledger entry fetch contract-data [OPTIONS] <CONTRACT>`
-
-###### **Arguments:**
-
-* `<CONTRACT>` — Contract alias or address to fetch
+**Usage:** `stellar ledger entry fetch contract-data [OPTIONS] --contract <CONTRACT>`
 
 ###### **Options:**
 
+* `--contract <CONTRACT>` — Contract alias or address to fetch
 * `--rpc-url <RPC_URL>` — RPC server endpoint
 * `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
 * `--network-passphrase <NETWORK_PASSPHRASE>` — Network passphrase to sign the transaction sent to the rpc server
@@ -4097,68 +4090,15 @@ Fetch contract ledger entry by address or alias and storage key
 
 
 
-## `stellar ledger entry fetch config`
-
-Fetch the current network config by `ConfigSettingId`. All config settings are returned if no id is provided
-
-**Usage:** `stellar ledger entry fetch config [OPTIONS] [CONFIG_SETTING_IDS]...`
-
-###### **Arguments:**
-
-* `<CONFIG_SETTING_IDS>` — Valid config setting IDs (Config Setting ID => Name):
-   0 => ContractMaxSizeBytes
-   1 => ContractComputeV0
-   2 => ContractLedgerCostV0
-   3 => ContractHistoricalDataV0
-   4 => ContractEventsV0
-   5 => ContractBandwidthV0
-   6 => ContractCostParamsCpuInstructions
-   7 => ContractCostParamsMemoryBytes
-   8 => ContractDataKeySizeBytes
-   9 => ContractDataEntrySizeBytes
-   10 => StateArchival
-   11 => ContractExecutionLanes
-   12 => LiveSorobanStateSizeWindow
-   13 => EvictionIterator
-   14 => ContractParallelComputeV0
-   15 => ContractLedgerCostExtV0
-   16 => ScpTiming
-
-###### **Options:**
-
-* `--rpc-url <RPC_URL>` — RPC server endpoint
-* `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
-* `--network-passphrase <NETWORK_PASSPHRASE>` — Network passphrase to sign the transaction sent to the rpc server
-* `-n`, `--network <NETWORK>` — Name of network to use from config
-* `--global` — ⚠️ Deprecated: global config is always on
-* `--config-dir <CONFIG_DIR>` — Location of config directory. By default, it uses `$XDG_CONFIG_HOME/stellar` if set, falling back to `~/.config/stellar` otherwise. Contains configuration files, aliases, and other persistent settings
-* `--output <OUTPUT>` — Format of the output
-
-  Default value: `json`
-
-  Possible values:
-  - `json`:
-    JSON output of the ledger entry with parsed XDRs (one line, not formatted)
-  - `json-formatted`:
-    Formatted (multiline) JSON output of the ledger entry with parsed XDRs
-  - `xdr`:
-    Original RPC output (containing XDRs)
-
-
-
-
 ## `stellar ledger entry fetch claimable-balance`
 
 Fetch a claimable balance ledger entry by id
 
-**Usage:** `stellar ledger entry fetch claimable-balance [OPTIONS] [IDS]...`
-
-###### **Arguments:**
-
-* `<IDS>` — Claimable Balance Ids to fetch an entry for
+**Usage:** `stellar ledger entry fetch claimable-balance [OPTIONS]`
 
 ###### **Options:**
 
+* `--id <ID>` — Claimable Balance Ids to fetch an entry for
 * `--rpc-url <RPC_URL>` — RPC server endpoint
 * `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
 * `--network-passphrase <NETWORK_PASSPHRASE>` — Network passphrase to sign the transaction sent to the rpc server
@@ -4184,14 +4124,11 @@ Fetch a claimable balance ledger entry by id
 
 Fetch a liquidity pool ledger entry by id
 
-**Usage:** `stellar ledger entry fetch liquidity-pool [OPTIONS] [IDS]...`
-
-###### **Arguments:**
-
-* `<IDS>` — Liquidity pool ids
+**Usage:** `stellar ledger entry fetch liquidity-pool [OPTIONS]`
 
 ###### **Options:**
 
+* `--id <ID>` — Liquidity pool ids
 * `--rpc-url <RPC_URL>` — RPC server endpoint
 * `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
 * `--network-passphrase <NETWORK_PASSPHRASE>` — Network passphrase to sign the transaction sent to the rpc server
@@ -4217,14 +4154,11 @@ Fetch a liquidity pool ledger entry by id
 
 Fetch a Contract's WASM bytecode by WASM hash
 
-**Usage:** `stellar ledger entry fetch contract-code [OPTIONS] [WASM_HASHES]...`
-
-###### **Arguments:**
-
-* `<WASM_HASHES>` — Get WASM bytecode by hash
+**Usage:** `stellar ledger entry fetch contract-code [OPTIONS]`
 
 ###### **Options:**
 
+* `--wasm-hash <WASM_HASH>` — Get WASM bytecode by hash
 * `--rpc-url <RPC_URL>` — RPC server endpoint
 * `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
 * `--network-passphrase <NETWORK_PASSPHRASE>` — Network passphrase to sign the transaction sent to the rpc server
@@ -4274,7 +4208,7 @@ Fetch a trustline by account and asset
 
 * `--account <ACCOUNT>` — Account alias or address to lookup
 * `--asset <ASSET>` — Assets to get trustline info for
-* `--hd-path <HD_PATH>` — If identity is a seed phrase use this hd path, default is 0
+* `--hd-path <HD_PATH>` — If account is a seed phrase use this hd path, default is 0
 
 
 

cmd/crates/soroban-test/tests/it/integration/keys.rs

@@ -90,3 +90,56 @@ async fn overwrite_identity() {
 
     assert_ne!(initial_pubkey, pubkey_for_identity(sandbox, "test2"));
 }
+
+#[tokio::test]
+#[allow(clippy::too_many_lines)]
+async fn overwrite_identity_with_add() {
+    let sandbox = &TestEnv::new();
+    sandbox
+        .new_assert_cmd("keys")
+        .arg("generate")
+        .arg("test3")
+        .assert()
+        .success();
+
+    let initial_pubkey = sandbox
+        .new_assert_cmd("keys")
+        .arg("address")
+        .arg("test3")
+        .assert()
+        .stdout_as_str();
+
+    // Try to add a key with the same name, should fail
+    sandbox
+        .new_assert_cmd("keys")
+        .arg("add")
+        .arg("test3")
+        .arg("--public-key")
+        .arg("GAKSH6AD2IPJQELTHIOWDAPYX74YELUOWJLI2L4RIPIPZH6YQIFNUSDC")
+        .assert()
+        .stderr(predicate::str::contains(
+            "error: An identity with the name 'test3' already exists",
+        ));
+
+    // Verify the key wasn't changed
+    assert_eq!(initial_pubkey, pubkey_for_identity(sandbox, "test3"));
+
+    // Try again with --overwrite flag, should succeed
+    sandbox
+        .new_assert_cmd("keys")
+        .arg("add")
+        .arg("test3")
+        .arg("--public-key")
+        .arg("GAKSH6AD2IPJQELTHIOWDAPYX74YELUOWJLI2L4RIPIPZH6YQIFNUSDC")
+        .arg("--overwrite")
+        .assert()
+        .stderr(predicate::str::contains("Overwriting identity 'test3'"))
+        .success();
+
+    // Verify the key was changed
+    assert_ne!(initial_pubkey, pubkey_for_identity(sandbox, "test3"));
+    assert_eq!(
+        "GAKSH6AD2IPJQELTHIOWDAPYX74YELUOWJLI2L4RIPIPZH6YQIFNUSDC",
+        pubkey_for_identity(sandbox, "test3").trim()
+    );
+}

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

@@ -31,6 +31,9 @@ pub enum Error {
 
     #[error("secret input error")]
     PasswordRead,
+
+    #[error("An identity with the name '{0}' already exists")]
+    IdentityAlreadyExists(String),
 }
 
 #[derive(Debug, clap::Parser, Clone)]
@@ -48,11 +51,24 @@ pub struct Cmd {
     /// Add a public key, ed25519, or muxed account, e.g. G1.., M2..
     #[arg(long, conflicts_with = "seed_phrase", conflicts_with = "secret_key")]
     pub public_key: Option<String>,
+
+    /// Overwrite existing identity if it already exists.
+    #[arg(long)]
+    pub overwrite: bool,
 }
 
 impl Cmd {
     pub fn run(&self, global_args: &global::Args) -> Result<(), Error> {
         let print = Print::new(global_args.quiet);
+
+        if self.config_locator.read_identity(&self.name).is_ok() {
+            if !self.overwrite {
+                return Err(Error::IdentityAlreadyExists(self.name.to_string()));
+            }
+
+            print.exclaimln(format!("Overwriting identity '{}'", &self.name.to_string()));
+        }
+
         let key = if let Some(key) = self.public_key.as_ref() {
             key.parse()?
         } else {

cookbook/stellar-keys.mdx

@@ -0,0 +1,124 @@
+---
+title: Stellar Keys
+hide_table_of_contents: true
+description: Manage stellar keys
+custom_edit_url: https://github.com/stellar/stellar-cli/edit/main/cookbook/stellar-keys.mdx
+---
+
+This guide walks you through generating, inspecting, and removing a Stellar identity using the CLI.
+
+### 1. Generate a New Identity
+
+Run the following command to create a new keypair and save it under the alias named `carol`:
+
+```bash
+stellar keys generate carol
+```
+
+Output:
+
+```
+✅ Key saved with alias carol in ".config/soroban/identity/carol.toml"
+```
+
+The CLI stores this identity in a TOML file.
+
+### 2. Verify the Identity File
+
+Navigate to the configuration directory and list the contents:
+
+```bash cookbooktest.ignore
+cd .config/soroban/identity && ls
+```
+
+Output:
+
+```
+carol.toml
+```
+
+The file carol.toml contains the seed phrase for your identity.
+
+### 3. View the Seed Phrase
+
+```bash cookbooktest.ignore
+cat carol.toml
+```
+
+Output:
+
+```
+seed_phrase = "patrol clean public grocery roof aim have valve cherry dismiss lunar tail duty license capable little version banana amount often cover dice couple party"
+```
+
+:::danger
+
+Note: The seed phrase is sensitive information. Handle it with care and never expose it publicly.
+
+:::
+
+### 4. Derive the Secret Key
+
+To display the secret key for the carol identity:
+
+```bash
+stellar keys secret carol
+```
+
+Output:
+
+```
+SCJP663VYFZPYN75H2DYJA3FYUBP5UR23HZ4ZDHDMDY6TXVYUYMWNKTI
+```
+
+:::danger
+
+Note: The secret key is sensitive information. Handle it with care and never expose it publicly.
+
+:::
+
+### 5. Derive the Public Key
+
+To display the corresponding public key for the carol identity:
+
+```bash
+stellar keys public-key carol
+```
+
+Output:
+
+```
+GD3BFFX7DTNJAGDVVM5RYGGQQNURZTH4VSBLWF55YXY3L6T2WWZK57EI
+```
+
+This is the public address of your key.
+
+### 6. Fund this account
+
+```bash
+stellar keys fund carol
+```
+
+Output:
+
+```
+✅ Account carol funded on "Test SDF Network ; September 2015"
+```
+
+You can also fund the account while creating the key by using `stellar keys generate --fund`.
+
+### 7. Remove the Identity
+
+When you no longer need this identity, remove it using:
+
+```bash
+stellar keys rm carol
+```
+
+Output:
+
+```
+ℹ️  Removing the key's cli config file
+```
+
+At this point, the identity file carol.toml is deleted, and the alias is no longer available in the CLI.