Developer Release Notes

The DFINITY Canister Software Development Kit (SDK) enables developers to develop applications for the Internet Computer using the Motoko programing language. Motoko is a new programming language optimized for creating tamper-proof software and open internet services that will be hosted on the Internet Computer.

The DFINITY Canister SDK provides everything you need to perform the following key tasks:

  • Author canisters in Motoko and compile them to WebAssembly.

  • Run Internet Computer replica processes locally on your development computer.

  • Deploy compiled programs as standalone canisters and interact with the canisters using a command-line interface.

This 0.6.12 version of the DFINITY Canister Software Development Kit (SDK) is an interim update of the Internet Computer Developer Network available for application testing, demonstration, and exploration. As part of our commitment to continuous improvement and iterative development focused on addressing developer feedback, this version includes numerous fixes and enhancements.

Note that DFINITY Canister Software Development Kit (SDK) and Motoko programming language releases are intended to introduce you to building applications that run on the Internet Computer. This 0.6.12 version of the software and programming language should not be used for developing production applications at this time.

Highlights of what’s new in 0.6.12

The 0.6.12 release includes both user-visible new features and internal enhancements and fixes. The most significant new features and fixes include the following:

  • You can now access the Internet Computer network running remotely without user name and password credentials using the new ic network alias.

    In previous releases, the network alias tungsten was pre-configured in the project dfx.json file. With authorized credentials, you could then use this network alias to access to the Internet Computer network when running dfx commands by using the --network=tungsten option.

    In this release, the ic network alias is pre-configured in the project dfx.json file to replace the tungsten alias. In addition, you are no longer required to provide a user name and password as credentials to authenticate your identity. Instead, you can access the Internet Computer network when running dfx commands simply by using the new ic network alias. For example, to register, build, and deploy an application on the Internet Computer, you can run the following command:

    dfx deploy --network=ic

    Note that the ic network alias is a reserved alias. Although you can add other network providers to your dfx.json file, you cannot use the ic alias for those providers. You can, however, use variations on the reserved name such as ic-pubs or ic-examplenet.

  • Error and status messages are decoded and displayed as human-readable text.

    Previously, some agent and HTTP error and status messages were returned in an encoded format. With this release, these agent and HTTP status messages are properly decoded and displayed as human-readable plain text.

  • This release of Motoko improves stability of `Blob` and Text iterators when garbage collection happens.

  • This release of Motoko fixes some erroneous-reported type errors related to using break in the context of an unconditional loop.

    For example, Motoko supports the following to break out of a loop without type errors:

    label l : Int loop { break l(42) };

For information about breaking changes that were introduced in previous releases, see Breaking changes.

For information about known issues that were introduced in previous releases, see Known issues and limitations.

Highlights of what’s new in 0.6.11

The 0.6.11 release includes both user-visible new features and internal enhancements and fixes. The most significant new features and capabilities include the following:

  • You can now specify arguments on the command-line when you deploy a single canister using an actor class with the dfx deploy command.

  • Improved handling of SIGINT and SIGTERM events ensures that Ctrl-C can now reliably shut down the Internet Computer network replica process when running the Internet Computer locally.

  • Enable the dfx start and dfx bootstrap commands to start the Internet Computer using a randomly-selected webserver port.

    To use a randomly-selected port, you can specify 0 as the port when running dfx start or dfx bootstrap commands. For example:

    dfx start --host 192.168.47.1:0
    dfx bootstrap --port 0
  • The dfx start command now supports specifying the --host option using the IPv6 address format.

For information about breaking changes that were introduced in previous releases, see Breaking changes.

For information about known issues that were introduced in previous releases, see Known issues and limitations.

Highlights of what’s new in 0.6.10

The 0.6.10 release includes both user-visible new features and internal enhancements and fixes. The most significant new features and capabilities include the following:

  • You can run the new dfx identity get-principal command to return the principal associated with the current identity.

    Note that you must be able to provide a principal identifier for either the default or a specific identity to deploy or manage applications on the external Internet Computer network.

    For more information about getting access to the Internet Computer, see Sodium Developer Network onboarding.

  • A new dfx canister set-controller command enables you to specify the identity to use as the new controller for a specified canister.

    When you specify a controller identity, that identity has special rights to manage the canister it controls. For example, only the controlling identity can be used to install, upgrade, or delete the canister under its control.

Highlights of what’s new in 0.6.9

The 0.6.9 release includes the following new features and capabilities:

  • You can now register, build, and deploy applications with a single command.

    This release introduces a simplified developer workflow using the the dfx deploy command. You can use this command to replace running the following commands as separate steps:

    dfx canister create --all
    dfx build
    dfx canister install -all

    For a preview of how to use the simplified developer workflow, see Developer Workflow Preview.

  • You can now specify arguments on the command-line when you deploy a single canister using an actor class with the dfx canister install command.

    For example, you might use the following command to add the self Text argument when deploying the canister named profile_map locally.

    dfx canister install profile_map '("self")'

    Note that you specify the argument you want to pass using the Candid interface description format.

  • A new --memory allocation command-line option enables you to specify a memory allocation when deploying a canister.

  • The dfx identity new command has been enhanced to display a confirmation message when adding a new identify is successful.

