Summary
The subnet selection guide needs several targeted improvements, primarily around the --proxy section and linking out to the canister migration guide.
Issues found
1. --proxy section is incomplete (most important)
The section currently says:
"The proxy canister must implement a proxy method that forwards management canister calls."
Two things are missing:
Cycles model is not explained. The proxy canister pays for canister creation from its own cycle balance — not the caller. Ingress messages on ICP cannot carry cycles; the --cycles value is passed as data in ProxyArgs, and the proxy canister spends from its own balance. Users who assume --cycles draws from their own wallet will be confused. This needs to be stated explicitly.
"Existing canister" is misleading. The phrase "when you already have a deployed canister and want new canisters to live on the same subnet" implies any deployed canister can serve as a proxy. It cannot — the proxy must implement the specific proxy method with the correct ProxyArgs/ProxyResult Candid interface. An arbitrary canister will reject the call. The text should say "a canister that implements the proxy interface" rather than just "an existing canister."
Additionally: --proxy and --subnet are mutually exclusive (the CLI enforces this), but the guide doesn't mention it.
2. Troubleshooting section doesn't link to the canister migration guide
The "Canister is on the wrong subnet" entry correctly mentions snapshot transfer and icp canister migrate-id, but doesn't link to the full canister migration guide. That guide covers the complete step-by-step workflow including the cycle warning, the snapshot deletion requirement before migrate-id, the NNS controller cleanup step, and interruption recovery. Users hitting this troubleshooting entry need that guide.
The "Next steps" section also omits the migration guide — it links to canister snapshots but not migration, even though migration is the most complex follow-on task from this page.
3. "by default" phrasing in troubleshooting is ambiguous
"Canisters cannot be moved between subnets while keeping the same canister ID by default."
"By default" implies a non-default mode exists that doesn't require tooling. What it means is "without using icp canister migrate-id." Should say that directly.
Suggested changes
--proxy section: add that the proxy canister pays from its own cycle balance; clarify it must implement a specific Candid interface, not just any canister; note mutual exclusivity with --subnet- Troubleshooting "wrong subnet" entry: add a direct link to the canister migration guide
- Next steps: add canister migration guide as a link
- "by default" phrasing: replace with "without
icp canister migrate-id" or equivalent
What's working well
The rest of the guide is solid: default subnet behavior is correctly explained, the --subnet only-affects-creation caveat is present, subnet types are accurately described, and the tECDSA/vetKeys warning is correct and prominent.
Summary
The subnet selection guide needs several targeted improvements, primarily around the
--proxysection and linking out to the canister migration guide.Issues found
1.
--proxysection is incomplete (most important)The section currently says:
Two things are missing:
Cycles model is not explained. The proxy canister pays for canister creation from its own cycle balance — not the caller. Ingress messages on ICP cannot carry cycles; the
--cyclesvalue is passed as data inProxyArgs, and the proxy canister spends from its own balance. Users who assume--cyclesdraws from their own wallet will be confused. This needs to be stated explicitly."Existing canister" is misleading. The phrase "when you already have a deployed canister and want new canisters to live on the same subnet" implies any deployed canister can serve as a proxy. It cannot — the proxy must implement the specific
proxymethod with the correctProxyArgs/ProxyResultCandid interface. An arbitrary canister will reject the call. The text should say "a canister that implements the proxy interface" rather than just "an existing canister."Additionally:
--proxyand--subnetare mutually exclusive (the CLI enforces this), but the guide doesn't mention it.2. Troubleshooting section doesn't link to the canister migration guide
The "Canister is on the wrong subnet" entry correctly mentions snapshot transfer and
icp canister migrate-id, but doesn't link to the full canister migration guide. That guide covers the complete step-by-step workflow including the cycle warning, the snapshot deletion requirement beforemigrate-id, the NNS controller cleanup step, and interruption recovery. Users hitting this troubleshooting entry need that guide.The "Next steps" section also omits the migration guide — it links to canister snapshots but not migration, even though migration is the most complex follow-on task from this page.
3. "by default" phrasing in troubleshooting is ambiguous
"By default" implies a non-default mode exists that doesn't require tooling. What it means is "without using
icp canister migrate-id." Should say that directly.Suggested changes
--proxysection: add that the proxy canister pays from its own cycle balance; clarify it must implement a specific Candid interface, not just any canister; note mutual exclusivity with--subneticp canister migrate-id" or equivalentWhat's working well
The rest of the guide is solid: default subnet behavior is correctly explained, the
--subnetonly-affects-creation caveat is present, subnet types are accurately described, and the tECDSA/vetKeys warning is correct and prominent.