diff --git a/README.md b/README.md index 74d2428..1f99168 100644 --- a/README.md +++ b/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:** diff --git a/SPEC.md b/SPEC.md index 425e94b..193a623 100644 --- a/SPEC.md +++ b/SPEC.md @@ -17,7 +17,7 @@ The following flags are accepted by the CLI. All flags are optional. * `--bind=`: Specifies the IP address/network interface to bind both ports to. * `--state-dir=`: Specifies the directory that PocketIC's state should be saved to/loaded from. * `--artificial-delay-ms=`: In milliseconds, specifies an artificial network latency that update calls should incur. -* `--subnet=`†: 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=`†: 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=`: Specifies a bitcoind node to connect to, enables regtest Bitcoin support, and implies `--subnet=bitcoin`. This flag is repeatable. * `--dogecoind-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. diff --git a/src/main.rs b/src/main.rs index fa5f625..ec07cb2 100644 --- a/src/main.rs +++ b/src/main.rs @@ -53,7 +53,7 @@ struct Cli { /// Artificial delay for execution, in milliseconds. #[arg(long)] artificial_delay_ms: Option, - /// 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, /// 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();