🚀 aengel 2.0 , an autonomous entity on aeternity blockchain

🌟 This project is proudly supported by the Aeternity Foundation - Advancing decentralized communication technologies through innovative AI solutions.

@elizaos/plugin-aeternity

An advanced æeternity blockchain plugin for Eliza OS that provides intelligent tipping, wallet management, and autonomous community engagement features.

Current Status: 🎉 Aengel is Successfully Operational! All core features are working including intelligent username extraction, LLM-based contribution analysis, sophisticated anti-abuse detection, and successful AE transactions on testnet.

Project Status: Production Ready (Phase 1 Complete)

Aengel has successfully completed Phase 1 development and is operational with all core features working:

✅ Phase 1: Core Intelligence & Tipping (COMPLETE)

✅ Intelligent Username Extraction: Fixed placeholder issues, correctly extracts usernames like 'alexshelpin'
✅ LLM vs Manual Detection: Properly distinguishes between AI-generated and manual tipping commands
✅ Advanced Anti-Abuse System: 32.5% risk assessment working with behavioral pattern analysis
✅ Successful Transaction Processing: Confirmed working with transaction hash th_2F5Rh1H5WNA1A278poYYAauMojnrRzdVPGaTC6hTjLmy2fpXbW
✅ Address Resolution: Automatic address lookup and registration system
✅ Content Tracking: Enhanced metadata recording for abuse prevention

🔧 Known Issues Being Addressed

Duplicate Transaction Prevention: Currently implementing enhanced conversation context tracking to prevent duplicate tips (identified from user feedback "But you did it twice !!!")

⏳ Phase 2: Advanced Features (In Development)

Proactive ecosystem catalyst
Adaptive learning system
Context-aware conversation analysis
Multi-modal contribution recognition

📅 Phase 3: Ecosystem Integration (Planned)

Cross-platform intelligence (GitHub, Discord, Twitter)
Reputation and achievement systems
Predictive community health monitoring
Real-time analytics dashboard

Latest Test Results

Recent Successful Transaction:

Amount: 5 AE
Recipient: alexshelpin (ak_yGsU9y5ahk9u6b8Lbz3DjWLiMRVj1tZeh31cqZz57h6yewCdL)
Transaction Hash: th_2F5Rh1H5WNA1A278poYYAauMojnrRzdVPGaTC6hTjLmy2fpXbW
Analysis Type: LLM_ANALYZED
Risk Assessment: 32.5% (approved)
Reason: "Insightful explanation of Hyperchains and Sophia's role in enhancing scalability and security for decentralized applications"

Overview

Aengel is an intelligent autonomous entity that operates on the Aeternity blockchain, designed to foster community engagement through strategic tipping and contribution recognition. It serves as a foundational component of Eliza OS, bridging Aeternity blockchain capabilities with advanced AI-driven community management.

Features

🧠 Intelligent Contribution Analysis

LLM-Powered Assessment: Advanced natural language processing to evaluate contribution quality
Multi-Factor Analysis: Considers technical depth, community value, innovation, and educational content
Risk Assessment: Sophisticated anti-abuse detection with behavioral pattern analysis
Context Awareness: Understands conversation flow and timing for appropriate responses
Adaptive Learning: Improves decision-making based on community feedback and outcomes

🔒 Advanced Security & Anti-Abuse

Behavioral Pattern Analysis: Detects tip farming through rapid successive similar contributions
Content Manipulation Detection: Identifies keyword stuffing, artificial complexity, and gaming attempts
Semantic Similarity Analysis: Prevents duplicate content exploitation using advanced semantic comparison
Frequency Analysis: Multi-timeframe monitoring to prevent spam farming
Gaming Pattern Detection: Recognizes explicit tip requests and manipulation attempts

💰 Wallet Management

Private Key Encryption: Secure private key storage with advanced encryption
Key Generation: Secure key pair generation with customizable security levels
Address Management: Comprehensive Aeternity address handling
Balance Tracking: Real-time account balance monitoring
Transaction State Management: Comprehensive tracking to prevent duplicates

🚀 Transaction Operations

AE Transfers: Secure native AE token transfers with confirmation tracking
Transaction Monitoring: Real-time status updates and confirmation tracking
Fee Optimization: Intelligent fee calculation for optimal transaction processing
Payload Management: Smart message handling with encoding optimization

📱 Telegram Integration

Intelligent User Tipping: Context-aware AE token distribution to valuable contributors
Seamless Address Registration: Automated address collection and verification via DM
Group Notifications: Real-time transaction announcements and status updates
Transaction History: Comprehensive tipping history with metadata
Personalized Messages: Custom message support with contribution descriptions

🎯 Proactive Community Building

Contribution Recognition: Automatically identifies and rewards valuable ecosystem contributions
Technical Discussion Amplification: Highlights and rewards high-quality technical insights
Innovation Incubation: Nurtures and supports innovative project ideas
Knowledge Aggregation: Creates connections between related discussions and contributors

Installation

npm install @elizaos/plugin-aeternity

Configuration

Configure the plugin by setting the following environment variables:

