0.9.3

DFX

feat: dfx deploy now displays URLs for the frontend and candid interface

dfx.json

In preparation for BTC integration, added configuration for the bitcoind port:

{
  "canisters": {},
  "defaults": {
    "bitcoind": {
      "port": 18333
    }
  }
}

icx-proxy

Updated icx-proxy to commit 594b6c81cde6da4e08faee8aa8e5a2e6ae815602, now static-linked.

• upgrade HTTP calls upon canister request
• no longer proxies /_/raw to the dfx internal webserver
• allows for generic StreamingCallback tokens

Replica

Updated replica to blessed commit d004accc3904e24dddb13a11d93451523e1a8a5f.
This incorporates the following executed proposals:

• 49653
• 49011
• 48427
• 47611
• 47512
• 47472
• 45984
• 45982

Motoko

Updated Motoko from 0.6.21 to 0.6.25.

SDK 0.9.2

Overview

Be sure to see the 0.9.0 Release Notes and follow the instructions due to breaking changes since dfx 0.8.4.

DFX

feat: Verify Candid and Motoko stable variable type safety of canister upgrades

Newly deployed Motoko canisters now embed the Candid interface and Motoko stable signatures in the Wasm module.
dfx deploy and dfx canister install will automatically check

1) the backward compatible of Candid interface in both upgrade and reinstall mode;
2) the type safety of Motoko stable variable type in upgrade mode to avoid accidentally lossing data;

See Upgrade compatibility for more details.

feat: Unified environment variables across build commands

The three canister types that use a custom build tool - assets, rust, and custom - now all support the same set of environment variables during the build task:

• DFX_VERSION - The version of DFX that was used to build the canister.
• DFX_NETWORK - The network name being built for. Usually ic or local.
• CANISTER_ID_{canister} - The canister principal ID of the canister {canister} registered in dfx.json.
• CANISTER_CANDID_PATH_{canister} - The path to the Candid interface file for the canister {canister} among your canister's dependencies.
• CANISTER_CANDID_{canister} (deprecated) - the same as CANISTER_CANDID_PATH_{canister}. This is provided for backwards compatibility with rust and custom canisters, and will be removed in dfx 0.10.0.
• CANISTER_ID - Same as CANISTER_ID_{self}, where {self} is the name of this canister.
• CANISTER_CANDID_PATH - Same as CANISTER_CANDID_PATH_{self}, where {self} is the name of this canister.

feat: Support for local ledger calls

If you have an installation of the ICP Ledger (see Ledger Installation Guide), dfx ledger balance and dfx ledger transfer now support
--ledger-canister-id parameter.

Some examples:

$ dfx ledger \
  --network local \
  balance \
  --ledger-canister-id  rrkah-fqaaa-aaaaa-aaaaq-cai
1000.00000000 ICP

$ dfx ledger \
  --network local \
  transfer --amount 0.1 --memo 0 \
  --ledger-canister-id  rrkah-fqaaa-aaaaa-aaaaq-cai 8af54f1fa09faeca18d294e0787346264f9f1d6189ed20ff14f029a160b787e8
Transfer sent at block height: 1

feat: dfx ledger account-id can now compute canister addresses

The dfx ledger account-id can now compute addresses of principals and canisters.
The command also supports ledger subaccounts now.

dfx ledger account-id --of-principal 53zcu-tiaaa-aaaaa-qaaba-cai
dfx ledger --network small02 account-id --of-canister ledger_demo
dfx ledger account-id --of-principal 53zcu-tiaaa-aaaaa-qaaba-cai --subaccount 0000000000000000000000000000000000000000000000000000000000000001

feat: Print the full error chain in case of a failure

All dfx commands will now print the full stack of errors that led to the problem, not just the most recent error.
Example:

Error: Subaccount '00000000000000000000000000000000000000000000000000000000000000000' is not a valid hex string
Caused by:
  Odd number of digits

fix: dfx import will now import pem files created by quill generate

quill generate currently outputs .pem files without an EC PARAMETERS section.
dfx identity import will now correctly identify these as EC keys, rather than Ed25519.

fix: retry on failure for ledger create-canister, top-up, transfer

dfx now calls transfer rather than send_dfx, and sets the created_at_time field in order to retry the following commands:

• dfx ledger create-canister
• dfx ledger top-up
• dfx ledger transfer

feat: Remote canister support

It's now possible to specify that a canister in dfx.json references a "remote" canister on a specific network,
that is, a canister that already exists on that network and is managed by some other project.

Motoko, Rust, and custom canisters may be configured in this way.

This is the general format of the configuration in dfx.json:

