0.14.0

See also: migration guide

DFX

fix: stop dfx deploy from creating a wallet if all canisters exist

feat: expose wasm-opt optimizer in ic-wasm to users

Add option to specify an "optimize" field for canisters to invoke the wasm-opt optimizer through ic-wasm.

This behavior is disabled by default.

If you want to enable this behavior, you can do so in dfx.json:

"canisters" : {
    "app" : {
        "optimize" : "cycles"
    }
}

The options are "cycles", "size", "O4", "O3", "O2", "O1", "O0", "Oz", and "Os". The options starting with "O" are the optimization levels that wasm-opt provides. The "cycles" and "size" options are recommended defaults for optimizing for cycle usage and binary size respectively.

feat: updates the dfx new starter project for env vars

• Updates the starter project for env vars to use the new dfx build & dfx deploy environment variables
• Changes the format of the canister id env vars to be CANISTER_ID_<canister_name_uppercase>, for the frontend declaraction file to be consistent with the dfx environment variables. CANISTER_ID as both a prefix and suffix are supported for backwards compatibility.

fix!: --clean required when network configuration changes

If the network configuration has changed since last time dfx start was run, dfx start will now error if you try to run it without --clean, to avoid spurious errors. You can provide the --force flag if you are sure you want to start it without cleaning state.

feat: --artificial-delay flag

The local replica uses a 600ms delay by default when performing update calls. With dfx start --artificial-delay <ms>, you can decrease this value (e.g. 100ms) for faster integration tests, or increase it (e.g. 2500ms) to mimick mainnet latency for e.g. UI responsiveness checks.

fix: make sure assetstorage did file is created as writeable.

feat: specify id when provisional create canister

When creating a canister on non-mainnet replica, you can now specify the canister ID.

dfx canister create <CANISTER_NAME> --specified-id <PRINCIPAL>

dfx deploy <CANISTER_NAME> --specified-id <PRINCIPAL>

You can specify the ID in the range of [0, u64::MAX / 2].
If not specify the ID, the canister will be created in the range of [u64::MAX / 2 + 1, u64::MAX].
This canister ID allocation behavior only applies to the replica, not the emulator (ic-ref).

feat: dfx nns install --ledger-accounts

dfx nns install now takes an option --ledger-accounts to initialize the ledger canister with these accounts.

fix: update Rust canister template.

ic-cdk-timers is included in the dependencies.

chore: change the default Internet Computer gateway domain to icp0.io

By default, DFX now uses the icp0.io domain to connect to Internet Computer as opposed to using ic0.app.
Canisters communicating with ic0.app will continue to function nominally.

feat: --no-asset-upgrade

feat: confirmation dialogues are no longer case sensitive and accept 'y' in addition to 'yes'

fix: dfx generate no longer requires canisters to have a canister ID

Previously, canisters required that the canister was created before dfx generate could be called.

As a result, the --network parameter does not have an impact on the result of dfx generate anymore.
This means that dfx generate now also generates type declarations for remote canisters.

fix: Make build field optional in dfx.json

The build field in custom canisters was already optional in code, but this fixes it in the schema.

By specifying the --no-asset-upgrade flag in dfx deploy or dfx canister install, you can ensure that the asset canister itself is not upgraded, but instead only the assets themselves are installed.

feat: Get identity from env var if present

The identity may be specified using the environment variable DFX_IDENTITY.

feat: Add DFX_ASSETS_WASM

Added the ability to configure the WASM module used for assets canisters through the environment variable DFX_ASSETS_WASM.

feat: dfx pull can download wasm

fix: dfx deploy and icx-asset no longer retry on permission failure

feat: --created-at-time for the ledger functions: transfer, create-canister, and top-up

fix: ledger transfer duplicate transaction prints the duplicate transaction response before returning success to differentiate between a new transaction response and between a duplicate transaction response.

Before it was possible that a user could send 2 ledger transfers with the same arguments at the same timestamp and both would show success but there would have been only 1 ledger transfer. Now dfx prints different messages when the ledger returns a duplicate transaction response and when the ledger returns a new transaction response.

chore: clarify dfx identity new help text

chore: Add a message that redeem_faucet_coupon may take a while to complete

feat: dfx deploy --by-proposal

This supports asset updates through SNS proposal.

Uploads asset changes to an asset canister (propose_commit_batch()), but does not commit them.

The SNS will call commit_proposed_batch() to commit the changes. If the proposal fails, the caller of dfx deploy --by-proposal should call delete_batch().

feat: dfx deploy --compute-evidence

Builds the specified asset canister, determines the batch operations required to synchronize the assets, and computes a hash ("evidence") over those batch operations. This evidence will match the evidence computed by dfx deploy --by-proposal, and which will be specified in the update proposal.

No permissions are required to compute evidence, so this can be called with --identity anonymous or any other identity.

Asset Canister

Added validate_take_ownership() method so that an SNS is able to add a custom call to take_ownership().

Added is_aliased field to get_asset_properties and set_asset_properties.

Added partial support for proposal-based asset updates:

• Batch ids are now stable. With upcoming changes to support asset updates by proposal,
  having the asset canister not reuse batch ids will make it easier to verify that a particular
  batch has been proposed.
• Added methods:
  • propose_commit_batch() stores batch arguments for later commit
  • delete_batch() deletes a batch, intended for use after compute_evidence if cancellation needed
  • compute_evidence() computes a hash ("evidence") over the proposed batch arguments. Once evidence computation is complete, batch will not expire.
  • commit_proposed_batch() commits batch previously proposed (must have evidence computed)
  • validate_commit_proposed_batch() required validation method for SNS

Added api_version endpoint. With upcoming changes we will introduce breaking changes to asset canister's batch upload process. New endpoint will help ic-asset with differentiation between API version, and allow it to support all versions of the asset canister.

