@dfinity/cmc

cmc-js

A library for interfacing with the cycle minting canister.

Table of contents

• Installation
• Usage
• Features

Installation

You can use cmc-js by installing it in your project.

npm i @dfinity/cmc

The bundle needs peer dependencies, be sure that following resources are available in your project as well.

npm i @dfinity/agent @dfinity/candid @dfinity/principal @dfinity/utils

Usage

The features are available through the class CMCCanister. It has to be instantiated with the canister ID of the cycles minting canister. On mainnet, its ID is rkp4c-7iaaa-aaaaa-aaaca-cai.

e.g. querying the current Icp to cycles conversion rate.

import { CMCCanister } from "@dfinity/cmc";
import { createAgent } from "@dfinity/utils";

const agent = await createAgent({
  identity,
  host: HOST,
});

const { getIcpToCyclesConversionRate } = CMCCanister.create({
  agent,
  canisterId: CYCLES_MINTING_CANISTER_ID,
});

const rate = await getIcpToCyclesConversionRate();

Features

cmc-js implements following features:

:factory: CMCCanister

:link: Source

Static Methods

• create

:gear: create

Method	Type
create	(options: CMCCanisterOptions) => CMCCanister

:link: Source

Methods

• getIcpToCyclesConversionRate
• notifyCreateCanister
• notifyTopUp
• getDefaultSubnets
• getSubnetTypesToSubnets

:gear: getIcpToCyclesConversionRate

Returns conversion rate of ICP to Cycles. It can be called as query or update.

Method	Type
getIcpToCyclesConversionRate	({ certified, }?: QueryParams) => Promise<bigint>

Parameters:

• params: - The parameters for the call.
• params.certified: - Determines whether the response should be certified (default: non-certified)

Returns:

Promise

:link: Source

:gear: notifyCreateCanister

Notifies Cycles Minting Canister of the creation of a new canister. It returns the new canister principal.

Method	Type
notifyCreateCanister	(request: NotifyCreateCanisterArg) => Promise<Principal>

Returns:

Promise

:link: Source

:gear: notifyTopUp

Notifies Cycles Minting Canister of new cycles being added to canister. It returns the new Cycles of the canister.

Method	Type
notifyTopUp	(request: NotifyTopUpArg) => Promise<bigint>

Returns:

Promise

:link: Source

:gear: getDefaultSubnets

This function calls the get_default_subnets method of the CMC canister, which returns a list of default subnets as Principal objects. It can be called as query or update.

Method	Type
getDefaultSubnets	({ certified }?: QueryParams) => Promise<Principal[]>

Parameters:

• params: - The query parameters for the call.
• params.certified: - Determines whether the response should be certified (default: non-certified if not specified).

Returns:

• A promise that resolves to an array of Principal objects representing the default subnets.

:link: Source

:gear: getSubnetTypesToSubnets

This function calls the get_subnet_types_to_subnets method of the CMC canister, which returns a list of subnets where canisters can be created. These subnets are excluded from the random subnet selection process used by the CMC when no explicit subnet ID is provided during canister creation and therefore, not provided in the results of the similar function get_default_subnets.

Method	Type
getSubnetTypesToSubnets	({ certified, }?: QueryParams) => Promise<SubnetTypesToSubnetsResponse>

Parameters:

• params: - The optional query parameters for the call.
• params.certified: - Specifies whether the response should be certified. If not provided, the response defaults to non-certified.

Returns:

• A promise that resolves to an object representing the mapping of subnet types to subnets.

:link: Source