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://internetcomputer.org/docs/current/references/ic-interface-spec.
The primary method for this namespace is CanisterStatus.request
Classes
Section titled “Classes”CustomPath
Section titled “CustomPath”Defined in: packages/core/src/agent/utils/readState.ts:67
Interface to define a custom path. Nested paths will be represented as individual buffers, and can be created from text using TextEncoder.
the key to use to access the returned value in the status map
the path to the desired value, represented as an array of buffers
the strategy to use to decode the returned value
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new CustomPath(
key,path,decodeStrategy):CustomPath
Defined in: packages/core/src/agent/utils/readState.ts:71
Parameters
Section titled “Parameters”string
string | Uint8Array<ArrayBufferLike>[]
decodeStrategy
Section titled “decodeStrategy”Returns
Section titled “Returns”Properties
Section titled “Properties”decodeStrategy
Section titled “decodeStrategy”decodeStrategy:
DecodeStrategy
Defined in: packages/core/src/agent/utils/readState.ts:70
Implementation of
Section titled “Implementation of”CustomPath.decodeStrategy
key:
string
Defined in: packages/core/src/agent/utils/readState.ts:68
Implementation of
Section titled “Implementation of”CustomPath.key
path:
string|Uint8Array<ArrayBufferLike>[]
Defined in: packages/core/src/agent/utils/readState.ts:69
Implementation of
Section titled “Implementation of”CustomPath.path
Interfaces
Section titled “Interfaces”CanisterStatusOptions
Section titled “CanisterStatusOptions”Defined in: packages/core/src/agent/canisterStatus/index.ts:42
Properties
Section titled “Properties”agent:
HttpAgent
Defined in: packages/core/src/agent/canisterStatus/index.ts:50
The agent to use to make the canister request. Must be authenticated.
canisterId
Section titled “canisterId”canisterId:
Principal
Defined in: packages/core/src/agent/canisterStatus/index.ts:46
The effective canister ID to use in the underlying HttpAgent.readState call.
disableCertificateTimeVerification?
Section titled “disableCertificateTimeVerification?”
optionaldisableCertificateTimeVerification?:boolean
Defined in: packages/core/src/agent/canisterStatus/index.ts:60
Whether to disable the certificate freshness checks.
Default
Section titled “Default”falsepaths?
Section titled “paths?”Defined in: packages/core/src/agent/canisterStatus/index.ts:55
The paths to request.
Default
Section titled “Default”[]Type Aliases
Section titled “Type Aliases”DecodeStrategy
Section titled “DecodeStrategy”DecodeStrategy =
"cbor"|"hex"|"leb128"|"utf-8"|"raw"
Defined in: packages/core/src/agent/utils/readState.ts:59
Decode strategy for custom paths
Path =
"time"|"controllers"|"subnet"|"module_hash"|"candid"|CustomPath
Defined in: packages/core/src/agent/canisterStatus/index.ts:38
Pre-configured fields for canister status paths
Status
Section titled “Status”Status =
BaseStatus|SubnetStatus
Defined in: packages/core/src/agent/canisterStatus/index.ts:33
StatusMap
Section titled “StatusMap”Defined in: packages/core/src/agent/canisterStatus/index.ts:40
SubnetStatus
Section titled “SubnetStatus”SubnetStatus =
BaseSubnetStatus
Defined in: packages/core/src/agent/canisterStatus/index.ts:32
Functions
Section titled “Functions”encodePath()
Section titled “encodePath()”encodePath(
path,canisterId):Uint8Array<ArrayBufferLike>[]
Defined in: packages/core/src/agent/canisterStatus/index.ts:225
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”Returns
Section titled “Returns”Uint8Array<ArrayBufferLike>[]
fetchNodeKeys()
Section titled “fetchNodeKeys()”fetchNodeKeys(
certificate,canisterId,root_key?):BaseSubnetStatus
Defined in: packages/core/src/agent/canisterStatus/index.ts:196
Lookup node keys from a certificate for a given canister. The certificate is assumed to be already verified, including whether the canister is in range of the subnet.
Parameters
Section titled “Parameters”certificate
Section titled “certificate”Uint8Array
the certificate to lookup node keys from
canisterId
Section titled “canisterId”the canister ID to lookup node keys for
root_key?
Section titled “root_key?”Uint8Array<ArrayBufferLike>
the root key to use to lookup node keys
Returns
Section titled “Returns”BaseSubnetStatus
a map of node IDs to public keys
request()
Section titled “request()”request(
options):Promise<StatusMap>
Defined in: packages/core/src/agent/canisterStatus/index.ts:81
Requests information from a canister’s read_state endpoint.
Can be used to request information about the canister’s controllers, time, module hash, candid interface, and more.
[!WARNING] Requesting the
subnetpath from the canister status might be deprecated in the future. Use SubnetStatus.request to fetch subnet information instead.
Parameters
Section titled “Parameters”options
Section titled “options”The configuration for the canister status request.
Returns
Section titled “Returns”Promise<StatusMap>
A map populated with data from the requested paths. Each path is a key in the map, and the value is the data obtained from the certificate for that path.
CanisterStatusOptions for detailed options.
Example
Section titled “Example”const status = await canisterStatus({ paths: ['controllers', 'candid'], ...options});
const controllers = status.get('controllers');