Candid Interface Description Language

Candid is an interface description language (IDL) used for developing decentralized applications (dapps) on the Internet Computer (IC). It allows back-end and front-end developers to define the interfaces of canisters, enabling seamless communication between different components.

For developers looking to use Candid in their projects, the documentation is organized into three main areas:

1. Concepts: Understanding the purpose, key features, and how Candid works.
2. How-to Guides: Instructions for performing typical development tasks.
3. Reference: Access to Candid tools, libraries, and a detailed list of supported types.

If you are looking to implement support for a new language or extend existing Candid features, you should refer to the formal Candid specification rather than the developer guides.

Candid provides a set of Rust crates for serialization and deserialization using the Candid interface description language. Depending on your use case, you will interact with different crates:

• candid: The primary crate for most users. It allows seamless conversion between Rust values and Candid in both binary and text formats. If you are developing canisters for the Internet Computer, use this crate.
• candid_parser: Use this if you are building tools that need to parse Candid data or generate bindings.
• ic_principal: Provides the Principal types used on the Internet Computer. These types are exported by the candid crate.
• candid_derive: An internal crate for converting Rust types to Candid. Do not use this directly; instead, use the candid crate which provides the necessary derivation capabilities.

Candid provides several tools for working with the Candid interface description language:

• Didc: A multi-purpose tool that includes the 'DFINITY Interface Description Compiler'. It is the primary CLI for interacting with Candid files.
• Candiff: A tool used to relate Candid values that change over time.
• @dfinity/didc: A JavaScript library that serves as the JavaScript counterpart to the didc tool, designed for use in JavaScript/TypeScript projects.

Several tools are available to work with Candid definitions and canister communication:

• didc: The Candid CLI for interacting with Candid files.
• ui: A Candid UI canister for visual interaction.
• ic-repl: A REPL environment to communicate with canisters using Candid.
• Explain Candid: An online tool to decode and explain Candid messages.
• Candid playground: An online playground that dynamically generates a UI based on your Candid definitions.

The @dfinity/didc package is a multi-purpose Candid tool for JavaScript projects. It allows you to encode Candid text values into hex or blob formats and decode hex or blob values back into Candid text format using an Interface Definition Language (IDL) as a schema.

import { getServiceMethods, encode, decode } from "@dfinity/didc";

Candid is supported across many languages. DFINITY provides official implementations for:

• Rust: A serialization library based on Serde and a compiler for generating bindings.
• Motoko: Compiler support for importing Candid files.
• JavaScript: A library for serializing native JavaScript values and a visitor class for building tools like UIs or random testing.

Community-maintained libraries are also available for Haskell, Elm, Kotlin, AssemblyScript, Java, Dart, C#, C++, and Python.

The didc CLI is a multi-purpose tool for interacting with Candid files and data. It supports type checking, generating language bindings, encoding/decoding binary data, and generating random values.

Available Subcommands:

• check: Type check a Candid file.
• bind: Generate bindings for different languages.
• hash: Compute the hash of a field name.
• encode: Encode a Candid value into binary format.
• decode: Decode Candid binary data into a textual representation.
• assist: Generate textual Candid values via a terminal dialog.
• random: Generate random Candid values.
• subtype: Check for subtyping.

didc <SUBCOMMAND>

Candid is an Interface Description Language (IDL) designed to document, discover, and interact with canisters (also known as services or actors) on the Internet Computer. It provides a language-independent way to specify canister interfaces and the data they exchange, including method names, parameter formats, and result formats.

Key characteristics include:

• Language-independent: Describes interfaces and data exchange formats usable by various programming languages.
• Simple and canonical constructs: Uses C-like constructs and algebraic types (sums, products, exponentials).
• Extensible and backwards-compatible: Designed to grow without breaking existing interfaces.
• Declarative: Can be used as input for binding code generators.
• Machine and Human Readable: Designed to be easily parsed by tools and read by developers.