SignerAgent
Defined in: src/agent/agent.ts:100
An Agent implementation that routes canister calls through a Signer for user approval. Drop-in replacement for HttpAgent when canister calls need to be signed by an external signer.
Calls are sent to the signer via ICRC-49, and the returned content map and certificate are validated before being returned to the caller.
Use SignerAgent.create or SignerAgent.createSync to construct an instance — the constructor is private.
Example
Section titled “Example”const agent = await SignerAgent.create({ signer, account });const result = await agent.update(canisterId, { methodName: "transfer", arg, effectiveCanisterId: canisterId });Type Parameters
Section titled “Type Parameters”T extends Transport = Transport
Implements
Section titled “Implements”Agent
Accessors
Section titled “Accessors”rootKey
Section titled “rootKey”Get Signature
Section titled “Get Signature”get rootKey():
Uint8Array<ArrayBufferLike>
Defined in: src/agent/agent.ts:116
The root key used for certificate verification.
Returns
Section titled “Returns”Uint8Array<ArrayBufferLike>
Implementation of
Section titled “Implementation of”Agent.rootKey
signer
Section titled “signer”Get Signature
Section titled “Get Signature”get signer():
Signer<T>
Defined in: src/agent/agent.ts:121
The signer this agent routes calls through.
Returns
Section titled “Returns”Signer<T>
Methods
Section titled “Methods”call()
Section titled “call()”call(
canisterId,fields):Promise<SubmitResponse>
Defined in: src/agent/agent.ts:237
Sends a canister call through the signer. Returns the request ID and a synthetic HTTP response.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
The target canister principal or its text representation.
fields
Section titled “fields”CallOptions
The call options including method name and arguments.
Returns
Section titled “Returns”Promise<SubmitResponse>
Implementation of
Section titled “Implementation of”Agent.call
createReadStateRequest()
Section titled “createReadStateRequest()”createReadStateRequest(
_options,_identity?):Promise<unknown>
Defined in: src/agent/agent.ts:333
Internal
Parameters
Section titled “Parameters”_options
Section titled “_options”ReadStateOptions
The read state options.
_identity?
Section titled “_identity?”Identity
The identity to use for the request.
Returns
Section titled “Returns”Promise<unknown>
Implementation of
Section titled “Implementation of”Agent.createReadStateRequest
fetchRootKey()
Section titled “fetchRootKey()”fetchRootKey():
Promise<Uint8Array<ArrayBufferLike>>
Defined in: src/agent/agent.ts:319
Fetches the IC root key via the underlying HttpAgent.
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
Implementation of
Section titled “Implementation of”Agent.fetchRootKey
getPrincipal()
Section titled “getPrincipal()”getPrincipal():
Promise<Principal>
Defined in: src/agent/agent.ts:324
Returns the account principal this agent makes calls on behalf of.
Returns
Section titled “Returns”Promise<Principal>
Implementation of
Section titled “Implementation of”Agent.getPrincipal
query()
Section titled “query()”query(
canisterId,options,_identity?):Promise<ApiQueryResponse>
Defined in: src/agent/agent.ts:294
Executes a query by upgrading it to a canister call through the signer. The signer signs and submits the call, and the reply is extracted from the certified response.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
The target canister principal or its text representation.
options
Section titled “options”QueryFields
The query fields including method name and arguments.
_identity?
Section titled “_identity?”Identity | Promise<Identity>
Ignored. The signer manages identity internally.
Returns
Section titled “Returns”Promise<ApiQueryResponse>
Implementation of
Section titled “Implementation of”Agent.query
readState()
Section titled “readState()”readState(
_canisterId,options,_identity?,_request?):Promise<ReadStateResponse>
Defined in: src/agent/agent.ts:348
Returns the raw certificate for a previously completed call. The certificate is deleted after being read (single-use).
Only supports request_status paths for request IDs that were
returned by a prior call, update, or query.
Parameters
Section titled “Parameters”_canisterId
Section titled “_canisterId”string | Principal
The target canister principal (unused).
options
Section titled “options”ReadStateOptions
The read state options containing paths to look up.
_identity?
Section titled “_identity?”Identity | Promise<Identity>
The identity to use (unused).
_request?
Section titled “_request?”unknown
The request object (unused).
Returns
Section titled “Returns”Promise<ReadStateResponse>
Implementation of
Section titled “Implementation of”Agent.readState
replaceAccount()
Section titled “replaceAccount()”replaceAccount(
account):void
Defined in: src/agent/agent.ts:380
Replaces the account principal used for subsequent calls.
Parameters
Section titled “Parameters”account
Section titled “account”Principal
The new account principal to use for subsequent calls.
Returns
Section titled “Returns”void
status()
Section titled “status()”status():
Promise<JsonObject>
Defined in: src/agent/agent.ts:372
Queries the IC replica status via the underlying HttpAgent.
Returns
Section titled “Returns”Promise<JsonObject>
Implementation of
Section titled “Implementation of”Agent.status
update()
Section titled “update()”update(
canisterId,fields,_pollingOptions?):Promise<UpdateResult>
Defined in: src/agent/agent.ts:261
Executes a canister update call and returns the certified result. Combines call with certificate validation and reply extraction.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string | Principal
The target canister principal or its text representation.
fields
Section titled “fields”CallOptions
The call options including method name and arguments.
_pollingOptions?
Section titled “_pollingOptions?”unknown
Ignored. The signer already returns the certificate with the reply in a single round-trip.
Returns
Section titled “Returns”Promise<UpdateResult>
Implementation of
Section titled “Implementation of”Agent.update
create()
Section titled “create()”
staticcreate<T>(options):Promise<SignerAgent<T>>
Defined in: src/agent/agent.ts:130
Creates a new SignerAgent, asynchronously initializing the underlying HttpAgent if one is not provided.
Type Parameters
Section titled “Type Parameters”T extends Transport
Parameters
Section titled “Parameters”options
Section titled “options”The signer agent options.
Returns
Section titled “Returns”Promise<SignerAgent<T>>
createSync()
Section titled “createSync()”
staticcreateSync<T>(options):SignerAgent<T>
Defined in: src/agent/agent.ts:143
Creates a new SignerAgent synchronously. Use this when you already have an HttpAgent or don’t need async initialization.
Type Parameters
Section titled “Type Parameters”T extends Transport
Parameters
Section titled “Parameters”options
Section titled “options”The signer agent options.
Returns
Section titled “Returns”SignerAgent<T>