feat: create canister on specific subnets or subnet types

CHANGELOG.md

@@ -36,6 +36,13 @@ Providers can provide the hash through `wasm_hash_url` instead of hard coding th
 
 If the hash of downloaded wasm doesn’t match the provided hash (`wasm_hash`, `wasm_hash_url` or read from mainnet state tree), dfx deps won’t abort. Instead, it will print a warning message.
 
+### feat: create canister on specific subnets or subnet types
+
+`dfx deploy`, `dfx canister create`, and `dfx ledger create-canister` now support the option `--subnet <subnet principal>` to create canisters on specific subnets.
+
+`dfx canister create` and `dfx deploy` now support the option `--subnet-type <subnet type>` to create canisters on a random subnet of a certain type.
+Use `dfx ledger show-subnet-types` to list the available subnet types
+
 ### feat!: update `dfx cycles` commands with mainnet `cycles-ledger` canister ID
 
 The `dfx cycles` command no longer needs nor accepts the `--cycles-ledger-canister-id <canister id>` parameter.

docs/cli-reference/dfx-canister.md

@@ -220,6 +220,8 @@ You can use the following options with the `dfx canister create` command.
 | `--no-wallet`                             | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default.                                                                                                                                                                                                                                                                    |
 | `--with-cycles <number-of-cycles>`        | Specifies the initial cycle balance to deposit into the newly created canister. The specified amount needs to take the canister create fee into account. This amount is deducted from the wallet's cycle balance.                                                                                                                                                                        |
 | `--specified-id <PRINCIPAL>`              | Attempts to create the canister with this Canister ID |
+| `--subnet-type <subnet-type>`             | Specify the subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet.                      |
+| `--subnet <subnet-principal>`             | Specify the subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet.                                |
 
 ### Arguments
 

docs/cli-reference/dfx-deploy.md

@@ -30,6 +30,8 @@ You can use the following options with the `dfx deploy` command.
 | `--specified-id <PRINCIPAL>`       | Attempts to create the canister with this Canister ID                                                                                 |
 | `--by-proposal`                    | Upload proposed changed assets, but do not commit them.  Follow up by calling either commit_proposed_batch() or delete_batch().                                             |
 | `--compute-evidence`               | Build a frontend canister, determine batch operations required to synchronize asset canister contents, and compute a hash over those operations.  Displays this hash ("evidence"), which should match the evidence displayed by `dfx deploy --by-proposal`. |
+| `--subnet-type <subnet-type>`      | Specify the subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet.                      |
+| `--subnet <subnet-principal>`      | Specify the subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet.                                |
 
 ### Arguments
 

docs/cli-reference/dfx-ledger.md

@@ -121,6 +121,7 @@ You can specify the following argument for the `dfx ledger create-canister` comm
 | `--icp <icp>`                 | Specify ICP tokens as a whole number. You can use this option on its own or in conjunction with `--e8s`.                                                                                                                                             |
 | `--max-fee <max-fee>`         | Specify a maximum transaction fee. The default is 10000 e8s.                                                                                                                                                                                         |
 | `--subnet-type <subnet-type>` | Specify the optional subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet.                                                                                      |
+| `--subnet <subnet-principal>` | Specify the optional subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet.                                                                                                |
 | `--created-at-time <timestamp>`| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for controlling transaction-de-duplication. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication-  |
 
 ### Examples

e2e/assets/cycles-ledger/dfx.json

@@ -5,10 +5,10 @@
       "wasm": "cycles-ledger.wasm.gz",
       "candid": "cycles-ledger.did"
     },
-    "cycles-depositor": {
+    "depositor": {
       "type": "custom",
-      "wasm": "cycles-depositor.wasm.gz",
-      "candid": "cycles-depositor.did"
+      "wasm": "depositor.wasm.gz",
+      "candid": "depositor.did"
     }
   }
-}
+}

e2e/assets/fake_cmc/dfx.json

@@ -0,0 +1,9 @@
+{
+  "canisters": {
+    "fake-cmc": {
+      "type": "custom",
+      "wasm": "fake-cmc.wasm.gz",
+      "candid": "fake-cmc.did"
+    }
+  }
+}

e2e/tests-dfx/create.bash

@@ -1,6 +1,7 @@
 #!/usr/bin/env bats
 
 load ../utils/_
+load ../utils/cycles-ledger
 
 setup() {
   standard_setup
@@ -269,3 +270,28 @@ teardown() {
   assert_command dfx wallet upgrade --identity alice
   assert_command dfx canister create --all --controller alice --controller bob --identity alice
 }
+
+@test "create canister - subnet targetting" {
+  # fake cmc setup
+  cd ..
+  dfx_new fake_cmc
+  install_asset fake_cmc
+  install_cycles_ledger_canisters
+  dfx_start
+  assert_command dfx deploy fake-cmc --specified-id "rkp4c-7iaaa-aaaaa-aaaca-cai" # CMC canister id
+  cd ../e2e_project
+
+  # use --subnet <principal>
+  SUBNET_ID="5kdm2-62fc6-fwnja-hutkz-ycsnm-4z33i-woh43-4cenu-ev7mi-gii6t-4ae" # a random, valid principal
+  assert_command dfx canister create e2e_project_backend --subnet "$SUBNET_ID"
+  cd ../fake_cmc
+  assert_command dfx canister call fake-cmc last_create_canister_args
+  assert_contains "subnet = principal \"$SUBNET_ID\";"
+
+  # use --subnet-type
+  cd ../e2e_project
+  assert_command dfx canister create e2e_project_frontend --subnet-type custom_subnet_type
+  cd ../fake_cmc
+  assert_command dfx canister call fake-cmc last_create_canister_args
+  assert_contains 'subnet_type = opt "custom_subnet_type"'
+}