• Public
  • Public/Protected
  • All

Namespace CanisterStatus

The CanisterStatus utility is used to request structured data directly from the IC public API. This data can be accessed using agent.readState, but CanisterStatus provides a helpful abstraction with some known paths.

You can request a canisters Controllers, ModuleHash, Candid interface, Subnet, or Time, or provide a custom path CanisterStatus.CustomPath and pass arbitrary buffers for valid paths identified in https://smartcontracts.org/docs/current/references/ic-interface-spec/.

The primary method for this namespace is CanisterStatus.request


Type aliases

CanisterStatusOptions: { agent: HttpAgent; canisterId: Principal; paths?: Path[] | Set<Path> }

Type declaration

Path: "time" | "controllers" | "subnet" | "module_hash" | "candid" | MetaData | CustomPath

Pre-configured fields for canister status paths

Status: string | ArrayBuffer | Date | ArrayBuffer[] | Principal[] | bigint | null

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.

StatusMap: Map<Path | string, Status>


  • encodePath(path: Path, canisterId: Principal): ArrayBuffer[]
  • example

    const status = await canisterStatus({ paths: ['controllers', 'candid'], ...options });

    const controllers = status.get('controllers');


    • options: { agent: HttpAgent; canisterId: Principal; paths?: Set<Path> | Path[] }
      • agent: HttpAgent

        HttpAgent optional authenticated agent to use to make the canister request. Useful for accessing private metadata under icp:private

      • canisterId: Principal

        {@link Principal}

      • Optional paths?: Set<Path> | Path[]

        {@link Path[]}

    Returns Promise<StatusMap>

    object populated with data from the requested paths

Generated using TypeDoc