Added support for v2 asset certification. In comparison to v1, v2 asset certification not only certifies the http response body, but also the headers. The v2 spec is first published in this PR

Added canister metadata field supported_certificate_versions, which contains a comma-separated list of all asset certification protocol versions. You can query it e.g. using dfx canister --network ic metadata <canister name or id> supported_certificate_versions. In this release, the value of this metadata field value is 1,2 because certification v1 and v2 are supported.

Fixed a bug in http_request that served assets with the wrong certificate. If no encoding specified in the Accept-Encoding header is available with a certificate, an available encoding is returned without a certificate (instead of a wrong certificate, which was the case previously). Otherwise, nothing changed.
For completeness' sake, the new behavior is as follows:

• If one of the encodings specified in the Accept-Encoding header is available with certification, it now is served with the correct certificate.
• If no requested encoding is available with certification, one of the requested encodings is returned without a certificate (instead of a wrong certificate, which was the case previously).
• If no encoding specified in the Accept-Encoding header is available, a certified encoding that is available is returned instead.

Added support for API versioning of the asset canister in ic-asset.

Added functionality that allows you to set asset properties during dfx deploy, even if the asset has already been deployed to a canister in the past. This eliminates the need to delete and re-deploy assets to modify properties - great news! This feature is also available when deploying assets using the --by-proposal flag. As a result, the API version of the frontend canister has been incremented from 0 to 1. The updated ic-asset version (which is what is being used during dfx deploy) will remain compatible with frontend canisters implementing both API 0 and 1. However, please note that the new frontend canister version (with API v1) will not work with tooling from before the dfx release (0.14.0).

Dependencies

Frontend canister

• API version: 1
• Module hash: e7866e1949e3688a78d8d29bd63e1c13cd6bfb8fbe29444fa606a20e0b1e33f0
• #3094
• #3002
• #3065
• #3058
• #3057
• #2960
• htt...

0.13.1

Asset Canister

Added validate_grant_permission() and validate_revoke_permission() methods per SNS requirements.

Dependencies

Frontend canister

• Module hash: 98863747bb8b1366ae5e3c5721bfe08ce6b7480fe4c3864d4fec3d9827255480
• #2958

0.13.0

DFX

feat: Add dfx sns download

This allows users to download SNS canister WASMs.

fix: fixed error text

• dfx nns install had the wrong instructions for setting up the local replica type

fix: creating an identity with --force no longer switches to the newly created identity

feat(frontend-canister)!: reworked to use permissions-based access control

The permissions are as follows:

• ManagePermissions: Can grant and revoke permissions to any principal. Controllers implicitly have this permission.
• Prepare: Can call create_batch and create_chunk
• Commit: Can call commit_batch and methods that manipulate assets directly, as well as any method permitted by Prepare.

For upgraded frontend canisters, all authorized principals will be granted the Commit permission.
For newly deployed frontend canisters, the initializer (first deployer of the canister) will be granted the Commit permission.

Added three new methods:

• list_permitted: lists principals with a given permission.
  • Callable by anyone.
• grant_permission: grants a single permission to a principal
  • Callable by Controllers and principals with the ManagePermissions permission.
• revoke_permission: removes a single permission from a principal
  • Any principal can revoke its own permissions.
  • Only Controllers and principals with the ManagePermissions permission can revoke the permissions of other principals.

Altered the behavior of the existing authorization-related methods to operate only on the "Commit" permission. In this way, they are backwards-compatible.

• authorize(principal): same as grant_permission(principal, Commit)
• deauthorize(principal): same as revoke_permission(permission, Commit)
• list_authorized(): same as list_permitted(Commit)

fix(frontend-canister)!: removed ability of some types of authorized principals to manage the ACL

It used to be the case that any authorized principal could authorize and deauthorize any other principal.
This is no longer the case. See rules above for grant_permission and revoke_permission.

feat(frontend-canister)!: default secure configuration for assets in frontend project template

• Secure HTTP headers, preventing several typical security vulnerabilities (e.g. XSS, clickjacking, and many more). For more details, see comments in headers section in default .ic-assets.json5.
• Configures allow_raw_access option in starter .ic-assets.json5 config files, with the value set to its default value (which is false). We are showing that configuration in the default starter projects for the sake of easier discoverability, even though its value is set to the default.

feat(frontend-canister)!: add allow_raw_access config option

By default, the frontend canister will now restrict the access of traffic to the <canister-id>.raw.ic0.app domain, and will automatically redirect all requests to the certified domain (<canister-id>.ic0.app), unless configured explicitly. Below is an example configuration to allow access to the robots.txt file from the "raw" domain:

[
  {
    "match": "robots.txt",
    "allow_raw_access": true
  }
]

Important: Note that any assets already uploaded to an asset canister will be protected by this redirection, because at present the asset synchronization process does not update the allow_raw_access property, or any other properties, after creating an asset. This also applies to assets that are deployed without any configuration, and later configured to allow raw access.
At the present time, there are two ways to reconfigure an existing asset:

1. re-create the asset
   1. delete the asset in your project's directory
   2. execute dfx deploy
   3. re-create the asset in your project's directory
   4. modify .ic-assets.json acordingly
   5. execute dfx deploy
2. via manual candid call

   dfx canister call PROJECT_NAME_frontend set_asset_properties '( record { key="/robots.txt"; allow_raw_access=opt(opt(true)) })'
   

feat(frontend-canister): pretty print asset properties when deploying assets to the canister

feat(frontend-canister): add take_ownership() method

Callable only by a controller. Clears list of authorized principals and adds the caller (controller) as the only authorized principal.

feat(ic-ref):

• effective_canister_id used for provisional_create_canister_with_cycles is passed as an command-line argument (defaults to rwlgt-iiaaa-aaaaa-aaaaa-cai if not provided or upon parse failure)

