16 June 2021 - SDK/Motoko Documentation

Highlights of what’s new in 0.7.2

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

The most significant changes in this release include the following:

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

• The availability of new application subnets enable you to now deploy projects on the Internet Computer.

• The default cycle balance for new cycles wallet canisters is now set to 3T (three trillion) cycles on application subnets and 4T (four trillion) on verified application subnets.

4 June 2021 - SDK/Motoko Documentation

Highlights of what’s new in 0.7.1

The 0.7.1 release includes new features and fixes to DFX commands, Motoko, the Motoko base library, and Candid.

New features and capabilities

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

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

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

  dfx canister send message.json --status
  

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

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

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

  dfx canister deposit-cycles 125000000000 hello_world
  

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

  dfx canister uninstall-code hello_world
  

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

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

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

  dfx start -no-artificial-delay
  

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

Breaking change

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

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

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

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

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

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

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

Issues fixed in this release

This section covers any reported issues that have been fixed in this release.

• Allow consistent use of canisters names or identifiers in dfx canister commands.

  Previously, dfx canister commands were inconsistent about whether you could specify a canister using a canister name or a canister identifier.
  With this change, all dfx canister commands now accept either a canister name as specified in the local dfx.json configuration file or a valid canister identifier as listed in the canister_ids.json file.

27 May 2021 SDK/Motoko Documentation

Highlights of what's new in 0.7.0

18 March 2021 - SDK/Motoko Documentation

Highlights of what’s new in 0.6.26

The 0.6.26 release primarily consists of changes to support new features that are not yet complete, including fixes and updates to DFX commands, Motoko, the Motoko base library, and Candid.

New features and capabilities

The most significant new feature included in this release is the publication of the Internet Computer Interface Specification.

The Internet Computer Interface Specification details many technical properties that describe the lower-level interfaces for interacting with the Internet Computer. For example, the Internet Computer Interface Specification describes the HTTPS endpoints that are exposed to handle incoming requests and how low-level bindings enable canisters to interact with system components.

If you use existing tools—like the DFINITY Canister SDK or Canister Development Kit for Rust—to work with canisters, these tools interact with lower-level interfaces described in the Internet Computer Interface Specification on your behalf. If you want to create your own tooling for working with canisters, however, the Internet Computer Interface Specification includes the technical details you need to understand how the Internet Computer external interfaces work.

If you are interested in expanding the Internet Computer ecosystem, you’ll find information in the Internet Computer Interface Specification to help you in developing the following types of projects:

• Building front-end agents for user-facing interaction in any programming language, including popular languages such as Python, Golang, or C.

• Building back-end Canister Development Kits (CDKs) in any language that can compile down to WebAssembly bytecode.

• Building local development tools such as command line interfaces or Internet Computer emulators and debuggers.

• Implementing features and enhancements to improve the developer experience for deploying and managing canisters running remotely on the network.

Issues fixed in this release

This section covers any reported issues that have been fixed in this release.

This release fixes an issue with memory allocation in the default cycles wallet that caused an error after creating and deploying canisters. If you encountered this issue, you might have seen an error message similar to the following:

The Replica returned an error: code 5, message: "Canister 6dtaa-vaaaa-aaaab-aaipa-cai exceeded its allowed memory allocation"

This release updates the default cycles wallet to provide better handling of unused memory and how memory is allocated when creating and deploying canisters.

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.

Only the default wallet canister principal can perform canister management tasks

The introduction of the cycles wallet canister changes the default principal used to perform key canister management tasks, such as registering a new canister identifier and deploying a new canister on the Internet Computer. This change introduces some inconsistencies in the identity used to perform certain tasks and can result in potential access control issues.

You should note that none of the tutorials have been updated to reflect this specific change in behavior yet and the current version of the Add access control with identities tutorial is known to be invalid for this release. If you want to experiment with access control using the Add access control with identities tutorial, you should install the DFINITY Canister SDK version 0.6.23 (or older).