const aeternityEnvSchema = {
  // Wallet secret key (encrypted or hashed)
  WALLET_SECRET_KEY: string (optional),
  
  // Public address
  AE_WALLET_ADDRESS: string (optional),
  
  // Salt for encryption/decryption
  WALLET_SECRET_SALT: string (optional),
  
  // Network node URL
  AETERNITY_NODE_URL: string (default: 'https://testnet.aeternity.io'),
  
  // Compiler URL for smart contracts
  AETERNITY_COMPILER_URL: string (default: 'https://compiler.aeternity.io'),
  
  // Network ID
  AETERNITY_NETWORK_ID: string (default: 'ae_uat'),
  
  // Explorer API URL
  AETERNITY_EXPLORER_URL: string (default: 'https://explorer.aeternity.io/api'),
};

Usage

Basic Setup

import { initializeRuntime } from '@elizaos/core';
import { aeternityPlugin } from '@elizaos/plugin-aeternity';

// Initialize the plugin
const runtime = await initializeRuntime({
  plugins: [aeternityPlugin],
});

Intelligent Tipping

Aengel automatically analyzes contributions and determines appropriate tip amounts:

// Automatic contribution analysis and tipping
const result = await runtime.executeAction('TIP_TELEGRAM_USER', {
  recipientTelegramUsername: 'alexshelpin',
  contributionDescription: 'Insightful explanation of Hyperchains and Sophia smart contracts with technical depth and educational value',
  // Amount automatically calculated based on contribution analysis
});

console.log('Contribution Level:', result.contributionLevel); // "LLM_ANALYZED"
console.log('Tip Amount:', result.tipAmount); // e.g., "2.5"
console.log('Risk Assessment:', result.riskScore); // e.g., "32.5%"

Manual Tipping with Override

// Manual tip with explicit amount
const result = await runtime.executeAction('TIP_TELEGRAM_USER', {
  recipientTelegramUsername: 'developer_user',
  amountAE: 5.0, // Explicit amount overrides analysis
  message: 'Excellent work on the documentation!',
  messageContext: {
    chatId: 'your_group_chat_id',
    originalMessageId: 'message_id',
    replyToMessageId: 'reply_id'
  }
});

Address Management

// Automatic address resolution and registration
const result = await runtime.executeAction('PROCESS_ADDRESS_REGISTRATION', {
  username: 'new_contributor',
  address: 'ak_2buwmB9YM81jiXEECXcfpw6D7kp4RNixzDc5wWqHcqFymcacKP',
  chatId: 'your_group_chat_id'
});

How Intelligent Tipping Works

Contribution Detection - Aengel monitors conversations for valuable technical insights, educational content, and community contributions
Multi-Factor Analysis - Advanced LLM analysis evaluates technical depth, innovation, educational value, and community impact
Risk Assessment - Sophisticated anti-abuse detection prevents gaming, spam, and manipulation attempts
Contextual Decision - Considers conversation flow, user history, and community engagement patterns
Secure Transaction - Executes blockchain transaction with confirmation tracking and metadata recording
Community Notification - Announces successful tips with contribution recognition to foster positive community culture

Security & Anti-Abuse Features

Intelligent Pattern Recognition

Behavioral Analysis: Detects rapid successive similar contributions and unusual posting frequency
Content Manipulation: Identifies keyword stuffing, artificial complexity, and copy-paste patterns
Semantic Fingerprinting: Advanced similarity detection prevents duplicate content exploitation
Gaming Detection: Recognizes explicit tip requests and manipulation language

Risk Scoring System

Multi-Layer Analysis: Combines behavioral, semantic, frequency, and gaming pattern detection
Weighted Confidence: Sophisticated scoring with 60% abuse threshold
Historical Context: Considers user contribution history and engagement patterns
Real-time Adaptation: Continuously learns from community interactions

Transaction Security

Duplicate Prevention: Conversation-aware deduplication with timing analysis
State Management: Comprehensive transaction tracking and confirmation
Error Recovery: Graceful handling of network issues and transaction failures
Audit Trail: Complete logging for transparency and debugging

Telegram Bot Integration

Aengel seamlessly integrates with Telegram through ElizaOS:

Automatic Recognition: Monitors group conversations for valuable contributions
Intelligent Analysis: Evaluates contribution quality using advanced NLP
Secure Tipping: Processes transactions with comprehensive security checks
Community Engagement: Fosters positive community culture through recognition

Example character configuration:

{
  "name": "ængel",
  "description": "Autonomous Aeternity ecosystem catalyst",
  "capabilities": [
    "intelligent_contribution_analysis",
    "secure_ae_tipping",
    "anti_abuse_detection",
    "community_engagement"
  ],
  "clients": ["telegram"],
  "actions": ["TIP_TELEGRAM_USER", "PROCESS_ADDRESS_REGISTRATION"]
}

Development Status & Testing

Successful Test Results

✅ Username extraction working correctly (no more placeholder issues)
✅ LLM vs manual detection functioning properly
✅ Anti-abuse system operational (32.5% risk assessment approved)
✅ Transaction processing confirmed working on testnet
✅ Address resolution and content tracking functional