feat(frontend-canister): add get_asset_properties and set_asset_properties to frontend canister

As part of creating the support for future work, it's now possible to get and set AssetProperties for assets in frontend canister.

feat: write canister metadata sections for dfx pull

feat: add --argument-file argument to the dfx canister sign command

Similar to how this argument works in dfx canister call, this argument allows providing arguments for the request from a file.

feat: Add support for a default network key

A remote canister ID can now be specified for the __default network. If specified, dfx will assume that the canister is remote at the specified canister ID for all networks that don't have a dedicated entry.

feat: use OS-native keyring for pem file storage

If keyring integration is available, PEM files (except for the default identity) are now by default stored in the OS-provided keyring.
If it is not available, it will fall back on the already existing password-encrypted PEM files.
Plaintext PEM files are still available (e.g. for use in non-interactive situations like CI), but not recommended for use since they put the keys at risk.

To force the use of one specific storage mode, use the --storage-mode flag with either --storage-mode password-protected or --storage-mode plaintext.
This works for both dfx identity new and dfx identity import.

The flag --disable-encryption is deprecated in favour of --storage-mode plaintext. It has the same behavior.

feat: dfx pull

• write canister metadata for dfx pull.
• dfx pull can fetch dfx:deps metadata and resolve dependencies recursively.

feat(frontend-canister): better control and overview for asset canister authorized principals

The asset canister now has two new functions:

• Query function list_authorized displays a list of all principals that are currently authorized to change assets and the list of authorized principals.
• Update function deauthorize that removes a principal from the list of authorized principals. It can be called by authorized principals and cotrollers of the canister.

In addition, the update function authorize has new behavior:
Now, controllers of the asset canister are always allowed to authorize new principals (including themselves).

fix: add retry logic to dfx canister delete

dfx canister delete tries to withdraw as many cycles as possible from a canister before deleting it.
To do so, dfx has to manually send all cycles in the canister, minus some margin.
The margin was previously hard-coded, meaning that withdrawals can fail if the margin is not generous enough.
Now, upon failure with some margin, dfx will retry withdrawing cycles with a continuously larger margin until withdrawing succeeds or the margin becomes larger than the cycles balance.

fix: dfx deploy --mode reinstall for a single Motoko canister fails to compile

The Motoko compiler expects all imported canisters' .did files to be in one folder when it compiles a canister.
dfx failed to organize the .did files correctly when running dfx deploy <single Motoko canister> in combintaion with the --mode reinstall flag.

fix: give more cycles margin when deleting canisters

There have been a few reports of people not being able to delete canisters.
The error happens if the temporary wallet tries to transfer out too many cycles.
The number of cycles left in the canister is bumped a little bit so that people can again reliably delete their canisters.

Dependencies

Updated candid to 0.8.4

• Bug fix in TS bindings
• Pretty print numbers

Frontend canister

• Module hash: d12e4493878911c21364c550ca90b81be900ebde43e7956ae1873c51504a8757
• #2942

ic-ref

Updated ic-ref to master commit 3cc51be5

Motoko

Updated Motoko to 0.7.6

Replica

Updated replica to elected commit b5a1a8c0e005216f2d945f538fc27163bafc3bf7.
This incorporates the following executed proposals:

• 100821
• 97472
• 96114
• 94953
• 94852
• 93761
• 93507
• 92573
• 92338
• 91732
• 91257

0.12.1

DFX

fix: default not shrink for custom canisters

Dependencies

Replica

Updated replica to elected commit dcbf401f27d9b48354e68389c6d8293c4233b055.
This incorporates the following executed proposals:

• 90485
• 90008

Frontend canister

• Module hash: db07e7e24f6f8ddf53c33a610713259a7c1eb71c270b819ebd311e2d223267f0
• #2753

0.12.0

DFX

feat(frontend-canister): add warning if config is provided in .ic-assets.json but not used

fix(frontend-canister): Allow overwriting default HTTP Headers for assets in frontend canister

Allows to overwrite Content-Type, Content-Encoding, and Cache-Control HTTP headers with custom values via .ic-assets.json5 config file. Example .ic-assets.json5 file:

[
    {
        "match": "web-gz.data.gz",
        "headers": {
            "Content-Type": "application/octet-stream",
            "Content-Encoding": "gzip"
        }
    }
]

This change will trigger the update process for frontend canister (new module hash: 2ff0513123f11c57716d889ca487083fac7d94a4c9434d5879f8d0342ad9d759).

feat: warn if an unencrypted identity is used on mainnet

fix: Save SNS canister IDs

SNS canister IDs were not being parsed reliably. Now the candid file is being specified explicitly, which resolves the issue in at least some cases.

feat: NNS usability improvements

The command line interface for nns commands has been updated to:

• Give better help when the subnet type is incorrect
• Not offer --network as a flag given that it is unused
• List nns subcommands

feat: -y flag for canister installation

dfx canister install and dfx deploy now have a -y flag that will automatically confirm any y/n checks made during canister installation.

fix: Compute Motoko dependencies in linear (not exponential) time by detecting visited imports.

fix(generate): add missing typescript types and fix issues with bindings array in dfx.json

chore: update Candid UI canister with commit 79d55e7f568aec00e16dd0329926cc7ea8e3a28b

refactor: Factor out code for calling arbitrary bundled binaries

The function for calling sns can now call any bundled binary.

docs: Document dfx nns subcommands

dfx nns commands are used to deploy and manage local NNS canisters, such as:

• Governance for integration with the Internet Computer voting system
• Ledger for financial integration testing
• Internet Identity for user registration and authenttication

feat(frontend-canister): Add simple aliases from <asset> to <asset>.html and <asset>/index.html

The asset canister now by default aliases any request to <asset> to <asset>.html or <asset>/index.html.
This can be disabled by setting the field "enable_aliasing" to false in a rule for that asset in .ic-assets.json.
This change will trigger frontend canister upgrades upon redeploying any asset canister.