Incompatibility when using the JavaScript agent (@dfinity/agent) directly in a project

If you access the @dfinity/agent JavaScript agent directly in a project—that is, without going through the bootstrap server—you will not be able to import the bls certification scheme with the agent-js release.
If your application uses the JavaScript agent directly, you should use the latest beta version (@dfinity/agent@0.6.26-beta.1) of the agent instead of the published version.

12 March 2021 - SDK/Motoko Documentation

Highlights of what’s new in 0.6.25

The 0.6.25 release primarily consists of changes to support new features that are not yet complete, including fixes and updates to DFX commands, Motoko, the Motoko base library, and Candid.

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

• This release introduces environment variables for specifying canister identifiers.
  You can now use the CANISTER_ID_{canister.name} and CANISTER_CANDID_PATH_{canister.name} environment variables to reference canister identifiers and the path to the canister Candid description (.did file) during the build process. These environment variables enable you to construct the JavaScript for front-end assets using the correct canister identifiers.

  The environment variables are intended to replace the import syntax for dependent canisters described in Entry and output configuration which is being deprecated and will be removed in a future release.

• A new dfx identity import subcommand enables you to import a security certificate to create an identity.

For example, if you use a hardware wallet or a key generation utility to generate a PEM file for authenticating your identity, you can now import that PEM file into dfx to create a new identity. After importing the PEM file, you can run the dfx identity use command to set that identity as your default context.

For example, to import the my-external-id.pem and create an identity named alice, you would run the following command:

dfx identity import alice my-external-id.pem

After running this command, you would run the following command to begin using the new identity:

dfx identity use alice

5 March 2021 - SDK/Motoko Documentation

Highlights of what's new in 0.6.24

The 0.6.24 release primarily consists of changes to support new features that are not yet complete, including fixes and updates to DFX commands, Motoko, the Motoko base library, and Candid.

DFX

• With this release, you must have a wallet canister with cycles to deploy or manage applications on the Internet Computer.

  For local development, dfx automatically creates a wallet for you when you run dfx canister create or dfx deploy commands within each project.

  Wallets are also created automatically if you deploy to the {IC} using the ic network alias before the network is upgraded to require a cycle balance.

  To deploy and manage applications on the main {IC} network, you must provide the {company-id} Foundation with a principal associated with your user identity and receive a wallet canister identifier in return.

  To deploy applications on the {IC} network:

  1. Download and install the {sdk-short-name}.
  2. Run the dfx identity get-principal command to create your default identity and principal:

  dfx identity get-principal
  

  1. Running the command displays output similar to the following:

  Creating the "default" identity.
    - generating new key at /Users/pubs/.config/dfx/identity/default/identity.pem
  Created the "default" identity.
  wre5u-xietp-k5jz4-sdaaz-g3x4l-zjzxa-lxnly-fp2mk-j3j77-25qat-pqe
  

  1. Submit the principal to get your wallet canister identifier.
  2. Run the dfx identity set-wallet command to associate your wallet canister identifier with your default identity.

  dfx identity set-wallet <wallet-canister-identifier>
  

  1. Open the wallet application in a web browser by navigating to the canister with a URL similar to the following:

  https://<WALLET-CANISTER-ID>.ic0.app
  

• A new command-line option enables you to specify the number of initial cycles to transfer to a newly-created canister.

  The dfx canister create and dfx deploy commands now support a new --with-cycles <number-of-cycles> option.
  This option allows you to specify the initial cycle balance of a canister created by your wallet.

  You can use this option when running the Internet Computer network locally or connected to the current ic network (Sodium) for testing purposes. However, because wallets and cycle balances are not currently used for canisters you create while connected to the current ic network (Sodium), the --with-cycles option does not affect any canister operations.

  For example, you might run the following dfx canister create command to initialize 8000000000000 cycles for all of the canisters in a project:

  dfx canister create --with-cycles 8000000000 --all
  

  If using +dfx deploy+, you might run the following command to initialize +8000000000+ cycles for the +backend+ canister in a project:

  dfx deploy --with-cycles 8000000000000 backend
  

  NOTE: You must have a wallet canister with a cycles balance on the network where you want to create or deploy additional canisters.

