The Canister Plugin provides comprehensive canister management capabilities, including lifecycle operations, WASM deployment, method calls, and controller management.

Overview

The Canister Plugin supports:

Lifecycle Management: Create, start, stop, delete canisters
Code Deployment: Install, upgrade, uninstall WASM modules
Method Calls: Query and update calls with IDL support
Actor Creation: Direct typed actor creation
Controller Management: Add/remove controllers, update settings
Metrics Tracking: Call counts, response times, error rates

Lifecycle Operations

`create(options?)`

Create a new canister. Parameters:

options (optional): ICanisterCreateOptions
- settings: ICanisterSettings - Initial canister settings
- cycles: bigint | string - Initial cycles amount

Returns: Promise<{ canisterId: Principal }> - Created canister information Example:

// Create basic canister
const { canisterId } = await agent.canisterPlugin.create();

// Create with custom settings and cycles
const { canisterId: customCanister } = await agent.canisterPlugin.create({
  cycles: '5T', // 5 trillion cycles
  settings: {
    controllers: [Principal.fromText('controller-principal')],
    computeAllocation: 10,
    memoryAllocation: BigInt(1024 * 1024), // 1MB
    freezingThreshold: 2592000 // 30 days
  }
});

`deploy(options)`

Deploy WASM code to a canister. Parameters:

options: ICanisterDeployOptions
- canisterId: Principal - Target canister ID
- wasmModule: Uint8Array - WASM module bytes
- installArgs: Uint8Array - Installation arguments (optional)
- mode: 'install' | 'upgrade' | 'reinstall' - Installation mode (default: ‘install’)

Returns: Promise<IDeployResult>

canisterId: Principal - Deployed canister ID
moduleHash: string - Hash of deployed module
cyclesUsed: bigint - Cycles consumed during deployment

Example:

import { readFileSync } from 'fs';

// Load WASM module
const wasmModule = readFileSync('./hello-world.wasm');

// Deploy to canister
const result = await agent.canisterPlugin.deploy({
  canisterId: Principal.fromText('canister-id'),
  wasmModule,
  mode: 'install'
});

console.log('Deployed with hash:', result.moduleHash);
console.log('Cycles used:', agent.canisterPlugin.formatCycles(result.cyclesUsed));

`start(canisterId)`

Start a stopped canister. Parameters:

canisterId: Principal | string - Canister to start

Returns: Promise<void> Example:

await agent.canisterPlugin.start('canister-id');
console.log('Canister started');

`stop(canisterId)`

Stop a running canister. Parameters:

canisterId: Principal | string - Canister to stop

Returns: Promise<void> Example:

await agent.canisterPlugin.stop('canister-id');
console.log('Canister stopped');

`delete(canisterId)`

Delete a canister (must be stopped first). Parameters:

canisterId: Principal | string - Canister to delete

Returns: Promise<void> Example:

// Stop then delete
await agent.canisterPlugin.stop('canister-id');
await agent.canisterPlugin.delete('canister-id');
console.log('Canister deleted');

Method Calls

`call(options)`

Execute an update call on a canister. Parameters:

options: ICanisterCallOptions
- canisterId: Principal - Target canister
- methodName: string - Method to call
- args: unknown[] - Method arguments
- idlFactory: IDL.InterfaceFactory - Candid interface factory

Returns: Promise<unknown> - Method result Example:

import { idlFactory } from './hello-world.did.js';

const result = await agent.canisterPlugin.call({
  canisterId: Principal.fromText('canister-id'),
  methodName: 'greet',
  args: ['World'],
  idlFactory
});

console.log('Greeting result:', result);

`query(options)`

Execute a query call on a canister (read-only, faster). Parameters:

options: ICanisterQueryOptions
- canisterId: Principal - Target canister
- methodName: string - Method to call
- args: unknown[] - Method arguments
- idlFactory: IDL.InterfaceFactory - Candid interface factory

Returns: Promise<unknown> - Method result Example:

const balance = await agent.canisterPlugin.query({
  canisterId: Principal.fromText('canister-id'),
  methodName: 'getBalance',
  args: [],
  idlFactory
});

console.log('Current balance:', balance);

`createActor(canisterId, idlFactory)`

Create a typed actor for easier method calls. Parameters:

canisterId: Principal | string - Target canister
idlFactory: IDL.InterfaceFactory - Candid interface factory

Returns: ActorSubclass<T> - Typed actor instance Example:

import { idlFactory } from './hello-world.did.js';

const actor = agent.canisterPlugin.createActor('canister-id', idlFactory);

// Use actor methods directly
const greeting = await actor.greet('World');
const balance = await actor.getBalance();
const result = await actor.updateCounter(42);