Current Enhancements

🔧 Implementing enhanced duplicate prevention system
🔧 Advanced conversation context tracking
🔧 Improved transaction state management

Testing Environment

# Test the plugin in development
pnpm tsx pre-prod-test.ts

# Run comprehensive tests
pnpm test

Phase 2: Intelligence Amplification (Weeks 2-3)

Proactive Ecosystem Catalyst: Transform from reactive to proactive community building
Technical Discussion Amplifier: Automatically identify and reward high-quality technical insights
Innovation Incubator: Spot and nurture innovative project ideas with strategic tipping
Community Connector: Facilitate introductions between complementary skill sets
Adaptive Learning System: Continuous improvement through interaction analysis

Phase 3: Advanced Community Features (Weeks 4-5)

Multi-Modal Contribution Recognition: Expand beyond text to diverse contribution types
Reputation & Achievement System: Build long-term community engagement through recognition
Cross-Platform Intelligence: GitHub, Discord, Twitter integration
Predictive Community Health: Monitor and optimize community dynamics

Phase 4: Ecosystem Integration (Weeks 6-7)

Ecosystem-Wide Activity Correlation: Connect activities across all Aeternity platforms
Advanced User Profiling: Comprehensive contributor assessment and specialization tracking
Intervention Systems: Automated community health optimization
Real-Time Analytics Dashboard: Comprehensive monitoring and insights

Phase 5: Advanced Analytics & Optimization (Week 8)

Autonomous Strategy Adaptation: Self-improving system based on outcomes
Performance Optimization: Advanced algorithms and caching strategies
Comprehensive Documentation: Full system documentation and guides

Pre-Production Environment

The plugin is available for pre-production testing. We've implemented:

Mock Client Mode: For development and testing without real blockchain transactions
Testing Suite: Comprehensive tests for all functionality
Error Handling: Graceful error handling for development and testing
Environment Variables: Configuration for different environments

To run the pre-production tests:

pnpm tsx pre-prod-test.ts

This will test all the core functionality in a simulated environment without making actual blockchain transactions.

Production Deployment Requirements

To deploy this plugin in a production environment, the following steps are required:

Secure Key Management:
- Implement proper private key encryption with strong salts
- Consider using a Hardware Security Module (HSM) or Trusted Execution Environment (TEE)
- Never store unencrypted keys in environment variables or config files
Blockchain Integration:
- Configure connection to a reliable Aeternity node
- Set up monitoring for node connectivity and blockchain health
- Implement transaction receipt verification and confirmation monitoring
Security Considerations:
- Implement rate limiting to prevent abuse
- Add IP-based restrictions for sensitive operations
- Set up logging and alerting for unusual activities
- Consider multi-signature wallets for large transaction amounts
Testing Process:
- Test transactions on testnet before mainnet deployment
- Perform security audits of key handling code
- Conduct penetration testing of the API endpoints

By completing these steps, the plugin will be ready for secure production deployment with real transactions on the Aeternity blockchain.

Overview

The Aeternity plugin serves as a foundational component of Eliza OS, bridging Aeternity blockchain capabilities with the Eliza ecosystem. It provides crucial services for secure private key management, transaction operations, and Telegram tipping features enabling agents to reward valuable community contributions.

Features

Wallet Management

Private Key Encryption: Secure private key storage using encryption
Key Generation: Secure key pair generation with customizable security levels
Address Management: Manage Aeternity addresses
Balance Tracking: Monitor account balances

Transaction Operations

AE Transfers: Send and receive native AE tokens securely
Transaction Tracking: Monitor transaction status and confirmations
Fee Estimation: Calculate appropriate transaction fees

Telegram Integration

User Tipping: Send AE tokens to Telegram users
Address Registration: Request and store Aeternity addresses from users via DM
Group Notifications: Notify groups when tips are sent and addresses are registered
Transaction Records: Track tipping history
Custom Messages: Include personalized messages with tips

Contribution Analysis

Automated Evaluation: Analyze the description of a contribution to determine its value
Suggested Tip Amounts: Get recommended tip amounts based on contribution level
Contribution Levels: Support for minor, helpful, valuable, major, and exceptional contributions
Contribution Types: Categorization of contributions (code, tutorial, Q&A, etc.)
Customizable Amounts: Adjust tip amounts for each contribution level
Confidence Scoring: Assess the reliability of contribution analysis
Automatic Tipping: Determine tip amount automatically without specifying an explicit amount

Installation

npm install @elizaos/plugin-aeternity

Configuration

Configure the plugin by setting the following environment variables:

const aeternityEnvSchema = {
  // Wallet secret key (encrypted or hashed)
  WALLET_SECRET_KEY: string (optional),
  
  // Public address
  AE_WALLET_ADDRESS: string (optional),
  
  // Salt for encryption/decryption
  WALLET_SECRET_SALT: string (optional),
  
  // Network node URL
  AETERNITY_NODE_URL: string (default: 'https://mainnet.aeternity.io'),
  
  // Compiler URL for smart contracts
  AETERNITY_COMPILER_URL: string (default: 'https://compiler.aeternity.io'),
  
  // Network ID
  AETERNITY_NETWORK_ID: string (default: 'ae_mainnet'),
  
  // Explorer API URL
  AETERNITY_EXPLORER_URL: string (default: 'https://explorer.aeternity.io/api'),
};