fix: Only kill main process on dfx stop

Removes misleading panics when running dfx stop.

feat: dfx nns install works offline if all assets have been cached.

feat: Initialise the nns with an account controlled by a secp256k1 key

This enables easy access to toy ICP using command line tools and this key:

-----BEGIN EC PRIVATE KEY-----
MHQCAQEEICJxApEbuZznKFpV+VKACRK30i6+7u5Z13/DOl18cIC+oAcGBSuBBAAK
oUQDQgAEPas6Iag4TUx+Uop+3NhE6s3FlayFtbwdhRVjvOar0kPTfE/N8N6btRnd
74ly5xXEBNSXiENyxhEuzOZrIWMCNQ==
-----END EC PRIVATE KEY-----

For example, you can create an identity in dfx by putting this key in the file ident-1.pem and importing it:

dfx identity import ident-1 ident-1.pem
dfx --identity ident-1 ledger balance

feat: default to run ic-wasm shrink when build canisters

This behavior applies to Motoko, Rust and Custom canisters.
If you want to disable this behavior, you can config it in dfx.json:

"canisters" : {
    "app" : {
        "shrink" : false,
    }
}

feat: configurable custom wasm sections

It's now possible to define custom wasm metadata sections and their visibility in dfx.json.

At present, dfx can only add wasm metadata sections to canisters that are in wasm format. It cannot add metadata sections to compressed canisters. Since the frontend canister is now compressed, this means that at present it is not possible to add custom metadata sections to the frontend canister.

dfx no longer adds candid:service metadata to canisters of type "custom" by default. If you want dfx to add your canister's candid definition to your custom canister, you can do so like this:

    "my_canister_name": {
      "type": "custom",
      "candid": "main.did",
      "wasm": "main.wasm",
      "metadata": [
        {
          "name": "candid:service"
        }
      ]
    },

This changelog entry doesn't go into all of the details of the possible configuration. For that, please see concepts/canister-metadata and the docs in the JSON schema.

fix: Valid canister-based env vars

Hyphens are not valid in shell environment variables, but do occur in canister names such as smiley-dapp. This poses a problem for vars with names such as CANISTER_ID_${CANISTER_NAME}. With this change, hyphens are replaced with underscores in environment variables. The canister id of smiley-dapp will be available as CANISTER_ID_smiley_dapp. Other environment variables are unaffected.

feat: Add dfx sns deploy

This allows users to deploy a set of SNS canisters.

fix: cargo run -p dfx -- --version prints correct version

feat: add --mode=auto

When using dfx canister install, you can now pass auto for the --mode flag, which will auto-select install or upgrade depending on need, the same way dfx deploy does. The default remains install to prevent mistakes.

feat: add --network flag to dfx generate

dfx generate's generated bindings use network-specific canister IDs depending on the generated language, but there was previously no way to configure which network this was, so it defaulted to local. A --network flag has been added for this purpose.

feat: sns config validate

There is a new command that verifies that an SNS initialization config is valid.

feat: sns config create

There is a new command that creates an sns config template.

fix: remove $ from wasms dir

The wasms dir path had a $ which is unwanted and now gone.

fix: Correct wasm for the SNS swap canister

Previously the incorrect wasm canister was installed.

fix: Use NNS did files that matches the wasms

Previously the did files and wasms could be incompatible.

fix: allow users to skip compatibility check if parsing fails

feat: canister HTTP support is now enabled by default.

dfx start and dfx replica now ignore the --enable-canister-http parameter.

You can still disable the canister http feature through configuration:

• ~/.config/dfx/networks.json: .local.canister_http.enabled=false
• dfx.json (project-specific networks) : .networks.local.canister_http.enabled=false

feat: custom canister wasm field can now specify a URL from which to download

• note that dfx will report an error if a custom canister's wasm field is a URL and the canister also has build steps.

feat: custom canister candid field can now specify a URL from which to download

feat: deploy NNS canisters

A developer is now able to install NNS canisters, including back end canisters such as ledger and governance, and front end canisters such as nns-dapp and internet-identity, on their local DFX server. Usage:

dfx start --clean --background
dfx nns install

This feature currently requires that the network 'local' is used and that it runs on port 8080.
The network's port can be controlled by using the field "provider" in the network's definition, e.g. by setting it to "127.0.0.1:8080".

feat: configure logging level of http adapter

It is now possible to set the http adapter's log level in dfx.json or in networks.json:

"http": {
  "enabled": true,
  "log_level": "info"
}

By default, a log level of "error" is used, in order to keep the output of a first-time dfx start minimal. Change it to "debug" for more verbose logging.

fix(typescript): add index.d.ts file for type safety when importing generated declarations

Adds an index.d.ts file to the generated declarations, allowing for better type safety in TypeScript projects.

chore: reduce verbosity of dfx start

dfx start produces a lot of log output that is at best irrelevant for most users.
Most output is no longer visible unless either --verbose is used with dfx or the relevant part's (e.g. http adapter, btc adapter, or replica) log level is changed in dfx.json or networks.json.

feat: generate secp256k1 keys by default

When creating a new identity with dfx identity new, whereas previously it would have generated an Ed25519 key, it now generates a secp256k1 key. This is to enable users to write down a BIP39-style seed phrase, to recover their key in case of emergency, which will be printed when the key is generated and can be used with a new --seed-phrase flag in dfx identity import. dfx identity import is however still capable of importing an Ed25519 key.

chore: update Candid UI canister with commit 528a4b04807904899f67b919a88597656e0cd6fa

• Allow passing did files larger than 2KB.
• Better integration with Motoko Playground.

feat: simplify verification of assets served by asset canister

• SHA256 hashes of all assets are displayed when deploying the asset canister.
• A query method is added to the asset canister that returns the entire asset hash tree together with the certificate containing the certified variables of the asset canister.

