@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

pnpm 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:

pnpm install

3. Build the plugin:

pnpm run build

4. Run tests:

pnpm 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:

• Internet Computer: Decentralized cloud computing platform
• @dfinity/agent: ICP HTTP client and agent
• @dfinity/candid: Candid interface description language
• @dfinity/principal: Principal identifier handling
• @dfinity/identity: Identity management

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:

• ICP Documentation
• DFINITY Developer Portal
• ICP Dashboard
• Candid Documentation

License

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