Usage

Basic Setup

import { initializeRuntime } from 'elizaos';
import { aeternityPlugin } from '@elizaos/plugin-aeternity';

// Initialize the plugin
const runtime = await initializeRuntime({
  plugins: [aeternityPlugin],
});

Key Management

Generate a new key pair:

// Example usage
const result = await runtime.executeAction('GENERATE_KEY_PAIR', {
  password: 'securePassword123',
  securityLevel: 'high', // 'low', 'medium', 'high', or 'tee'
});

console.log('Public Key:', result.publicKey);
console.log('Encrypted Private Key:', result.encryptedPrivateKey);

Transfer AE Tokens

Send AE tokens to another address:

// Example usage
const result = await runtime.executeAction('TRANSFER_AE', {
  recipient: 'ak_recipientAddressHere',
  amount: '1.5', // Amount in AE
  options: {
    fee: '0.00002', // Optional custom fee
  },
});

console.log('Transaction Hash:', result.hash);

Tip Telegram Users

Send AE tokens as tips to Telegram users:

// Example usage - with direct wallet address
const result = await runtime.executeAction('TIP_TELEGRAM_USER', {
  recipient: 'ak_recipientAddressHere', // Recipient wallet address
  amount: '0.1', // Amount in AE
  message: 'Thanks for your helpful answer!', // Optional message
  chatId: 'your_group_chat_id', // Optional group chat ID for notifications
});

// With Telegram username
const result = await runtime.executeAction('TIP_TELEGRAM_USER', {
  recipient: '@telegramUsername', // Telegram username
  amount: '0.1', // Amount in AE
  message: 'Thanks for your helpful answer!', // Optional message
  chatId: 'your_group_chat_id', // Optional group chat ID for notifications
});

If the user hasn't registered an address yet:

The bot will send a DM to the user requesting their Aeternity address
The bot will send a message in the group chat notifying the user to check their DMs
The tip will be stored as "pending" (Note: pending tip processing is currently disabled)
When the user responds with their address, the bot will register the address

Process Address Registration

When a user sends their Aeternity address, register it:

// Example usage
const result = await runtime.executeAction('PROCESS_ADDRESS_REGISTRATION', {
  username: 'telegramUsername', // Without @ prefix
  address: 'ak_recipientAddressHere',
  chatId: 'your_group_chat_id', // Optional group chat ID for notifications
});

console.log('Registration successful:', result.success);

Analyze Contributions

Analyze a contribution description to determine its level and recommended tip amount:

// Example usage
const result = await runtime.executeAction('ANALYZE_CONTRIBUTION', {
  description: 'This detailed explanation about smart contract security was very helpful and saved me hours of debugging.',
  contributor: 'expert_user', // Optional
  type: 'TECHNICAL_EXPLANATION', // Optional
  context: 'In response to a question about contract vulnerabilities' // Optional
});

console.log('Contribution Level:', result.analysis.level);
console.log('Suggested Tip Amount:', result.suggestedTipAmount);
console.log('Confidence Score:', result.analysis.confidenceScore);

You can also use contribution descriptions when tipping, without specifying an amount:

// Tip with auto-calculated amount based on contribution description
const result = await runtime.executeAction('TIP_TELEGRAM_USER', {
  recipient: '@expert_user',
  contributionDescription: 'Great explanation of how state channels work. The examples were very clear and helped me understand the concept completely.',
  message: 'Thank you for your detailed explanation!',
  chatId: 'your_group_chat_id' // Optional
});

console.log('Tip Amount:', result.tipAmount);
console.log('Contribution Level:', result.contributionLevel);

Customize Tip Amounts

You can customize the tip amounts for each contribution level:

// Get the contribution analyzer provider
const contributionAnalyzer = await runtime.getProvider('contributionAnalyzer');

// Set custom tip amounts
contributionAnalyzer.setTipAmounts({
  minor: '0.2',        // 0.2 AE for minor contributions
  helpful: '0.75',     // 0.75 AE for helpful contributions
  valuable: '2.0',     // 2.0 AE for valuable contributions
  major: '5.0',        // 5.0 AE for major contributions
  exceptional: '10.0'  // 10.0 AE for exceptional contributions
});

Telegram Bot Integration

To use this plugin with a Telegram bot for tipping:

Use the ElizaOS Telegram client
Configure the bot to recognize tipping commands
The plugin automatically handles message processing for address registration
Call the TIP_TELEGRAM_USER action when appropriate, providing the group chat ID

Example character configuration:

{
  "name": "AeTipBot",
  "capabilities": ["can_tip_users", "can_analyze_contributions"],
  "clients": ["telegram"],
  "actions": [
    {
      "name": "TIP_TELEGRAM_USER",
      "description": "Tip a user with AE tokens",
      "plugin": "aeternity"
    },
    {
      "name": "PROCESS_ADDRESS_REGISTRATION",
      "description": "Register an Aeternity address for a user",
      "plugin": "aeternity" 
    },
    {
      "name": "ANALYZE_CONTRIBUTION",
      "description": "Analyze a contribution to determine its value and appropriate tip amount",
      "plugin": "aeternity"
    }
  ]
}

Development Notes

TypeScript Errors

When developing the plugin, you may encounter these TypeScript errors:

Missing elizaos Module

Error: Cannot find module 'elizaos' or its corresponding type declarations

This error is expected during development as the 'elizaos' module is only available in the ElizaOS runtime environment. We've added mock type definitions in the src/types directory to help with development.
ContributionAnalyzerService Constructor Parameters

Error: Expected 1-2 arguments, but got 0

The ContributionAnalyzerService requires the ElizaOS runtime to be passed in. During development, this parameter is optional to allow for testing, but in the actual ElizaOS environment, it's required.
Action Type Issues

Error: Type 'Action' is not generic

The Action type in ElizaOS is being updated. The plugin currently implements a modified version in the index.ts file to handle this.

Pre-production Testing

You can test the plugin in a pre-production environment using the provided test scripts:

# Install dependencies
pnpm install

# Run the Telegram tipping test script
pnpm tsx test-telegram-tip.ts

The test script simulates:

Address registration for Telegram users
Sending tips to registered users
Handling unregistered users
Using contribution-based tip amounts

Note: The test runs in mock mode, simulating blockchain transactions without requiring a real blockchain connection.

Production Deployment

For deploying to a production environment, please refer to the Production Guide, which covers:

Security considerations
Environment configuration
Deployment steps
Production features and monitoring
Backup and recovery procedures
Troubleshooting common issues

Provider Access

Access the wallet provider directly:

// Get the wallet provider
const walletProvider = await runtime.getProvider('aeternityWallet');

// Get wallet address
const address = await walletProvider.getAddress();

// Get wallet balance
const balance = await walletProvider.getBalance();

console.log(`Address: ${address}, Balance: ${balance} AE`);

Access the user address service:

// Get the user address service
const userAddressService = await runtime.getProvider('aeternityUserAddress');

// Get address for a Telegram user
const address = userAddressService.getAddress('telegramUsername');

// Store an address for a user
userAddressService.storeAddress('telegramUsername', 'ak_address');

// Check pending tips
const pendingTips = userAddressService.getPendingTips('telegramUsername');

How Telegram Tipping Works

User Makes Valuable Contribution - Someone in your Telegram community shares helpful information
Bot Sends Tip - Your bot decides to tip this user with TIP_TELEGRAM_USER action
Group Notification - Bot announces in the group chat that the user has been tipped and should check their DMs
Address Request - The bot sends the user a DM requesting their Aeternity address
User Registers Address - User replies with their Aeternity address
Address Confirmed - Bot announces in the group that the user has registered their address
Future Tips - Next time the user is tipped, their address is already known and tip is processed directly

Group Chat Notifications

The plugin sends the following notifications to group chats:

When Tipping a User Without Address:

@username, someone wants to tip you with AE tokens! I've sent you a direct message - please check your DMs and reply with your Aeternity address to receive your tip.

When a User Registers an Address:

@username has registered their Aeternity address and is now ready to receive tips! 🎉

When Sending a Tip to a User with Registered Address:

Tip sent! @username has received 0.1 AE with message: "Thanks for your help!" (TX: ak_2tfrsj5...)

Security Best Practices

Private Key Storage
- Always encrypt private keys when storing
- Use environment variables or secure secret storage
- Consider hardware wallets for production use
Transaction Verification
- Verify transaction parameters before signing
- Implement confirmation steps for high-value transactions
- Use simulation to preview transaction outcomes
Network Configuration
- Use secure, trusted RPC endpoints
- Consider private nodes for production environments
- Implement connection fallbacks

Development Roadmap

Current (Phase 1)

✅ Private key management
✅ AE transfers
✅ Telegram tipping interface
✅ Address registration via DM
⏳ Pending tip handling (temporarily disabled)
✅ Group chat notifications
✅ Contribution analysis and automatic tip amount determination

Next (Phase 2) - Coming Soon

⏳ AEX-9 token deployment
⏳ Token transfers
⏳ Token balance management

Future (Phase 3)

📅 Superhero DEX integration
📅 Price fetching
📅 Trading operations

Troubleshooting

Common Issues

Connection Errors

Error: Failed to connect to Aeternity node

Verify network connectivity
Check node URL configuration
Ensure node is operational

Transaction Failures

Error: Transaction rejected

Check account balance
Verify recipient address format
Ensure proper fee configuration

Key Management Issues

Error: Failed to decrypt private key

Verify encryption password is correct
Check salt configuration
Ensure private key format is valid

Telegram Integration Issues

Error: Could not request address from @username