breaking change: dfx canister update-settings --compute-allocation always fails

See https://forum.dfinity.org/t/fixing-incorrect-compute-allocation-fee/14830

Until the rollout is complete, dfx canister update-settings --compute-allocation <N>
will fail with an error from the replica such as the following:

The Replica returned an error: code 1, message: "Canister requested a compute allocation of 1% which cannot be satisfied because the Subnet's remaining compute capacity is 0%"

fix: For default node starter template: copy...

0.11.2

DFX

fix: disable asset canister redirection of all HTTP traffic from .raw.ic0.app to .ic0.app

fix: disable asset canister's ETag HTTP headers

The feature is not yet implemented on icx-proxy-level, and is causing 500 HTTP response for some type of assets every second request.

0.11.1

DFX

fix: dfx now only adds candid:service metadata to custom canisters that have at least one build step

This way, if a canister uses a premade canister wasm, dfx will use it as-is.

fix: "canister alias not defined" in the Motoko language server

It is now possible to develop multiple-canister projects using the Motoko VSCode extension.

fix: improve browser compatibility for the JavaScript language binding

Patches a JavaScript language binding compatibility issue encountered in web browsers which do not support the (?.) operator.

feat: print dfx.json schema

dfx is now capable of displaying the schema for dfx.json. You can see the schema by running dfx schema or write the schema to a file with dfx schema --outfile path/to/file/schema.json.

feat: support for configuring assets in assets canister

• The .ic-assets.json file should be placed inside directory with assets, or its subdirectories. Multiple config files can be used (nested in subdirectories). Example of .ic-assets.json file format:

[
    {
        "match": ".*",
        "cache": {
            "max_age": 20
        },
        "headers": {
            "X-Content-Type-Options": "nosniff"
        },
        "ignore": false
    },
    {
        "match": "**/*",
        "headers": null
    },
    {
        "match": "file.json",
        "ignore": true
    }
]

• Configuring assets works only during asset creation - any changes to .ic-assets.json files won't have any effect effect for assets that have already been created. We are working on follow up implementation with improvements to handle updating these properties.

• headers from multiple applicable rules are being stacked/concatenated, unless null is specified, which resets/empties the headers.

• Both "headers": {} and absence of headers field don't have any effect on end result.

• Valid JSON format is required, i.e. the array of maps, match field is required. Only the following fields are accepted: cache, ignore, headers, match. The glob pattern has to be valid.

• The way matching rules work:

  1. The most deeply nested config file takes precedence over the one in parent dir. In other words, properties from a rule matching a file in a subdirectory override properties from a rule matching a file in a parent directory
  2. Order of rules within file matters - last rule in config file takes precedence over the first one

• The way ignore field works:

  1. By default, files that begin with a . are ignored, while all other files are included.
  2. The .ignore field overrides this, if present.
  3. If a directory is ignored, file and directories within it cannot be un-ignored.
  4. A file can be ignored and un-ignored many times, as long as any of its parent directories haven't been ignored.

fix: Allow dfx deploy to not take arguments for canisters not being installed

A longstanding bug with dfx deploy is that if an installation is skipped (usually an implicitly included dependency), it still requires arguments even if the installed canister doesn't. As of this release that bug is now fixed.

feat: Add additional logging from bitcoin canister in replica.

Configures the replica to emit additional logging from the bitcoin canister whenever the bitcoin feature is enabled. This helps show useful information to developers, such as the bitcoin height that the replica currently sees.

fix: make build field optional for custom canisters

Prior to 0.11.0, a custom canister's build field could be left off if dfx build was never invoked. To aid in deploying prebuilt canisters, this behavior is now formalized; omitting build is equivalent to build: [].

feat: Use --locked for Rust canisters

dfx build, in Rust canisters, now uses the --locked flag when building with Cargo. To offset this, dfx new --type rust now runs cargo update on the resulting project.

feat: Enable threshold ecdsa signature

ECDSA signature signing is now enabled by default in new projects, or by running dfx start --clean.
A test key id "Secp256k1:dfx_test_key" is ready to be used by locally created canisters.

Dependencies

Updated agent-rs to 0.20.0

Updated candid to 0.7.15

Replica

Updated replica to elected commit 6e86169e98904047833ba6133e5413d2758d90eb.
This incorporates the following executed proposals:

• 72225
• 71669
• 71164
• 70375
• 70002

0.11.0

DFX

feat: renamed canisters in new projects to _frontend and _backend

The names of canisters created for new projects have changed.
After dfx new <project>, the canister names are:

• <project>_backend (previously <project>)
• <project>_frontend (previously <project>_assets)

feat: Enable threshold ecdsa signature

feat: new command: dfx canister metadata

For example, to query a canister's candid service definition: dfx canister metadata hello_backend candid:service

refactor: deprecate /_/candid internal webserver

The dfx internal webserver now only services the /_/candid endpoint. This
is now deprecated. If you were using this to query candid definitions, you
can instead use dfx canister metadata.

refactor: optimize from ic-wasm

Optimize Rust canister WASM module via ic-wasm library instead of ic-cdk-optimizer. A separate installation of ic-cdk-optimizer is no longer needed.

The actual optimization was kept the same.

feat: Read dfx canister call argument from a file or stdin

Enables passing large arguments that cannot be passed directly in the command line using the --argument-file flag. For example:

• Named file: dfx canister call --argument-file ./my/argument/file.txt my_canister_name greet
• Stdin: echo '( null )' | dfx canister call --argument-file - my_canister_name greet

fix: Use default setting for BTC adapter idle seconds

A lower threshold was no longer necessary.

feat: Allow users to configure logging level of bitcoin adapter

The bitcoin adapter's logging can be very verbose if debug logging is enabled, making it difficult to make sense of what's going on. On the other hand, these logs are useful for triaging problems.

