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.

SDK 0.7.1

New features and capabilities

The most significant new features and capabilities include the following updates for DFX commands:

• An update to the dfx canister sign command enables you to sign request_status messages for update calls.

  If you are using dfx canister sign to call a method that generates an update message, the command also signs a corresponding request_status message and appends it to the message.json file as signed_request_status. After you send the message using the dfx canister send command, you can check the request_status of the call by running the following command:

  dfx canister send message.json --status

  This change is particularly useful if you are using the dfx canister sign and dfx canister send commands to call the ledger or governance canister to make a transaction or stake tokens as a two-step process.

• There are new deposit_cycles and uninstall_code management canister methods that are also exposed as dfx canister subcommands.

  The two new commands are dfx canister deposit-cycles and dfx canister uninstall-code. For example, you can now send cycles from your cycles wallet to a specific canister by running a command similar to the following:

  dfx canister deposit-cycles 125000000000 hello_world

  You can uninstall code for a deployed WASM module by running a command similar to the following:

  dfx canister uninstall-code hello_world

• A new --no-artificial-delay option enables you to reduce the time it takes for the local Internet Computer to start.

  This change adds the --no-artificial-delay flag to dfx start and dfx replica commands. By default, the local Internet Computer replica that is installed with the SDK has an artificial consensus delay to simulate the delay users might see in a networked environment. With this new flag, you can skip the built-in delay when you start the local Internet Computer by running either the dfx start --no-artificial-delay or dfx replica --no-artificial-delay command.

  For example, you can start the local Internet Computer without a delay by running the following command:

  dfx start -no-artificial-delay

  If you use this option, however, you might an increase in the CPU used by the local Internet Computer replica.

Breaking change

The SDK version 0.7.1 introduces a change to the default principal used when you run dfx canister call commands. Depending on the version of the SDK that you were previously using, this change might require changes to your program code or to the way you call methods in deployed canisters.

• The cycles wallet canister identifier is not longer used as the message caller by default.

  In some previous versions of the SDK, the dfx canister call command would use the cycles wallet canister identifier as the message caller to perform queries and update calls by default.

  The --no-wallet command-line option was introduced to allow you to bypass the cycles wallet canister identifier and perform query and update calls using the currently-selected identity.

  However, using the cycles wallet canister identifier to execute dfx canister call commands resulted in each call being treated as an inter-canister call and the calls would take longer than necessary to resolve.

  With this release, dfx canister call commands no longer use the cycles wallet canister identifier to execute query and update calls by default. If you want to execute a query or update call using the cycles wallet, you can run a command similar to the following:

  dfx canister --wallet=cycles-wallet-id call canister method

DFX

feat: sign request_status for update call

When using dfx canister sign to generate a update message, a corresponding
request_status message is also signed and append to the json as signed_request_status.
Then after sending the update message, the user can check the request_status using
dfx canister send message.json --status.

fix: wallet will not proxy dfx canister call by default

Previously, dfx canister call would proxy queries and update calls via the wallet canister by default.
(There was the --no-wallet flag to bypass the proxy and perform the calls as the selected identity.)
However, this behavior had drawbacks, namely each dfx canister call was an inter-canister call
by default and calls would take a while to resolve. This fix makes it so that dfx canister call no longer
proxies via the wallet by default. To proxy calls via the wallet, you can do
dfx canister --wallet=<wallet-id> call.

feat: add --no-artificial-delay to dfx replica and start

This change adds the --no-artificial-delay flag to dfx start and dfx replica.
The replica shipped with dfx has always had an artificial consensus delay (introduced to simulate
a delay users might see in a networked environment.) With this new flag, that delay can
be lessened. However, you might see increased CPU utilization by the replica process.

feat: add deposit cycles and uninstall code

This change introduces the deposit_cycles and uninstall_code management canister
methods as dedicated dfx canister subcommands.

fix: allow consistent use of canisters ids in canister command

This change updates the dfx commands so that they will accept either a canister name
(sourced from your local project) or a valid canister id.

SDK 0.7.0

DFX

feat: add output type to request-status

This change allows you to specify the format the return result for dfx canister request-status.

fix: deleting a canister on a network removes entries for other networks

This change fixes a bug where deleting a canister on a network removed all other entries for
the canister in the canister_ids.json file.