Ensure Telegram client is properly configured
Verify the user accepts DMs from bots
Check if the username exists

Action Type Errors

TypeError: action.validate is not a function

This is a known issue related to action type definitions
The current fix is implemented in index.ts

Development

For local development:

# Clone the repository
git clone https://github.com/your-username/plugin-aeternity.git

# Install dependencies
cd plugin-aeternity
npm install

# Build the plugin
npm run build

# Run tests
npm test

Credits

This plugin integrates with and builds upon several key technologies:

Aeternity - The core blockchain platform
aepp-sdk - Official Aeternity JavaScript SDK
crypto-js - Encryption library

Special thanks to:

The Aeternity developer community
The Eliza community for their contributions and feedback

For more information about Aeternity blockchain capabilities:

License

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

SDK Version Compatibility

This plugin is compatible with @aeternity/aepp-sdk version 13.2.2. Using other versions may require adjustments to the implementation, particularly in the wallet provider and transaction services.

The plugin has been updated to work with the changes in the Aeternity SDK, including:

Using the new constructor pattern for MemoryAccount, Node, and Universal
Implementing required account methods like signTypedData and signDelegation
Supporting the sk_ prefix format for secret keys

Dependencies and Compatibility

Aeternity SDK Integration

This plugin is compatible with @aeternity/aepp-sdk version 13.2.2. Using other versions may require adjustments to the implementation, particularly in the wallet provider and transaction services.

When developing locally, you have two options:

Install the SDK from npm: pnpm add @aeternity/[email protected]

Clone and link the SDK repository:

git clone https://github.com/aeternity/aepp-sdk-js.git
cd aepp-sdk-js
npm install
npm run build
cd /path/to/your/project
mkdir -p node_modules/@aeternity
ln -s /path/to/aepp-sdk-js node_modules/@aeternity/aepp-sdk

TypeScript Support

The plugin includes TypeScript declarations for the Aeternity SDK, which may be missing in the SDK itself. These declarations are located in src/types/aeternity-sdk.d.ts and ensure proper type checking for the SDK functions.

Mock Mode for Development

The plugin includes a mock mode for development that simulates Aeternity blockchain interactions without making actual transactions. This is useful for testing without requiring real tokens or network connectivity.

In the walletProvider.ts file, we automatically fallback to mock mode if the SDK initialization fails, allowing development and testing to continue without requiring a proper SDK setup.

License

ISC

Based on ElizaOS 🤖

📑 Technical Report | 📖 Documentation | 🎯 Examples

📖 README Translations

🚩 Overview

✨ Features

🛠️ Full-featured Discord, X (Twitter) and Telegram connectors
🔗 Support for every model (Llama, Grok, OpenAI, Anthropic, Gemini, etc.)
👥 Multi-agent and room support
📚 Easily ingest and interact with your documents
💾 Retrievable memory and document store
🚀 Highly extensible - create your own actions and clients
📦 Just works!

Video Tutorials

AI Agent Dev School

🎯 Use Cases

🤖 Chatbots
🕵️ Autonomous Agents
📈 Business Process Handling
🎮 Video Game NPCs
🧠 Trading

🚀 Quick Start

Prerequisites

Note for Windows Users: WSL 2 is required.

Use the Starter (Recommended for Agent Creation)

Full steps and documentation can be found in the Eliza Starter Repository.

git clone https://github.com/elizaos/eliza-starter.git
cd eliza-starter
cp .env.example .env
pnpm i && pnpm build && pnpm start

Manually Start Eliza (Only recommended for plugin or platform development)

Checkout the latest release

# Clone the repository
git clone https://github.com/elizaos/eliza.git

# This project iterates fast, so we recommend checking out the latest release
git checkout $(git describe --tags --abbrev=0)
# If the above doesn't checkout the latest release, this should work:
# git checkout $(git describe --tags `git rev-list --tags --max-count=1`)

If you would like the sample character files too, then run this:

# Download characters submodule from the character repos
git submodule update --init

Edit the .env file

Copy .env.example to .env and fill in the appropriate values.

cp .env.example .env

Note: .env is optional. If you're planning to run multiple distinct agents, you can pass secrets through the character JSON

Start Eliza

pnpm i
pnpm build
pnpm start

# The project iterates fast, sometimes you need to clean the project if you are coming back to the project
pnpm clean

Interact via Browser

Once the agent is running, you should see the message to run "pnpm start:client" at the end.

Open another terminal, move to the same directory, run the command below, then follow the URL to chat with your agent.

pnpm start:client

Then read the Documentation to learn how to customize your Eliza.

Automatically Start Eliza

The start script provides an automated way to set up and run Eliza:

sh scripts/start.sh

For detailed instructions on using the start script, including character management and troubleshooting, see our Start Script Guide.

Note: The start script handles all dependencies, environment setup, and character management automatically.

Modify Character

Open packages/core/src/defaultCharacter.ts to modify the default character. Uncomment and edit.
To load custom characters:
- Use pnpm start --characters="path/to/your/character.json"
- Multiple character files can be loaded simultaneously
Connect with X (Twitter)
- change "clients": [] to "clients": ["twitter"] in the character file to connect with X

Add more plugins

run npx elizaos plugins list to get a list of available plugins or visit https://elizaos.github.io/registry/
run npx elizaos plugins add @elizaos-plugins/plugin-NAME to install the plugin into your instance

Additional Requirements

You may need to install Sharp. If you see an error when starting up, try installing it with the following command:

pnpm install --include=optional sharp

Using Your Custom Plugins

Plugins that are not in the official registry for ElizaOS can be used as well. Here's how:

Installation

Upload the custom plugin to the packages folder:

packages/
├─plugin-example/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts        # Main plugin entry
│   ├── actions/        # Custom actions
│   ├── providers/      # Data providers
│   ├── types.ts        # Type definitions
│   └── environment.ts  # Configuration
├── README.md
└── LICENSE

Add the custom plugin to your project's dependencies in the agent's package.json:

{
  "dependencies": {
    "@elizaos/plugin-example": "workspace:*"
  }
}

Import the custom plugin to your agent's character.json

  "plugins": [
    "@elizaos/plugin-example",
  ],

Start Eliza with Gitpod

Deploy Eliza in one click

Use Fleek to deploy Eliza in one click. This opens Eliza to non-developers and provides the following options to build your agent:

Start with a template
Build characterfile from scratch
Upload pre-made characterfile

Click here to get started!

Community & contact

GitHub Issues. Best for: bugs you encounter using Eliza, and feature proposals.
elizaOS Discord. Best for: hanging out with the elizaOS technical community
DAO Discord. Best for: hanging out with the larger non-technical community

Citation

We now have a paper you can cite for the Eliza OS:

@article{walters2025eliza,
  title={Eliza: A Web3 friendly AI Agent Operating System},
  author={Walters, Shaw and Gao, Sam and Nerd, Shakker and Da, Feng and Williams, Warren and Meng, Ting-Chien and Han, Hunter and He, Frank and Zhang, Allen and Wu, Ming and others},
  journal={arXiv preprint arXiv:2501.06781},
  year={2025}
}

Contributors

Star History

🛠️ System Requirements

Minimum Requirements

CPU: Dual-core processor
RAM: 4GB
Storage: 1GB free space
Internet connection: Broadband (1 Mbps+)

Software Requirements

Python 2.7+ (3.8+ recommended)
Node.js 23+
pnpm
Git

Optional Requirements

GPU: For running local LLM models
Additional storage: For document storage and memory
Higher RAM: For running multiple agents

📁 Project Structure

eliza/
├── packages/
│   ├── core/           # Core Eliza functionality
│   ├── clients/        # Client implementations
│   └── actions/        # Custom actions
├── docs/              # Documentation
├── scripts/           # Utility scripts
└── examples/          # Example implementations

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

Fork the repository
Create a new branch: git checkout -b feature/your-feature-name
Make your changes
Run tests: pnpm test
Submit a pull request

Types of Contributions

🐛 Bug fixes
✨ New features
📚 Documentation improvements
🌍 Translations
🧪 Test improvements

Code Style

Follow the existing code style
Add comments for complex logic
Update documentation for changes
Add tests for new features

IDE Configuration

VS Code

Use the provided .vscode/settings.json. TypeScript server will be configured automatically.

JetBrains IDEs (WebStorm, IntelliJ)

Open tsconfig.ide.json as the project's TypeScript configuration.

Other IDEs

Configure your TypeScript Language Server to:

Use the workspace TypeScript version (5.6.3)
Use non-relative imports
Skip type checking in node_modules

Build System

ElizaOS now features a standardized build system that enables clean, reproducible builds across all packages. To build the entire project:

./clean-build.sh

The build system follows these steps:

Checks for circular dependencies
Standardizes package configurations
Builds packages in dependency order
Verifies the built packages can be imported correctly

