Skip to content

Latest commit

 

History

History
235 lines (163 loc) · 5.51 KB

README.md

File metadata and controls

235 lines (163 loc) · 5.51 KB

@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
  1. Build the plugin:
pnpm run build
  1. 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:

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.