HttpAgent

Defined in: packages/agent/src/agent/http/index.ts:284

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

Agent

Constructors

Constructor

new HttpAgent(options): HttpAgent

Defined in: packages/agent/src/agent/http/index.ts:324

Parameters

options

HttpAgentOptions = {}

Options for the HttpAgent

Returns

HttpAgent

Deprecated

Use HttpAgent.create or HttpAgent.createSync instead

Properties

_isAgent

readonly _isAgent: true = true

Defined in: packages/agent/src/agent/http/index.ts:307

config

config: HttpAgentOptions = {}

Defined in: packages/agent/src/agent/http/index.ts:308

host

readonly host: URL

Defined in: packages/agent/src/agent/http/index.ts:297

log

log: ObservableLog

Defined in: packages/agent/src/agent/http/index.ts:310

rootKey

rootKey: null | Uint8Array<ArrayBufferLike>

Defined in: packages/agent/src/agent/http/index.ts:285

Implementation of

Agent.rootKey

Methods

_transform()

protected _transform(request): Promise<HttpAgentRequest>

Defined in: packages/agent/src/agent/http/index.ts:1375

Parameters

request

HttpAgentRequest

Returns

Promise<HttpAgentRequest>

addTransform()

addTransform(type, fn, priority): void

Defined in: packages/agent/src/agent/http/index.ts:441

Parameters

type

"query" | "update"

fn

HttpAgentRequestTransformFn

priority

number = ...

Returns

void

call()

call(canisterId, options, identity?): Promise<SubmitResponse>

Defined in: packages/agent/src/agent/http/index.ts:484

Makes a call to a canister method.

Parameters

canisterId

The ID of the canister to call. Can be a Principal or a string.

string | Principal

options

Options for the call.

arg

Uint8Array

The argument to pass to the method, as a Uint8Array.

callSync?

boolean

(Optional) Whether to use synchronous call mode. Defaults to true.

effectiveCanisterId?

string | Principal

(Optional) The effective canister ID, if different from the target canister ID.

methodName

string

The name of the method to call.

nonce?

Uint8Array<ArrayBufferLike> | Nonce

(Optional) A unique nonce for the request. If provided, it will override any nonce set by transforms.

identity?

(Optional) The identity to use for the call. If not provided, the agent’s current identity will be used.

Identity | Promise<Identity>

Returns

Promise<SubmitResponse>

A promise that resolves to the response of the call, including the request ID and response details.

Implementation of

Agent.call

createReadStateRequest()

createReadStateRequest(fields, identity?): Promise<any>

Defined in: packages/agent/src/agent/http/index.ts:1062

Create the request for the read state call. readState uses this internally. Useful to avoid signing the same request multiple times.

Parameters

fields

ReadStateOptions

identity?

Identity | Promise<Identity>

Returns

Promise<any>

Implementation of

Agent.createReadStateRequest

fetchRootKey()

fetchRootKey(): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/agent/src/agent/http/index.ts:1308

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

Promise<Uint8Array<ArrayBufferLike>>

Implementation of

Agent.fetchRootKey

fetchSubnetKeys()

fetchSubnetKeys(canisterId): Promise<undefined | SubnetStatus>

Defined in: packages/agent/src/agent/http/index.ts:1357

Parameters

canisterId

string | Principal

Returns

Promise<undefined | SubnetStatus>

getPrincipal()

getPrincipal(): Promise<Principal>

Defined in: packages/agent/src/agent/http/index.ts:465

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

Promise<Principal>

Implementation of

Agent.getPrincipal

invalidateIdentity()

invalidateIdentity(): void

Defined in: packages/agent/src/agent/http/index.ts:1349

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

void

Implementation of

Agent.invalidateIdentity

isLocal()

isLocal(): boolean

Defined in: packages/agent/src/agent/http/index.ts:436

Returns

boolean

parseTimeFromResponse()

parseTimeFromResponse(response): number

Defined in: packages/agent/src/agent/http/index.ts:1183

Parameters

response

certificate

Uint8Array

Returns

number

query()

query(canisterId, fields, identity?): Promise<ApiQueryResponse>

Defined in: packages/agent/src/agent/http/index.ts:866

Send a query call to a canister. See the interface spec.

Parameters

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

fields

QueryFields

identity?

Sender principal to use when sending the query.

Identity | Promise<Identity>

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

Agent.query

readState()

readState(canisterId, fields, _identity?, request?): Promise<ReadStateResponse>

Defined in: packages/agent/src/agent/http/index.ts:1098

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

canisterId

A Canister ID related to this call.

string | Principal

fields

ReadStateOptions

The options for this call.

_identity?

Identity for the call. If not specified, uses the instance identity.

Identity | Promise<Identity>

request?

any

The request to send in case it has already been created.

Returns

Promise<ReadStateResponse>

Implementation of

Agent.readState

replaceIdentity()

replaceIdentity(identity): void

Defined in: packages/agent/src/agent/http/index.ts:1353

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

identity

Identity

Returns

void

Implementation of

Agent.replaceIdentity

status()

status(): Promise<JsonObject>

Defined in: packages/agent/src/agent/http/index.ts:1290

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

Promise<JsonObject>

A JsonObject that is essentially a record of fields from the status endpoint.

Implementation of

Agent.status

syncTime()

syncTime(canisterIdOverride?): Promise<void>

Defined in: packages/agent/src/agent/http/index.ts:1223

Allows agent to sync its time with the network. Can be called during intialization 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