feat: point built-in ic network provider at mainnet

--network ic now points to the mainnet IC (as Sodium has been deprecated.)

feat: add candid UI canister

The dedicated candid UI canister is installed on a local network when doing a dfx canister install
or dfx deploy.

fix: Address already in use (os error 48) when issuing dfx start

This fixes an error which occurred when starting a replica right after stopping it.

feat: ledger subcommands

dfx now supports a dedicated dfx ledger subcommand. This allows you to interact with the ledger
canister installed on the Internet Computer. Example commands include dfx ledger account-id which
prints the Account Identifier associated with your selected identity, dfx ledger transfer which
allows you to transfer ICP from your ledger account to another, and dfx ledger create-canister which
allows you to create a canister from ICP.

feat: update to 0.17.0 of the Interface Spec

This is a breaking change to support 0.17.0 of the Interface Spec. Compute & memory allocation values
are set when creating a canister. An optional controller can also be specified when creating a canister.
Furthermore, dfx canister set-controller is removed, in favor of dfx canister update-settings which
allows the controller to update the controller, the compute allocation, and the memory allocation of the
canister. The freezing threshold value isn't exposed via dfx cli yet, but it may still be modified by
calling the management canister via dfx canister call aaaaa-aa update-settings

feat: add wallet subcommands

dfx now supports a dedicated dfx wallet subcommand. This allows you to interact with the cycles wallet
associated with your selected identity. For example, dfx wallet balance to get the cycle balance,
dfx wallet list-addresses to display the associated controllers & custodians, and dfx wallet send <destination> <amount>
to send cycles to another wallet.

Cycles Wallet

• Module Hash: a609400f2576d1d6df72ce868b359fd08e1d68e58454ef17db2361d2f1c242a1
• dfinity/cycles-wallet@06bb256

feat: Use Internet Identity Service.

SDK 0.6.26

DFX

feat: add --no-wallet flag and --wallet option to allow Users to bypass Wallet or specify a Wallet to use for calls (#1476)

Added --no-wallet flag to dfx canister and dfx deploy. This allows users to call canister management functionality with their Identity as the Sender (bypassing their Wallet canister.)
Added --wallet option to dfx canister and dfx deploy. This allows users to specify a wallet canister id to use as the Sender for calls.
--wallet and --no-wallet conflict with each other. Omitting both will invoke the selected Identity's wallet canister to perform calls.

feat: add canister subcommands sign and send

Users can use dfx canister sign ... to generated a signed canister call in a json file. Then dfx canister send [message.json] to the network.

Users can sign the message on an air-gapped computer which is secure to host private keys.

Note

• sign and send currently don't proxy through wallet canister. Users should use the subcommands with dfx canister --no-wallet sign ....

• The sign option --expire-after will set the ingress_expiry to a future timestamp which is current plus the duration.
  Then users can send the message during a 5 minutes time window ending in that ingress_expiry timestamp. Sending the message earlier or later than the time window will both result in a replica error.

feat: implement the HTTP Request proposal in dfx' bootstrap webserver. +

And add support for http requests in the base storage canister (with a default to /index.html).

This does not support other encodings than identity for now (and doesn't even return any headers). This support will be added to the upgraded asset storage canister built in #1482.

Added a test that uses curl localhost to test that the asset storage AND the webserver properly support the http requests.

This commit also upgrades tokio and reqwest in order to work correctly. There are also some performance issues noted (this is slower than the icx-http-server for some reason), but those are not considered criticals and could be improved later on.

Renamed the project_name in our own generated assets to canister_name, for things that are generated during canister build (and not project generation).

feat: add support for ECDSA on secp256k1

You can now a generate private key via OpenSSL or a simlar tool, import it into dfx, and use it to sign an ingress message.

openssl ecparam -name secp256k1 -genkey -out identity.pem
dfx identity import <name> identity.pem
dfx identity use <name>
dfx canister call ...

Asset Canister

feat: The asset canister can now store assets that exceed the message ingress limit (2 MB)

• Please note that neither the JS agent nor the HTTP server have been updated yet to server such large assets.
• The existing interface is left in place for backwards-compatibility, but deprecated:
  ** retrieve(): use get() and get_chunk() instead
  ** store(): use create_batch(), create_chunk(), and commit_batch() instead
  ** list(): use keys() instead