{
  "canisters": {
    "<canister name>": {
      "remote": {
        "candid": "<path to candid file to use when building on remote networks>",
        "id": {
          "<network name>": "<principal on network>"
        }
      }
    }
  }
}

The "id" field, if set for a given network, specifies the canister ID for the canister on that network.
The canister will not be created or installed on these remote networks.
For other networks, the canister will be created and installed as usual.

The "candid" field, if set within the remote object, specifies the candid file to build against when
building other canisters on a network for which the canister is remote. This definition can differ
from the candid definitions for local builds.

For example, if have an installation of the ICP Ledger (see Ledger Installation Guide)
in your dfx.json, you could configure the canister ID of the Ledger canister on the ic network as below. In this case,
the private interfaces would be available for local builds, but only the public interfaces would be available
when building for --network ic.

{
  "canisters": {
    "ledger": {
      "type": "custom",
      "wasm": "ledger.wasm",
      "candid": "ledger.private.did",
      "remote": {
        "candid": "ledger.public.did",
        "id": {
          "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai"
        }
      }
    },
    "app": {
      "type": "motoko",
      "main": "src/app/main.mo",
      "dependencies": [ "ledger" ]
    }
  }
}

As a second example, suppose that you wanted to write a mock of the ledger in Motoko.
In this case, since the candid definition is provided for remote networks,
dfx build (with implicit --network local) will build app against the candid
definitions defined by mock.mo, but dfx build --network ic will build app against
ledger.public.did.

This way, you can define public update/query functions to aid in local testing, but
when building/deploying to mainnet, references to methods not found in ledger.public.did
will be reports as compilation errors.

{
  "canisters": {
    "ledger": {
      "type": "motoko",
      "main": "src/ledger/mock.mo",
      "remote": {
        "candid": "ledger.public.did",
        "id": {
          "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai"
        }
      }
    },
    "app": {
      "type": "motoko",
      "main": "src/app/main.mo",
      "dependencies": [ "ledger" ]
    }
  }
}

feat: Generating remote canister bindings

It's now possible to generate the interface of a remote canister using a .did file using the dfx remote generate-binding <canister name>|--all command. This makes it easier to write mocks for local development.

Currently, dfx can generate .mo, .rs, .ts, and .js bindings.

This is how you specify how to generate the bindings in dfx.json:

{
  "canisters": {
    "<canister name>": {
      "main": "<path to mo/rs/ts/js file that will be generated>",
      "remote": {
        "candid": "<path to candid file to use when generating bindings>"
        "id": {}
      }
    }
  }
}

ic-ref

Upgraded from a432156f24faa16d387c9d36815f7ddc5d50e09f to ab8e3f5a04f0f061b8157c2889f8f5de05f952bb

• Support 128-bit system api for cycles
• Include canister_ranges in the state tree
• Removed limit on cycles in a canister

Replica

Updated replica to blessed commit 04fe8b0a1262f07c0cec1fdfa838a37607370a61.
This incorporates the following executed proposals:

• 45091
• 43635
• 43633
• 42783
• 42410
• 40908
• 40647
• 40328
• 39791
• 38541

Motoko

Updated Motoko from 0.6.20 to 0.6.21.

0.9.0

Overview

This release removes the --no-wallet parameter by making use of the fact that canisters can now have multiple controllers.

Please see below for required upgrade steps.

DFX

feat!: Remove the wallet proxy and the --no-wallet flag

Breaking change: Canister commands, except for dfx canister create, will make the call directly, rather than via the user's wallet. The --no-wallet flag is thus removed from dfx canister as its behavior is the default.

When working with existing canisters, use the --wallet flag in conjunction with dfx identity get-wallet in order to restore the old behavior.

You will need to upgrade your wallet and each of your existing canisters to work with the new system. To do so, execute the following in each of your dfx projects:

dfx wallet upgrade
dfx canister --wallet "$(dfx identity get-wallet)" update-settings --all --add-controller "$(dfx identity get-principal)"

To upgrade projects that you have deployed to the IC mainnet, execute the following:

dfx wallet --network ic upgrade
dfx canister --network ic --wallet "$(dfx identity --network ic get-wallet)" update-settings --all --add-controller "$(dfx identity get-principal)"

feat: Add --add-controller and --remove-controller flags for "canister update-settings"

dfx canister update-settings previously only let you overwrite the entire controller list; --add-controller and --remove-controller instead add or remove from the list.

feat: Add --no-withdrawal flag for "canister delete" for when the canister is out of cycles

dfx canister delete --no-withdrawal <canister> can be used to delete a canister without attempting to withdraw cycles.

