Skip to main content

Candid serialization

Candid is an interface description language and serialization format designed specifically for the Internet Computer protocol. It's a crucial component that enables seamless communication between different services and canister smart contracts on ICP, regardless of the programming languages they're implemented in.

At its core, Candid provides a language-agnostic way to describe and transmit data. Strong typing guarantees accurate data interpretation across various services and languages. This type safety is complemented by an efficient binary format for encoding data, making it ideal for network transmission. In the context of Motoko, Candid is deeply integrated into the language. Motoko automatically generates Candid interfaces for canister smart contracts and provides built-in functions like to_candid and from_candid for easy serialization and deserialization of data to and from Candid format.

In a broader scope, Candid serves as the standard communication protocol between canisters. When one canister calls another, the arguments are serialized to Candid, transmitted, and then deserialized by the receiving canister. This standardization enables developers to create frontends in languages like JavaScript that can easily interact with backend canisters written in Motoko or Rust.

Importantly, Candid's design allows for backwards-compatible upgrades of canister interfaces. This feature facilitates the evolution of services over time, a critical aspect for long-lived applications on the Internet Computer.

Autogenerated Candid interfaces​

When Motoko code is compiled, a Candid interface file (.did) for the canister's public methods is automatically generated. This file is used to ensure data passed into and returned from these methods is automatically encoded to and decoded from Candid’s binary format.

Motoko canisters automatically handle the serialization and deserialization of data when the canister interacts with inter-canister calls or ingress messages.

Candid operators​

Motoko provides the to_candid and from_candid functions for serializing and deserializing Candid-encoded data.

It's important to note that there are many valid Candid encodings, and therefore many different Blob representations, for the same value. As a result, to_candid does not guarantee that the same input will always produce the same Blob. You should never use the output of to_candid to compare values for equality or to compute hashes.

In most cases, explicit serialization using to_candid and from_candid is unnecessary during regular development. These functions are typically reserved for advanced scenarios, such as:

  • Making dynamic calls to arbitrary canisters.

  • Handling raw binary data for storage or transmission.

  • Managing stable data formats during canister upgrades.

For most common interactions, Candid serialization is handled automatically by the Motoko compiler.

to_candid​

The to_candid serializes Motoko values into a Candid-encoded binary Blob. This is useful when explicitly encoding data for storage, transmission between canisters, or dynamic inter-canister calls. The to_candid function can accept one or multiple arguments separated by commas.

let encoding =  to_candid(true, "hello", 68, -90) // (Bool, Text, Nat, Int)

Each argument must be composed of sharable types. The resulting Blob precisely represents the original Motoko values according to Candid specifications.

import Debug "mo:base/Debug";

actor {
  public type User = {
    userId : Nat;
    name : Text;
  };
  
  public func serializeUser(user : User) : async Blob {
    let encodedData : Blob = to_candid(user);
    Debug.print("User data serialized successfully.");
    encodedData;
  };
}

from_candid​

The from_candid function deserializes a Candid-encoded binary Blob back into Motoko values. This explicit decoding is useful in scenarios where serialized data needs to be processed or restored, such as reading from stable storage or handling dynamic input.

To decode a Blob correctly, from_candid requires an explicit type annotation or a clear type context. The result is returned as an optional (?) value, allowing you to safely handle potential failures caused by type mismatches or malformed data.

import Debug "mo:base/Debug";

actor {
  public type User = {
    userId : Nat;
    name : Text;
  };

  public func deserializeUser(encodedData : Blob) : async ?User {
    let decodedUser : ?User = from_candid(encodedData);

    switch decodedUser {
      case (?user) {
        Debug.print("User data deserialized successfully.");
        return ?user;
      };
      case null {
        Debug.print("Deserialization failed: Invalid blob or type mismatch.");
        return null;
      };
    };
  };
}

Although to_candid will return a valid Candid encoding of its argument, there are actually many different Candid encodings, and thus blobs, for the same value. There is no guarantee that to_candid will always return the same blob, given the same argument. That means that you should never use these blobs to compare values for equality or be tempted to compute a hash for a value by hashing its Candid encoding. The hash of a value should be unique, but if you compute it from one of several Candid encodings, it may not be.

Dynamic calls​

Most users should never need to use to_candid and from_candid. One scenario in which the operations are useful is when calling canister methods dynamically using the call function from the ExperimentalInternetComputer base library.

Although most canisters on ICP speak Candid, this isn't mandated by ICP. At the protocol level, canisters communicate in raw binary data. Candid is just a common interpretation of that data that allows canisters written in different languages to interoperate.

The call function takes a canister principal, the name of a method as text, and a raw binary blob and returns a future containing the result of the call, also as a raw binary blob.

Dynamic calls are particularly useful when working with canisters or services that have complex or non-standard interfaces, or when you need fine-grained control over the calling process. However, they require manual handling of binary encoding and decoding, which is more error-prone than using the high-level abstractions provided by Motoko.

When a service does speak Candid and you know the types of the method you want to invoke, you can use to_candid and from_candid to deal with the binary format.

Typically, you might use to_candid to prepare the argument of a call and from_candid to process its result.

In this example, we use the imported call function to make a dynamic call on the actor:

import Principal "mo:base/Principal";
import {call} "mo:base/ExperimentalInternetComputer";

persistent actor This {

   public func concat(ts : [Text]) : async Text {
      var r = "";
      for (t in ts.values()) { r #= t };
      r
   };

   public func test() : async Text {
       let arguments = to_candid (["a", "b", "c"]);
       let results = await call(Principal.fromActor(This), "concat", arguments);
       let ?t = from_candid(results) : ?Text;
       t
   }

}

While dynamic calls offer more flexibility, they should be used judiciously. In most cases, the standard inter-canister call mechanisms and automatic Candid handling in Motoko provide a safer and more convenient approach to canister interactions.

Resources​

For more detailed information on Candid, refer to: