Candid

Candid is an interface description language (IDL) for interacting with canisters (also known as services or actors) running on the Internet Computer. It provides a language-independent description of canister interfaces and the data they exchange, with type safety and extensibility.

Documentation

• The spec directory contains Candid specifications, including the Candid language specification and a soundness proof.
• The official manual is hosted by dfinity; see ./docs for the source code.
• Roman Kashitsyn's Candid for engineers blog post.
• Joachim Breitner's Candid explainer blog post.

Implementations

Candid supports several different programming languages. This repository contains some of the implementations developed by DFINITY.

• Rust: A serialization library based on Serde, and a compiler for generating bindings for other languages.
• Motoko: Compiler support for importing/export Candid files. Also see the Motoko-Candid type mapping specification.
• JavaScript: We provide a library for serialization of native JavaScript values, and a visitor class for extending Candid for building generic tools such as UI and random testing.

A list of community maintained Candid libraries:

• Haskell
• Elm
• Kotlin
• AssemblyScript
• Java
• Dart
• Motoko
• C#
• C++
• Python

Tools

• didc: Candid CLI. Download prebuilt binary.
• ui: Candid UI canister. See deployed canister on the IC
• ic-repl: A REPL environment to communicate with canisters using Candid
• Explain Candid: An online tool that decodes and explains a given Candid message. (Thanks to Ben Lynn)
• Candid playground: A playground that generates UI dynamically as you type in the Candid definitions. (Thanks to B3Forge)

Tests

We provide a test suite to check Candid implementations for compliance.

Release

This repo ships two kinds of release artifacts, each driven by its own tag.

candid_ui canister wasm

Released on a date-based tag. As the repo contains several targets, it is hard to give a version to the tag, so the tag is always today's date:

• Update CHANGELOG.md and merge the PR into master.
• git tag 2020-04-01 -m "2020-04-01"
• git push origin 2020-04-01

This triggers candid-ui.yml, which builds and uploads candid_ui.wasm to the matching GitHub release.

didc binaries

Released by cargo-dist on a SemVer tag matching the didc crate version in tools/didc/Cargo.toml:

• Bump the didc version and merge the PR into master.
• git tag didc-v0.6.1 -m "didc-v0.6.1"
• git push origin didc-v0.6.1

This triggers didc-release.yml, which builds didc for linux (x86_64, x86_64-musl, arm64) and macOS (x86_64, arm64), and uploads the archives, a shell installer, and checksums to the GitHub release. The build config lives in dist-workspace.toml; regenerate the workflow with dist generate after editing it.

Contribution

See our CONTRIBUTING and CODE OF CONDUCT to get started.