Status and Information

`getStatus(canisterId)`

Get detailed canister status information. Parameters:

canisterId: Principal | string - Canister to query

Returns: Promise<ICanisterStatus>

canisterId: Principal - Canister ID
status: 'running' | 'stopping' | 'stopped' - Current status
settings: ICanisterSettings - Current settings
memorySize: bigint - Memory usage in bytes
cycles: bigint - Current cycles balance
moduleHash: string - Hash of installed module

Example:

const status = await agent.canisterPlugin.getStatus('canister-id');

console.log('Status:', status.status);
console.log('Cycles:', agent.canisterPlugin.formatCycles(status.cycles));
console.log('Memory:', status.memorySize, 'bytes');
console.log('Controllers:', status.settings.controllers?.map(p => p.toText()));

Controller Management

`updateSettings(canisterId, settings)`

Update canister settings. Parameters:

canisterId: Principal | string - Target canister
settings: Partial<ICanisterSettings> - Settings to update

Returns: Promise<void> Example:

await agent.canisterPlugin.updateSettings('canister-id', {
  computeAllocation: 20,
  memoryAllocation: BigInt(2 * 1024 * 1024), // 2MB
  freezingThreshold: 7776000 // 90 days
});

`addController(canisterId, controller)`

Add a new controller to a canister. Parameters:

canisterId: Principal | string - Target canister
controller: Principal | string - New controller principal

Returns: Promise<void> Example:

await agent.canisterPlugin.addController(
  'canister-id',
  'new-controller-principal'
);

`removeController(canisterId, controller)`

Remove a controller from a canister. Parameters:

canisterId: Principal | string - Target canister
controller: Principal | string - Controller to remove

Returns: Promise<void> Example:

await agent.canisterPlugin.removeController(
  'canister-id',
  'old-controller-principal'
);

Utility Functions

`formatCycles(cycles)`

Format cycles amount for display. Parameters:

cycles: bigint - Cycles amount

Returns: string - Formatted cycles (e.g., “2.5T”, “1.2B”) Example:

const formatted = agent.canisterPlugin.formatCycles(BigInt('2500000000000'));
console.log(formatted); // "2.5T"

`parseCycles(cycles)`

Parse cycles string to bigint. Parameters:

cycles: string - Cycles string (e.g., “2.5T”, “1B”)

Returns: bigint - Parsed cycles amount Example:

const amount = agent.canisterPlugin.parseCycles('2.5T');
console.log(amount); // 2500000000000n

`exists(canisterId)`

Check if a canister exists. Parameters:

canisterId: Principal | string - Canister to check

Returns: Promise<boolean> - Whether canister exists Example:

const exists = await agent.canisterPlugin.exists('canister-id');
if (exists) {
  console.log('Canister exists');
}

`isController(canisterId)`

Check if current identity is a controller of the canister. Parameters:

canisterId: Principal | string - Canister to check

Returns: Promise<boolean> - Whether current identity is a controller Example:

const isController = await agent.canisterPlugin.isController('canister-id');
if (isController) {
  console.log('You are a controller of this canister');
}

Types

`ICanisterSettings`

Canister configuration settings.

interface ICanisterSettings {
  controllers?: Principal[];
  computeAllocation?: number; // 0-100
  memoryAllocation?: bigint; // bytes
  freezingThreshold?: number; // seconds
}

`ICanisterDeployOptions`

Options for deploying WASM to a canister.

interface ICanisterDeployOptions {
  canisterId: Principal;
  wasmModule: Uint8Array;
  installArgs?: Uint8Array;
  mode?: 'install' | 'upgrade' | 'reinstall';
}

`IDeployResult`

Result of canister deployment.

interface IDeployResult {
  canisterId: Principal;
  moduleHash: string;
  cyclesUsed: bigint;
}

`ICanisterCallOptions`

Options for canister method calls.

interface ICanisterCallOptions {
  canisterId: Principal;
  methodName: string;
  args: unknown[];
  idlFactory: IDL.InterfaceFactory;
}

Usage Patterns

Complete Canister Lifecycle

// 1. Create canister
const { canisterId } = await agent.canisterPlugin.create({
  cycles: '10T'
});

// 2. Deploy WASM
const wasmModule = await fetch('/hello-world.wasm').then(r => r.arrayBuffer());
await agent.canisterPlugin.deploy({
  canisterId,
  wasmModule: new Uint8Array(wasmModule)
});

// 3. Create actor for method calls
const actor = agent.canisterPlugin.createActor(canisterId, idlFactory);