Motoko updates

Key updates for Motoko include backend support for the following features and changes:

  • Preliminary support for importing and exporting actor classes and for dynamic canister installation.

  • Improved error handling for actor classes and input/output exceptions.

  • The Motoko compiler no longer supports arbitrary declarations preceding the main actor or an actor class. Only import declarations can be used as leading declarations for programs that define an actor or an actor class.

    As a recommended workaround for this change, you can:

    • Move the declarations that preceded the main actor into the actor’s body.

    • Move the declarations into a new, imported module, referenced from the main actor.

    • Use a combination of these strategies.

    For example, if you have a code snippet like this:

    type State = { #red; #orange; #green }
    var state : State = #red;
    actor TrafficLight {
      ...
    }

    You can modify it like this:

    import Types = "./types";
    actor TrafficLight {
      var state : Types.State = #red;
      ...
    }

Highlights of what’s new in 0.6.7

The 0.6.7 release includes the following new features and capabilities:

  • The dfx build command now supports building a specific canister, in addition to building all canisters.

    For example, you can compile the code for a back-end canister without building the canister used for your project’s front-end assets.

    Because of this change to the dfx build command, the --skip-frontend option is no longer needed and has been removed.

  • There are several new dfx identity commands that enable you to create, manage, and switch between different user identities when communicating with the Internet Computer network.

    You can also use a new --identity command-line option to set a specific user context when running dfx commands.

    This new support for multiple identities enables you to test role-based access control for your programs.

  • Updates to the Candid argument parser in dfx canister call include the following user-facing features:

    • Support type annotations when parsing Candid values. For example, you can use the following syntax to specify types:

      (42: nat8, vec {1;-3;5} : vec int8)
    • Support for pretty-print decoded Candid values:

      --output pp is the default and prints the value in multiple lines.

      --output idl prints the value in a single line.

    • Support for float e notation.

    • Support for Rust-like parsing errors.

  • Key updates for Motoko include the following:

    • Support for polymorphic equality that enables the == and != operators to work on all shareable types.

    • Improvements to catch clashing function and class declarations.

    • Language support to enable canisters to take installation arguments. An actor class defines a canister that takes an argument on installation.

    • Optimized backend handling for Bool data types.

Highlights of what’s new in 0.6.6

The 0.6.6 release features several new commands for managing canisters. The release include the following new commands for managing canister operations and the canister lifecycle:

  • The dfx canister status command enables you to check whether all canisters or a specific canister in a project are currently running.

  • The dfx canister stop command enables you to stop all canisters or a specific canister in a project to prevent canisters from receiving new requests.

  • The dfx canister start command enables you to restart all canisters or a specific canister in a project so they can resume receiving new requests.

  • The dfx canister delete command enables you to delete all canisters or a specific canister in a project.

Highlights of what’s new in 0.6.4

The 0.6.4 release primarily included internal improvements that are not user-facing. The only user-facing features and fixes in the 0.6.4 release are the following:

  • A new Reserved type has been added to the JavaScript agent library.

  • Fixed the timer that is used in the Candid UI when issuing function calls.

Highlights of what’s new in 0.6.3

The 0.6.3 release only included minor fixes and enhancements including the following:

  • The dfx start --clean command has been improved to no longer crash if you run the command in a project that is already in a clean state.

    Without this fix, manually removing the directories the command is intended to delete would result in dfx exiting without restarting the Internet Computer.

  • The parsing logic for the dfx canister call command has been improved to more consistently recognize arguments in Candid format and to return better error messages when argument formats are not recognized.

  • The Welcome page displayed when you create a new project has been updated to reflect the current location of SDK and Motoko documentation.

Highlights of what’s new in 0.6.2

The 0.6.2 release only included one important user-facing change which was also a breaking change that required you to update all existing projects.

Starting with the 0.6.2 release, all canister identifiers are generated using a text-based representation. To work with the 0.6.12 release, therefore, you must update your projects to use the new canister identifier format.

If you are connected to the Internet Computer running locally, do the following in each project directory:

  1. Stop the Internet Computer by running the following command:

    dfx stop
  2. Restart the Internet Computer in a clean state by running the following command:

    dfx start --clean

    This command removes all existing canister state and build output.

  3. Generate new textual canister identifiers by running the following command:

    dfx canister create --all
  4. Redeploy the updated canisters to use the new text-based identifiers by running the following command:

    dfx canister install --all

Highlights of what’s new in 0.6.1

The 0.6.1 release only included the following user-facing changes:

  • An update to the dfx ping command enables you to specify a network name to check the status of a network connection.

  • An update to the user authentication method enables dfx to use the browser’s localStorage for the user’s public and private keys if cookies are not enabled.

  • Motoko programming guidelines are now available as part of the programming language guide on the SDK website.

Highlights of what’s new in 0.6.0

The 0.6.0 release included many new features and enhancements. The following sections describe the key features and enhancements that were introduced in the 0.6.0 release.

SDK

  • You can now look up a canister identifier using the command dfx canister id <canister_name>.

  • The --check flag can be used with the dfx build command to check whether a canister will build before creating or building the canister.

  • Both canister name and canister identifiers are displayed when canisters are created.

  • The dfx.json configuration file has a new field—defaults/build/packtool—to support the Vessel package manager.

  • The dfx.json file supports canister new types—motoko, assets, and custom—to allow different build tools to be used for building canisters:

    • The motoko canister type uses the motoko (moc) compiler to build a canister.

    • The assets canister type uses npm run build by default to build files and uploads them to an asset canister.

    • The custom canister type uses a custom builder that should output WebAssembly (WASM) and Candid (DID) files.

  • The dfx.json file includes network mapping for local and the Internet Computer network. The local network defaults to 127.0.0.1:8000.

Tungsten Developer Network

There are several features that are only applicable for users who have access to the Internet Computer through the Tungsten Developer Network gateway. The following features are only applicable if you are granted access to the Internet Computer through the Tungsten Developer Network gateway:

  • User name and password credentials enable HTTP authentication for onboarded users.

  • The tungsten network alias is included as a network in the dfx.json files.

  • You can use the dfx ping command to ping the Internet Computer network and request its status.

  • You can use the --network <network> command-line option to build and deploy canisters on the on the Internet Computer network you specify.

  • A change to the formatting for the canister identifiers you use to access applications deployed on the Internet Computer using a web browser.

Motoko

  • The motoko-base repository is now open source. You can use the Vessel package manager to download the latest base libraries directly from the master branch of the motoko-base repository.

  • Stable variable support.

  • The mo-doc command-line utility enables you to generate documentation directly from Motoko comments.

  • Better support for Char and Text modules.

  • Error module for rejecting messages.

  • Buf module renamed to Buffer.

Breaking changes

In addition to the change described in Highlights of what’s new, the 0.6.12 release includes the following changes that might require updates to existing programs:

  • If a Motoko library contains a single actor class, it is imported as a module, which provides access to both the class type and the class constructor function as module components. This change restores the invariant that imported libraries are modules.

  • The Motoko compiler no longer supports arbitrary declarations preceding the main actor or an actor class.

  • The command dfx new now creates a separate assets canister by default. Programs built with earlier versions of the SDK should be converted to this new format.

  • You must now register canister identifiers using the dfx canister create command before building and deploying.

  • The dfx canister call will consult the Candid file for method types. You no longer need to use --type string or --type number to specify the argument type. These flags have been deprecated.

Issues fixed in this release

This section covers the issues fixed in this release. The 0.6.12 release includes internal fixes and improvements to the Candid user interface, the interface description library, and some refactoring of dfx commands.

  • Certification validation error fixed on Linux and NixOS.

  • dfx stop now finds and kills all dfx start and dfx replica processes.

  • Allow lowercase hex in canister identifiers.

  • Allow installation without sudo when possible.

  • Install script issues resolved for Ubuntu and Mac.

  • Check added to forbid starting a web server with a forwarded port.

  • Cache directory management and error messages.

  • Improved error messages for HTTP server errors.

Known issues and limitations

This section covers any known issues or limitations that might affect how you work with the DFINITY Canister SDK in specific environments or scenarios. If there are workarounds to any of the issues described in this section, you can find them in the Troubleshooting section.

  • Creating a new project displays errors or warnings.

    By default, creating a new project installs node dependencies to support building a front-end for your project.

    Depending on your environment, the installation of node dependencies might display errors or warnings generated by the npm package manager. For example, you might see errors or warnings similar to the following on macOS:

    gyp ERR! configure error
    gyp ERR! stack Error: `gyp` failed with exit code: 1
    gyp ERR! stack     at ChildProcess.onCpExit (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:351:16)
    gyp ERR! stack     at ChildProcess.emit (events.js:321:20)
    gyp ERR! stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:275:12)
    gyp ERR! System Darwin 19.6.0
    gyp ERR! command "/usr/local/Cellar/node/13.7.0/bin/node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
    gyp ERR! cwd /Users/pubs/hello/node_modules/watchpack-chokidar2/node_modules/fsevents
    gyp ERR! node -v v13.7.0
    gyp ERR! node-gyp -v v5.0.5
    ⠴ Installing node dependencies...
    npm WARN notsup Unsupported engine for [email protected]: wanted: {"node":"<8.10.0"} (current: {"node":"13.7.0","npm":"6.13.6"})
    npm WARN notsup Not compatible with your version of node/npm: [email protected]
    npm WARN [email protected] No repository field.
    npm WARN [email protected] No license field.

    The errors and warnings issued by the npm package manager do not prevent you from successfully creating a new project and, in most cases, can be safely ignored.

Additional questions and feedback

Check out Troubleshooting for additional information about common issues and troubleshooting tips. For technical support, send email to DFINITY Support.