To get the best of both worlds, this release adds support for an additional configuration option in dfx.json:

"bitcoin": {
  "enabled": true,
  "nodes": ["127.0.0.1:18444"],
  "log_level": "info" <------- users can now configure the log level
}

By default, a log level of "info" is used, which is relatively quiet. Users can change it to "debug" for more verbose logging.

chore: update Candid UI canister with commit bffa0ae3c416e8aa3c92c33722a6b1cb31d0f1c3

This includes the following changes:

• Fetch did file from canister metadata
• Better flamegraph support
• Fix bigint error for vec nat8 type

feat: dfx will look up the port of the running webserver from .dfx/webserver-port, if present

After dfx start --host 127.0.0.1:0, the dfx webserver will listen on an ephemeral port. It stores the port value in .dfx/webserver-port. dfx will now look for this file, and if a port is contained within, use that port to connect to the dfx webserver.

fix: dfx commands once again work from any subdirectory of a dfx project

Running dfx deploy, dfx canister id, dfx canister call and so forth work as expected
if run from within any subdirectory of a dfx project. Previously, this would create
canister_ids.json or .dfx/local/canister_ids.json within the subdirectory.

feat: Post-installation tasks

You can now add your own custom post-installation/post-deployment tasks to any canister type. The new post-install key for canister objects in dfx.json can be a command or list of commands, similar to the build key of custom canisters, and receives all the same environment variables. For example, to replicate the upload task performed with assets canisters, you might set "post-install": "icx-asset sync $CANISTER_ID dist".

feat: assets are no longer copied from source directories before being uploaded to asset canister

Assets are now uploaded directly from their source directories, rather than first being copied
to an output directory.

If you're using dfx deploy, you won't see any change in functionality. If you're running
dfx canister install --mode=upgrade, changed files in asset source directories will
be detected and uploaded even without an intervening dfx build.

fix: Added src/declarations to .gitignore for new projects

fix: remove deprecated candid path environment variable

The environment variable format CANISTER_CANDID_{name}, used in Rust projects, was deprecated in 0.9.2, to be unified with the variables CANISTER_CANDID_PATH_{name} which are used in other project types. It has now been removed. Note that you will need to update ic-cdk-macros if you use the #[import] macro.

feat: deprecate dfx config for removal

The dfx config command has several issues and is ultimately a poor replacement for jq. The command is being deprecated, and will be removed in a later release; we recommend switching to jq or similar tools (e.g. ConvertTo-Json in PowerShell, to json in nushell, etc.)

feat: Better build scripts for type:custom

Build scripts now always receive a CWD of the DFX project root, instead of wherever dfx was invoked from, and a bare script script.sh can be specified without needing to prefix with ./.

feat: rust, custom, and asset canisters now include candid:service metadata

Motoko canisters already included this metadata.

Also added this metadata to the asset canister wasm, which will cause the next deploy to
install this new version.

feat: Add safeguard to freezing threshold

Some developers mistakenly think that the freezing threshold is measured in cycles, but it is actually measured in seconds. To stop them from accidentally freezing their canisters, setting a freezing threshold above 50M seconds (~1.5 years) now requires a confirmation.

fix: restores assets to webpack devserver

chore: updates webpack dependencies for dfx new project

Resolves an issue where webpack-cli was was breaking when users tried to run npm start in a fresh project. For affected users of 0.10.1, you can resolve this issue manually by running npm install webpack@latest webpack-cli@latest terser-webpack-plugin@latest.

feat: Support for new ledger notify function

Ledger 7424ea8 deprecates the existing notify function with a switch parameter between creating and topping up a canister, and introduces two
functions for doing the same. This should mostly be invisible to users, except that previously, if dfx ledger create-canister or dfx ledger top-up
failed, you would call dfx ledger notify after correcting the issue. In order to support the change, this command has been changed to two subcommands:
dfx ledger notify create-canister and dfx ledger notify top-up.

feat: --from-subaccount

Previously, the ledger commands assumed all transfers were made from the default subaccount for the identity principal. This feature adds a --from-subaccount flag to dfx ledger transfer, dfx ledger create-canister, and dfx ledger top-up, to enable making transfers from a selected subaccount. A --subaccount flag is also added to dfx ledger balance for convenience. Subaccounts are expected as 64-character hex-strings (i.e. 32 bytes).

feat: cargo audit when building rust canisters

When a canister with type rust is built and cargo-audit is installed, dfx will now check for vulnerabilities in the dependencies. If a vulnerability is found, dfx will recommend that the user update to a version without known vulnerabilities.

fix: Freezing Threshold now documented

Calls made to retrieve the help output for canister update-settings was missing the freezing-threshold parameter.

chore: warnings and errors are more visible

WARN and ERROR messages are now clearly labelled as such, and the labels are colored accordingly.
This is now included when running dfx canister update-settings -h.

fix: dfx schema does not require valid dfx.json

There is no real reason for dfx schema to not work when a broken dfx.json is in the current folder - this is actually a very common scenario when dfx schema gets used.

fix: canister call uses candid file if canister type cannot be determined

The candid file specified in the field canisters.<canister name>.candid of dfx.json, or if that not exists canisters.<canister name>.remote.candid, is now used when running dfx canister call, even when dfx fails to determine the canister type.

fix: btc/canister http adapter socket not found by replica after restart

After running dfx start --enable-bitcoin twice in a row (stopping dfx in between), the second
launched replica would fail to connect to the btc adapter. This is because ic-starter
does not write a new configuration file if one already exists, so the configuration file
used by the replica referred to one socket path, while dfx passed a different socket path
to the btc adapter.

Now dfx reuses the previously-used unix domain socket path, for both the btc adapter
and for the canister http adapter.

fix: dfx stop now waits until dfx and any child processes exit

