Skip to main content

@elizaos/plugin-icp

Internet Computer Protocol (ICP) plugin for Eliza OS.

Features​

  • Create meme tokens on PickPump
  • Interact with ICP canisters
  • Handle ICRC-1 token standard
  • Manage ICP wallets and identities
  • Support for anonymous and authenticated calls

Installation​

bun install @elizaos/plugin-icp

Configuration​

The plugin requires the following environment variables:

INTERNET_COMPUTER_PRIVATE_KEY=<your-ed25519-private-key>

Usage​

Import and Register​

import { icpPlugin } from '@elizaos/plugin-icp';

// Register the plugin with Eliza
eliza.registerPlugin(icpPlugin);

Available Actions​

Create Token​

Creates a new meme token on PickPump with AI-generated logo and description.

// Example usage in chat
'Create a space cat token on PickPump';
'Help me create a pizza-themed funny token on PP';

Providers​

ICP Wallet Provider​

Manages ICP wallet operations and canister interactions.

const { wallet } = await icpWalletProvider.get(runtime, message, state);

Common Issues & Troubleshooting​

  1. Identity Creation Failures

    • Ensure private key is exactly 32 bytes
    • Verify private key is properly hex-encoded
    • Check if private key has correct permissions

  2. Canister Interaction Issues

    • Verify canister ID is valid
    • Ensure proper network configuration (mainnet/testnet)
    • Check if canister is available and running

  3. Transaction Failures

    • Verify sufficient balance for operation
    • Check cycle balance for canister calls
    • Ensure proper fee calculation

  4. Authentication Problems

    • Verify identity is properly initialized
    • Check if agent is configured correctly
    • Ensure proper network connectivity

Security Best Practices​

  1. Key Management

    • Never expose private keys in code or logs
    • Use environment variables for sensitive data
    • Rotate keys periodically
    • Use separate keys for development and production

  2. Identity Security

    • Create separate identities for different purposes
    • Limit identity permissions appropriately
    • Monitor identity usage and access patterns

  3. Canister Interaction Safety

    • Validate all input parameters
    • Implement proper error handling
    • Use query calls when possible to save cycles
    • Implement rate limiting for calls

  4. Network Security

    • Use secure endpoints
    • Implement proper timeout handling
    • Validate responses from canisters
    • Handle network errors gracefully

API Reference​

Types​

// Token Creation Arguments
export type CreateMemeTokenArg = {
  name: string;
  symbol: string;
  description: string;
  logo: string;
  twitter?: string;
  website?: string;
  telegram?: string;
};

// ICP Configuration
export interface ICPConfig {
  privateKey: string;
  network?: 'mainnet' | 'testnet';
}

Utilities​

The plugin provides various utility functions for:

  • Principal/Account conversions
  • Candid type handling
  • Result/Variant unwrapping
  • Array/Hex conversions

Helper Functions​

// Convert principal to account
principal2account(principal: string, subaccount?: number[]): string

// Check if text is valid principal
isPrincipalText(text: string): boolean

// Create anonymous actor for public queries
createAnonymousActor<T>(idlFactory, canisterId, host?)

Development Guide​

Setting Up Development Environment​

  1. Clone the repository
  2. Install dependencies:
bun install
  1. Build the plugin:
bun run build
  1. Run tests:
bun test

Testing with Local Replica​

  1. Start a local Internet Computer replica
  2. Configure environment for local testing
  3. Use test identities for development

Dependencies​

  • @dfinity/agent: ^2.1.3
  • @dfinity/candid: ^2.1.3
  • @dfinity/identity: ^2.1.3
  • @dfinity/principal: ^2.1.3
  • @elizaos/core: workspace:*

Future Enhancements​

  • Support for additional canister standards
  • Enhanced error handling and recovery
  • Batch transaction support
  • Advanced identity management
  • Improved cycle management
  • Extended canister interaction capabilities

Contributing​

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Credits​

This plugin integrates with and builds upon several key technologies:

Special thanks to:

  • The DFINITY Foundation for developing the Internet Computer
  • The ICP Developer community
  • The DFINITY SDK maintainers
  • The PickPump team for meme token infrastructure
  • The Eliza community for their contributions and feedback

For more information about Internet Computer capabilities:

License​

This plugin is part of the Eliza project. See the main project repository for license information.