Candid tools
Overview
Candid is an interface description language that can be used by BIG canisters to define the public interface of a service. Candid is language-agnostic and allows for the inter-operation of services and frontends written in different programming languages, including Motoko, Rust, and JavaScript.
Several tools exist to facilitate writing, testing, and interacting with Candid. These tools are described below.
didc
Candid CLI, known as didc, is a multi-purpose CLI tool that can be used to execute several Candid functions, such as checking the validity of a Candid file, generating test suites for different languages, encoding and decoding Candid binary data, and generating random Candid values.
To use didc, first download the prebuilt binary.
The following commands for didc are available:
| Command | Description | Example | Example response |
|---|---|---|---|
didc check <INPUT> [PREVIOUS] | Type check Candid file | didc check test_file.did | Will return parser error if invalid; will return no output if valid. |
didc bind --target <TARGET> <INPUT> | Binding for different languages | didc bind hello.did -t js | export const idlFactory = ({ IDL }) => { return IDL.Service({ 'greet' : IDL.Func([IDL.Text] [IDL.Text], []) });} |
didc test [OPTIONS] <INPUT> | Generate test suites for different languages | didc test -t did test_file.test.did | Will return parser error if invalid; will return no output if valid. |
didc encode [OPTIONS] [ARGS] | Encode Candid value | didc encode '(42, vec {1;2;-3})' | 4449444c016d7c027c002a0301027d |
didc decode [OPTIONS] [BLOB] | Decode Candid binary data | didc decode '4449444c016d7c027c002a0301027d' | |
didc random [OPTIONS] | Generate random Candid values | didc random -t '(int, text)' | (-72_594_379_354_493_140_610_202_928_640_651_761_468, "_J:t7^>") |
didc hash <INPUT> | Compute the hash of a field name | didc hash '(int, text)' | 2392326401 |
didc subtype [OPTIONS] <TY1> <TY2> | Check for subtyping | didc subtype func () -> (t1) | Result is a reference or null |
Candid UI
Candid UI is web-based tool used to interact with a canister's Candid interface. It is automatically generated for every canister with a Candid definition when that canister is deployed. However, it can also be used through the dedicated Candid UI canister running on the mainnet, which allows you to provide a canister ID or upload a .did file to interact with the canister's Candid interface.
You can learn more about the Candid UI in using Candid.
ic-repl
ic-repl is a REPL environment that can be used to communicate with canisters using Candid. The documentation for ic-repl can be found in the GitHub ic-repl repo.
Candid test suite
For additional Candid testing, you can use the Candid test suite, which uses Candid test data to test the implementation for compliance. The test suite covers:
Parsing Candid service descriptions.
Decoding binary Candid data for a given a Candid type and asserting a success or failure.
Parsing textual Candid data for given a Candid type and asserting a success or failure.
Comparing decoded/parsed values, using the host language’s notion of equality.
The Candid test suite currently does not include testing for encoding since the Candid binary format is not canonical. It is encouraged that implementations of this test suite be extended with randomized round-tripping tests (host value → candid → host value) to cover encoding.