Previously, dfx stop would send the TERM signal to the running dfx and its child processes,
and then exit immediately.

This avoids interference between a dfx process performing cleanup at shutdown and
a dfx process that is starting.

fix: dfx ping no longer creates a default identity

dfx ping now uses the anonymous identity, and no longer requires dfx.json to be present.

fix: Initialize replica with bitcoin regtest flag

When the bitcoin feature is enabled, dfx was launching the replica with the "bitcoin_testnet" feature.
The correct feature to use is "bitcoin_regtest".

dfx bootstrap now looks up the port of the local replica

dfx replica writes the port of the running replica to one of these locations:

• .dfx/replica-configuration/replica-1.port
• .dfx/ic-ref.port

dfx bootstrap will now use this port value, so it's no longer necessary to edit dfx.json after running dfx replica.

feat: dfx.json local network settings can be set on the local network, rather than defaults

In dfx.json, the bootstrap, ...

0.10.1

DFX

fix: Webpack config no longer uses CopyPlugin

Dfx already points to the asset canister's assets directory, and copying to disk could sometimes
lead to an annoying "too many open files" error.

fix: HSMs are once again supported on Linux

On Linux, dfx 0.10.0 failed any operation with an HSM with the following error:

Error: IO: Dynamic loading not supported

The fix was to once again dynamically-link the Linux build.

feat: error explanation and fixing instructions engine

Dfx is now capable of providing explanations and remediation suggestions for entire categories of errors at a time.
Explanations and suggestions will slowly be added over time.
To see an example of an already existing suggestion, run dfx deploy --network ic while using an identity that has no wallet configured.

chore: add context to errors

Most errors that happen within dfx are now reported in much more detail. No more plain File not found without explanation what even was attempted.

fix: identities with configured wallets are not broken anymore and removed only when using the --drop-wallets flag

When an identity has a configured wallet, dfx no longer breaks the identity without actually removing it.
Instead, if the --drop-wallets flag is specified, it properly removes everything and logs what wallets were linked,
and when the flag is not specified, it does not remove anything.

The behavior for identities without any configured wallets is unchanged.

feat: bitcoin integration: dfx now generates the bitcoin adapter config file

dfx command-line parameters for bitcoin integration:

dfx start   --enable-bitcoin  # use default node 127.0.0.1:18444
dfx start   --enable-bitcoin --bitcoin-node <node>

The above examples also work for dfx replica.

These default to values from dfx.json:

.defaults.bitcoin.nodes
.defaults.bitcoin.enabled

The --bitcoin-node parameter, if specified on the command line, implies --enable-bitcoin.

If --enable-bitcoin or .defaults.bitcoin.enabled is set, then dfx start/replica will launch the ic-btc-adapter process and configure the replica to communicate with it.

feat: print wallet balance in a human readable form #2184

Default behaviour changed for dfx wallet balance, it will now print cycles amount upscaled to trillions.

New flag --precise added to dfx wallet balance. Allows to get exact amount of cycles in wallet (without upscaling).

feat: canister http integration

dfx command-line parameters for canister http requests integration:

dfx start --enable-canister-http
dfx replica --enable-canister-http

This defaults to the following value in dfx.json:

.defaults.canister_http.enabled

fix: specifying ic provider with a trailing slash is recognised correctly

Specifying the network provider as https://ic0.app/ instead of https://ic0.app is now recognised as the real IC network.

Binary cache

Added ic-canister-http-adapter to the binary cache.

Dependencies

Updated agent-rs to 0.17.0

Motoko

Updated Motoko from 0.6.26 to 0.6.28.

Replica

Updated replica to elected commit b90edb9897718730f65e92eb4ff6057b1b25f766.
This incorporates the following executed proposals:

• 61004
• 60222
• 59187
• 58479
• 58376
• 57843
• 57395

icx-proxy

Updated icx-proxy to commit c312760a62b20931431ba45e5b0168ee79ea5cda

• Added gzip and deflate body decoding before certification validation.
• Fixed unzip and streaming bugs
• Added Prometheus metrics endpoint
• Added root and invalid ssl and dns mapping

0.10.0

Overview

The default subnet type is now application for local networks. This means cycles limits will match the values enforced for your canisters on mainnet, and the local replica will track cycle usage for your canisters. You can top up your local canisters with the new dfx ledger fabricate-cycles command.

We've upgraded the cycles wallet to support 128-bit operations. You will need to upgrade it with dfx wallet upgrade and/or dfx wallet --network ic upgrade.

dfx can now store private keys in an encrypted format.

DFX

feat: Use null as default value for opt arguments

Before this, deploying a canister with an opt Foo init argument without specifying an --argument would lead to an error:

$ dfx deploy
Error: Invalid data: Expected arguments but found none.

With this change, this isn't an error anymore, but instead null is passed as a value. In general, if the user does not provide an --argument, and if the init method expects only opt arguments, then dfx will supply null for each argument.

Note in particular that this does not try to match opt arguments for heterogeneous (opt/non-opt) signatures. Note moreover that this only impacts a case that would previously error out, so no existing (working) workflows should be affected.

feat: dfx identity set-wallet now checks that the provided canister is actually a wallet

This check was previously performed on local networks, but not on mainnet.

feat: dfx canister call --candid ...

Allows one to provide the .did file for calls to an arbitrary canister.

feat: Install arbitrary wasm into canisters

You no longer need a DFX project setup with a build task to install an already-built wasm module into a canister ID. The new --wasm <path> flag to dfx canister install will bypass project configuration and install the wasm module at <path>. A DFX project setup is still recommended for general use; this should mostly be used for installing pre-built canisters. Note that DFX will also not perform its usual checks for API/ABI/stable-memory compatibility in this mode.

feat: Support for 128-bit cycle counts

