@dfinity/ic-management/dist/types/ic-management.canister.d.ts

A library for interfacing with the IC management canister.

import { Principal } from "@dfinity/principal";
import type { chunk_hash, list_canister_snapshots_result, snapshot_id, take_canister_snapshot_result } from "../candid/ic-management";
import type { ICManagementCanisterOptions } from "./types/canister.options";
import { type ClearChunkStoreParams, type CreateCanisterParams, type InstallChunkedCodeParams, type InstallCodeParams, type ProvisionalCreateCanisterWithCyclesParams, type SnapshotIdText, type StoredChunksParams, type UninstallCodeParams, type UpdateSettingsParams, type UploadChunkParams } from "./types/ic-management.params";
import type { CanisterStatusResponse, FetchCanisterLogsResponse } from "./types/ic-management.responses";
export declare class ICManagementCanister {
    private readonly service;
    private constructor();
    static create(options: ICManagementCanisterOptions): ICManagementCanister;
    /**
     * Create a new canister
     *
     * @param {Object} params
     * @param {CanisterSettings} params.settings
     * @param {BigInt} params.senderCanisterVersion
     * @returns {Promise<Principal>}
     */
    createCanister: ({ settings, senderCanisterVersion, }?: CreateCanisterParams) => Promise<Principal>;
    /**
     * Update canister settings
     *
     * @param {Object} params
     * @param {Principal} params.canisterId
     * @param {BigInt} params.senderCanisterVersion
     * @param {CanisterSettings} params.settings
     * @returns {Promise<void>}
     */
    updateSettings: ({ canisterId, senderCanisterVersion, settings, }: UpdateSettingsParams) => Promise<void>;
    /**
     * Install code to a canister
     *
     * @param {Object} params
     * @param {canister_install_mode} params.mode
     * @param {Principal} params.canisterId
     * @param {Uint8Array} params.wasmModule
     * @param {Uint8Array} params.arg
     * @param {BigInt} params.senderCanisterVersion
     * @returns {Promise<void>}
     */
    installCode: ({ canisterId, wasmModule, senderCanisterVersion, ...rest }: InstallCodeParams) => Promise<void>;
    /**
     * Upload chunks of Wasm modules that are too large to fit in a single message for installation purposes.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-upload_chunk
     *
     * @param {UploadChunkParams} params
     * @param {canisterId} params.canisterId The canister in which the chunks will be stored.
     * @param {Uint8Array | number[]} params.chunk A chunk of Wasm module.
     * @returns {Promise<chunk_hash>} The hash of the stored chunk.
     */
    uploadChunk: ({ canisterId, ...rest }: UploadChunkParams) => Promise<chunk_hash>;
    /**
     * Clear the entire chunk storage of a canister.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-clear_chunk_store
     *
     * @param {ClearChunkStoreParams} params
     * @param {canisterId} params.canisterId The canister in which the chunks are stored.
     */
    clearChunkStore: ({ canisterId, }: ClearChunkStoreParams) => Promise<void>;
    /**
     * List the hashes of chunks in the chunk storage of a canister.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-stored_chunks
     *
     * @param {StoredChunksParams} params
     * @param {canisterId} params.canisterId The canister in which the chunks are stored.
     * @returns {Promise<chunk_hash[]>} The list of hash of the stored chunks.
     */
    storedChunks: ({ canisterId, }: StoredChunksParams) => Promise<chunk_hash[]>;
    /**
     * Installs code that had previously been uploaded in chunks.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-install_chunked_code
     *
     * @param {InstallChunkedCodeParams} params
     * @param {canister_install_mode} params.mode Installation, re-installation or upgrade.
     * @param {Uint8Array} params.arg The arguments of the canister.
     * @param {Uint8Array | undefined} params.senderCanisterVersion The optional sender_canister_version parameter can contain the caller's canister version.
     * @param {Array<chunk_hash>} params.chunkHashesList The list of chunks of the Wasm module to install.
     * @param {Principal} params.targetCanisterId Specifies the canister where the code should be installed.
     * @param {Principal | undefined} params.storeCanisterId Specifies the canister in whose chunk storage the chunks are stored (this parameter defaults to target_canister if not specified).
     * @param {String} 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.
     * @returns {Promise<void>}
     */
    installChunkedCode: ({ senderCanisterVersion, chunkHashesList, targetCanisterId, storeCanisterId, wasmModuleHash, ...rest }: InstallChunkedCodeParams) => Promise<void>;
    /**
     * Uninstall code from a canister
     *
     * @param {Object} params
     * @param {Principal} params.canisterId
     * @param {BigInt} params.senderCanisterVersion
     * @returns {Promise<void>}
     */
    uninstallCode: ({ canisterId, senderCanisterVersion, }: UninstallCodeParams) => Promise<void>;
    /**
     * Start a canister
     *
     * @param {Principal} canisterId
     * @returns {Promise<void>}
     */
    startCanister: (canisterId: Principal) => Promise<void>;
    /**
     * Stop a canister
     *
     * @param {Principal} canisterId
     * @returns {Promise<void>}
     */
    stopCanister: (canisterId: Principal) => Promise<void>;
    /**
     * Get canister details (memory size, status, etc.)
     *
     * @param {Principal} canisterId
     * @returns {Promise<CanisterStatusResponse>}
     */
    canisterStatus: (canisterId: Principal) => Promise<CanisterStatusResponse>;
    /**
     * Deletes a canister
     *
     * @param {Principal} canisterId
     * @returns {Promise<void>}
     */
    deleteCanister: (canisterId: Principal) => Promise<void>;
    /**
     * Creates a canister. Only available on development instances.
     *
     * @param {Object} params
     * @param {Principal} params.canisterId
     * @param {BigInt} params.amount
     * @param {CanisterSettings} params.settings
     * @returns {Promise<Principal>}
     */
    provisionalCreateCanisterWithCycles: ({ settings, amount, canisterId, }?: ProvisionalCreateCanisterWithCyclesParams) => Promise<Principal>;
    /**
     * 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.
     *
     * @param {Principal} canisterId
     * @returns {Promise<FetchCanisterLogsResponse>}
     */
    fetchCanisterLogs: (canisterId: Principal) => Promise<FetchCanisterLogsResponse>;
    /**
     * 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.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-take_canister_snapshot
     *
     * @param {Object} params - Parameters for the snapshot operation.
     * @param {Principal} params.canisterId - The ID of the canister for which the snapshot will be taken.
     * @param {SnapshotIdText | snapshot_id} [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.
     *
     * @returns {Promise<take_canister_snapshot_result>} A promise that resolves with the snapshot details,
     * including the snapshot ID, total size, and timestamp.
     *
     * @throws {Error} If the snapshot operation fails.
     */
    takeCanisterSnapshot: ({ canisterId, snapshotId, }: {
        canisterId: Principal;
        snapshotId?: SnapshotIdText | snapshot_id;
    }) => Promise<take_canister_snapshot_result>;
    /**
     * Lists the snapshots of a canister.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-list_canister_snapshots
     *
     * @param {Object} params - Parameters for the listing operation.
     * @param {Principal} params.canisterId - The ID of the canister for which snapshots will be listed.
     *
     * @returns {Promise<list_canister_snapshots_result>} A promise that resolves with the list of snapshots.
     *
     * @throws {Error} If the operation fails.
     */
    listCanisterSnapshots: ({ canisterId, }: {
        canisterId: Principal;
    }) => Promise<list_canister_snapshots_result>;
    /**
     * Loads a snapshot of a canister's state.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-load_canister_snapshot
     *
     * @param {Object} params - Parameters for the snapshot loading operation.
     * @param {Principal} params.canisterId - The ID of the canister for which the snapshot will be loaded.
     * @param {snapshot_id} params.snapshotId - The ID of the snapshot to load.
     * @param {BigInt} [params.senderCanisterVersion] - The optional sender canister version. If provided, its value must be equal to ic0.canister_version.
     *
     * @returns {Promise<void>} A promise that resolves when the snapshot is successfully loaded.
     *
     * @throws {Error} If the snapshot loading operation fails.
     */
    loadCanisterSnapshot: ({ canisterId, snapshotId, senderCanisterVersion, }: {
        canisterId: Principal;
        snapshotId: SnapshotIdText | snapshot_id;
        senderCanisterVersion?: bigint;
    }) => Promise<void>;
    /**
     * Deletes a specific snapshot of a canister.
     *
     * @link https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-delete_canister_snapshot
     *
     * @param {Object} params - Parameters for the deletion operation.
     * @param {Principal} params.canisterId - The ID of the canister for which the snapshot will be deleted.
     * @param {snapshot_id} params.snapshotId - The ID of the snapshot to delete.
     *
     * @returns {Promise<void>} A promise that resolves when the snapshot is successfully deleted.
     *
     * @throws {Error} If the deletion operation fails.
     */
    deleteCanisterSnapshot: ({ canisterId, snapshotId, }: {
        canisterId: Principal;
        snapshotId: SnapshotIdText | snapshot_id;
    }) => Promise<void>;
}