@dfinity/ic-management

ic-management-js

A library for interfacing with the Internet Computer (IC) management canister.

Table of contents

• Installation
• Usage
• Features

Installation

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

npm i @dfinity/ic-management

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 ICMgmtCanister. It has to be instantiated with a canister ID.

e.g. fetching a token metadata.

import { ICManagementCanister } from "@dfinity/ic-management";
import { createAgent } from "@dfinity/utils";

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

const { canisterStatus } = ICManagementCanister.create({
  agent,
});

const { status, memory_size, ...rest } = await canisterStatus(YOUR_CANISTER_ID);

Features

ic-management-js implements following features:

:factory: ICManagementCanister

:link: Source

Methods

• create
• createCanister
• updateSettings
• installCode
• uploadChunk
• clearChunkStore
• storedChunks
• installChunkedCode
• uninstallCode
• startCanister
• stopCanister
• canisterStatus
• deleteCanister
• provisionalCreateCanisterWithCycles
• fetchCanisterLogs
• takeCanisterSnapshot
• listCanisterSnapshots
• loadCanisterSnapshot
• deleteCanisterSnapshot

:gear: create

Method	Type
create	(options: ICManagementCanisterOptions) => ICManagementCanister

:link: Source

:gear: createCanister

Create a new canister

Method	Type
createCanister	({ settings, senderCanisterVersion, }?: CreateCanisterParams) => Promise<Principal>

:link: Source

:gear: updateSettings

Update canister settings

Method	Type
updateSettings	({ canisterId, senderCanisterVersion, settings, }: UpdateSettingsParams) => Promise<void>

:link: Source

:gear: installCode

Install code to a canister

Method	Type
installCode	({ canisterId, wasmModule, senderCanisterVersion, ...rest }: InstallCodeParams) => Promise<void>

:link: Source

:gear: uploadChunk

Upload chunks of Wasm modules that are too large to fit in a single message for installation purposes.

Method	Type
uploadChunk	({ canisterId, ...rest }: UploadChunkParams) => Promise<chunk_hash>

Parameters:

• params.canisterId: The canister in which the chunks will be stored.
• params.chunk: A chunk of Wasm module.

:link: Source

:gear: clearChunkStore

Clear the entire chunk storage of a canister.

Method	Type
clearChunkStore	({ canisterId, }: ClearChunkStoreParams) => Promise<void>

Parameters:

• params.canisterId: The canister in which the chunks are stored.

:link: Source

:gear: storedChunks

List the hashes of chunks in the chunk storage of a canister.

Method	Type
storedChunks	({ canisterId, }: StoredChunksParams) => Promise<chunk_hash[]>

Parameters:

• params.canisterId: The canister in which the chunks are stored.

:link: Source

:gear: installChunkedCode

Installs code that had previously been uploaded in chunks.

Method	Type
installChunkedCode	({ senderCanisterVersion, chunkHashesList, targetCanisterId, storeCanisterId, wasmModuleHash, ...rest }: InstallChunkedCodeParams) => Promise<void>

Parameters:

• params.mode: Installation, re-installation or upgrade.
• params.arg: The arguments of the canister.
• params.senderCanisterVersion: The optional sender_canister_version parameter can contain the caller's canister version.
• params.chunkHashesList: The list of chunks of the Wasm module to install.
• params.targetCanisterId: Specifies the canister where the code should be installed.
• params.storeCanisterId: Specifies the canister in whose chunk storage the chunks are stored (this parameter defaults to target_canister if not specified).
• params.wasmModuleHash: The Wasm module hash as hex string. Used to check that the SHA-256 hash of wasm_module is equal to the wasm_module_hash parameter and can calls install_code with parameters.

:link: Source

:gear: uninstallCode

Uninstall code from a canister

Method	Type
uninstallCode	({ canisterId, senderCanisterVersion, }: UninstallCodeParams) => Promise<void>

:link: Source

:gear: startCanister

Start a canister

Method	Type
startCanister	(canisterId: Principal) => Promise<void>

:link: Source

:gear: stopCanister

Stop a canister

Method	Type
stopCanister	(canisterId: Principal) => Promise<void>

:link: Source

:gear: canisterStatus

Get canister details (memory size, status, etc.)

Method	Type
canisterStatus	(canisterId: Principal) => Promise<canister_status_result>

:link: Source

:gear: deleteCanister

Deletes a canister

Method	Type
deleteCanister	(canisterId: Principal) => Promise<void>

:link: Source

:gear: provisionalCreateCanisterWithCycles

Creates a canister. Only available on development instances.

Method	Type
provisionalCreateCanisterWithCycles	({ settings, amount, canisterId, }?: ProvisionalCreateCanisterWithCyclesParams) => Promise<Principal>

:link: Source

:gear: fetchCanisterLogs

Given a canister ID as input, this method returns a vector of logs of that canister including its trap messages. The canister logs are not collected in canister methods running in non-replicated mode (NRQ, CQ, CRy, CRt, CC, and F modes, as defined in Overview of imports). The total size of all returned logs does not exceed 4KiB. If new logs are added resulting in exceeding the maximum total log size of 4KiB, the oldest logs will be removed. Logs persist across canister upgrades and they are deleted if the canister is reinstalled or uninstalled.

Method	Type
fetchCanisterLogs	(canisterId: Principal) => Promise<fetch_canister_logs_result>

:link: Source

:gear: takeCanisterSnapshot

This method takes a snapshot of the specified canister. A snapshot consists of the wasm memory, stable memory, certified variables, wasm chunk store and wasm binary.

Method	Type
takeCanisterSnapshot	({ canisterId, snapshotId, }: { canisterId: Principal; snapshotId?: string or snapshot_id or undefined; }) => Promise<snapshot>

Parameters:

• params: - Parameters for the snapshot operation.
• params.canisterId: - The ID of the canister for which the snapshot will be taken.
• params.snapshotId: - The ID of the snapshot to replace, if applicable. Can be provided as a string or a Uint8Array. If not provided, a new snapshot will be created.

:link: Source

:gear: listCanisterSnapshots

Lists the snapshots of a canister.

Method	Type
listCanisterSnapshots	({ canisterId, }: { canisterId: Principal; }) => Promise<list_canister_snapshots_result>

Parameters:

• params: - Parameters for the listing operation.
• params.canisterId: - The ID of the canister for which snapshots will be listed.

:link: Source

:gear: loadCanisterSnapshot

Loads a snapshot of a canister's state.

Method	Type
loadCanisterSnapshot	({ canisterId, snapshotId, senderCanisterVersion, }: { canisterId: Principal; snapshotId: string or snapshot_id; senderCanisterVersion?: bigint or undefined; }) => Promise<void>

Parameters:

• params: - Parameters for the snapshot loading operation.
• params.canisterId: - The ID of the canister for which the snapshot will be loaded.
• params.snapshotId: - The ID of the snapshot to load.
• params.senderCanisterVersion: - The optional sender canister version. If provided, its value must be equal to ic0.canister_version.

:link: Source

:gear: deleteCanisterSnapshot

Deletes a specific snapshot of a canister.

Method	Type
deleteCanisterSnapshot	({ canisterId, snapshotId, }: { canisterId: Principal; snapshotId: string or snapshot_id; }) => Promise<void>

Parameters:

• params: - Parameters for the deletion operation.
• params.canisterId: - The ID of the canister for which the snapshot will be deleted.
• params.snapshotId: - The ID of the snapshot to delete.

:link: Source

Resources

• IC Interface Specification