Cycle counts can now exceed the previously set maximum of 2^64. The new limit is 2^128. A new wallet version has been bundled with this release that supports the new cycle count. You will not be able to use this feature with your existing wallets without running dfx wallet upgrade, but old wallets will still work just fine with old cycle counts.

fix: dfx start will once again notice if dfx is already running

dfx will once again display 'dfx is already running' if dfx is already running,
rather than 'Address already in use'.

As a consequence, after dfx start failed to notice that dfx was already running,
it would replace .dfx/pid with an empty file. Later invocations of dfx stop
would display no output and return a successful exit code, but leave dfx running.

fix: dfx canister update-settings works even if the canister id is not known to the project.

This makes the behavior match the usage text of the command:
<CANISTER> Specifies the canister name or id to update. You must specify either canister name/id or the --all option

feat: dfx deploy --upgrade-unchanged or dfx canister install --mode upgrade --upgrade-unchanged

When upgrading a canister, dfx deploy and dfx canister install skip installing the .wasm
if the wasm hash did not change. This avoids a round trip through stable memory for all
assets on every dfx deploy, for example. By passing this argument, dfx will instead
install the wasm even if its hash matches the already-installed wasm.

feat: Introduce DFX_CACHE_ROOT environment variable

A new environment variable, DFX_CACHE_ROOT, has been introduced to allow setting the cache root directory to a different location than the configuration root directory. Previously DFX_CONFIG_ROOT was repurposed for this which only allowed one location to be set for both the cache and configuration root directories.

This is a breaking change since setting DFX_CONFIG_ROOT will no longer set the cache root directory to that location.

fix: Error if nonzero cycles are passed without a wallet proxy

Previously, dfx canister call --with-cycles 1 would silently ignore the --with-cycles argument as the DFX principal has no way to pass cycles and the call must be forwarded through the wallet. Now it will error instead of silently ignoring it. To forward a call through the wallet, use --wallet $(dfx identity get-wallet), or --wallet $(dfx identity --network ic get-wallet) for mainnet.

feat: Configure subnet type of local replica

The local replica sets its parameters according to the subnet type defined in defaults.replica.subnet_type, defaulting to 'application' when none is specified.
This makes it less likely to accidentally hit the 'cycles limit exceeded' error in production. Since the previous default was system, you may see these types errors in development instead.
Possible values for defaults.replica.subnet_type are: "application", "verifiedapplication", "system"

Example how to specify the subnet type:

{
  "defaults": {
    "replica": {
      "subnet_type": "verifiedapplication"
    }
  }
}

feat: Introduce command for local cycles top-up

dfx ledger fabricate-cycles <canister (id)> <optional amount> can be used during local development to create cycles out of thin air and add them to a canister. Instead of supplying a canister name or id it is also possible to use --all to add the cycles to every canister in the current project. When no amount is supplied, the command uses 10T cycles as default. Using this command with --network ic will result in an error.

feat: Private keys can be stored in encrypted format

dfx identity new and dfx identity import now ask you for a password to encrypt the private key (PEM file) when it is stored on disk.
If you decide to use a password, your key will never be written to disk in plain text.
In case you don't want to enter your password all the time and want to take the risk of storing your private key in plain text, you can use the --disable-encryption flag.

The default identity as well as already existing identities will NOT be encrypted. If you want to encrypt an existing identity, use the following commands:

dfx identity export identity_name > identity.pem
# if you have set old_identity_name as the identity that is used by default, switch to a different one
dfx identity use other_identity
dfx identity remove identity_name
dfx identity import identity_name identity.pem

feat: Identity export

If you want to get your identity out of dfx, you can use dfx identity export identityname > exported_identity.pem. But be careful with storing this file as it is not protected with your password.

feat: Identity new/import now has a --force flag

If you want to script identity creation and don't care about overwriting existing identities, you now can use the --force flag for the commands dfx identity new and dfx identity import.

fix: Do not automatically create a wallet on IC

When running dfx deploy --network ic, dfx canister --network ic create, or dfx identity --network ic get-wallet dfx no longer automatically creates a cycles wallet for the user if none is configured. Instead, it will simply report that no wallet was found for that user.

Dfx still creates the wallet automatically when running on a local network, so the typical workflow of dfx start --clean and dfx deploy will still work without having to manually create the wallet.

fix: Identities cannot exist and not at the same time

When something went wrong during identity creation, the identity was not listed as existing.
But when trying to create an identity with that name, it was considered to be already existing.

feat: dfx start and dfx replica can now launch the ic-btc-adapter process

Added command-line parameters:

dfx start   --enable-bitcoin --btc-adapter-config <path>
dfx replica --enable-bitcoin --btc-adapter-config <path>

These default to values from dfx.json:

.defaults.bitcoin.btc_adapter_config
.defaults.bitcoin.enabled

The --btc-adapter-config parameter, if specified on the command line, implies --enable-bitcoin.

If --enable-bitcoin or .defaults.bitcoin.enabled is set, and a btc adapter configuration is specified,
then dfx start/replica will launch the ic-btc-adapter process.

This integration is not yet complete, pending upcoming functionality in ic-starter.

fix: report context of errors

dfx now displays the context of an error in several places where previously the only error
message would be something like "No such file or directory."

chore: updates starter project for Node 18

Webpack dev server now works for Node 18 (and should work for Node 17). A few packages are also upgraded

updating dependencies

Updated to version 0.14.0 of agent-rs

Cycles wallet

• Module hash: bb001d1ebff044ba43c060956859f614963d05c77bd778468fce4de095fe8f92
• dfinity/cycles-wallet@f18e9f5

Replica

Updated replica to elected commit b3788091fbdb8bed7e527d2df4cc5e50312f476c.
This incorporates the following executed proposals:

• 57150
• 54964
• 53702
• 53231
• 53134
• 52627
• [52144](https://dashboard.internetcompu...