For more details on the build system, see Build System Documentation.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.backups		.backups
.cursor/rules		.cursor/rules
.devcontainer		.devcontainer
.github		.github
.patches		.patches
Eliza		Eliza
agent-test		agent-test
agent		agent
characters		characters
client		client
cursor_rules		cursor_rules
data		data
docs		docs
i18n/readme		i18n/readme
packages		packages
patches		patches
ports		ports
relay-server		relay-server
releases		releases
scripts		scripts
src		src
test-build		test-build
test-types		test-types
tests		tests
tmp		tmp
tools		tools
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
.gitpod.yml		.gitpod.yml
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
ANTI_ABUSE_FIXES_IMPLEMENTED.md		ANTI_ABUSE_FIXES_IMPLEMENTED.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CRITICAL_TIP_SYSTEM_FIXES.md		CRITICAL_TIP_SYSTEM_FIXES.md
DIRECT_MESSAGE_TIP_FIX.md		DIRECT_MESSAGE_TIP_FIX.md
Dockerfile		Dockerfile
Dockerfile.docs		Dockerfile.docs
INTELLIGENT_TIP_SYSTEM_FIXES.md		INTELLIGENT_TIP_SYSTEM_FIXES.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SOLUTION.md		SOLUTION.md
aengel_status.md		aengel_status.md
agent-wrapper.mjs		agent-wrapper.mjs
agent.log		agent.log
biome.json		biome.json
build-all.sh		build-all.sh
build-core.sh		build-core.sh
character-actions-patch.mjs		character-actions-patch.mjs
check-pending-tips.js		check-pending-tips.js
clean-test-expert-fix.log		clean-test-expert-fix.log
cleanup-agents.sh		cleanup-agents.sh
codecov.yml		codecov.yml
commitlint.config.js		commitlint.config.js
d3b358b8-0785-59fe-a4bf-9c817acdd674.sqlite-shm		d3b358b8-0785-59fe-a4bf-9c817acdd674.sqlite-shm
d3b358b8-0785-59fe-a4bf-9c817acdd674.sqlite-wal		d3b358b8-0785-59fe-a4bf-9c817acdd674.sqlite-wal
debug-aeternity-plugin.js		debug-aeternity-plugin.js
direct-action-fix.js		direct-action-fix.js
direct-fix.js		direct-fix.js
direct-generation-patch.js		direct-generation-patch.js
direct-llm-patch.js		direct-llm-patch.js
direct-model-patch.js		direct-model-patch.js
direct-patch.js		direct-patch.js
direct-settings-patch.js		direct-settings-patch.js
docker-compose-docs.yaml		docker-compose-docs.yaml
docker-compose.yaml		docker-compose.yaml
ecosystem.config.js		ecosystem.config.js
eliza.log		eliza.log
eliza.manifest.template		eliza.manifest.template
enhanced-agent-launcher.js		enhanced-agent-launcher.js
env-example.txt		env-example.txt
expert-questions-final.md		expert-questions-final.md
expert-questions.md		expert-questions.md
expert-runtime-fix-success.md		expert-runtime-fix-success.md
expert-status-update.md		expert-status-update.md
expert_database_consultation.md		expert_database_consultation.md
expert_followup_execution_issue.md		expert_followup_execution_issue.md
final-agent-start.sh		final-agent-start.sh
final-expert-questions.md		final-expert-questions.md
final-tip-test.md		final-tip-test.md
final_expert_validation_consultation.md		final_expert_validation_consultation.md
fix-action-injection-runtime.js		fix-action-injection-runtime.js
fix-action-injection.js		fix-action-injection.js
fix-actions.js		fix-actions.js
fix-and-run.sh		fix-and-run.sh
fix-character-actions.js		fix-character-actions.js
fix-core-models.js		fix-core-models.js
fix-deps.sh		fix-deps.sh
fix-eliza-config.js		fix-eliza-config.js
fix-models.js		fix-models.js
fix-monorepo-links.sh		fix-monorepo-links.sh
fix-monorepo.sh		fix-monorepo.sh
force-start-agent.js		force-start-agent.js
fresh-test.log		fresh-test.log
full-rebuild.sh		full-rebuild.sh

License

Shelpin/aengel_2.0

Folders and files

Latest commit

History

Repository files navigation

🚀 aengel 2.0 , an autonomous entity on aeternity blockchain

@elizaos/plugin-aeternity

Project Status: Production Ready (Phase 1 Complete)

✅ Phase 1: Core Intelligence & Tipping (COMPLETE)

🔧 Known Issues Being Addressed

⏳ Phase 2: Advanced Features (In Development)

📅 Phase 3: Ecosystem Integration (Planned)

Latest Test Results

Overview

Features

🧠 Intelligent Contribution Analysis

🔒 Advanced Security & Anti-Abuse

💰 Wallet Management

🚀 Transaction Operations

📱 Telegram Integration

🎯 Proactive Community Building

Installation

Configuration

Usage

Basic Setup

Intelligent Tipping

Manual Tipping with Override

Address Management

How Intelligent Tipping Works

Security & Anti-Abuse Features

Intelligent Pattern Recognition

Risk Scoring System

Transaction Security

Telegram Bot Integration

Development Status & Testing

Successful Test Results

Current Enhancements

Testing Environment

Phase 2: Intelligence Amplification (Weeks 2-3)

Phase 3: Advanced Community Features (Weeks 4-5)

Phase 4: Ecosystem Integration (Weeks 6-7)

Phase 5: Advanced Analytics & Optimization (Week 8)

Pre-Production Environment

Production Deployment Requirements

Overview

Features

Wallet Management

Transaction Operations

Telegram Integration

Contribution Analysis

Installation

Configuration

Usage

Basic Setup

Key Management

Transfer AE Tokens

Tip Telegram Users

Process Address Registration

Analyze Contributions

Customize Tip Amounts

Telegram Bot Integration

Development Notes

TypeScript Errors

Pre-production Testing

Production Deployment

Provider Access

How Telegram Tipping Works

Group Chat Notifications

Security Best Practices

Development Roadmap

Current (Phase 1)

Next (Phase 2) - Coming Soon

Future (Phase 3)

Troubleshooting

Common Issues

Development

Credits

License

SDK Version Compatibility

Packages