fix: set RUST_MIN_STACK to 8MB for ic-starter (and therefore replica)

This matches the value used in production and is meant to exceed the configured 5 MB wasmtime stack.

fix: asset uploads will retry failed requests as expected

Fixed a defect in asset synchronization where no retries would be attempted after the first 30 seconds overall.

Motoko

Updated Motoko from 0.6.11 to 0.6.20.

• Implement type union/intersection
• Transform for-loops on arrays into while-loops
• Tighten typing rules for type annotations in patterns
• Candid decoding: skip vec any fast
• Bump up MAX_HP_FOR_GC from 1GB to 3GB
• Candid decoder: Trap if a principal value is too large
• Eliminate bignum calls from for-iteration on arrays
• Improve scheduling
• Improve performance of bignum equality
• Stable signatures: frontend, metadata, command-line args
• Added heartbeat support

Cycles wallet

• Module hash: 53ec1b030f1891bf8fd3877773b15e66ca040da539412cc763ff4ebcaf4507c5
• dfinity/cycles-wallet@57e53fc

Replica

Updated replica to blessed commit 75138bbf11e201aac47266f07bee289dc18a082b.
This incorporates the following executed proposals:

• 33828
• 31275
• 31165
• 30392
• 30078
• 29235
• 28784
• 27975
• 26833
• 25343
• 23633

SDK 0.8.4

DFX

feat: "rust" canister type

You can now declare "rust" canisters in dfx.json.

{
  "canisters": {
    "canister_name": {
      "type": "rust",
      "package": "crate_name",
      "candid": "path/to/canister_name.did"
    }
  }
}

Don't forget to place a Cargo.toml in your project root.
Then dfx will build the rust canister with your rust toolchain.
Please also make sure that you have added the WebAssembly compilation target.

rustup target add wasm32-unknown-unknown

You can also create new dfx project with a default rust canister.

dfx new --type=rust <project-name>

chore: updating dfx new template

Updates dependencies to latest for Webpack, and updates config. Additionally simplifies environment variables for canister ID's in config.

Additionally adds some polish to the starter template, including a favicon and using more semantic html in the example app

feat: environment variable overrides for executable pathnames

You can now override the location of any executable normally called from the cache by specifying
an environment variable. For example, DFX_ICX_PROXY_PATH will specify the path for icx-proxy.

feat: dfx deploy --mode=reinstall

dfx deploy can now reinstall a single canister, controlled by a new --mode=reinstall parameter.
This is destructive (it resets the state of the canister), so it requires a confirmation
and can only be performed on a single canister at a time.

dfx canister install --mode=reinstall <canister> also requires the same confirmation,
and no longer works with --all.

Replica

The included replica now supports canister_heartbeat. This only works with rust canisters for the time being,
and does not work with the emulator (dfx start --emulator).

Fix links to /nix/store libraries in linux binaries

DFX

fix: ic-ref linux binary no longer references /nix/store

This means dfx start --emulator has a chance of working if nix is not installed.
This has always been broken, even before dfx 0.7.0.

fix: replica and ic-starter linux binaries no longer reference /nix/store

This means dfx start will work again on linux. This bug was introduced in dfx 0.8.2.

feat: replaced --no_artificial_delay option with a sensible default.

The --no-artificial-delay option not being the default has been causing a lot of confusion.
Now that we have measured in production and already applied a default of 600ms to most subnets deployed out there,
we have set the same default for dfx and removed the option.

Motoko

Updated Motoko from 0.6.10 to 0.6.11.

