HttpAgent
Defined in: packages/core/src/agent/agent/http/index.ts:268
A HTTP agent allows users to interact with a client of the internet computer using the available methods. It exposes an API that closely follows the public view of the internet computer, and is not intended to be exposed directly to the majority of users due to its low-level interface. There is a pipeline to apply transformations to the request before sending it to the client. This is to decouple signature, nonce generation and other computations so that this class can stay as simple as possible while allowing extensions.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new HttpAgent(
options?):HttpAgent
Defined in: packages/core/src/agent/agent/http/index.ts:310
Parameters
Section titled “Parameters”options?
Section titled “options?”HttpAgentOptions = {}
Options for the HttpAgent
Returns
Section titled “Returns”HttpAgent
Deprecated
Section titled “Deprecated”Use HttpAgent.create or HttpAgent.createSync instead
Properties
Section titled “Properties”_isAgent
Section titled “_isAgent”
readonly_isAgent:true=true
Defined in: packages/core/src/agent/agent/http/index.ts:293
config
Section titled “config”config:
HttpAgentOptions={}
Defined in: packages/core/src/agent/agent/http/index.ts:294
readonlyhost:URL
Defined in: packages/core/src/agent/agent/http/index.ts:282
log:
ObservableLog
Defined in: packages/core/src/agent/agent/http/index.ts:296
rootKey
Section titled “rootKey”rootKey:
Uint8Array<ArrayBufferLike> |null
Defined in: packages/core/src/agent/agent/http/index.ts:269
Implementation of
Section titled “Implementation of”Methods
Section titled “Methods”_transform()
Section titled “_transform()”
protected_transform(request):Promise<HttpAgentRequest>
Defined in: packages/core/src/agent/agent/http/index.ts:1671
Parameters
Section titled “Parameters”request
Section titled “request”Returns
Section titled “Returns”Promise<HttpAgentRequest>
addTransform()
Section titled “addTransform()”addTransform(
type,fn,priority?):void
Defined in: packages/core/src/agent/agent/http/index.ts:443
Parameters
Section titled “Parameters”"query" | "update"
priority?
Section titled “priority?”number = ...
Returns
Section titled “Returns”void
call()
Section titled “call()”call(
canisterId,options,identity?):Promise<SubmitResponse>
Defined in: packages/core/src/agent/agent/http/index.ts:486
Makes a call to a canister method.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
The ID of the canister to call. Can be a Principal or a string.
options
Section titled “options”Options for the call.
Uint8Array
The argument to pass to the method, as a Uint8Array.
callSync?
Section titled “callSync?”boolean
(Optional) Whether to use synchronous call mode. Defaults to true.
effectiveCanisterId?
Section titled “effectiveCanisterId?”string | Principal
(Optional) The effective canister ID, if different from the target canister ID.
methodName
Section titled “methodName”string
The name of the method to call.
nonce?
Section titled “nonce?”Uint8Array<ArrayBufferLike> | Nonce
(Optional) A unique nonce for the request. If provided, it will override any nonce set by transforms.
identity?
Section titled “identity?”(Optional) The identity to use for the call. If not provided, the agent’s current identity will be used.
Returns
Section titled “Returns”Promise<SubmitResponse>
A promise that resolves to the response of the call, including the request ID and response details.
Implementation of
Section titled “Implementation of”createReadStateRequest()
Section titled “createReadStateRequest()”createReadStateRequest(
fields,identity?):Promise<any>
Defined in: packages/core/src/agent/agent/http/index.ts:1206
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”fields
Section titled “fields”identity?
Section titled “identity?”Returns
Section titled “Returns”Promise<any>
Implementation of
Section titled “Implementation of”fetchRootKey()
Section titled “fetchRootKey()”fetchRootKey():
Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/core/src/agent/agent/http/index.ts:1540
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>>
Implementation of
Section titled “Implementation of”fetchSubnetKeys()
Section titled “fetchSubnetKeys()”fetchSubnetKeys(
canisterId):Promise<SubnetNodeKeys>
Defined in: packages/core/src/agent/agent/http/index.ts:1590
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
Returns
Section titled “Returns”Promise<SubnetNodeKeys>
getPrincipal()
Section titled “getPrincipal()”getPrincipal():
Promise<Principal>
Defined in: packages/core/src/agent/agent/http/index.ts:467
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>
Implementation of
Section titled “Implementation of”getSubnetIdFromCanister()
Section titled “getSubnetIdFromCanister()”getSubnetIdFromCanister(
canisterId):Promise<Principal>
Defined in: packages/core/src/agent/agent/http/index.ts:1654
Returns the subnet ID for a given canister ID, by looking at the certificate delegation
returned by the canister’s state obtained by requesting the /time path with readState.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
The canister ID to get the subnet ID for.
Returns
Section titled “Returns”Promise<Principal>
The subnet ID for the given canister ID.
getTimeDiffMsecs()
Section titled “getTimeDiffMsecs()”getTimeDiffMsecs():
number
Defined in: packages/core/src/agent/agent/http/index.ts:1692
Returns the time difference in milliseconds between the IC network clock and the client’s clock, after the clock has been synced.
If the time has not been synced, returns 0.
Returns
Section titled “Returns”number
hasSyncedTime()
Section titled “hasSyncedTime()”hasSyncedTime():
boolean
Defined in: packages/core/src/agent/agent/http/index.ts:1699
Returns true if the time has been synced at least once with the IC network, false otherwise.
Returns
Section titled “Returns”boolean
invalidateIdentity()
Section titled “invalidateIdentity()”invalidateIdentity():
void
Defined in: packages/core/src/agent/agent/http/index.ts:1582
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
Implementation of
Section titled “Implementation of”isLocal()
Section titled “isLocal()”isLocal():
boolean
Defined in: packages/core/src/agent/agent/http/index.ts:438
Returns
Section titled “Returns”boolean
parseTimeFromResponse()
Section titled “parseTimeFromResponse()”parseTimeFromResponse(
response):number
Defined in: packages/core/src/agent/agent/http/index.ts:1361
Parameters
Section titled “Parameters”response
Section titled “response”certificate
Section titled “certificate”Uint8Array
Returns
Section titled “Returns”number
query()
Section titled “query()”query(
canisterId,fields,identity?):Promise<ApiQueryResponse>
Defined in: packages/core/src/agent/agent/http/index.ts:1020
Send a query call to a canister. See the interface spec.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
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).
fields
Section titled “fields”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.
Implementation of
Section titled “Implementation of”readState()
Section titled “readState()”readState(
canisterId,fields,_identity?,request?):Promise<ReadStateResponse>
Defined in: packages/core/src/agent/agent/http/index.ts:1242
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”canisterId
Section titled “canisterId”string | Principal
fields
Section titled “fields”_identity?
Section titled “_identity?”request?
Section titled “request?”any
The request to send in case it has already been created.
Returns
Section titled “Returns”Promise<ReadStateResponse>
Implementation of
Section titled “Implementation of”readSubnetState()
Section titled “readSubnetState()”readSubnetState(
subnetId,options):Promise<ReadStateResponse>
Defined in: packages/core/src/agent/agent/http/index.ts:1292
Reads the state of a subnet from the /api/v3/subnet/{subnetId}/read_state endpoint.
Parameters
Section titled “Parameters”subnetId
Section titled “subnetId”string | Principal
The ID of the subnet to read the state of. If you have a canister ID, you can use getSubnetIdFromCanister to get the subnet ID.
options
Section titled “options”The options for the read state request.
Returns
Section titled “Returns”Promise<ReadStateResponse>
The response from the read state request.
replaceIdentity()
Section titled “replaceIdentity()”replaceIdentity(
identity):void
Defined in: packages/core/src/agent/agent/http/index.ts:1586
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 @icp-sdk/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
Implementation of
Section titled “Implementation of”status()
Section titled “status()”status():
Promise<JsonObject>
Defined in: packages/core/src/agent/agent/http/index.ts:1521
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.
Implementation of
Section titled “Implementation of”syncTime()
Section titled “syncTime()”syncTime(
canisterIdOverride?):Promise<void>
Defined in: packages/core/src/agent/agent/http/index.ts:1401
Allows agent to sync its time with the network. Can be called during initialization or mid-lifecycle if the device’s clock has drifted away from the network time. This is necessary to set the Expiry for a request
Parameters
Section titled “Parameters”canisterIdOverride?
Section titled “canisterIdOverride?”Pass a canister ID if you need to sync the time with a particular subnet. Uses the ICP ledger canister by default.
Returns
Section titled “Returns”Promise<void>
syncTimeWithSubnet()
Section titled “syncTimeWithSubnet()”syncTimeWithSubnet(
subnetId):Promise<void>
Defined in: packages/core/src/agent/agent/http/index.ts:1464
Allows agent to sync its time with the network.
Parameters
Section titled “Parameters”subnetId
Section titled “subnetId”Pass the subnet ID you need to sync the time with.
Returns
Section titled “Returns”Promise<void>
update()
Section titled “update()”update(
canisterId,fields,pollingOptions?):Promise<UpdateResult>
Defined in: packages/core/src/agent/agent/http/index.ts:657
Executes an update call to a canister and returns the certified result.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
The canister to call.
fields
Section titled “fields”The call options (method name, arg, effective canister ID, optional nonce).
pollingOptions?
Section titled “pollingOptions?”PollingOptions = {}
Optional polling configuration.
Returns
Section titled “Returns”Promise<UpdateResult>
The certified result including the certificate, reply bytes, and raw certificate bytes.
Implementation of
Section titled “Implementation of”create()
Section titled “create()”
staticcreate(options?):Promise<HttpAgent>
Defined in: packages/core/src/agent/agent/http/index.ts:413
Parameters
Section titled “Parameters”options?
Section titled “options?”HttpAgentOptions = {}
Returns
Section titled “Returns”Promise<HttpAgent>
createSync()
Section titled “createSync()”
staticcreateSync(options?):HttpAgent
Defined in: packages/core/src/agent/agent/http/index.ts:409
Parameters
Section titled “Parameters”options?
Section titled “options?”HttpAgentOptions = {}
Returns
Section titled “Returns”HttpAgent
from()
Section titled “from()”
staticfrom(agent):Promise<HttpAgent>
Defined in: packages/core/src/agent/agent/http/index.ts:419
Parameters
Section titled “Parameters”V1HttpAgentInterface | Pick<HttpAgent, "config">
Returns
Section titled “Returns”Promise<HttpAgent>