Actor

Defined in: packages/core/src/agent/actor.ts:183

An actor base class. An actor is an object containing only functions that will return a promise. These functions are derived from the IDL definition.

Constructors

Constructor

protected new Actor(metadata): Actor

Defined in: packages/core/src/agent/actor.ts:350

Parameters

metadata

ActorMetadata

Returns

Actor

Methods

agentOf()

static agentOf(actor): Agent | undefined

Defined in: packages/core/src/agent/actor.ts:189

Get the Agent class this Actor would call, or undefined if the Actor would use the default agent (global.ic.agent).

Parameters

actor

Actor

The actor to get the agent of.

Returns

Agent | undefined

canisterIdOf()

static canisterIdOf(actor): Principal

Defined in: packages/core/src/agent/actor.ts:201

Parameters

actor

Actor

Returns

Principal

createActor()

static createActor<T>(interfaceFactory, configuration): ActorSubclass<T>

Defined in: packages/core/src/agent/actor.ts:302

Creates an actor with the given interface factory and configuration.

The @icp-sdk/bindgen package can be used to generate the interface factory for your canister.

Type Parameters

T

T = Record<string, ActorMethod<unknown[], unknown>>

Parameters

interfaceFactory

InterfaceFactory

the interface factory for the actor, typically generated by the @icp-sdk/bindgen package

configuration

ActorConfig

the configuration for the actor

Returns

ActorSubclass<T>

an actor with the given interface factory and configuration

See

The Canister Environment Guide for more details on how to configure an actor using the canister environment.

Examples

Using the interface factory generated by the @icp-sdk/bindgen package:

import { Actor, HttpAgent } from '@icp-sdk/core/agent';
import { Principal } from '@icp-sdk/core/principal';
import { idlFactory } from './api/declarations/hello-world.did';

// For a convenient way to get the canister ID,
// see the https://js.icp.build/core/latest/canister-environment/ guide.
const canisterId = Principal.fromText('rrkah-fqaaa-aaaaa-aaaaq-cai');

const agent = await HttpAgent.create({
  host: 'https://icp-api.io',
});

const actor = Actor.createActor(idlFactory, {
  agent,
  canisterId,
});

const response = await actor.greet('world');
console.log(response);

Using the createActor wrapper function generated by the @icp-sdk/bindgen package:

import { HttpAgent } from '@icp-sdk/core/agent';
import { Principal } from '@icp-sdk/core/principal';
import { createActor } from './api/hello-world';

// For a convenient way to get the canister ID,
// see the https://js.icp.build/core/latest/canister-environment/ guide.
const canisterId = Principal.fromText('rrkah-fqaaa-aaaaa-aaaaq-cai');

const agent = await HttpAgent.create({
  host: 'https://icp-api.io',
});

const actor = createActor(canisterId, {
  agent,
});

const response = await actor.greet('world');
console.log(response);

createActorClass()

static createActorClass(interfaceFactory, options?): ActorConstructor

Defined in: packages/core/src/agent/actor.ts:205

Parameters

createActorWithExtendedDetails()

static createActorWithExtendedDetails<T>(interfaceFactory, configuration, actorClassOptions?): ActorSubclass<ActorMethodMappedExtended<T>>

Defined in: packages/core/src/agent/actor.ts:335

Returns an actor with methods that return the http response details along with the result