Agent
Defined in: packages/agent/src/agent/api.ts:171
An Agent able to make calls and queries to a Replica.
rootKey
Section titled “rootKey”
readonlyrootKey:null|Uint8Array<ArrayBufferLike>
Defined in: packages/agent/src/agent/api.ts:172
Methods
Section titled “Methods”call()
Section titled “call()”call(
canisterId,fields):Promise<SubmitResponse>
Defined in: packages/agent/src/agent/api.ts:203
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
fields
Section titled “fields”Returns
Section titled “Returns”Promise<SubmitResponse>
createReadStateRequest()?
Section titled “createReadStateRequest()?”
optionalcreateReadStateRequest(options,identity?):Promise<unknown>
Defined in: packages/agent/src/agent/api.ts:185
Create the request for the read state call.
readState uses this internally.
Useful to avoid signing the same request multiple times.
Parameters
Section titled “Parameters”options
Section titled “options”identity?
Section titled “identity?”Returns
Section titled “Returns”Promise<unknown>
fetchRootKey()
Section titled “fetchRootKey()”fetchRootKey():
Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/agent/src/agent/api.ts:243
By default, the agent is configured to talk to the main Internet Computer, and verifies responses using a hard-coded public key.
This function will instruct the agent to ask the endpoint for its public key, and use that instead. This is required when talking to a local test instance, for example.
Only use this when you are not talking to the main Internet Computer, otherwise you are prone to man-in-the-middle attacks! Do not call this function by default.
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
getPrincipal()
Section titled “getPrincipal()”getPrincipal():
Promise<Principal>
Defined in: packages/agent/src/agent/api.ts:178
Returns the principal ID associated with this agent (by default). It only shows the principal of the default identity in the agent, which is the principal used when calls don’t specify it.
Returns
Section titled “Returns”Promise<Principal>
invalidateIdentity()?
Section titled “invalidateIdentity()?”
optionalinvalidateIdentity():void
Defined in: packages/agent/src/agent/api.ts:250
If an application needs to invalidate an identity under certain conditions, an Agent may expose an invalidateIdentity method.
Invoking this method will set the inner identity used by the Agent to null.
A use case for this would be - after a certain period of inactivity, a secure application chooses to invalidate the identity of any HttpAgent instances. An invalid identity can be replaced by Agent.replaceIdentity
Returns
Section titled “Returns”void
query()
Section titled “query()”query(
canisterId,options,identity?):Promise<ApiQueryResponse>
Defined in: packages/agent/src/agent/api.ts:225
Send a query call to a canister. See the interface spec.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”The Principal of the Canister to send the query to. Sending a query to the management canister is not supported (as it has no meaning from an agent).
string | Principal
options
Section titled “options”Options to use to create and send the query.
identity?
Section titled “identity?”Sender principal to use when sending the query.
Returns
Section titled “Returns”Promise<ApiQueryResponse>
The response from the replica. The Promise will only reject when the communication failed. If the query itself failed but no protocol errors happened, the response will be of type QueryResponseRejected.
readState()
Section titled “readState()”readState(
effectiveCanisterId,options,identity?,request?):Promise<ReadStateResponse>
Defined in: packages/agent/src/agent/api.ts:196
Send a read state query to the replica. This includes a list of paths to return, and will return a Certificate. This will only reject on communication errors, but the certificate might contain less information than requested.
Parameters
Section titled “Parameters”effectiveCanisterId
Section titled “effectiveCanisterId”A Canister ID related to this call.
string | Principal
options
Section titled “options”The options for this call.
identity?
Section titled “identity?”Identity for the call. If not specified, uses the instance identity.
request?
Section titled “request?”unknown
The request to send in case it has already been created.
Returns
Section titled “Returns”Promise<ReadStateResponse>
replaceIdentity()?
Section titled “replaceIdentity()?”
optionalreplaceIdentity(identity):void
Defined in: packages/agent/src/agent/api.ts:261
If an application needs to replace an identity under certain conditions, an Agent may expose a replaceIdentity method.
Invoking this method will set the inner identity used by the Agent to a newly provided identity.
A use case for this would be - after authenticating using @dfinity/auth-client, you can replace the AnonymousIdentity of your Actor with a DelegationIdentity.
Actor.agentOf(defaultActor).replaceIdentity(await authClient.getIdentity());Parameters
Section titled “Parameters”identity
Section titled “identity”Returns
Section titled “Returns”void
status()
Section titled “status()”status():
Promise<JsonObject>
Defined in: packages/agent/src/agent/api.ts:212
Query the status endpoint of the replica. This normally has a few fields that corresponds to the version of the replica, its root public key, and any other information made public.
Returns
Section titled “Returns”Promise<JsonObject>
A JsonObject that is essentially a record of fields from the status endpoint.