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.18 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.18 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.18

The 0.6.18 release primarily includes internal enhancements, and fixes and updates to Motoko, the Motoko base library, and Candid.

The most significant new features and fixes include the following updates:

  • A fix to dfx upgrade that prevents a main thread panic when Option::unwrap() is called on a None value.

  • A fix to the name of the language service command to restore its compatibility with IDEs.

Motoko

  • New syntax for option types: Option blocks do ? <block> and option checks <exp> !.

    Inside an option block, an option check validates that its operand expression is not null. If it is, the entire option block is aborted and evaluates to null. This simplifies consecutive null handling by avoiding verbose switch expressions.

    For example, the expression do? { f(x!, y!) + z!.a } evaluates to null if either x, y or z is null; otherwise, it takes the options' contents and ultimately returns ?r, where r is the result of the addition.

  • The argument to a do or do ? expression must be a block { ... }, never a simple expression.

Highlights of what’s new in 0.6.17

The 0.6.17 release primarily includes user-visible new features, internal enhancements, and fixes and updates to the version of Motoko and the Motoko base library that are supported.

Some of the changes in the release are not backward-compatible and introduce breaking changes that might require you to update all existing projects or to modify Motoko programs.

The most significant new features and fixes include the following:

  • A new DER-based encoding format is used to generate principals. This change enhances the security, interoperability, and future features that the Internet Computer can support.

    This change enables the Internet Computer to support different types of keys, including keys that are most commonly used for web authentication requests and keys that use cryptographic schemes that are better supported by hardware. The new encoding enables the Internet Computer to distinguish between the different types of keys that the Internet Computer supports.

    This change also requires all principals to be regenerated to use the new encoding. If you have canisters deployed on the Internet Computer network or have canisters that use an existing principal for access control, you might need to do the following:

    1. Upgrade to the latest SDK release.

    2. Update your projects to use the new dfx version.

    3. Update your applications to use the new principal format, if needed, or to pass it programmatically.

    4. Recreate and redeploy your canisters.

    If your canisters are deployed on the Internet Computer Developer Network (Sodium), you can use the updated canisters that use the new principal for a limited period of time without submitting the new principal or receiving an updated wallet canister.

  • To improve security, performance, and flexibility, there’s a 2MB restriction of the size of update messages. In most cases, this restriction should not prevent you from building and deploying applications to run on the Internet Computer. However, if you find this limitation hinders your ability to design and deploy canisters, contact DFINITY support with details about your use case and for help resolving the issue.

  • You can use an environment variable to configure the root directory for storing the .cache and .config subdirectories for dfx.

    By default, the .cache and .config directories are located in the home directory for your development environment. For example, on macOS the default location is in the /Users/<YOUR-USER-NAME> directory. You can now use the DFX_CONFIG_ROOT environment variable to specify a different location for these directories.

  • Error handling has been improved.

Motoko and Candid updates

The 0.6.18 release includes changes to the version of Motoko, the motoko-base library, and Candid included with the DFINITY Canister SDK. This version of Motoko includes syntax changes that might require you to update existing programs.

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

  • Simple object literals of the form {a = foo(); b = bar()} no longer bind to field names locally. This change enables you to write expressions like this:

    func foo(x : Nat) { return {x = x} }.

    However, this new syntax breaks short-hand expressions such as:

    `+{a = 1; b = a + 1}+`

    Short-hand expressions like the one above must now be written differently for your program to compile. For example, you might modify the expression to use an auxiliary declaration like this:

    let a = 1; {a = a; b = a + 1}

    Alternatively, you could modify the program to use long form object syntax like this:

    object {public let a = 1; public let b = a + 1}
  • Free-standing blocks are no longer allowed.

    With this release, blocks are only allowed as sub-expressions of control flow expressions such as if, loop, and case. In all other places, braces are always considered to start an object literal. To use blocks that are not part of control flow expressions, you can use do {<block>} expressions.

    In this release, free-standing blocks that are not part of a control flow expressions display a warning but continue to compile. However, you should update your programs to replace the deprecated syntax to ensure your program continues to compile after the compiler enforces the syntax change.

  • Actor declarations are asynchronous and can only be used in asynchronous contexts.

    The return type of an actor class, if specified, must be an async actor type. To support actor declaration, the top-level context of an interpreted program is an asynchronous context, allowing implicit and explicit await expressions.

    This change mostly affects interpreted programs and compiled programs with explicit actor class return types.

  • Strict checking of utf8 strings for improved Candid compliance.

  • More liberal parsing of leb128-encoded numbers

  • New Random library added to motoko-base.

  • Candid includes the ability to extend records with optional fields in a backward-compatible way.

  • Injecting a value into an option type (? <exp>) no longer requires heap allocation in most cases. This removes the memory-tax of using iterators.

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.14

The 0.6.14 release primarily includes internal enhancements and fixes and updates to the version of Motoko and the Motoko base library that are supported.

There are no user-visible new features in this release.

Highlights of what’s new in 0.6.13

The 0.6.13 release primarily includes internal enhancements and fixes and updates to the version of Motoko and the Motoko base library that are supported.

The only user-visible new feature in this release is the ability to set the default compute and memory allocation settings for a project using the dfx.json configuration file. Previously, you could only set the compute allocation and memory allocation by specifying command-line options when running the dfx canister install command. Note that, although this release includes support for specifying the default compute and memory allocation settings in the dfx.json file, these keys are not exposed in the dfx.json template by default.

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) };

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.

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 requires 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.18 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.18 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.18 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.