Skip to main content

IC-CDK

The Canister Development Kit (ic-cdk or ic_cdk) provides core functionality for interacting with the Internet Computer in Rust.

Juno exposes a growing set of these features for TypeScript, allowing you to build serverless functions that interact with the IC using a familiar developer experience.

These features are made available through a layer that acts as a proxy between the Rust-based IC-CDK and JavaScript.

📦 Library

The IC-CDK for JS/TS is provided by the @junobuild/functions library.

To add it to your project:

npm i @junobuild/functions

You have to follow the pace of the Juno release to ensure compatibility. Refer to the maintenance guide for instructions.

canisterSelf​

Retrieves the Principal ID of the current Satellite.

This is useful when you want to use functions such as setDocStore with the caller set as the administrator. Since the code is running on the backend side (inside the container), the Satellite itself is considered the caller and has admin-level permissions.

function canisterSelf(): Principal;

📦 Import from @junobuild/functions/ic-cdk

Returns:​

  • Principal: The Principal ID of the currently executing Satellite.

Notes:​

  • This function is a JavaScript binding for the Rust function ic_cdk::id().
  • It was previously named id() and is also accessible as satelliteSelf().

call​

Makes an asynchronous call to a canister on the Internet Computer.

Use this function inside your serverless functions to interact with other canisters. It encodes arguments using Candid, performs the call, and decodes the response based on the expected result type.

function call<T>(params: CallParams): Promise<T | undefined>;

📦 Import from @junobuild/functions/ic-cdk

Parameters:​

  • params: The parameters required to make the canister call.
    • canisterId: The target canister's ID.
    • method: The name of the method to call. Must be at least one character long.
    • args (optional): An array of tuples containing each argument’s Candid type and its corresponding value.
    • result (optional): The expected result type used for decoding the response.

Returns:​

  • A promise resolving to the decoded result of the call. If the canister returns no value, undefined is returned.

Notes:​

  • This function is a JavaScript binding for the Rust function ic_cdk::call().

httpRequest​

Performs an HTTP request from a Juno serverless function.

function httpRequest(args: HttpRequestArgs): Promise<HttpRequestResult>;

📦 Import from @junobuild/functions/ic-cdk

Parameters:​

  • args: The HTTP request parameters.
  • url: The requested URL.
  • method: The HTTP method — GET, POST, or HEAD.
  • headers (optional): A list of HTTP request headers.
  • body (optional): The request body as a Uint8Array.
  • maxResponseBytes (optional): The maximal size of the response in bytes.
  • transform (optional): The name of a query function used to transform the response before consensus. If provided, a corresponding query must be declared using defineQuery.
  • isReplicated (optional): Whether all nodes should perform the request and agree on the response, or just one node. Defaults to all nodes if not specified.

Returns:​

  • Promise<HttpRequestResult>: A promise resolving to the HTTP response, containing status (bigint), headers, and body (Uint8Array).

Throws:​

  • ZodError if the provided arguments do not match the expected schema.
  • Error if the HTTP request fails.

Notes:​

msgCaller​

Returns the Principal ID of the caller of the current function.

function msgCaller(): Principal;

📦 Import from @junobuild/functions/ic-cdk

Returns:​

  • Principal: The Principal ID of the caller.

Notes:​

  • This function is a JavaScript binding for the Rust function ic_cdk::api::msg_caller().
  • In serverless hooks, the caller is the Satellite itself. The end user's Principal can be retrieved from the payload instead.
  • This function was previously named caller().

time​

Returns the current timestamp in nanoseconds since the Unix epoch.

This is useful when generating timestamps that match the Internet Computer's consensus state.

function time(): bigint;

📦 Import from @junobuild/functions/ic-cdk

Returns:​

  • bigint: The current timestamp in nanoseconds.

Notes:​

  • This function is a JavaScript binding for the Rust function ic_cdk::time().