refactor: split always-on base topology from --subnet workload selection

README.md

@@ -39,14 +39,20 @@ One launcher version is tied to one PocketIC version — if the PocketIC version
 
 ### Subnet Configuration
 
-The `--subnet` flag controls which subnets the local network includes. Available types: `application`, `system`, `verified-application`, `bitcoin`, `fiduciary`, `nns`, `sns`, `test-threshold-keys`.
+Subnets fall into two independent categories:
+
+**Always-on base topology** — created unconditionally, not affected by `--subnet`:
+- **NNS** — required for system operations.
+- **fiduciary** — mirrors the mainnet topology.
+- **test-threshold-keys** — provides `test_key_1` and `dfx_test_key` for all threshold algorithms (ECDSA, Schnorr, and VetKd).
+
+**Workload subnets** — selected with the `--subnet` flag. Available types: `application`, `system`, `verified-application`, `bitcoin`, `sns`.
 
 **Default behavior:**
-- With no `--subnet` flags: one **application** subnet is created.
-- With any `--subnet` flag: the default application subnet is **not** created. Only explicitly specified subnets are added.
-- An **NNS** subnet is **always** created regardless of flags (it is required for system operations).
-- A **fiduciary** subnet is **always** created regardless of flags (it mirrors the mainnet topology).
-- A **TestThresholdKeys** subnet is **always** created regardless of flags (it provides `test_key_1` and `dfx_test_key` for all threshold algorithms: ECDSA, Schnorr, and VetKd).
+- With no `--subnet` flags: one **application** subnet is created (in addition to the base topology).
+- With any `--subnet` flag: the default application subnet is **not** created; only the workload subnets you specify are added.
+
+> `--subnet=nns` and `--subnet=fiduciary` are still accepted for backward compatibility but have no effect, since those subnets are always created. `--subnet=test-threshold-keys` is not a valid value.
 
 **Examples:**
 

SPEC.md

@@ -17,7 +17,7 @@ The following flags are accepted by the CLI. All flags are optional.
 * `--bind=<IP>`: Specifies the IP address/network interface to bind both ports to.
 * `--state-dir=<DIR>`: Specifies the directory that PocketIC's state should be saved to/loaded from.
 * `--artificial-delay-ms=<DELAY_MS>`: In milliseconds, specifies an artificial network latency that update calls should incur.
-* `--subnet=<KIND>`†: Adds a subnet of kind `KIND` to the subnet list. This flag is repeatable. Valid subnet kinds are `application`, `system`, `verified-application`, `bitcoin`, `fiduciary`, `nns`, `sns`, and `test-threshold-keys`. Regardless of flags, the NNS subnet is always created, and threshold keys `key_1`, `test_key_1`, and `dfx_test_key` are always available for all supported algorithms (ECDSA, Schnorr, VetKd). If no flags are specified, one application subnet is created.
+* `--subnet=<KIND>`†: Adds a workload subnet of kind `KIND` to the subnet list. This flag is repeatable. Valid subnet kinds are `application`, `system`, `verified-application`, `bitcoin`, and `sns`. If no flags are specified, one application subnet is created. Regardless of flags, the NNS subnet is always created, and threshold keys `key_1`, `test_key_1`, and `dfx_test_key` are always available for all supported algorithms (ECDSA, Schnorr, VetKd). `nns` and `fiduciary` are also accepted as `KIND` for backward compatibility but have no effect.
 * `--bitcoind-addr=<ADDR>`: Specifies a bitcoind node to connect to, enables regtest Bitcoin support, and implies `--subnet=bitcoin`. This flag is repeatable.
 * `--dogecoind-addr=<ADDR>`: Specifies a dogecoind node to connect to, enables regtest Dogecoin support, and implies `--subnet=bitcoin`. This flag is repeatable.
 * `--ii`†: Installs the Internet Identity canister.

src/main.rs

@@ -53,7 +53,7 @@ struct Cli {
     /// Artificial delay for execution, in milliseconds.
     #[arg(long)]
     artificial_delay_ms: Option<u64>,
-    /// List of subnets to create. `--subnet=nns`, `--subnet=fiduciary`, and `--subnet=test-threshold-keys` are always implied. Defaults to `--subnet=application` when no subnets are specified.
+    /// List of workload subnets to create. Defaults to `--subnet=application` when none are specified. The NNS, fiduciary, and test-threshold-keys subnets are always created regardless of this flag.
     #[arg(long, value_enum, action = ArgAction::Append)]
     subnet: Vec<SubnetKind>,
     /// Addresses of bitcoind nodes to connect to (e.g. 127.0.0.1:18444 or bitcoind:18444).
@@ -103,10 +103,11 @@ enum SubnetKind {
     System,
     VerifiedApplication,
     Bitcoin,
-    Fiduciary,
-    Nns,
     Sns,
-    TestThresholdKeys,
+    /// Accepted for backward compatibility but ignored: the NNS subnet is always created.
+    Nns,
+    /// Accepted for backward compatibility but ignored: the fiduciary subnet is always created.
+    Fiduciary,
     #[cfg(feature = "cloud-engine")]
     CloudEngine,
 }
@@ -267,6 +268,16 @@ async fn main() -> anyhow::Result<()> {
         if let Some(dir) = state_dir {
             pic = pic.with_state_dir(dir.into());
         }
+        // Always-on base topology: mirrors the mainnet subnet layout and provides
+        // infrastructure. Created unconditionally, independent of --subnet.
+        pic = pic.with_nns_subnet();
+        pic = pic.with_fiduciary_subnet();
+        // TestThresholdKeys holds test_key_1 and dfx_test_key for all threshold algorithms
+        // (ECDSA, Schnorr, VetKd). As of pocket-ic 14.0.0 these keys are no longer held by
+        // the II or fiduciary subnets.
+        pic = pic.with_test_threshold_keys_subnet();
+        // Workload subnets selected via --subnet. With no --subnet, a single application
+        // subnet is created.
         if subnet.is_empty() {
             pic = pic.with_application_subnet();
         } else {
@@ -276,22 +287,15 @@ async fn main() -> anyhow::Result<()> {
                     SubnetKind::System => pic = pic.with_system_subnet(),
                     SubnetKind::VerifiedApplication => pic = pic.with_verified_application_subnet(),
                     SubnetKind::Bitcoin => pic = pic.with_bitcoin_subnet(),
-                    SubnetKind::Fiduciary => pic = pic.with_fiduciary_subnet(),
-                    SubnetKind::Nns => pic = pic.with_nns_subnet(),
                     SubnetKind::Sns => pic = pic.with_sns_subnet(),
-                    SubnetKind::TestThresholdKeys => pic = pic.with_test_threshold_keys_subnet(),
+                    // Part of the always-on base topology above; accepted for backward
+                    // compatibility but ignored here.
+                    SubnetKind::Nns | SubnetKind::Fiduciary => {}
                     #[cfg(feature = "cloud-engine")]
                     SubnetKind::CloudEngine => {} // handled above
                 }
             }
         }
-        pic = pic.with_nns_subnet();
-        // Fiduciary mirrors the mainnet topology and is always present.
-        pic = pic.with_fiduciary_subnet();
-        // TestThresholdKeys holds test_key_1 and dfx_test_key for all threshold algorithms
-        // (ECDSA, Schnorr, VetKd). As of pocket-ic 14.0.0 these keys are no longer held by
-        // the II or fiduciary subnets.
-        pic = pic.with_test_threshold_keys_subnet();
         // --bitcoind-addr and --dogecoind-addr imply --subnet=bitcoin
         if !bitcoind_addr.is_empty() || !dogecoind_addr.is_empty() {
             pic = pic.with_bitcoin_subnet();