• Assertion error messages are now reproducible (#2821)

Update replica: multiple controllers, 64-bit memory

Overview

Breaking change in how to specify a controller to dfx canister create

Be sure to upgrade your wallet with dfx wallet upgrade, or dfx wallet --network ic upgrade

DFX

feat: dfx canister delete can now return cycles to a wallet or dank

By default dfx canister delete will return cycles to the default cycles wallet.
Cycles can be returned to a designated canister with --withdraw-cycles-to-canister and
cycles can be returned to dank at the current identity principal with --withdraw-cycles-to-dank
and to a designated principal with --withdraw-cycles-to-dank-principal.

feat: dfx canister create now accepts multiple instances of --controller argument

It is now possible to create canisters with more than one controller by
passing multiple instances of the --controller parameter to dfx canister create`.

You will need to upgrade your wallet with dfx wallet upgrade, or dfx wallet --network ic upgrade

feat: dfx canister update-settings now accepts multiple instance of --controller argument

It is now possible to configure a canister to have more than one controller by
passing multiple instances of the --controller parameter to dfx canister update-settings`.

feat: dfx canister info and dfx canister status now display all controllers

feat!: dfx canister create --controller named parameter

Breaking change: The controller parameter for dfx canister create is now passed as a named parameter,
rather than optionally following the canister name.

Old: dfx canister create [canister name] [controller]
New: dfx canister create --controller [canister name]

fix: dfx now respects $DFX_CONFIG_ROOT when looking for legacy credentials

Previously this would always look in $HOME/.dfinity/identity/creds.pem.

fix: changed dfx canister (create|update-settings) --memory-allocation limit to 12 GiB

Updated the maximum value for the --memory-allocation value to be 12 GiB (12,884,901,888 bytes)

Cycles Wallet

• Module hash: 9183a38dd2eb1a4295f360990f87e67aa006f225910ab14880748e091248e086
• dfinity/cycles-wallet@9ef38bb

Added support for multiple controllers

You will need to upgrade your wallet with dfx wallet upgrade, or dfx wallet --network ic upgrade

Replica

The included replica now supports public spec 0.18.0

• Canisters can now have more than one controller
• Adds support for 64-bit stable memory
• The replica now goes through an initialization sequence, reported in its status
  as replica_health_status. Until this reports as healthy, queries or updates will
  fail.
  ** dfx start --background waits to exit until replica_health_status is healthy.
  ** If you run dfx start without --background, you can call dfx ping --wait-healthy
  to wait until the replica is healthy.

Motoko

Updated Motoko from 0.6.7 to 0.6.10

• add Debug.trap : Text -> None (motoko-base #288)
• Introduce primitives for Int ⇔ Float conversions (#2733)
• Fix crashing bug for formatting huge floats (#2737)

SDK 0.8.1

DFX

feat: dfx generate types command

dfx generate

This new command will generate type declarations for canisters in dfx.json.

You can control what will be generated and how with corresponding configuration in dfx.json.

Under dfx.json → "canisters" → "<canister_name>", developers can add a "declarations" config. Options are:

• "output" → directory to place declarations for that canister | default is "src/declarations/<canister_name>"

• "bindings" → [] list of options, ("js", "ts", "did", "mo") | default is "js", "ts", "did"

• "env_override" → a string that will replace process.env.{canister_name_uppercase}_CANISTER_ID in the "src/dfx/assets/language_bindings/canister.js" template.

js declarations output

• index.js (generated from "src/dfx/assets/language_bindings/canister.js" template)

• <canister_name>.did.js - candid js binding output

ts declarations output

• <canister_name>.did.d.ts - candid ts binding output

did declarations output

• <canister_name>.did - candid did binding output

mo declarations output

• <canister_name>.mo - candid mo binding output

feat: dfx now supports the anonymous identity

Use it with either of these forms:

dfx identity use anonymous
dfx --identity anonymous ...

feat: import default identities

Default identities are the pem files generated by dfx identity new ... which contain Ed25519 private keys.
They are located at ~/.config/dfx/identity/xxx/identity.pem.
Now, you can copy such pem file to another computer and import it there.

dfx identity new alice
cp ~/.config/dfx/identity/xxx/identity.pem alice.pem
# copy the pem file to another computer, then
dfx identity import alice alice.pem

Before, people can manually copy the pem files to the target directory to "import". Such workaround still works.
We suggest to use the import subcommand since it also validate the private key.

feat: Can now provide a nonstandard wallet module with DFX_WALLET_WASM environment variable

Define DFX_WALLET_WASM in the environment to use a different wasm module when creating or upgrading the wallet.

Asset Canister

fix: trust full asset SHA-256 hashes provided by the caller

When the caller provides SHA-256 hashes (which dfx does), the asset canister will no longer
recompute these hashes when committing the changes. These recomputations were causing
canisters to run out of cycles, or to attempt to exceed the maximum cycle limit per update.

Type Inference Update

Overview

The 0.8.0 release includes updates and fixes that are primarily internal to improve existing features and functions rather than user-visible.

Instructions on migrating to dfx 0.8.0

If your project does not have a frontend that relies on the JavaScript files that have been generated under .dfx/local, you should not expect to have any issues with dfx 0.8.0.

If you have an existing project that depends on dfx-generated frontend files, you may need to make some adjustments when upgrading to 0.8.0. Depending on your situation you may want to choose to set up environment variables or to make a minimum set of changes. We will document both cases here.

Environment variables

With webpack, we are providing environment variables by using an EnvironmentPlugin. At the top of webpack.config.js, we read from the root canister_ids.json and the one inside .dfx/local to map the canister IDs into environment variables, and then replace the process.env values in the code during development or at build time.

// webpack.config.js
let localCanisters, prodCanisters, canisters;

try {
  localCanisters = require(path.resolve(".dfx", "local", "canister_ids.json"));
} catch (error) {
  console.log("No local canister_ids.json found. Continuing production");
}

function initCanisterIds() {
  try {
    prodCanisters = require(path.resolve("canister_ids.json"));
  } catch (error) {
    console.log("No production canister_ids.json found. Continuing with local");
  }

  const network =
    process.env.DFX_NETWORK ||
    (process.env.NODE_ENV === "production" ? "ic" : "local");

  canisters = network === "local" ? localCanisters : prodCanisters;

  for (const canister in canisters) {
    process.env[canister.toUpperCase() + "_CANISTER_ID"] =
      canisters[canister][network];
  }
}
initCanisterIds();

With your bundler, whether it is Webpack or another bundler of your choice, you will need to account for the following:

1. Identifying canister ids. The output no longer hardcodes the canister ids into JavaScript, so you will need to provide that code using your own strategy. Other bundlers that allow for custom scripting should be able to re-use the webpack config logic.

2. Determining NODE_ENV. During development, the app should call agent.fetchRootKey(), but it should not fetch the root key in production.

3. Copying the codegen, as we do in the dfx new template, is optional. You still have access to the .did.js and .did.d.ts files in .dfx, so you can choose to ignore the new index.js format if it is inconvenient, and continue providing your own Actor.createActor pattern as before.

4. Return types - if you do not want to use the dfx-provided files, consider using the JSDoc comments that we have come up with. If the code knows that your actor has a type of ActorSubclass<_SERVICE>, for your particular service, the development process is significantly enhanced in compatible editors.

Minimal Update

If you are looking to minimally modify your project, here is all you need to do, assuming you are starting from the 0.7.2 starter:

You can continue using a query parameter in your URL, you can access it via

// src/example_assets/src/index.js
import { idlFactory as example_idl } from 'dfx-generated/example/example.did.js';
import canisterIds from '../../../.dfx/local/canister_ids.json'

const example_id = new URLSearchParams(window.location.search).get("exampleId") || canisterIds.example.local;

const agent = new HttpAgent();
agent.fetchRootKey();
const example = Actor.createActor(example_idl, { agent, canisterId: example_id });

And you can modify the aliases reducer to point to the path, rather than hardcoding the old <canister-name>.js file

// webpack.config.js

// Old
["dfx-generated/" + name]: path.join(outputRoot, name + ".js"),
// New
["dfx-generated/" + name]: path.join(outputRoot),

Then, you can dfx deploy like normal and visit your working site with http://localhost:8000/?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai&exampleId=rrkah-fqaaa-aaaaa-aaaaq-cai.

DFX

fix: dfx identity set-wallet no longer requires --force when used with --network ic

This was intended to skip verification of the wallet canister on the IC network,
but ended up only writing to the wallets.json file if --force was passed.

chore: updating dependencies

• Support for the latest version of the {IC} specification and replica.

• Updating to latest versions of Motoko, Candid, and agent-rs

feat: Type Inference Update

• Changes to dfx new project template and JavaScript codegen to support type inference in IDE's

• Adding webpack dev server to project template

• Migration path documented at https://sdk.dfinity.org/docs/release-notes/0.8.0-rn.html

0.7.7

Breaking changes to frontend code generation, documented in 0.8.0

The 0.7.7 release includes updates and fixes that are primarily internal to improve existing features and functions rather than user-visible.

The most significant changes in this release include the following:

• Support for the latest version of the Internet Computer specification and replica.

• Updating to latest versions of Motoko, Candid, and agent-rs

• Changes to dfx new project template and JavaScript codegen

DFX

feat: deploy and canister install will now only upgrade a canister if the wasm actually changed

dfx deploy and dfx canister install now compare the hash of the already-installed module
with the hash of the built canister's wasm output. If they are the same, they leave the canister
in place rather than upgrade it. They will still synchronize assets to an asset canister regardless
of the result of this comparison.

SDK 0.7.2

DFX

fix: set default cycle balance to 3T

Change the default cycle balance of a canister from 10T cycles to 3T cycles.

Cycles Wallet

• Module hash: 1404b28b1c66491689b59e184a9de3c2be0dbdd75d952f29113b516742b7f898
• dfinity/cycles-wallet@e902708

fix: It is no longer possible to remove the last controller.

Fixed an issue where the controller can remove itself from the list of controllers even if it's the only one,
leaving the wallet uncontrolled.
Added defensive checks to the wallet's remove_controller and deauthorize methods.