feat(pcli): subaccount migration (#5238)

## Describe your changes

Adds a new subcommand `pcli migrate subaccount-balance` to complement
the pre-existing `pcli migrate balance`. The goal is to provide
capability to migrate subaccounts, rather than entire wallets wholesale.
Accepts a `--from-range` argument, so that multiple subaccount indices
can be specified for the construction of the transaction plan.

## Issue ticket number and link
N/A

---------

Co-authored-by: Conor Schaefer <conor@penumbralabs.xyz>

Author: Erwan Or

crates/bin/pcli/src/command/migrate.rs

@@ -1,9 +1,10 @@
 use crate::App;
 use anyhow::{anyhow, Context, Result};
+use futures::TryStreamExt;
 use penumbra_sdk_asset::{asset, Value, STAKING_TOKEN_ASSET_ID};
 use penumbra_sdk_keys::FullViewingKey;
 use penumbra_sdk_num::Amount;
-use penumbra_sdk_proto::view::v1::GasPricesRequest;
+use penumbra_sdk_proto::view::v1::{AssetsRequest, GasPricesRequest};
 use penumbra_sdk_view::ViewClient;
 use penumbra_sdk_wallet::plan::Planner;
 use rand_core::OsRng;
@@ -20,6 +21,26 @@ fn read_fvk() -> Result<FullViewingKey> {
         .map_err(|_| anyhow::anyhow!("The provided string is not a valid FullViewingKey."))
 }
 
+fn parse_range(s: &str) -> Result<std::ops::Range<u32>> {
+    let parts: Vec<&str> = s.split("..").collect();
+    if parts.len() != 2 {
+        return Err(anyhow!("Invalid range format. Expected format: start..end"));
+    }
+
+    let start = parts[0]
+        .parse::<u32>()
+        .context("Invalid start value in range")?;
+    let end = parts[1]
+        .parse::<u32>()
+        .context("Invalid end value in range")?;
+
+    if start >= end {
+        return Err(anyhow!("Invalid range: start must be less than end"));
+    }
+
+    Ok(start..end)
+}
+
 #[derive(Debug, clap::Parser)]
 pub enum MigrateCmd {
     /// Migrate your entire balance to another wallet.
@@ -30,6 +51,24 @@ pub enum MigrateCmd {
     /// minus any gas prices for the migration transaction.
     #[clap(name = "balance")]
     Balance,
+    /// Migrate balances from specified subaccounts to a destination wallet.
+    ///
+    /// All assets from the specified source subaccounts will be sent to the destination wallet.
+    /// A FullViewingKey must be provided for the destination wallet.
+    /// Gas fees will be paid from the source subaccount with the most fee token.
+    #[clap(name = "subaccount-balance")]
+    SubaccountBalance {
+        /// Range of source subaccount indices to migrate from (e.g., 0..17)
+        ///
+        /// The range is inclusive of the `start` value, and exclusive of the `end` value,
+        /// such that `1..4` will migrate subaccounts 1, 2, & 3, but not 4. Therefore
+        /// to migrate only subaccount 4, use `4..5`.
+        #[clap(long, required = true, value_parser = parse_range, name = "subaccount_index_range")]
+        from_range: std::ops::Range<u32>,
+        /// Only print the transaction plan without executing it (for threshold signing)
+        #[clap(long)]
+        plan_only: bool,
+    },
 }
 
 impl MigrateCmd {
@@ -119,6 +158,199 @@ impl MigrateCmd {
                 }
                 app.build_and_submit_transaction(plan).await?;
 
+                Result::Ok(())
+            }
+            MigrateCmd::SubaccountBalance {
+                from_range,
+                plan_only,
+            } => {
+                let source_fvk = app.config.full_viewing_key.clone();
+
+                // Read destination FVK from stdin
+                let dest_fvk = read_fvk()?;
+
+                let mut planner = Planner::new(OsRng);
+                planner
+                    .set_gas_prices(gas_prices)
+                    .set_fee_tier(Default::default());
+
+                // Get asset cache for human-readable denominations
+                let assets_response = app
+                    .view
+                    .as_mut()
+                    .context("view service must be initialized")?
+                    .assets(AssetsRequest {
+                        filtered: false,
+                        include_specific_denominations: vec![],
+                        include_lp_nfts: true,
+                        include_delegation_tokens: true,
+                        include_unbonding_tokens: true,
+                        include_proposal_nfts: false,
+                        include_voting_receipt_tokens: false,
+                    })
+                    .await?;
+
+                // Build asset cache from the response
+                let mut asset_cache = penumbra_sdk_asset::asset::Cache::default();
+                let assets_stream = assets_response.into_inner();
+                let assets = assets_stream
+                    .try_collect::<Vec<_>>()
+                    .await
+                    .context("failed to collect assets")?;
+                for asset_response in assets {
+                    if let Some(denom) = asset_response.denom_metadata {
+                        let metadata =
+                            denom.try_into().context("failed to parse asset metadata")?;
+                        asset_cache.extend(std::iter::once(metadata));
+                    }
+                }
+
+                // Return all unspent notes from the view service
+                let all_notes = app
+                    .view
+                    .as_mut()
+                    .context("view service must be initialized")?
+                    .unspent_notes_by_account_and_asset()
+                    .await?;
+
+                // Track values per (subaccount, asset) for fee calculation
+                let mut subaccount_values: HashMap<(u32, asset::Id), Amount> = HashMap::new();
+
+                // Filter and spend notes only from subaccounts in the specified range
+                for (account, notes_by_asset) in all_notes {
+                    if from_range.contains(&account) {
+                        for notes in notes_by_asset.into_values() {
+                            for note in notes {
+                                let position = note.position;
+                                let note = note.note;
+                                let value = note.value();
+                                planner.spend(note, position);
+                                *subaccount_values
+                                    .entry((account, value.asset_id))
+                                    .or_default() += value.amount;
+                            }
+                        }
+                    }
+                }
+
+                if subaccount_values.is_empty() {
+                    anyhow::bail!("no notes found in the specified subaccount range");
+                }
+
+                // Find the subaccount with the most fee token to pay fees
+                let (&(fee_account, _), _) = subaccount_values
+                    .iter()
+                    .filter(|((_, asset), _)| *asset == *STAKING_TOKEN_ASSET_ID)
+                    .max_by_key(|&(_, &amount)| amount)
+                    .ok_or(anyhow!(
+                        "no subaccount in the range has the ability to pay fees"
+                    ))?;
+
+                // Set the change address to the destination's corresponding subaccount
+                planner.change_address(dest_fvk.payment_address(fee_account.into()).0);
+
+                // Create outputs for all assets to their corresponding destination subaccounts
+                for (&(account, asset_id), &amount) in &subaccount_values {
+                    // Skip empty values
+                    if amount == Amount::zero() {
+                        continue;
+                    }
+
+                    // For the fee account, the change will handle the remaining balance
+                    if account == fee_account && asset_id == *STAKING_TOKEN_ASSET_ID {
+                        continue;
+                    }
+
+                    let (dest_address, _) = dest_fvk.payment_address(account.into());
+                    planner.output(Value { asset_id, amount }, dest_address);
+                }
+
+                let memo = format!(
+                    "Migrating subaccounts {}..{} from {} to {}",
+                    from_range.start, from_range.end, source_fvk, dest_fvk
+                );
+
+                let plan = planner
+                    .memo(memo)
+                    .plan(
+                        app.view
+                            .as_mut()
+                            .context("view service must be initialized")?,
+                        Default::default(),
+                    )
+                    .await
+                    .context("can't build migration transaction")?;
+
+                if plan.actions.is_empty() {
+                    anyhow::bail!("migration plan contained zero actions: are the source subaccounts already empty?");
+                }
+
+                // Print migration summary
+                println!("\n=== Migration Summary ===");
+                println!("Source wallet: {}", source_fvk);
+                println!("Destination wallet: {}", dest_fvk);
+                println!(
+                    "Subaccounts: {} through {} (inclusive)",
+                    from_range.start, from_range.end
+                );
+
+                // Calculate total assets across all subaccounts
+                let mut asset_summary: HashMap<asset::Id, Amount> = HashMap::new();
+                for ((_, asset_id), amount) in &subaccount_values {
+                    *asset_summary.entry(*asset_id).or_default() += *amount;
+                }
+
+                // Show assets being migrated with human-readable denominations
+                println!("\nAssets to migrate:");
+                let mut total_outputs = 0;
+                for (asset_id, total_amount) in &asset_summary {
+                    if *total_amount > Amount::zero() {
+                        let value = penumbra_sdk_asset::Value {
+                            asset_id: *asset_id,
+                            amount: *total_amount,
+                        };
+                        println!("  • {}", value.format(&asset_cache));
+                        total_outputs += 1;
+                    }
+                }
+
+                println!("Total outputs: {}", total_outputs);
+
+                // Show which subaccounts contain assets
+                println!("\nSubaccounts with balances:");
+                let mut accounts_with_balance: Vec<u32> = subaccount_values
+                    .keys()
+                    .map(|(account, _)| *account)
+                    .collect::<std::collections::HashSet<_>>()
+                    .into_iter()
+                    .collect();
+                accounts_with_balance.sort();
+
+                for account in &accounts_with_balance {
+                    println!("  • Subaccount {}", account);
+                }
+
+                println!("\nFee-paying subaccount: {}", fee_account);
+                println!("Total distinct assets: {}", asset_summary.len());
+                println!("========================\n");
+
+                if *plan_only {
+                    println!("{}", serde_json::to_string_pretty(&plan)?);
+                } else {
+                    // Ask for confirmation
+                    print!("Send transaction? (Y/N): ");
+                    std::io::stdout().flush()?;
+
+                    let response: String = std::io::stdin().lock().read_line()?.unwrap_or_default();
+                    let trimmed = response.trim().to_lowercase();
+
+                    if trimmed == "y" || trimmed == "yes" {
+                        app.build_and_submit_transaction(plan).await?;
+                    } else {
+                        println!("Transaction cancelled.");
+                    }
+                }
+
                 Result::Ok(())
             }
         }