Candid: A Common Language for Application Interfaces on the Internet Computer

Introducing Candid, a new interface description language developed for the Internet Computer, which enables hosted code to seamlessly integrate

We developed tools to automatically generate UI and perform random testing based on the service description file.

As the DFINITY Foundation works to restore the internet to its free and open roots by launching the Internet Computer, the world’s first web-speed blockchain network with unbounded computational capacity, enhancing the developer experience and providing more options is a constant focus. The Internet Computer hosts software canisters, an evolution of traditional smart contracts that can scale, which bundle WebAssembly bytecode with pages of memory that the code runs inside. These enable developers to build revolutionary interoperable applications, systems, and internet services that are secure, unstoppable, and make use of blockchain features such as tokenization, which are deployed directly on the internet rather than on proprietary infrastructure.

To support the growth of a universe of reimagined software on a public blockchain where different programs can directly integrate with each other, and services can be easily composed and extended, our languages team developed the Candid interface description language (IDL), which allows those collaboratively building out the Internet Computer ecosystem to connect their code completely seamlessly, even when it is written in different languages, which we are excited to describe in more detail today.

What is Candid?

Candid is an IDL crafted specifically for the Internet Computer, providing a common language for application interfaces to facilitate communication between services that are written in different programming languages.

One of the key benefits of Candid is that it is language-agnostic, enabling interoperability between services and front ends that are written in different programming languages, such as Motoko, Rust, and JavaScript, among others. It allows developers to safely and seamlessly build services that rely on each other without worrying about interface upgrades on external services.

Through Candid, we sought to…

• Provide interface and data description: Developers using Candid have the ability to describe the public interface of a service, typically in the form of a program deployed as a canister. As a developer, you can call external services running on the Internet Computer as asynchronous function calls.
• Support interface evolution in a principled manner: Candid supports the evolution of service interfaces by precisely specifying the changes that can be made without breaking existing clients — meaning, for example, that you can safely add new optional parameters to a service without losing compatibility for existing clients.
• Support Internet Computer features: Candid is particularly well-suited for developing applications for the Internet Computer.

Candid was partly inspired by similar IDLs and data definition languages (DDLs), such as Protobuf, Thrift, and JSON. But Candid provides a unique combination of features that aren’t found in these other technologies:

• Candid is a full interface description language, not just a data description language.
• Candid implementations can map a Candid value directly to types and values of the host language.
• Candid is inherently a higher-order language that allows message arguments to include references to other services and methods.
• Candid has built-in support for specific Internet Computer features, such as the query annotation.
• Candid defines rules for how services and their interface can be upgraded in a sound and compositional way, including higher-order uses.

How do I use Candid?

Candid’s primary purpose is to connect programs that are written in some host language — e.g., Motoko, Rust, or JavaScript — with the Internet Computer. In most cases, you don’t have to deal with your program data as Candid values. Instead, you work with a host language like JavaScript using familiar JavaScript values, and then rely on Candid to transparently transport those values to a canister written in Rust or Motoko. The canister receives the values and treats them as native Rust or Motoko values.

There are some cases where it is useful to see the Candid values directly in a human-readable form — for example, when logging, debugging, or interacting with a service on the command-line. In these scenarios, you can use the textual presentation for Candid values.

Candid is a strongly typed system with a set of types that canonically cover most uses (to see a list, refer to our SDK page). The philosophy behind this set of types is that they are sufficient to describe the structure of data so that information can be encoded, passed around, and decoded, but they do not attempt to describe semantic constraints beyond that. Candid supports this set of types to allow a natural mapping of data types based on reasonable, canonical choices that are suitable for each host language, whether you’re writing your code in Motoko, Rust, JavaScript, or some other language.

Candid types can be used to describe a service via a Candid service description file (.did file), which can either be manually written or generated from a service implementation. If you write a canister in Motoko, for example, the compiler automatically generates a Candid description when you compile the program. In other languages, like Rust, you will have to write the Candid interface description manually. With the help of types, we developed tools to automatically generate UI and perform random testing based on the service description file.

Candid is also useful for service upgrades. Services evolve over time; they gain new methods, and existing methods return more data, or expect additional arguments. Usually, service authors want to do that without breaking existing clients. Candid helps services safely evolve by defining precise subtyping rules (formalized in Coq!) that indicate when the new service type will still be able to communicate with all other parties that are using the previous interface description.

Interested in learning more? Here are some Candid-related materials to get you started…

Candid tutorials and resources

• Candid explainer video: You can find a video tutorial on how to use Candid here.
• Candid documentation and tutorials: You can refer to our documentation on Candid on our SDK site here.
• Candid Crate: The Candid crate is a serialization/deserialization library that can be used to create Candid services or clients in Rust.
• Internet Computer agent library for JavaScript: This agent includes support for Candid.
• Community-supported libraries for Candid: Libraries currently exist for Haskell, Elm, AssemblyScript, and Kotlin.
• Candid UI: This canister generates a front-end UI for any canister running on the Internet Computer, enabling developers to interact with canisters on the web (as opposed to the terminal), as well as providing debugging capabilities.