@dfinity/agent/lib/esm/canisterStatus/index.d.ts

JavaScript and TypeScript library to interact with the Internet Computer

import { Principal } from '@dfinity/principal';
import { HttpAgent } from '../agent/http/index.ts';
import { type CreateCertificateOptions } from '../certificate.ts';
import { type DerEncodedPublicKey } from '../auth.ts';
/**
 * Represents the useful information about a subnet
 * @param {string} subnetId the principal id of the canister's subnet
 * @param {string[]} nodeKeys the keys of the individual nodes in the subnet
 */
export type SubnetStatus = {
    subnetId: string;
    nodeKeys: Map<string, DerEncodedPublicKey>;
    metrics?: {
        num_canisters: bigint;
        canister_state_bytes: bigint;
        consumed_cycles_total: {
            current: bigint;
            deleted: bigint;
        };
        update_transactions_total: bigint;
    };
};
/**
 * Types of an entry on the canisterStatus map.
 * An entry of null indicates that the request failed, due to lack of permissions or the result being missing.
 */
export type Status = string | Uint8Array | Date | Uint8Array[] | Principal[] | SubnetStatus | bigint | null;
/**
 * Interface to define a custom path. Nested paths will be represented as individual buffers, and can be created from text using TextEncoder.
 * @param {string} key the key to use to access the returned value in the canisterStatus map
 * @param {Uint8Array[]} path the path to the desired value, represented as an array of buffers
 * @param {string} decodeStrategy the strategy to use to decode the returned value
 */
export declare class CustomPath implements CustomPath {
    key: string;
    path: Uint8Array[] | string;
    decodeStrategy: 'cbor' | 'hex' | 'leb128' | 'utf-8' | 'raw';
    constructor(key: string, path: Uint8Array[] | string, decodeStrategy: 'cbor' | 'hex' | 'leb128' | 'utf-8' | 'raw');
}
/**
 * @deprecated Use {@link CustomPath} instead
 * @param {string} key the key to use to access the returned value in the canisterStatus map
 * @param {string} path the path to the desired value, represented as a string
 * @param {string} decodeStrategy the strategy to use to decode the returned value
 */
export interface MetaData {
    kind: 'metadata';
    key: string;
    path: string | Uint8Array;
    decodeStrategy: 'cbor' | 'hex' | 'leb128' | 'utf-8' | 'raw';
}
/**
 * Pre-configured fields for canister status paths
 */
export type Path = 'time' | 'controllers' | 'subnet' | 'module_hash' | 'candid' | MetaData | CustomPath;
export type StatusMap = Map<Path | string, Status>;
export type CanisterStatusOptions = {
    canisterId: Principal;
    agent: HttpAgent;
    paths?: Path[] | Set<Path>;
    blsVerify?: CreateCertificateOptions['blsVerify'];
};
/**
 * Request information in the request_status state tree for a given canister.
 * Can be used to request information about the canister's controllers, time, module hash, candid interface, and more.
 * @param {CanisterStatusOptions} options {@link CanisterStatusOptions}
 * @param {CanisterStatusOptions['canisterId']} options.canisterId {@link Principal}
 * @param {CanisterStatusOptions['agent']} options.agent {@link HttpAgent} optional authenticated agent to use to make the canister request. Useful for accessing private metadata under icp:private
 * @param {CanisterStatusOptions['paths']} options.paths {@link Path[]}
 * @returns {Status} object populated with data from the requested paths
 * @example
 * const status = await canisterStatus({
 *   paths: ['controllers', 'candid'],
 *   ...options
 * });
 *
 * const controllers = status.get('controllers');
 */
export declare const request: (options: {
    canisterId: Principal;
    agent: HttpAgent;
    paths?: Path[] | Set<Path>;
}) => Promise<StatusMap>;
export declare const fetchNodeKeys: (certificate: Uint8Array, canisterId: Principal, root_key?: Uint8Array) => SubnetStatus;
export declare const encodePath: (path: Path, canisterId: Principal) => Uint8Array[];