// 4. Call methods
const result = await actor.greet('World');
console.log('Result:', result);

// 5. Monitor status
const status = await agent.canisterPlugin.getStatus(canisterId);
console.log('Remaining cycles:', agent.canisterPlugin.formatCycles(status.cycles));

Multi-Canister Management

const canisters = ['canister-1', 'canister-2', 'canister-3'];

// Check status of all canisters
for (const canisterId of canisters) {
  const status = await agent.canisterPlugin.getStatus(canisterId);
  console.log(`${canisterId}: ${status.status}, ${agent.canisterPlugin.formatCycles(status.cycles)} cycles`);
}

// Stop all canisters
await Promise.all(canisters.map(id => agent.canisterPlugin.stop(id)));

// Update settings for all
const newSettings = { computeAllocation: 10 };
await Promise.all(canisters.map(id => 
  agent.canisterPlugin.updateSettings(id, newSettings)
));

Canister Upgrade Pattern

// Upgrade existing canister
const newWasmModule = await fetch('/hello-world-v2.wasm').then(r => r.arrayBuffer());

// First, check if we're a controller
const isController = await agent.canisterPlugin.isController('canister-id');
if (!isController) {
  throw new Error('Not authorized to upgrade canister');
}

// Perform upgrade
await agent.canisterPlugin.deploy({
  canisterId: Principal.fromText('canister-id'),
  wasmModule: new Uint8Array(newWasmModule),
  mode: 'upgrade'
});

console.log('Canister upgraded successfully');

Error Handling

import { ICPAgentError } from 'icp-agent-kit';

try {
  await agent.canisterPlugin.call({
    canisterId: Principal.fromText('invalid-canister'),
    methodName: 'test',
    args: [],
    idlFactory
  });
} catch (error) {
  if (error instanceof ICPAgentError) {
    if (error.code === 'CANISTER_NOT_FOUND') {
      console.log('Canister does not exist');
    } else if (error.code === 'INSUFFICIENT_CYCLES') {
      console.log('Not enough cycles for operation');
    }
  }
}

Get Started

Core Plugins

API Reference

LangChain Integration

Canister Plugin

Overview

Lifecycle Operations

`create(options?)`

`deploy(options)`

`start(canisterId)`

`stop(canisterId)`

`delete(canisterId)`

Method Calls

`call(options)`

`query(options)`

`createActor(canisterId, idlFactory)`

Status and Information

`getStatus(canisterId)`

Controller Management

`updateSettings(canisterId, settings)`

`addController(canisterId, controller)`

`removeController(canisterId, controller)`

Utility Functions

`formatCycles(cycles)`

`parseCycles(cycles)`

`exists(canisterId)`

`isController(canisterId)`

Types

`ICanisterSettings`

`ICanisterDeployOptions`

`IDeployResult`

`ICanisterCallOptions`

Usage Patterns

Complete Canister Lifecycle

Multi-Canister Management

Canister Upgrade Pattern

Error Handling

Get Started

Core Plugins

API Reference

LangChain Integration

Documentation Index

​Overview

​Lifecycle Operations

​create(options?)

​deploy(options)

​start(canisterId)

​stop(canisterId)

​delete(canisterId)

​Method Calls

​call(options)

​query(options)

​createActor(canisterId, idlFactory)

​Status and Information

​getStatus(canisterId)

​Controller Management

​updateSettings(canisterId, settings)

​addController(canisterId, controller)

​removeController(canisterId, controller)

​Utility Functions

​formatCycles(cycles)

​parseCycles(cycles)

​exists(canisterId)

​isController(canisterId)

​Types

​ICanisterSettings

​ICanisterDeployOptions

​IDeployResult

​ICanisterCallOptions

​Usage Patterns

​Complete Canister Lifecycle

​Multi-Canister Management

​Canister Upgrade Pattern

​Error Handling

Overview

Lifecycle Operations

`create(options?)`

`deploy(options)`

`start(canisterId)`

`stop(canisterId)`

`delete(canisterId)`

Method Calls

`call(options)`

`query(options)`

`createActor(canisterId, idlFactory)`

Status and Information

`getStatus(canisterId)`

Controller Management

`updateSettings(canisterId, settings)`

`addController(canisterId, controller)`

`removeController(canisterId, controller)`

Utility Functions

`formatCycles(cycles)`

`parseCycles(cycles)`

`exists(canisterId)`

`isController(canisterId)`

Types

`ICanisterSettings`

`ICanisterDeployOptions`

`IDeployResult`

`ICanisterCallOptions`

Usage Patterns

Complete Canister Lifecycle

Multi-Canister Management

Canister Upgrade Pattern

Error Handling