Candid
- text
- blob
- nat
- nat8
- nat16
- nat32
- nat64
- int
- int8
- int16
- int32
- int64
- float32
- float64
- bool
- null
- vec
- opt
- record
- variant
- func
- service
- principal
- reserved
- empty
Candid is an interface description language created by DFINITY. It can be used to define interfaces between services (canisters), allowing canisters and clients written in various languages to easily interact with each other. This interaction occurs through the serialization/encoding and deserialization/decoding of runtime values to and from Candid bytes.
Azle performs automatic encoding and decoding of
JavaScript values to and from Candid bytes
through the use of various
CandidType
objects. For example,
CandidType
objects are used when
defining the parameter and return types of your
query and update methods. They are also used to
define the keys and values of a
StableBTreeMap
.
It's important to note that the
CandidType
objects decode Candid
bytes into specific JavaScript runtime data
structures that may differ in behavior from the
description of the actual Candid type. For
example, a float32
Candid type is a
JavaScript Number, a nat64
is a
JavaScript BigInt, and an int
is also a
JavaScript BigInt.
Keep this in mind as it may result in unexpected
behavior. Each CandidType
object
and its equivalent JavaScript runtime value is
explained in more detail in
The Azle Book Candid reference.
A more canonical reference of all Candid types available on the Internet Computer (IC) can be found here.
The following is a simple example showing how to
import and use many of the
CandidType
objects available in
Azle:
import {
blob,
bool,
Canister,
float32,
float64,
Func,
int,
int16,
int32,
int64,
int8,
nat,
nat16,
nat32,
nat64,
nat8,
None,
Null,
Opt,
Principal,
query,
Record,
Recursive,
text,
update,
Variant,
Vec
} from 'azle/experimental';
const MyCanister = Canister({
query: query([], bool),
update: update([], text)
});
const Candid = Record({
text: text,
blob: blob,
nat: nat,
nat64: nat64,
nat32: nat32,
nat16: nat16,
nat8: nat8,
int: int,
int64: int64,
int32: int32,
int16: int16,
int8: int8,
float64: float64,
float32: float32,
bool: bool,
null: Null,
vec: Vec(text),
opt: Opt(nat),
record: Record({
firstName: text,
lastName: text,
age: nat8
}),
variant: Variant({
Tag1: Null,
Tag2: Null,
Tag3: int
}),
func: Recursive(() => Func([], Candid, 'query')),
canister: Canister({
query: query([], bool),
update: update([], text)
}),
principal: Principal
});
export default Canister({
candidTypes: query([], Candid, () => {
return {
text: 'text',
blob: Uint8Array.from([]),
nat: 340_282_366_920_938_463_463_374_607_431_768_211_455n,
nat64: 18_446_744_073_709_551_615n,
nat32: 4_294_967_295,
nat16: 65_535,
nat8: 255,
int: 170_141_183_460_469_231_731_687_303_715_884_105_727n,
int64: 9_223_372_036_854_775_807n,
int32: 2_147_483_647,
int16: 32_767,
int8: 127,
float64: Math.E,
float32: Math.PI,
bool: true,
null: null,
vec: ['has one element'],
opt: None,
record: {
firstName: 'John',
lastName: 'Doe',
age: 35
},
variant: {
Tag1: null
},
func: [
Principal.fromText('rrkah-fqaaa-aaaaa-aaaaq-cai'),
'candidTypes'
],
canister: MyCanister(Principal.fromText('aaaaa-aa')),
principal: Principal.fromText('ryjl3-tyaaa-aaaaa-aaaba-cai')
};
})
});
Calling candidTypes
with
dfx
will return:
(
record {
func = func "rrkah-fqaaa-aaaaa-aaaaq-cai".candidTypes;
text = "text";
nat16 = 65_535 : nat16;
nat32 = 4_294_967_295 : nat32;
nat64 = 18_446_744_073_709_551_615 : nat64;
record = record { age = 35 : nat8; lastName = "Doe"; firstName = "John" };
int = 170_141_183_460_469_231_731_687_303_715_884_105_727 : int;
nat = 340_282_366_920_938_463_463_374_607_431_768_211_455 : nat;
opt = null;
vec = vec { "has one element" };
variant = variant { Tag1 };
nat8 = 255 : nat8;
canister = service "aaaaa-aa";
int16 = 32_767 : int16;
int32 = 2_147_483_647 : int32;
int64 = 9_223_372_036_854_775_807 : int64;
null = null : null;
blob = vec {};
bool = true;
principal = principal "ryjl3-tyaaa-aaaaa-aaaba-cai";
int8 = 127 : int8;
float32 = 3.1415927 : float32;
float64 = 2.718281828459045 : float64;
},
)