• You can now use the new dfx toolchain command to manage the version of the dfx command-line interface you are using for your projects.
  The dfx toolchain command enables you to install, uninstall, and set the default version of dfx that you want to use.
  You can specify the version by the complete version number, the major and minor version number, or a tag name.
  For example:

  dfx toolchain install 0.6.24 # complete version
  dfx toolchain install 0.6    # major minor version
  dfx toolchain install latest # tag name
  

• A new deploy-wallet subcommand enables you to specify the canister identifier for your cycles wallet WebAssembly module (WASM).

  For example, if you have an account with a third party exchange provider and receive a wallet canister identifier, you can run a command similar to the following to deploy the wallet and uses its cycles for development:

  dfx identity deploy-wallet <canister-identifier>
  

  NOTE: The deploy-wallet feature is intended for a future use case. The command is only applicable if you received the wallet canister identifier as part of a transfer operation that converted ICP tokens to cycles.
  In addition, the deploy-wallet subcommand is not intended for use with the current version of the Internet Computer running locally or on the remote network.

Candid

• New Candid documentation for developers provides type mapping information for Rust and JavaScript.

• Candid now supports additional native Rust types and Typescript.

• For additional information, see the Candid changelog.

Motoko

• The Motoko compiler (moc) now accepts the -Werror flag to turn warnings into errors.

• The language server now returns documentation comments alongside
  completions and hover notifications.

• Motoko supports wrapping arithmetic and bit-wise operations on NatN and IntN.

  The conventional arithmetic operators on NatN and IntN trap on overflow.
  If wrap-around semantics is desired, the operators +%, -%, *% and **% can be used. The corresponding assignment operators (+%= etc.) are also available.

  Likewise, the bit fiddling operators (&, |, ^, <<, >>, <<>,<>> etc.) are now also available on NatN and IntN. The right shift operator (>>) is an unsigned right shift on NatN and a signed right shift on IntN; the +>> operator is not available on these types.

  The motivation for this change is to eventually deprecate and remove the
  WordN types.
  Therefore, the wrapping arithmetic operations on WordN are deprecated and their use will print a warning.
  For information about replacing Word types, see link:../language-guide/language-manual{outfilesuffix}#word-types[Word types].

• For values x of type Blob, an iterator over the elements of the blob x.vals() is introduced.
  It works like x.bytes(), but returns the elements as type Nat8.

• The base library documentation tool +mo-doc+ now generates cross-references for types in signatures.
  With this enhancement, when you view a signature like fromIter : I.Iter<Nat> -> List.List<Nat>, you can click I.Iter or List.List to navigate to the appropriate definition.

• Improvements to the type checker and compiler provide better handling for object literals.

19 February 2021 - SDK/Motoko Documentation

Highlights of what's new in 0.6.23

The 0.6.23 release consists of changes to support new features and enhancements that are not yet complete.

The most significant new feature enables you to use a locally-installed +@dfinity/bootstrap+ server.

5 February 2021 - SDK/Motoko Documentation

Highlights of what’s new in 0.6.22

The 0.6.22 release consists of changes to support new features that are not yet complete, including fixes and updates to DFX commands, Motoko, the Motoko base library, and Candid.

The most significant new features and capabilities include updates in the following functional areas:

• DFX
• Sample applications
• Candid
• Motoko

DFX

• The dfx canister call command can now pass a randomly-generated value to a canister method when an argument is required but not provided.

• The dfx canister call command can take canister identifiers for local canisters even if the canister is installed on a remote network.

