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:102
A read_state path defined by the user, with a string DecodeStrategy. Consumed by the
status utilities (e.g. CanisterStatus.request), which translate it into a KnownPath
before calling Agent.readState.
the key to use to access the returned value in the status map
the path to the desired value
the strategy used to decode the returned value
Deprecated
Section titled “Deprecated”Use KnownPath with Agent.readState instead.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new CustomPath(
key,path,decodeStrategy):CustomPath
Defined in: packages/core/src/agent/utils/readState.ts:106
Parameters
Section titled “Parameters”string
string | Uint8Array<ArrayBufferLike> | 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:105
key:
string
Defined in: packages/core/src/agent/utils/readState.ts:103
path:
string|Uint8Array<ArrayBufferLike> |Uint8Array<ArrayBufferLike>[]
Defined in: packages/core/src/agent/utils/readState.ts:104
Interfaces
Section titled “Interfaces”CanisterStatusOptions
Section titled “CanisterStatusOptions”Defined in: packages/core/src/agent/canisterStatus/index.ts:75
Properties
Section titled “Properties”agent:
HttpAgent
Defined in: packages/core/src/agent/canisterStatus/index.ts:83
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:79
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:93
Whether to disable the certificate freshness checks.
Default
Section titled “Default”falsepaths?
Section titled “paths?”Defined in: packages/core/src/agent/canisterStatus/index.ts:88
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:61
Decode strategy for a CustomPath. 'raw' returns the looked-up bytes unchanged.
Path =
"time"|"controllers"|"subnet"|"module_hash"|"candid"|CustomPath
Defined in: packages/core/src/agent/canisterStatus/index.ts:35
Pre-configured fields for canister status paths
Status
Section titled “Status”Status =
BaseStatus|SubnetStatus
Defined in: packages/core/src/agent/canisterStatus/index.ts:30
StatusMap
Section titled “StatusMap”Defined in: packages/core/src/agent/canisterStatus/index.ts:37
SubnetStatus
Section titled “SubnetStatus”SubnetStatus =
BaseSubnetStatus
Defined in: packages/core/src/agent/canisterStatus/index.ts:29
Functions
Section titled “Functions”fetchNodeKeys()
Section titled “fetchNodeKeys()”fetchNodeKeys(
certificate,canisterId,root_key?):BaseSubnetStatus
Defined in: packages/core/src/agent/canisterStatus/index.ts:183
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:115
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.
Deprecated
Section titled “Deprecated”Use HttpAgent.readState directly with StatePaths instead. This function will be removed in a future release.
CanisterStatusOptions for detailed options.
Example
Section titled “Example”const status = await canisterStatus({ paths: ['controllers', 'candid'], ...options});
const controllers = status.get('controllers');