feat: support for canister ID migration

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 # UNRELEASED
 
+### feat: support for canister ID migration
+
+Canister ID migration can be performed using `dfx canister migrate-id`
+and its status can be checked out using `dfx canister migration-status`.
+
 # 0.30.1
 
 ### feat: support dogecoin for the local dev environment

Cargo.toml

@@ -26,12 +26,12 @@ future_not_send = "warn"
 candid = "0.10.18"
 candid_parser = "0.2.2"
 dfx-core = { path = "src/dfx-core", version = "0.2.0" }
-ic-agent = "0.44.2"
+ic-agent = { git = "https://github.com/dfinity/agent-rs", rev = "57befac12a96a90868744f48660f31aff3835739" }
 ic-asset = { path = "src/canisters/frontend/ic-asset", version = "0.25.0" }
 ic-cdk = "0.19.0-beta.2"
-ic-identity-hsm = "0.44.2"
-ic-utils = "0.44.2"
-ic-management-canister-types = "0.4.1"
+ic-identity-hsm = { git = "https://github.com/dfinity/agent-rs", rev = "57befac12a96a90868744f48660f31aff3835739" }
+ic-utils = { git = "https://github.com/dfinity/agent-rs", rev = "57befac12a96a90868744f48660f31aff3835739" }
+ic-management-canister-types = "0.5.0"
 
 aes-gcm = { version = "0.10.3", features = ["std"] }
 anyhow = "1.0.56"

docs/cli-reference/dfx-canister.mdx

@@ -34,6 +34,8 @@ For reference information and examples that illustrate using `dfx canister` comm
 | [`install`](#dfx-canister-install)                 | Installs compiled code in a canister.                                                                                                                  |
 | [`logs`](#dfx-canister-logs)                       | Returns the logs from a canister.                                                                                                                      |
 | [`metadata`](#dfx-canister-metadata)               | Displays metadata of a canister.                                                                                                                       |
+| [`migrate-id`](#dfx-canister-migrate-id)           | Performs canister ID migration.                                                                                                                        |
+| [`migration-status`](#dfx-canister-migration-status) | Displays the current status for a canister ID migration.                                                                                             |
 | [`request-status`](#dfx-canister-request-status)   | Requests the status of a call to a canister.                                                                                                           |
 | [`send`](#dfx-canister-send)                       | Send a previously-signed message.                                                                                                                      |
 | [`set-id`](#dfx-canister-id)                       | Sets the identifier of a canister.                                                                                                                     |
@@ -718,6 +720,88 @@ service : {
 }
 ```
 
+## dfx canister migrate-id
+
+Use the `dfx canister migrate-id` command to perform canister ID migration
+of a canister on one subnet (called the "migrated" canister)
+to another subnet replacing the canister ID of a canister on that other subnet.
+
+### Basic usage
+
+``` bash
+dfx canister migrate-id <canister> --replace <replace>
+```
+
+### Arguments
+
+You can use the following arguments with the `dfx canister migrate-id` command.
+
+| Argument        | Description                                                                                              |
+|-----------------|----------------------------------------------------------------------------------------------------------|
+| `canister`      | Specifies the name or id of the canister whose canister ID you want to migrate.                          |
+| `replace`       | Specifies the name or id of the canister whose canister ID will be replaced by the migrated canister ID. |
+
+### Examples
+
+To migrate the canister ID of the canister called `migrated` and
+replace the canister ID of the canister called `replaced`,
+you can run the following command:
+
+```bash
+$ dfx canister migrate-id migrated --replace replaced
+```
+
+The command displays output similar to the following:
+
+```
+WARNING!
+Canister 'migrated' will be removed from its own subnet. Continue?
+Do you want to proceed? yes/No
+yes
+Migration succeeded at 2025-11-26 08:57:41 UTC
+```
+
+## dfx canister migration-status
+
+Use the `dfx canister migration-status` command to display the current status
+for a canister ID migration (triggered by a separate command [`migrate-id`](#dfx-canister-migrate-id))
+of a canister on one subnet (called the "migrated" canister)
+to another subnet replacing the canister ID of a canister on that other subnet.
+
+### Basic usage
+
+``` bash
+dfx canister migration-status <canister> --replace <replace>
+```
+
+### Arguments
+
+You can use the following arguments with the `dfx canister migration-status` command.
+
+| Argument        | Description                                                                                              |
+|-----------------|----------------------------------------------------------------------------------------------------------|
+| `canister`      | Specifies the name or id of the canister whose canister ID you want to migrate.                          |
+| `replace`       | Specifies the name or id of the canister whose canister ID will be replaced by the migrated canister ID. |
+
+### Examples
+
+To display the current status for a canister ID migration
+of the canister called `migrated` and
+replacing the canister ID of the canister called `replaced`,
+you can run the following command:
+
+```bash
+$ dfx canister migration-status migrated --replace replaced
+```
+
+The command displays output similar to the following:
+
+```
+| Canister                    | Canister To Be Replaced     | Migration Status           |
+| --------------------------- | --------------------------- | -------------------------- |
+| uqqxf-5h777-77774-qaaaa-cai | ahree-maaaa-aaaar-q777q-cai | In progress: SourceDeleted |
+```
+
 ## dfx canister request-status
 
 Use the `dfx canister request-status` command to request the status of a call to a canister. This command

e2e/tests-dfx/canister_migration.bash

@@ -0,0 +1,41 @@
+#!/usr/bin/env bats
+
+load ../utils/_
+
+setup() {
+    standard_setup
+    dfx_new hello
+}
+
+teardown() {
+    dfx_stop
+    standard_teardown
+}
+
+@test "canister migrate canister id" {
+    dfx_start --system-canisters
+    install_asset counter
+
+    # Update dfx.json: rename hello_backend -> source, and add target canister
+    jq '.canisters.source = .canisters.hello_backend | del(.canisters.hello_backend)' dfx.json | sponge dfx.json
+    jq '.canisters.target = { "main": "counter.mo", "type": "motoko" }' dfx.json | sponge dfx.json
+
+    # Deploy the source to the application subnet.
+    dfx deploy source
+
+    # Create the target canister on the fiduciary subnet.
+    dfx canister create target --subnet-type fiduciary
+
+    dfx canister stop source
+    dfx canister stop target
+
+    # Make sure the source has enough cycles to do the migration.
+    dfx ledger fabricate-cycles --canister source --cycles 10000000000000
+
+    # The migration will take a few minutes to complete.
+    assert_command dfx canister migrate-id source --replace target --yes
+    assert_contains "Migration succeeded"
+
+    assert_command dfx canister status source
+    assert_command_fail dfx canister status target
+}

src/dfx/src/actors/pocketic.rs

@@ -394,7 +394,7 @@ async fn initialize_pocketic(
             ii: Some(IcpFeaturesConfig::default()),
             nns_ui: Some(IcpFeaturesConfig::default()),
             bitcoin: icp_features.bitcoin,
-            canister_migration: None,
+            canister_migration: Some(IcpFeaturesConfig::default()),
             dogecoin: icp_features.dogecoin,
         }
     } else {