• The dfx replica command has been fixed so that it does not attempt to write the replica pid to a nonexistent directory.

• The default webpack.config.js file used when you create new projects has been modified to comment out the configuration to enable TypeScript.

  Previously, the webpack.config.js file configured ts-loader to process files with the .js file extension, which could lead to errors. This configuration is now disabled by default and the commented-out configuration only processes .ts, .tsx, and .jsx files through ts-loader.

Sample applications

• There have been updates, improvements, and new sample applications added to the examples repository.

  All of Motoko sample apps in the examples repository have been updated to work with the latest release of the DFINITY Canister SDK.
  There are also new sample apps to illustrate using arrays (Quicksort) and building create/read/update/delete (CRUD) operations for a web application Superheroes.

  The LinkedUp sample application has been updated to work with the latest release of Motoko and the SDK.

Candid

• Candid changelog

Motoko

• The Motoko compiler now reports errors and warnings with an additional error code.

  You can use the error code to look up a more detailed description for a given error by passing the --explain flag with a code to the compiler.

  Note that detailed descriptions are not yet available for most error codes and will be added incrementally in upcoming releases.

28 January 2021 - SDK/Motoko Documentation

Highlights of what’s new in 0.6.21

The 0.6.21 release primarily consists of changes to support new features that are not yet complete, including fixes and updates to DFX commands, Motoko, the Motoko base library, and Candid.

New features and capabilities

The most significant new features and capabilities include updates in the following functional areas:

• DFX
• Candid
• Motoko

DFX

Two new subcommands—get-wallet and set-wallet—have been added to the dfx identity command to support working with wallet canisters.

In a future release, you will be able to use these commands locally for testing purposes. However, the commands are not currently supported on any version of the Internet Computer network available for you to run locally or on the public Internet Computer network.

Candid

Candid changelog

Motoko

The Motoko compiler now reports errors and warnings with an additional error code.

You can use the error code to look up a more detailed description for a given error by passing the --explain flag with a code to the compiler.

Note that detailed descriptions are not yet available for most error codes and will be added incrementally in upcoming releases.

22 January 2021 - SDK/Motoko Documentation

Highlights of what's new in 0.6.20

The 0.6.20 release primarily both user-facing and internal enhancements, including fixes and updates to {proglang}, the {proglang} base library, and Candid.

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

• A new notification message that the DFINITY Canister SDK sends anonymous usage data to DFINITY Stiftung by
  default has been added to dfx commands. The notification message is only displayed once, the first time you run any dfx subcommand.
  For example, the first time you run dfx new to create a new project, the notification is displayed before any other project creation messages.

  The purpose of this notification is to inform you that dfx is configured to collect anonymous information about dfx command activity and errors. Collecting anonymous data is enabled by default in an effort to improve the developer experience based on usage patterns and behavior.

  If you want to prevent the collection of data about dfx usage, you can explicitly opt-out by setting the following environment
  variable:

  DFX_TELEMETRY_DISABLED=1
  

  To find out more about the data collected and what your consent means, see the DFINITY Canister SDK Terms and Conditions.

• The dfx commands that support the --network option have been updated to support URLs when specifying the network value.

  Previously, the --network option required you to specify a network name that matched a network aliases configured in the project's dfx.json file.

Candid

The Candid web interface has been updated to provide easier navigation and a better user experience.
The updates to the Candid web interface include the following new features and improvements:

• A new Console drawer provides quick access to method output and a list of all available methods as links for fast navigation.
• Canister methods and their related form elements are more clearly separated and annotated.
• Method output is selectable and easier to toggle between text, UI, and JSON formats.
• The layout is now responsive to provide an optimized display when viewing service using mobile devices or other media.

Motoko

• The Motoko base documentation examples are now executable in the browser.

• The Motoko compiler supports specifying command-line arguments using --args <file> and --args0 <file>.

  The new options enable the compiler to read newline and NUL terminated arguments from a specified file name.