dfinity · adamspofford-dfinity · May 2, 2025 · May 1, 2025 · May 1, 2025 · May 1, 2025
@@ -162,9 +162,6 @@ jobs:
           echo "archive=$(pwd)/e2e/archive" >> "$GITHUB_ENV"
           echo "assets=$(pwd)/e2e/assets" >> "$GITHUB_ENV"
           echo "utils=$(pwd)/e2e/utils" >> "$GITHUB_ENV"
-          if [ "${{ matrix.backend == 'replica' || '' }}" ]; then
-            echo "USE_REPLICA=1" >> "$GITHUB_ENV"
-          fi
           export
       - name: Download bats-support as a git submodule
         run: git submodule update --init --recursive

@@ -2,6 +2,10 @@
 
 # UNRELEASED
 
+### feat!: remove the 'native' replica
+
+The native replica is no longer bundled with dfx; dfx only uses PocketIC for local networks. Accordingly `dfx start --replica` and `dfx info replica-port` now report an error. See the [migration guide](./docs/migration/dfx-0.27.0-migration-guide.md) for more information.
+
 ### chore: removes the outdated `_language-service` command
 
 ### feat: Support 'follow' mode for 'dfx canister logs'

@@ -67,13 +67,6 @@ sdk $ bats e2e/tests-dfx/*.bash
 sdk $ bats e2e/tests-replica/*.bash
 ```
 
-#### Running End-to-End Tests Against Local Replica
-
-``` bash
-sdk $ USE_REPLICA=1 bats e2e/tests-dfx/*.bash
-sdk $ USE_REPLICA=1 bats e2e/tests-replica/*.bash
-```
-
 ## Conventional Commits
 
 We use a squash & merge PR strategy, which means that each PR will result in exactly

@@ -18,14 +18,13 @@ dfx start [option] [flag]
 
 You can use the following optional flags with the `dfx start` command.
 
-| Flag                     | Description                                                                                                                                                                                                                                             |
-|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--background`           | Starts the local development environment and web server processes in the background and waits for a reply before returning to the shell.                                                                                                         |
-| `--clean`                | Starts the local development environment and web server processes in a clean state by removing checkpoints from your project cache. You can use this flag to set your project cache to a new state when troubleshooting or debugging.            |
-| `--enable-bitcoin`       | Enables bitcoin integration.                                                                                                                                                                                                                            |
-| `--enable-canister-http` | Enables canister HTTP requests. (deprecated: now enabled by default)                                                                                                                                                                                    |
-| `--pocketic`             | Runs [PocketIC](https://github.com/dfinity/pocketic) instead of the replica. PocketIC is the default if no flag is used.                                                                                                                                                                           |
-| `--replica`              | Runs the replica instead of [PocketIC](https://github.com/dfinity/pocketic).                                                                                                                                                                            |
+| Flag                     | Description                                                                                                                                                                                                                           |
+|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--background`           | Starts the local development environment and web server processes in the background and waits for a reply before returning to the shell.                                                                                              |
+| `--clean`                | Starts the local development environment and web server processes in a clean state by removing checkpoints from your project cache. You can use this flag to set your project cache to a new state when troubleshooting or debugging. |
+| `--enable-bitcoin`       | Enables bitcoin integration.                                                                                                                                                                                                          |
+| `--enable-canister-http` | Enables canister HTTP requests. (deprecated: now enabled by default)                                                                                                                                                                  |
+| `--pocketic`             | Runs [PocketIC](https://github.com/dfinity/pocketic) instead of the replica. PocketIC is the default if no flag is used.                                                                                                              |
 
 ## Options
 

@@ -0,0 +1,18 @@
+# dfx 0.27.0 migration guide
+
+## Removal of the replica
+
+dfx 0.27.0 no longer bundles the replica and the `--replica` flag to `dfx start` produces an error. The `--pocketic` flag will remain, but does nothing. This means that if you were depending on any replica-specific implementation details, you will need to adapt your project to the PocketIC equivalent.
+
+### If you have been using an agent to create canisters
+
+Creating a canister via `CreateCanisterBuilder::as_provisional_create_with_*`/`aaaaa-aa.provisional_create_canister_with_cycles` requires that the 'effective canister ID' be specified with a canister on the same subnet that the canister you are creating will go on. When using the replica, `ic-utils` was able to fill this in for you. When using PocketIC, you must specify it yourself. You can get the current default effective canister ID from dfx via `dfx info default-effective-canister-id`. You may alternatively process the topology at `http://localhost:{port}/_/topology`, which will be a JSON object containing at least the path `.default_effective_canister_id.canister_id`, which will contain the base64 encoding of the principal's byte representation.
+
+### If you have been referring to the adapter or sandbox processes in scripts
+
+PocketIC does not use the adapter processes or sandbox processes, and dfx no longer bundles them. You should remove references to these processes from your scripts.
+
+## Removal of other tools
+
+dfx 0.27.0 no longer bundles the `ic-admin`, `sns`, or `ic-nns-init` CLI tools. If you are using these, you can download them from the following URL: `https://download.dfinity.systems/ic/<rev>/binaries/x86_64-linux/<bin>.gz`, where `<rev>` is the git commit hash of an elected replica release and `<bin>` is `ic-admin`, `ic-nns-init`, or `sns`.
+
@@ -1,5 +1,6 @@
 # DFX Migration Guide
 
+- [dfx 0.27.0](./dfx-0.27.0-migration-guide.md)
 - [dfx 0.23.0](./dfx-0.23.0-migration-guide.md)
 - [dfx 0.18.0](./dfx-0.18.0-migration-guide.md)
 - [dfx 0.17.0](./dfx-0.17.0-migration-guide.md)

@@ -5,11 +5,7 @@ set timeout 330
 
 spawn dfx cache install
 expect "Installed dfx"
-if [info exists env(USE_REPLICA)] {
-    spawn dfx start --replica --clean
-} else {
-    spawn dfx start --clean
-}
+spawn dfx start --clean
 set pid [exp_pid]
 expect "Using" {
     sleep 1

@@ -36,73 +36,6 @@ set_local_network_bitcoin_enabled() {
   assert_command bitcoin-cli -regtest generatetoaddress 101 "$ADDRESS"
 }
 
-@test "dfx restarts replica when ic-btc-adapter restarts" {
-  [[ ! "$USE_REPLICA" ]] && skip "skipped for pocketic: bitcoin adapter is a replica implementation detail"
-  dfx_new_assets hello
-  dfx_start --enable-bitcoin
-
-  install_asset greet
-  assert_command dfx deploy
-  assert_command dfx canister call hello_backend greet '("Alpha")'
-  assert_eq '("Hello, Alpha!")'
-
-  REPLICA_PID=$(get_replica_pid)
-  BTC_ADAPTER_PID=$(get_btc_adapter_pid)
-
-  echo "replica pid is $REPLICA_PID"
-  echo "ic-btc-adapter pid is $BTC_ADAPTER_PID"
-
-  kill -KILL "$BTC_ADAPTER_PID"
-  assert_process_exits "$BTC_ADAPTER_PID" 15s
-  assert_process_exits "$REPLICA_PID" 15s
-
-  timeout 30s sh -c \
-    'until dfx ping; do echo waiting for replica to restart; sleep 1; done' \
-    || (echo "replica did not restart" && ps aux && exit 1)
-  wait_until_replica_healthy
-
-  # Sometimes initially get an error like:
-  #     IC0537: Attempt to execute a message on canister <>> which contains no Wasm module
-  # but the condition clears.
-  timeout 30s sh -c \
-    "until dfx canister call hello_backend greet '(\"wait 1\")'; do echo waiting for any canister call to succeed; sleep 1; done" \
-    || (echo "canister call did not succeed") # but continue, for better error reporting
-  # even after the above, still sometimes fails with
-  #     IC0208: Certified state is not available yet. Please try again...
-  sleep 10
-  timeout 30s sh -c \
-    "until dfx canister call hello_backend greet '(\"wait 2\")'; do echo waiting for any canister call to succeed; sleep 1; done" \
-    || (echo "canister call did not succeed") # but continue, for better error reporting
-
-  assert_command dfx canister call hello_backend greet '("Omega")'
-  assert_eq '("Hello, Omega!")'
-
-  ID=$(dfx canister id hello_frontend)
-
-  timeout 15s sh -c \
-    "until curl --fail http://localhost:\$(cat \"$E2E_SHARED_LOCAL_NETWORK_DATA_DIRECTORY/webserver-port\")/sample-asset.txt?canisterId=$ID; do echo waiting for pocket-ic proxy to restart; sleep 1; done" \
-    || (echo "pocket-ic proxy did not restart" && ps aux && exit 1)
-
-  assert_command curl --fail http://localhost:"$(get_webserver_port)"/sample-asset.txt?canisterId="$ID"
-}
-
-@test "dfx start --bitcoin-node <node> implies --enable-bitcoin" {
-  [[ ! "$USE_REPLICA" ]] && skip "skipped for pocketic: bitcoin adapter is a replica implementation detail"
-  dfx_new hello
-  dfx_start "--bitcoin-node" "127.0.0.1:18444"
-
-  assert_file_not_empty "$E2E_SHARED_LOCAL_NETWORK_DATA_DIRECTORY/ic-btc-adapter-pid"
-}
-
-@test "dfx start --enable-bitcoin with no other configuration succeeds" {
-  [[ ! "$USE_REPLICA" ]] && skip "skipped for pocketic: bitcoin adapter is a replica implementation detail"
-  dfx_new hello
-
-  dfx_start --enable-bitcoin
-
-  assert_file_not_empty "$E2E_SHARED_LOCAL_NETWORK_DATA_DIRECTORY/ic-btc-adapter-pid"
-}
-
 @test "dfx start --enable-bitcoin --background waits until bitcoin canister is installed" {
   dfx_new hello
 
@@ -113,53 +46,6 @@ set_local_network_bitcoin_enabled() {
   assert_contains "Module hash: 0x"
 }
 
-@test "can enable bitcoin through default configuration - dfx start" {
-  [[ ! "$USE_REPLICA" ]] && skip "skipped for pocketic: bitcoin adapter is a replica implementation detail"
-  dfx_new hello
-  define_project_network
-  set_project_default_bitcoin_enabled
-
-  dfx_start
-
-  assert_file_not_empty .dfx/network/local/ic-btc-adapter-pid
-}
-
-@test "can enable bitcoin through shared local network - dfx start" {
-  [[ ! "$USE_REPLICA" ]] && skip "skipped for pocketic: bitcoin adapter is a replica implementation detail"
-  dfx_new hello
-  set_shared_local_network_bitcoin_enabled
-
-  dfx_start
-
-  assert_file_not_empty "$E2E_SHARED_LOCAL_NETWORK_DATA_DIRECTORY/ic-btc-adapter-pid"
-}
-
-@test "can enable bitcoin through local network configuration - dfx start" {
-  [[ ! "$USE_REPLICA" ]] && skip "skipped for pocketic: bitcoin adapter is a replica implementation detail"
-  dfx_new hello
-  set_local_network_bitcoin_enabled
-
-  dfx_start
-
-  assert_file_not_empty .dfx/network/local/ic-btc-adapter-pid
-}
-
-@test "dfx start with both bitcoin and canister http enabled" {
-  [[ ! "$USE_REPLICA" ]] && skip "skipped for pocketic: bitcoin adapter is a replica implementation detail"
-  dfx_new hello
-
-  dfx_start --enable-bitcoin --enable-canister-http
-
-  assert_file_not_empty "$E2E_SHARED_LOCAL_NETWORK_DATA_DIRECTORY/ic-btc-adapter-pid"
-  assert_file_not_empty "$E2E_SHARED_LOCAL_NETWORK_DATA_DIRECTORY/ic-https-outcalls-adapter-pid"
-
-  install_asset greet
-  assert_command dfx deploy
-  assert_command dfx canister call hello_backend greet '("Alpha")'
-  assert_eq '("Hello, Alpha!")'
-}
-
-
 @test "bitcoin canister has decent amount of cycles" {
   dfx_start --enable-bitcoin
   # The canister is created with default amount of cycles: 100T

@@ -199,7 +199,7 @@ teardown() {
   dfx canister create --all
   dfx build
   dfx canister install hello_backend
-  [[ ! "$USE_REPLICA" ]] && dfx ledger fabricate-cycles --t 9999999 --canister hello_backend
+  dfx ledger fabricate-cycles --t 9999999 --canister hello_backend
   assert_command dfx canister call hello_backend recurse 100
 }
 
@@ -369,14 +369,10 @@ function impersonate_sender() {
 }
 
 @test "impersonate management canister as sender" {
-    [[ "$USE_REPLICA" ]] && skip "skipped for replica: impersonating sender is only supported for PocketIC"
-
     impersonate_sender "aaaaa-aa"
 }
 
 @test "impersonate new random identity as sender" {
-    [[ "$USE_REPLICA" ]] && skip "skipped for replica: impersonating sender is only supported for PocketIC"
-
     dfx identity new impersonated_identity --storage-mode plaintext
     IDENTITY_PRINCIPAL="$(dfx --identity impersonated_identity identity get-principal)"
     dfx identity remove impersonated_identity