diff --git a/packages/plugin-0g/README.md b/packages/plugin-0g/README.md new file mode 100644 index 0000000000..4d6503fd38 --- /dev/null +++ b/packages/plugin-0g/README.md @@ -0,0 +1,212 @@ +# @elizaos/plugin-0g + +A plugin for storing data using the 0G protocol within the ElizaOS ecosystem. + +## Description +The 0G plugin enables seamless integration with the Zero Gravity (0G) protocol for decentralized file storage. It provides functionality to upload files to the 0G network. + +## Installation + +```bash +pnpm install @elizaos/plugin-0g +``` + +## Configuration + +The plugin requires the following environment variables to be set: +```typescript +ZEROG_INDEXER_RPC=<0G indexer RPC endpoint> +ZEROG_EVM_RPC=<0G EVM RPC endpoint> +ZEROG_PRIVATE_KEY= +ZEROG_FLOW_ADDRESS=<0G Flow contract address> +``` + +## Usage + +### Basic Integration + +```typescript +import { zgPlugin } from '@ai16z/plugin-0g'; +``` + + +### File Upload Example + +```typescript +// The plugin automatically handles file uploads when triggered +// through natural language commands like: + +"Upload my document.pdf" +"Store this image.png on 0G" +"Save my resume.docx to Zero Gravity" +``` + + +## API Reference + +### Actions + +#### ZG_UPLOAD + +Uploads files to the 0G network. + +**Aliases:** +- UPLOAD_FILE_TO_ZG +- STORE_FILE_ON_ZG +- SAVE_FILE_TO_ZG +- UPLOAD_TO_ZERO_GRAVITY +- STORE_ON_ZERO_GRAVITY +- SHARE_FILE_ON_ZG +- PUBLISH_FILE_TO_ZG + +**Input Content:** +```typescript +interface UploadContent { +filePath: string; +} +``` + + +## Common Issues & Troubleshooting + +1. **File Access Errors** + - Ensure the file exists at the specified path + - Check file permissions + - Verify the path is absolute or relative to the execution context + +2. **Configuration Issues** + - Verify all required environment variables are set + - Ensure RPC endpoints are accessible + - Confirm private key has sufficient permissions + +## Security Best Practices + +1. **Environment Variables** + - Never commit private keys to version control + - Use secure environment variable management + - Rotate private keys periodically + + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +4. Run the plugin: + +```bash +pnpm run dev +``` + +## Future Enhancements + +1. **Storage Management** + - Multi-file upload optimization + - Folder structure preservation + - Automated file replication + - Storage redundancy management + - File versioning system + - Archival storage options + +2. **Content Distribution** + - CDN integration + - Bandwidth optimization + - Geographic replication + - Edge caching support + - P2P content delivery + - Streaming optimization + +3. **Data Security** + - Enhanced encryption options + - Access control lists + - Key management system + - Data integrity verification + - Secure sharing mechanisms + - Privacy-preserving features + +4. **Integration Features** + - Additional blockchain support + - Cross-chain functionality + - Smart contract integration + - NFT storage optimization + - DApp integration tools + - API expansion + +5. **Performance Optimization** + - Upload speed improvements + - Parallel processing + - Compression algorithms + - Caching mechanisms + - Network optimization + - Resource management + +6. **Developer Tools** + - Enhanced SDK features + - CLI tool improvements + - Testing framework + - Monitoring dashboard + - Analytics integration + - Documentation generator + +7. **Content Management** + - Metadata management + - Search functionality + - Content indexing + - Tag system + - Collection management + - Batch operations + +8. **Protocol Features** + - Model service deployment + - KV store implementation + - State persistence + - Database integration + - Enhanced file metadata + - Protocol governance + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Zero Gravity (0G)](https://0g.xyz/): Decentralized file storage protocol +- [IPFS](https://ipfs.tech/): InterPlanetary File System +- [Filecoin](https://filecoin.io/): Decentralized storage network +- [Flow](https://flow.com/): Blockchain for open worlds +- [Content Addressable Storage](https://en.wikipedia.org/wiki/Content-addressable_storage): Storage architecture + +Special thanks to: +- The 0G Protocol development team +- The Protocol Labs team for IPFS +- The Filecoin Foundation +- The Flow blockchain team +- The decentralized storage community +- The Eliza community for their contributions and feedback + +For more information about 0G capabilities: +- [0G Documentation](https://docs.0g.xyz/) +- [IPFS Documentation](https://docs.ipfs.tech/) +- [Filecoin Docs](https://docs.filecoin.io/) +- [Flow Documentation](https://developers.flow.com/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-0g/readme.md b/packages/plugin-0g/readme.md deleted file mode 100644 index cf24cc94ce..0000000000 --- a/packages/plugin-0g/readme.md +++ /dev/null @@ -1,127 +0,0 @@ -# @elizaos/plugin-0g - -A plugin for storing data using the 0G protocol within the ElizaOS ecosystem. - -## Description -The 0G plugin enables seamless integration with the Zero Gravity (0G) protocol for decentralized file storage. It provides functionality to upload files to the 0G network. - -## Installation - -```bash -pnpm install @elizaos/plugin-0g -``` - -## Configuration - -The plugin requires the following environment variables to be set: -```typescript -ZEROG_INDEXER_RPC=<0G indexer RPC endpoint> -ZEROG_EVM_RPC=<0G EVM RPC endpoint> -ZEROG_PRIVATE_KEY= -ZEROG_FLOW_ADDRESS=<0G Flow contract address> -``` - -## Usage - -### Basic Integration - -```typescript -import { zgPlugin } from '@ai16z/plugin-0g'; -``` - - -### File Upload Example - -```typescript -// The plugin automatically handles file uploads when triggered -// through natural language commands like: - -"Upload my document.pdf" -"Store this image.png on 0G" -"Save my resume.docx to Zero Gravity" -``` - - -## API Reference - -### Actions - -#### ZG_UPLOAD - -Uploads files to the 0G network. - -**Aliases:** -- UPLOAD_FILE_TO_ZG -- STORE_FILE_ON_ZG -- SAVE_FILE_TO_ZG -- UPLOAD_TO_ZERO_GRAVITY -- STORE_ON_ZERO_GRAVITY -- SHARE_FILE_ON_ZG -- PUBLISH_FILE_TO_ZG - -**Input Content:** -```typescript -interface UploadContent { -filePath: string; -} -``` - - -## Common Issues & Troubleshooting - -1. **File Access Errors** - - Ensure the file exists at the specified path - - Check file permissions - - Verify the path is absolute or relative to the execution context - -2. **Configuration Issues** - - Verify all required environment variables are set - - Ensure RPC endpoints are accessible - - Confirm private key has sufficient permissions - -## Security Best Practices - -1. **Environment Variables** - - Never commit private keys to version control - - Use secure environment variable management - - Rotate private keys periodically - - -## Development Guide - -### Setting Up Development Environment - -1. Clone the repository -2. Install dependencies: - -```bash -pnpm install -``` - -3. Build the plugin: - -```bash -pnpm run build -``` - -4. Run the plugin: - -```bash -pnpm run dev -``` - -## Future Enhancements - -- Model service deployment on 0G serving network -- 0G KV store for plugin state persistence -- Upload history and file metadata storage -- 0G as a database option for Eliza state storage -- Enhanced file path and context extraction - -## Contributing - -Contributions are welcome! Please see our contributing guidelines for more details. - -## License - -[License information needed] \ No newline at end of file diff --git a/packages/plugin-3d-generation/README.md b/packages/plugin-3d-generation/README.md new file mode 100644 index 0000000000..c10c34d548 --- /dev/null +++ b/packages/plugin-3d-generation/README.md @@ -0,0 +1,208 @@ +# @elizaos/plugin-3d-generation + +A plugin for generating 3D models using the FAL.ai API within the ElizaOS ecosystem. + +## Description +The 3D Generation plugin enables AI-powered creation of 3D models through FAL.ai's services. It provides functionality to generate 3D models from text descriptions and save them locally. + +## Installation + +```bash +pnpm install @elizaos/plugin-3d-generation +``` + +## Configuration + +The plugin requires the following environment variable or runtime setting to be set: +```typescript +FAL_API_KEY= +``` + +## Usage + +### Basic Integration + +```typescript +import { ThreeDGenerationPlugin } from '@elizaos/plugin-3d-generation'; +``` + +### Model Generation Examples + +```typescript +// The plugin responds to natural language commands like: + +"Generate a 3D object of a cat playing piano" +"Create a 3D object of an anime character Goku" +"Make a 3D model of [your description]" +``` + +## API Reference + +### Actions + +#### GENERATE_3D + +Generates 3D models based on text descriptions. + +**Aliases:** +- 3D_GENERATION +- 3D_GEN +- CREATE_3D +- MAKE_3D +- TEXT23D +- TEXT_TO_3D +- 3D_CREATE +- 3D_MAKE + +**Default Configuration:** +```typescript +{ + geometry_file_format: "glb", // Available: glb, usdz, fbx, obj, stl + material: "PBR", // Available: PBR, Shaded + quality: "medium", // Available: extra-low, low, medium, high + tier: "Regular" // Available: Regular, Sketch +} +``` + +## Common Issues & Troubleshooting + +1. **Generation Failures** + - Verify FAL API key is correctly set + - Ensure prompt is descriptive (minimum 3 characters) + - Check network connectivity to FAL.ai services + +2. **Storage Issues** + - Verify write permissions to content_cache directory + - Ensure sufficient disk space + - Check if content_cache directory exists + +## Security Best Practices + +1. **API Key Management** + - Store FAL API key securely using runtime settings or environment variables + - Never commit API keys to version control + - Monitor API usage + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +4. Run the plugin: + +```bash +pnpm run dev +``` + +## Future Enhancements + +1. **Advanced Generation Features** + - Multi-object scene generation + - Texture customization options + - Animation support + - Material property controls + - Advanced lighting systems + - Physics-based rendering + +2. **Model Optimization** + - Automatic mesh simplification + - LOD (Level of Detail) generation + - Texture compression + - File size optimization + - Performance profiling + - Mobile-friendly exports + +3. **Format Support** + - Additional file format exports + - Custom format converters + - Batch format conversion + - Format-specific optimizations + - Metadata preservation + - Version control integration + +4. **AI Improvements** + - Enhanced prompt understanding + - Style transfer capabilities + - Real-time generation + - Multi-model support + - Quality improvements + - Consistency controls + +5. **Scene Management** + - Scene composition tools + - Environment management + - Asset library integration + - Scene presets + - Batch processing + - Scene version control + +6. **Developer Tools** + - API expansion + - Testing framework + - Documentation generator + - Debug visualization + - Performance monitoring + - Integration templates + +7. **Rendering Features** + - Real-time preview + - Custom shader support + - Post-processing effects + - Render queue management + - Batch rendering + - Cloud rendering options + +8. **Collaboration Features** + - Asset sharing + - Version control + - Team workspace + - Review system + - Access control + - Change tracking + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [FAL.ai](https://fal.ai/): AI model deployment platform +- [Three.js](https://threejs.org/): 3D graphics library +- [glTF](https://www.khronos.org/gltf/): 3D file format standard +- [USD](https://graphics.pixar.com/usd/): Universal Scene Description +- [Blender](https://www.blender.org/): 3D creation suite + +Special thanks to: +- The FAL.ai team for AI infrastructure +- The Three.js development community +- The Khronos Group for glTF standards +- The Pixar USD team +- The Blender Foundation +- The Eliza community for their contributions and feedback + +For more information about 3D generation capabilities: +- [FAL.ai Documentation](https://fal.ai/docs) +- [Three.js Documentation](https://threejs.org/docs/) +- [glTF Specification](https://github.com/KhronosGroup/glTF) +- [USD Documentation](https://graphics.pixar.com/usd/docs/index.html) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-abstract/README.md b/packages/plugin-abstract/README.md new file mode 100644 index 0000000000..9a1f0539cf --- /dev/null +++ b/packages/plugin-abstract/README.md @@ -0,0 +1,199 @@ +# @elizaos/plugin-abstract + +A plugin for interacting with the Abstract blockchain network within the ElizaOS ecosystem. + +## Description +The Abstract plugin enables seamless token transfers on the Abstract testnet. It provides functionality to transfer both native ETH and ERC20 tokens using secure wallet operations. + +## Installation + +```bash +pnpm install @elizaos/plugin-abstract +``` + +## Configuration + +The plugin requires the following environment variables to be set: +```typescript +ABSTRACT_ADDRESS= +ABSTRACT_PRIVATE_KEY= +``` + +## Usage + +### Basic Integration + +```typescript +import { abstractPlugin } from '@elizaos/plugin-abstract'; +``` + +### Transfer Examples + +```typescript +// The plugin responds to natural language commands like: + +"Send 100 USDC to 0xCCa8009f5e09F8C5dB63cb0031052F9CB635Af62" +"Transfer 0.1 ETH to 0xbD8679cf79137042214fA4239b02F4022208EE82" +"Pay 50 USDC on Abstract to [address]" +``` + +## API Reference + +### Actions + +#### SEND_TOKEN + +Transfers tokens from the agent's wallet to another address. + +**Aliases:** +- TRANSFER_TOKEN_ON_ABSTRACT +- TRANSFER_TOKENS_ON_ABSTRACT +- SEND_TOKENS_ON_ABSTRACT +- SEND_ETH_ON_ABSTRACT +- PAY_ON_ABSTRACT +- MOVE_TOKENS_ON_ABSTRACT +- MOVE_ETH_ON_ABSTRACT + +## Common Issues & Troubleshooting + +1. **Transaction Failures** + - Verify wallet has sufficient balance + - Check recipient address format + - Ensure private key is correctly set + - Verify network connectivity + +2. **Configuration Issues** + - Verify all required environment variables are set + - Ensure private key format is correct + - Check wallet address format + +## Security Best Practices + +1. **Private Key Management** + - Store private key securely using environment variables + - Never commit private keys to version control + - Use separate wallets for development and production + - Monitor wallet activity regularly + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +4. Run the plugin: + +```bash +pnpm run dev +``` + +## Future Enhancements + +1. **Smart Account Features** + - Multi-signature support + - Account recovery mechanisms + - Batch transaction processing + - Advanced permission management + - Account abstraction improvements + - Social recovery options + +2. **CosmWasm Integration** + - Contract deployment templates + - Smart contract verification tools + - Contract upgrade system + - Testing framework improvements + - Gas optimization tools + - Contract interaction templates + +3. **IBC Operations** + - Cross-chain transfer optimization + - IBC relayer monitoring + - Channel management tools + - Packet tracking system + - Timeout handling improvements + - Cross-chain messaging + +4. **DEX Integration** + - Advanced swap routing + - Liquidity pool management + - Yield farming automation + - Price impact analysis + - Slippage protection + - AMM optimization + +5. **Security Enhancements** + - Transaction simulation + - Risk assessment tools + - Rate limiting controls + - Fraud detection system + - Emergency shutdown features + - Audit integration tools + +6. **Developer Tools** + - Enhanced debugging capabilities + - Documentation generator + - CLI tool improvements + - Testing utilities + - Deployment automation + - Performance profiling + +7. **Analytics and Monitoring** + - Transaction tracking dashboard + - Network statistics + - Performance metrics + - Gas usage optimization + - Custom reporting tools + - Real-time monitoring + +8. **Wallet Management** + - Multiple wallet support + - Hardware wallet integration + - Address book features + - Transaction history analysis + - Balance monitoring + - Token management tools + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Abstract](https://abstract.money/): Smart account infrastructure +- [CosmWasm](https://cosmwasm.com/): Smart contract platform +- [Cosmos SDK](https://v1.cosmos.network/sdk): Blockchain application framework +- [IBC Protocol](https://ibcprotocol.org/): Inter-blockchain communication +- [Osmosis](https://osmosis.zone/): DEX infrastructure + +Special thanks to: +- The Abstract development team +- The CosmWasm core developers +- The Cosmos SDK maintainers +- The IBC Protocol team +- The Osmosis DEX team +- The Eliza community for their contributions and feedback + +For more information about Abstract capabilities: +- [Abstract Documentation](https://docs.abstract.money/) +- [CosmWasm Documentation](https://docs.cosmwasm.com/) +- [Cosmos SDK Docs](https://docs.cosmos.network/) +- [IBC Protocol Docs](https://ibc.cosmos.network/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-aptos/README.md b/packages/plugin-aptos/README.md new file mode 100644 index 0000000000..d6a10fa986 --- /dev/null +++ b/packages/plugin-aptos/README.md @@ -0,0 +1,231 @@ +# @elizaos/plugin-aptos + +A plugin for interacting with the Aptos blockchain network within the ElizaOS ecosystem. + +## Description +The Aptos plugin enables seamless token transfers and wallet management on the Aptos blockchain. It provides functionality to transfer APT tokens and monitor wallet balances with real-time price tracking. + +## Installation + +```bash +pnpm install @elizaos/plugin-aptos +``` + +## Configuration + +The plugin requires the following environment variables to be set: +```typescript +APTOS_PRIVATE_KEY= +APTOS_NETWORK=<"mainnet" | "testnet"> +``` + +## Usage + +### Basic Integration + +```typescript +import { aptosPlugin, WalletProvider, TransferAptosToken } from '@elizaos/plugin-aptos'; +``` + +### Transfer Examples + +```typescript +// The plugin responds to natural language commands like: + +"Send 69 APT tokens to 0x4f2e63be8e7fe287836e29cde6f3d5cbc96eefd0c0e3f3747668faa2ae7324b0" +"Transfer APT to [address]" +"Pay [amount] APT to [recipient]" +``` + +## API Reference + +### Actions + +#### SEND_TOKEN + +Transfers APT tokens from the agent's wallet to another address. + +**Aliases:** +- TRANSFER_TOKEN +- TRANSFER_TOKENS +- SEND_TOKENS +- SEND_APT +- PAY + +**Configuration:** +```typescript +{ + APT_DECIMALS: 8 // Decimal places for APT token +} +``` + +### Providers + +#### WalletProvider + +Provides wallet information and portfolio tracking. + +**Features:** +- Real-time APT price tracking +- Portfolio value calculation +- Cached wallet information (5-minute TTL) +- Formatted portfolio reports + +## Common Issues & Troubleshooting + +1. **Transaction Failures** + - Verify wallet has sufficient APT balance + - Check recipient address format + - Ensure private key is correctly set + - Verify network connectivity + +2. **Price Fetching Issues** + - Check connection to DexScreener API + - Verify cache functionality + - Monitor retry mechanism (3 attempts with exponential backoff) + +## Security Best Practices + +1. **Private Key Management** + - Store private key securely using environment variables + - Never commit private keys to version control + - Use separate wallets for development and production + - Monitor wallet activity regularly + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +4. Run tests: + +```bash +pnpm run test +``` + +5. Development mode: + +```bash +pnpm run dev +``` + +## Dependencies + +- @aptos-labs/ts-sdk: ^1.26.0 +- bignumber.js: 9.1.2 +- node-cache: 5.1.2 + +## Future Enhancements + +The following features and improvements are planned for future releases: + +1. **Advanced Token Operations** + - Batch token transfers + - Token creation templates + - NFT minting and management + - Token metadata management + - Custom tokenomics implementation + - Token upgrade mechanisms + +2. **DeFi Integration** + - Liquidity pool management + - Yield farming automation + - Staking optimization + - AMM integration + - Cross-chain bridges + - Price impact analysis + +3. **Move Contract Management** + - Contract deployment tools + - Contract verification + - Contract upgrade system + - Testing framework + - Gas optimization tools + - Security audit integration + +4. **Wallet Enhancements** + - Multi-wallet support + - Hardware wallet integration + - Transaction batching + - Address book management + - Custom signature schemes + - Account abstraction + +5. **Price Feed Improvements** + - Additional data sources + - Real-time price alerts + - Historical data analysis + - Custom price aggregation + - Price prediction tools + - Market sentiment analysis + +6. **Developer Tools** + - Enhanced debugging capabilities + - Move language IDE integration + - Documentation generator + - Performance profiling + - Testing utilities + - Deployment automation + +7. **Security Features** + - Transaction simulation + - Risk assessment tools + - Rate limiting controls + - Fraud detection + - Emergency shutdown + - Multi-signature support + +8. **Analytics and Monitoring** + - Transaction tracking + - Portfolio analytics + - Network statistics + - Gas usage optimization + - Performance metrics + - Custom reporting tools + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Aptos](https://aptoslabs.com/): Layer 1 blockchain platform +- [@aptos-labs/ts-sdk](https://github.com/aptos-labs/aptos-core/tree/main/ecosystem/typescript/sdk): Official TypeScript SDK +- [Petra Wallet](https://petra.app/): Aptos wallet integration +- [DexScreener](https://dexscreener.com/): Price feed integration +- [Move Language](https://github.com/move-language/move): Smart contract language + +Special thanks to: +- The Aptos Labs team for developing the blockchain +- The Petra Wallet development team +- The DexScreener team for price data +- The Move language developers +- The Aptos Developer community +- The Eliza community for their contributions and feedback + +For more information about Aptos capabilities: +- [Aptos Documentation](https://aptos.dev/) +- [Move Language Guide](https://move-language.github.io/move/) +- [Petra Wallet Docs](https://petra.app/docs) +- [DexScreener API](https://docs.dexscreener.com/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-avalanche/README.md b/packages/plugin-avalanche/README.md new file mode 100644 index 0000000000..4b1fa676b2 --- /dev/null +++ b/packages/plugin-avalanche/README.md @@ -0,0 +1,227 @@ +# @elizaos/plugin-avalanche + +A plugin for interacting with the Avalanche blockchain network within the ElizaOS ecosystem. + +## Description +The Avalanche plugin enables comprehensive DeFi operations on the Avalanche network, including token transfers, YAK swaps, yield strategy management, and token creation via Token Mill. + +## Installation + +```bash +pnpm install @elizaos/plugin-avalanche +``` + +## Configuration + +The plugin requires the following environment variable: +```typescript +AVALANCHE_PRIVATE_KEY= +``` + +## Features + +### 1. Token Transfers +- Send native AVAX and ERC20 tokens +- Support for multiple token standards +- Built-in address validation + +### 2. YAK Swaps +- Decentralized token swaps +- Automatic best path finding +- Slippage protection (default: 0.2%) +- Support for all major tokens + +### 3. Yield Strategies +- Deposit tokens into yield-generating strategies +- Support for multiple strategies including: + - YAK staking + - USDC Benqi + - gmYAK Token Mill + - PRINCESS staking + - JOE staking + +### 4. Token Mill +- Create new tokens +- Configure custom tokenomics +- Automatic market creation + +## Supported Tokens + +```typescript +const TOKENS = { + AVAX: "0x0000000000000000000000000000000000000000", + WAVAX: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7", + YAK: "0x59414b3089ce2AF0010e7523Dea7E2b35d776ec7", + gmYAK: "0x3A30784c1af928CdFce678eE49370220aA716DC3", + USDC: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", + // ... and more +} +``` + +## Usage Examples + +### Token Transfer +```typescript +// Send AVAX +"Send 10 AVAX to 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7" + +// Send ERC20 +"Transfer 100 USDC to [address]" +``` + +### YAK Swap +```typescript +// Swap tokens +"Swap 1 AVAX for USDC" +"Swap 10 USDC for gmYAK" +``` + +### Yield Strategy +```typescript +// Deposit into strategies +"Deposit 1 USDC into the strategy" +"Deposit 10 gmYAK to earn yield" +``` + +### Token Creation +```typescript +// Create new token +"Create a new memecoin called 'Test Token' with the symbol 'TEST'" +``` + +## Providers + +### 1. Wallet Provider +- Displays wallet balances +- Shows tokens in yield strategies +- Real-time balance updates + +### 2. Strategies Provider +- Lists available yield strategies +- Shows deposit token requirements + +### 3. Tokens Provider +- Lists supported tokens +- Shows token addresses + +## Development + +1. Clone the repository +2. Install dependencies: +```bash +pnpm install +``` + +3. Build the plugin: +```bash +pnpm run build +``` + +4. Run linting: +```bash +pnpm run lint +``` + +## Dependencies +- viem: ^2.21.49 +- @elizaos/core: workspace:* + +## Future Enhancements + +1. **Advanced DeFi Operations** + - Multi-hop yield strategies + - Auto-compounding features + - Yield optimization algorithms + - Risk assessment tools + - Portfolio rebalancing automation + - Cross-chain yield farming + +2. **Enhanced Token Management** + - Batch token operations + - Advanced token creation templates + - Token migration tools + - Automated token listing + - Token analytics dashboard + - Custom tokenomics implementation + +3. **YAK Protocol Integration** + - Advanced routing algorithms + - MEV protection features + - Gas optimization strategies + - Liquidity analysis tools + - Price impact predictions + - Custom trading strategies + +4. **Benqi Protocol Features** + - Collateral optimization + - Liquidation protection + - Interest rate monitoring + - Position management tools + - Risk assessment dashboard + - Auto-repayment features + +5. **Token Mill Improvements** + - Advanced token customization + - Automated market making + - Token distribution tools + - Vesting schedule management + - Governance token features + - Token upgrade mechanisms + +6. **Security Enhancements** + - Transaction simulation + - Smart contract auditing tools + - Real-time monitoring + - Automated safety checks + - Emergency shutdown features + - Multi-signature support + +7. **Developer Tools** + - Enhanced debugging capabilities + - Testing framework improvements + - Documentation generator + - CLI tools for common operations + - Integration templates + - Performance monitoring + +8. **Analytics and Reporting** + - Portfolio tracking + - Performance metrics + - Gas usage optimization + - Transaction history analysis + - Yield comparison tools + - Risk assessment reports + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Avalanche](https://www.avax.network/): High-performance blockchain platform +- [avalanchejs](https://github.com/ava-labs/avalanchejs): Official Avalanche JavaScript library +- [YAK Protocol](https://yak.exchange/): Decentralized exchange aggregator +- [Benqi](https://benqi.fi/): Lending and borrowing protocol +- [Token Mill](https://tokenmill.xyz/): Token creation platform + +Special thanks to: +- The Ava Labs team for developing Avalanche +- The YAK Protocol development team +- The Benqi protocol developers +- The Token Mill platform team +- The Avalanche Developer community +- The Eliza community for their contributions and feedback + +For more information about Avalanche capabilities: +- [Avalanche Documentation](https://docs.avax.network/) +- [YAK Protocol Docs](https://yak.exchange/docs) +- [Benqi Documentation](https://docs.benqi.fi/) +- [Token Mill Guide](https://docs.tokenmill.xyz/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-bootstrap/README.md b/packages/plugin-bootstrap/README.md new file mode 100644 index 0000000000..9fdeb69d7b --- /dev/null +++ b/packages/plugin-bootstrap/README.md @@ -0,0 +1,160 @@ +# @elizaos/plugin-bootstrap + +A plugin providing core functionality and basic actions for ElizaOS agents. + +## Description +The Bootstrap plugin enables fundamental agent behaviors including conversation management, room interactions, and fact tracking. It provides essential actions and evaluators that form the foundation of agent interactions. + +## Installation + +```bash +pnpm install @elizaos/plugin-bootstrap +``` + +## Features + +### 1. Conversation Management +- NONE action for basic responses +- CONTINUE action for follow-ups +- IGNORE action for appropriate disengagement +- Built-in conversation flow control + +### 2. Room Control +- Follow/Unfollow room functionality +- Mute/Unmute capabilities +- Automatic engagement level tracking +- Smart participation management + +### 3. Fact Management +- Automatic fact extraction +- Categorization of claims +- Deduplication of known information +- Support for multiple fact types: + - Permanent facts + - Status updates + - Opinions + - Biographical information + +### 4. Goal Tracking +- Track objective progress +- Update goal statuses +- Monitor completion states +- Automatic progress evaluation + +## Providers + +### 1. Boredom Provider +- Tracks engagement levels +- Provides status messages +- Monitors conversation quality +- Adjusts participation accordingly + +### 2. Facts Provider +- Manages fact database +- Retrieves relevant information +- Formats fact summaries +- Maintains fact context + +### 3. Time Provider +- Provides UTC timestamps +- Human-readable formatting +- Time-based operation support + +## Development + +1. Clone the repository +2. Install dependencies: +```bash +pnpm install +``` + +3. Build the plugin: +```bash +pnpm run build +``` + +4. Run linting: +```bash +pnpm run lint +``` + +## Dependencies +- @elizaos/core: workspace:* + +## Future Enhancements + +1. **Enhanced Conversation Management** + - Advanced context tracking + - Multi-thread conversation support + - Conversation state persistence + - Improved conversation flow control + - Natural language understanding improvements + +2. **Advanced Room Control** + - Dynamic room creation and management + - Room permission system + - Advanced moderation tools + - Room analytics and insights + - Cross-room communication features + +3. **Expanded Fact Management** + - Enhanced fact verification system + - Fact relationship mapping + - Automated fact updating + - Fact confidence scoring + - Cross-reference system + - Fact expiration management + +4. **Goal System Improvements** + - Multi-step goal planning + - Goal dependency tracking + - Progress visualization + - Goal priority management + - Automated milestone tracking + - Goal optimization suggestions + +5. **Provider Enhancements** + - Improved boredom detection + - Advanced engagement metrics + - Enhanced fact retrieval algorithms + - Real-time status updates + - Provider performance analytics + +6. **Memory Management** + - Enhanced memory prioritization + - Memory compression techniques + - Long-term memory storage + - Memory relationship mapping + - Context-aware recall + +7. **Developer Tools** + - Enhanced debugging capabilities + - Testing framework improvements + - Plugin development templates + - Documentation generator + - Performance profiling tools + +8. **Integration Features** + - Enhanced plugin interoperability + - External service connectors + - API gateway integration + - Webhook system improvements + - Third-party platform support + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +Special thanks to: +- The Eliza Core development team +- The Eliza community for their contributions and feedback + + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-coinbase/README.md b/packages/plugin-coinbase/README.md new file mode 100644 index 0000000000..78ac8cb487 --- /dev/null +++ b/packages/plugin-coinbase/README.md @@ -0,0 +1,198 @@ +# @elizaos/plugin-coinbase + +A comprehensive Coinbase integration plugin for ElizaOS that provides access to Coinbase's various APIs and services. + +## Features + +- **Commerce Integration**: Create and manage payment charges using Coinbase Commerce +- **Trading**: Execute trades and swaps between different assets +- **Token Contract Management**: Deploy and interact with ERC20, ERC721, and ERC1155 smart contracts +- **Mass Payments**: Process bulk transfers and payments to multiple addresses +- **Advanced Trading**: Access to Coinbase Advanced Trading API features +- **Webhook Management**: Create and manage webhooks for various blockchain events + +## Installation + +```bash +npm install @elizaos/plugin-coinbase +``` + +## Configuration + +The plugin requires several environment variables to be set: + +```env +COINBASE_API_KEY=your_api_key +COINBASE_PRIVATE_KEY=your_private_key +COINBASE_COMMERCE_KEY=your_commerce_key +COINBASE_NOTIFICATION_URI=your_webhook_notification_uri +``` + +## Usage + +```typescript +import { plugins } from '@elizaos/plugin-coinbase'; + +// Register all plugins +const { + coinbaseMassPaymentsPlugin, + coinbaseCommercePlugin, + tradePlugin, + tokenContractPlugin, + webhookPlugin, + advancedTradePlugin +} = plugins; + +// Register individual plugins as needed +runtime.registerPlugin(coinbaseCommercePlugin); +runtime.registerPlugin(tradePlugin); +// etc... +``` + +## Available Plugins + +### Commerce Plugin +- Create charges with fixed or dynamic pricing +- Support for multiple currencies (USD, EUR, USDC) +- Charge status tracking and management + +### Trade Plugin +- Execute basic trades between assets +- Support for market and limit orders +- Transaction logging and tracking + +### Token Contract Plugin +- Deploy ERC20, ERC721, and ERC1155 contracts +- Interact with deployed contracts +- Read contract data and balances + +### Mass Payments Plugin +- Process bulk transfers to multiple addresses +- Support for various assets and networks +- Transaction logging and CSV export + +### Advanced Trade Plugin +- Access to advanced trading features +- Support for complex order types +- Detailed trade history and tracking + +### Webhook Plugin +- Create and manage blockchain event webhooks +- Support for various event types and filters +- Webhook status tracking and logging + +## Supported Networks + +- Base (Mainnet & Sepolia) +- Ethereum (Mainnet & Holesky) +- Polygon Mainnet +- Solana (Mainnet & Devnet) +- Arbitrum Mainnet +- And more... + +## CSV Logging + +The plugin automatically logs various operations to CSV files: +- `trades.csv`: Trading operations +- `transactions.csv`: Mass payment transactions +- `webhooks.csv`: Webhook configurations +- `advanced_trades.csv`: Advanced trading operations + +## Dependencies + +- `@elizaos/core`: Core ElizaOS functionality +- `coinbase-api`: Coinbase API integration +- `coinbase-advanced-sdk`: Coinbase Advanced Trading SDK +- Additional type definitions and utilities + +## Future Enhancements + +1. **Advanced Trading Features** + - Real-time market data streaming + - Advanced order types (OCO, trailing stop) + - Portfolio rebalancing automation + - Custom trading strategies implementation + - Multi-exchange arbitrage support + +2. **Enhanced Commerce Integration** + - Subscription payment handling + - Multi-currency checkout optimization + - Advanced refund management + - Custom payment flow templates + - Automated invoice generation + +3. **Improved Token Management** + - Batch token operations + - Gas optimization for token contracts + - Token metadata management system + - Automated token listing process + - Smart contract deployment templates + +4. **Security Enhancements** + - Advanced API key management + - Multi-signature support + - Transaction monitoring system + - Risk assessment tools + - Rate limiting improvements + +5. **Analytics and Reporting** + - Custom report generation + - Trading performance analytics + - Payment flow analytics + - Real-time monitoring dashboard + - Historical data analysis tools + +6. **Webhook Management** + - Enhanced event filtering + - Retry mechanism improvements + - Webhook monitoring dashboard + - Custom webhook templates + - Event batching support + +7. **Developer Tools** + - SDK expansion + - Testing environment improvements + - Documentation generator + - CLI tools for common operations + - Integration templates + +8. **Cross-Platform Integration** + - Mobile SDK support + - Browser extension support + - Desktop application integration + - IoT device support + - Cross-chain bridging capabilities + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Coinbase](https://www.coinbase.com/): Digital currency exchange platform +- [Coinbase Commerce](https://commerce.coinbase.com/): Cryptocurrency payment solution +- [Coinbase Cloud](https://www.coinbase.com/cloud): Blockchain infrastructure +- [Coinbase Advanced Trade API](https://docs.cloud.coinbase.com/advanced-trade-api/): Trading interface +- [Coinbase Prime](https://prime.coinbase.com/): Institutional trading platform + +Special thanks to: +- The Coinbase development team +- The Coinbase Commerce team +- The Coinbase Cloud infrastructure team +- The Advanced Trade API maintainers +- The Eliza community for their contributions and feedback + +For more information about Coinbase capabilities: +- [Coinbase API Documentation](https://docs.cloud.coinbase.com/) +- [Commerce API Reference](https://docs.cloud.coinbase.com/commerce/reference/) +- [Advanced Trade Documentation](https://docs.cloud.coinbase.com/advanced-trade-api/) +- [Coinbase Prime Documentation](https://docs.prime.coinbase.com/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-conflux/README.md b/packages/plugin-conflux/README.md index bb71cf1174..fd60a605a3 100644 --- a/packages/plugin-conflux/README.md +++ b/packages/plugin-conflux/README.md @@ -1,25 +1,217 @@ # @elizaos/plugin-conflux -This plugin provides actions and providers for interacting with the [Conflux network](https://www.confluxdocs.com/docs/general). +A plugin for interacting with the Conflux blockchain network within the ElizaOS ecosystem. -## Actions +## Description -### ConfiPump +The Conflux plugin enables seamless interaction with both Conflux Core Space and eSpace networks. It provides functionality for token transfers, cross-space bridge operations, and ConfiPump token management (creation, buying, and selling). -Buy and sell tokens on Conflux's implementation of pump.fun (ConfiPump). +## Installation -### Transfer +```bash +pnpm install @elizaos/plugin-conflux +``` -Transfer tokens from one address to another within Conflux core space. +## Configuration -### Bridge Transfer +The plugin requires the following environment variables to be set: +```typescript +CONFLUX_CORE_PRIVATE_KEY= +CONFLUX_CORE_SPACE_RPC_URL= +CONFLUX_MEME_CONTRACT_ADDRESS= +``` -Transfer tokens from one address to Conflux eSpace. +## Usage -### Sponsor (TBD) +### Basic Integration -Provide gas for Conflux core space contracts so they can be called without the need to have Conflux in user's wallet. +```typescript +import { confluxPlugin } from '@elizaos/plugin-conflux'; +``` -### Swap (TBD) +### Example Usage + +```typescript +// Core Space Transfer +"Send 1 CFX to cfx:aaejuaaaaaaaaaaaaaaaaaaaaaaaaaaaa2eaeg85p5" + +// Cross-Space Bridge Transfer +"Send 1 CFX to eSpace Address 0x119DA8bbe74B1C5c987D0c64D10eC1dB301d4752" + +// ConfiPump Token Creation +"Create a new token called GLITCHIZA with symbol GLITCHIZA and generate a description about it" + +// ConfiPump Token Trading +"Buy 0.00069 CFX worth of GLITCHIZA(0x1234567890abcdef)" +"Sell 0.00069 CFX worth of GLITCHIZA(0x1234567890abcdef)" +``` + +## API Reference + +### Actions + +#### SEND_CFX +Transfers CFX tokens within Conflux Core Space. + +**Aliases:** +- SEND_CONFLUX +- SEND_CFX_CORE_SPACE +- TRANSFER_CFX + +**Input Content:** +```typescript +interface TransferContent { + to: string; // Conflux Core Space address (cfx: prefix) + amount: string; // Amount of CFX to send +} +``` + +#### BRIDGE_SEND_CFX +Transfers CFX tokens from Core Space to eSpace. + +**Aliases:** +- BRIDGE_SEND_CONFLUX +- CROSS_SPACE_SEND_CFX +- BRIDGE_TRANSFER_CFX +- CROSS_SPACE_TRANSFER_CFX + +**Input Content:** +```typescript +interface TransferContent { + to: string; // Conflux eSpace address (0x prefix) + amount: string; // Amount of CFX to send +} +``` + +#### CONFI_PUMP +Manages ConfiPump token operations. + +**Aliases:** +- SELL_TOKEN +- BUY_TOKEN +- CREATE_TOKEN + +**Input Content:** +```typescript +interface PumpContent { + action: "CREATE_TOKEN" | "BUY_TOKEN" | "SELL_TOKEN"; + params: { + name?: string; + symbol?: string; + description?: string; + tokenAddress?: string; + value?: string; + }; +} +``` + +## Common Issues & Troubleshooting + +1. **Transaction Failures** + - Ensure sufficient CFX balance for transactions + - Verify correct address format (cfx: for Core Space, 0x for eSpace) + - Check RPC endpoint connectivity + +## Security Best Practices + +1. **Private Key Management** + - Store private keys securely using environment variables + - Never expose private keys in code or logs + - Use separate accounts for development and production + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: +```bash +pnpm install +``` + +3. Build the plugin: +```bash +pnpm run build +``` + +4. Run the plugin: +```bash +pnpm run dev +``` + +## Future Enhancements + +1. **Advanced Token Management** + - Batch token transfers + - Token allowance management + - Advanced meme token features + - Token metadata management + +2. **Enhanced Bridge Operations** + - Multi-token bridge support + - Automated bridge fee optimization + - Bridge transaction status tracking + - Cross-space batch operations + +3. **Smart Contract Integration** + - Contract deployment tools + - Contract interaction templates + - ABI management system + - Contract verification tools + +4. **Performance Optimizations** + - Transaction batching + - Improved caching mechanisms + - Gas optimization strategies + - Network request optimization + +5. **Developer Tools** + - CLI tools for common operations + - Development environment templates + - Testing utilities + - Documentation generator + +6. **Security Features** + - Transaction simulation + - Risk assessment tools + - Address validation improvements + - Rate limiting controls + +7. **Monitoring and Analytics** + - Transaction tracking dashboard + - Performance metrics + - Error reporting system + - Usage analytics + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Conflux Network](https://confluxnetwork.org/): Hybrid consensus blockchain +- [js-conflux-sdk](https://www.npmjs.com/package/js-conflux-sdk): Official Conflux JavaScript SDK +- [ConfiPump](https://confipump.io/): Meme token creation platform +- [@conflux-dev/conflux-address-js](https://www.npmjs.com/package/@conflux-dev/conflux-address-js): Address utilities + +Special thanks to: +- The Conflux Foundation for developing the network +- The Conflux Developer community +- The ConfiPump team for meme token infrastructure +- The js-conflux-sdk maintainers +- The Eliza community for their contributions and feedback + +For more information about Conflux capabilities: +- [Conflux Documentation](https://developer.confluxnetwork.org/) +- [Conflux Portal](https://portal.confluxnetwork.org/) +- [ConfluxScan](https://confluxscan.io/) +- [Cross-Space Bridge](https://bridge.confluxnetwork.org/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. -Swap tokens on Conflux DEXs. diff --git a/packages/plugin-cronoszkevm/README.md b/packages/plugin-cronoszkevm/README.md new file mode 100644 index 0000000000..a662890d81 --- /dev/null +++ b/packages/plugin-cronoszkevm/README.md @@ -0,0 +1,150 @@ +# @elizaos/plugin-cronoszkevm + +A plugin for interacting with the Cronos zkEVM network within the ElizaOS ecosystem. + +## Description + +The Cronos zkEVM plugin enables seamless token transfers on the Cronos zkEVM network. It provides functionality for transferring various tokens including ZKCRO, USDC, and ETH using Web3 and zkSync integration. + +## Installation + +```bash +pnpm install @elizaos/plugin-cronoszkevm +``` + +## Configuration + +The plugin requires the following environment variables to be set: +```typescript +CRONOSZKEVM_ADDRESS= +CRONOSZKEVM_PRIVATE_KEY= +``` + +## Usage + +### Basic Integration + +```typescript +import { cronosZkEVMPlugin } from '@elizaos/plugin-cronoszkevm'; +``` + +### Example Usage + +```typescript +// Send USDC tokens +"Send 100 USDC to 0xCCa8009f5e09F8C5dB63cb0031052F9CB635Af62" + +// Send ZKCRO tokens +"Send 100 ZKCRO to 0xbD8679cf79137042214fA4239b02F4022208EE82" + +// Send ETH tokens +"Transfer 1 ETH to 0x123..." +``` + +## API Reference + +### Actions + +#### SEND_TOKEN +Transfers tokens on the Cronos zkEVM network. + +**Aliases:** +- TRANSFER_TOKEN_ON_CRONOSZKEVM +- TRANSFER_TOKENS_ON_CRONOSZK +- SEND_TOKENS_ON_CRONOSZKEVM +- SEND_TOKENS_ON_CRONOSZK +- SEND_ETH_ON_CRONOSZKEVM +- SEND_ETH_ON_CRONOSZK +- PAY_ON_CRONOSZKEVM +- PAY_ON_CRONOSZK + +**Input Content:** +```typescript +interface TransferContent { + tokenAddress: string; // The token contract address + recipient: string; // The recipient's address + amount: string | number; // Amount to transfer +} +``` + +## Common Issues & Troubleshooting + +1. **Transaction Failures** + - Ensure sufficient token balance for transfers + - Verify correct recipient address format (must start with 0x) + - Check network connectivity to Cronos zkEVM RPC endpoint + +2. **Configuration Issues** + - Verify CRONOSZKEVM_ADDRESS is properly set + - Ensure CRONOSZKEVM_PRIVATE_KEY is valid and secure + - Confirm RPC endpoint is accessible + +## Security Best Practices + +1. **Private Key Management** + - Store private keys securely using environment variables + - Never expose private keys in code or logs + - Use separate accounts for development and production + +2. **Transaction Validation** + - Always validate addresses before sending transactions + - Verify token amounts and decimals + - Implement proper error handling + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: +```bash +pnpm install +``` + +3. Build the plugin: +```bash +pnpm run build +``` + +4. Run the plugin: +```bash +pnpm run dev +``` + +## Common Token Addresses + +- ZKCRO/zkCRO: `0x000000000000000000000000000000000000800A` +- USDC/usdc: `0xaa5b845f8c9c047779bedf64829601d8b264076c` +- ETH/eth: `0x898b3560affd6d955b1574d87ee09e46669c60ea` + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Cronos zkEVM](https://cronos.org/zkevm): Layer 2 scaling solution for Cronos +- [Web3.js](https://web3js.org/): Ethereum JavaScript API +- [zkSync](https://zksync.io/): Zero-knowledge rollup technology +- [Ethers.js](https://docs.ethers.org/): Complete Ethereum library +- [Viem](https://viem.sh/): Modern TypeScript Ethereum library + +Special thanks to: +- The Cronos team for developing zkEVM +- The Matter Labs team for zkSync technology +- The Web3.js and Ethers.js maintainers +- The Viem development team +- The Eliza community for their contributions and feedback + +For more information about Cronos zkEVM capabilities: +- [Cronos zkEVM Documentation](https://docs.cronos.org/zkevm/) +- [zkEVM Bridge](https://zkevm.cronos.org/bridge) +- [Cronos Developer Portal](https://cronos.org/developers) +- [zkSync Integration Guide](https://docs.cronos.org/zkevm/integration) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-echochambers/README.md b/packages/plugin-echochambers/README.md index 6e515088ac..5b8e0f2715 100644 --- a/packages/plugin-echochambers/README.md +++ b/packages/plugin-echochambers/README.md @@ -1,4 +1,4 @@ -# EchoChambers Plugin for ELIZA +# @elizaos/plugin-echochambers The EchoChambers plugin enables ELIZA to interact in chat rooms, providing conversational capabilities with dynamic interaction handling. @@ -8,59 +8,181 @@ The EchoChambers plugin enables ELIZA to interact in chat rooms, providing conve - Respond to messages based on context and relevance - Retry operations with exponential backoff - Manage connection and reconnection logic +- Real-time chat room monitoring and interaction +- Intelligent message response generation +- Context-aware conversation handling +- Comprehensive message history tracking +- Multi-room support with configurable polling ## Installation 1. Install the plugin package: - - @elizaos/plugin-echochambers - OR copy the plugin code into your eliza project node_modules directory. (node_modules\@elizaos) +```bash +pnpm install @elizaos/plugin-echochambers +``` +OR copy the plugin code into your eliza project node_modules directory. (node_modules\@elizaos) 2. Import and register the plugin in your `character.ts` configuration: - ```typescript - import { Character, ModelProviderName, defaultCharacter } from "@elizaos/core"; - import { echoChamberPlugin } from "@elizaos/plugin-echochambers"; - - export const character: Character = { - ...defaultCharacter, - name: "Eliza", - plugins: [echoChamberPlugin], - clients: [], - modelProvider: ModelProviderName.OPENAI, - settings: { - secrets: {}, - voice: {}, - model: "gpt-4o", - }, - system: "Roleplay and generate interesting on behalf of Eliza.", - bio: [...], - lore: [...], - messageExamples: [...], - postExamples: [...], - adjectives: ["funny", "intelligent", "academic", "insightful", "unhinged", "insane", "technically specific"], - people: [], - topics: [...], - style: {...}, - }; - ``` +```typescript +import { Character, ModelProviderName, defaultCharacter } from "@elizaos/core"; +import { echoChamberPlugin } from "@elizaos/plugin-echochambers"; + +export const character: Character = { + ...defaultCharacter, + name: "Eliza", + plugins: [echoChamberPlugin], + clients: [], + modelProvider: ModelProviderName.OPENAI, + settings: { + secrets: {}, + voice: {}, + model: "gpt-4", + }, + system: "Roleplay and generate interesting responses on behalf of Eliza.", + bio: [...], + lore: [...], + messageExamples: [...], + postExamples: [...], + adjectives: ["funny", "intelligent", "academic", "insightful"], + people: [], + topics: [...], + style: {...}, +}; +``` ## Configuration -Add the following environment variables to your `.env` file: +The plugin requires the following environment variables: ```plaintext -# EchoChambers Configuration -ECHOCHAMBERS_API_URL="http://127.0.0.1:3333" # Replace with actual API URL -ECHOCHAMBERS_API_KEY="testingkey0011" # Replace with actual API key -ECHOCHAMBERS_USERNAME="eliza" # Optional: Custom username for the agent -ECHOCHAMBERS_DEFAULT_ROOM="general" # Optional: Default room to join -ECHOCHAMBERS_POLL_INTERVAL="60" # Optional: Polling interval in seconds -ECHOCHAMBERS_MAX_MESSAGES="10" # Optional: Maximum number of messages to fetch +# Required Settings +ECHOCHAMBERS_API_URL="http://127.0.0.1:3333" # Base URL for the EchoChambers API +ECHOCHAMBERS_API_KEY="your-api-key" # API key for authentication + +# Optional Settings +ECHOCHAMBERS_USERNAME="eliza" # Custom username for the agent +ECHOCHAMBERS_DEFAULT_ROOM="general" # Default room to join +ECHOCHAMBERS_POLL_INTERVAL="60" # Polling interval in seconds +ECHOCHAMBERS_MAX_MESSAGES="10" # Maximum messages in conversation thread ``` ## Usage Instructions ### Starting the Plugin -To start using the EchoChambers plugin, ensure that your character configuration includes it as shown above. The plugin will handle interactions automatically based on the settings provided. +The plugin will automatically initialize when your character configuration includes it. It handles: + +1. Room Connection Management + - Automatic joining of default room + - Reconnection handling with backoff + - Multi-room monitoring + +2. Message Processing + - Context-aware response generation + - Thread management + - History tracking + +3. Response Behavior + The plugin intelligently decides when to respond based on: + - Direct mentions or questions + - Topic relevance to agent's expertise + - Conversation context and timing + - Message substance and engagement level + +## Common Issues & Troubleshooting + +1. **Connection Issues** + - Verify API URL is correct and accessible + - Ensure API key is valid + - Check network connectivity + +2. **Message Processing** + - Verify environment variables are properly set + - Check log files for error messages + - Ensure proper character configuration + +## Security Best Practices + +1. **API Key Management** + - Store API keys securely using environment variables + - Never expose keys in code or logs + - Rotate keys periodically + +2. **Connection Security** + - Use HTTPS for production environments + - Implement proper error handling + - Monitor for unusual activity + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: +```bash +pnpm install +``` + +3. Build the plugin: +```bash +pnpm run build +``` + +4. Run in development mode: +```bash +pnpm run dev +``` + +## API Reference + +### Core Components + +1. **EchoChamberClient** + - Handles room connections + - Manages message sending/receiving + - Implements retry logic + +2. **InteractionClient** + - Processes messages + - Generates responses + - Maintains conversation context + +## Future Enhancements + +- Enhanced message filtering +- Custom response templates +- Advanced room management features +- Improved context handling +- Extended retry mechanisms + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Socket.IO](https://socket.io/): Real-time bidirectional event-based communication +- [Express](https://expressjs.com/): Web application framework +- [Redis](https://redis.io/): In-memory data structure store +- [js-tiktoken](https://github.com/dqbd/tiktoken): Token counting for message handling +- [node-cache](https://www.npmjs.com/package/node-cache): In-memory caching + +Special thanks to: +- The Socket.IO team for real-time communication infrastructure +- The Express.js maintainers +- The Redis development team +- The chat room infrastructure maintainers +- The Eliza community for their contributions and feedback + +For more information about chat capabilities: +- [Socket.IO Documentation](https://socket.io/docs/v4/) +- [Express Documentation](https://expressjs.com/en/4x/api.html) +- [Redis Pub/Sub](https://redis.io/docs/manual/pubsub/) +- [Real-time Chat Best Practices](https://socket.io/docs/v4/rooms/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-evm/README.md b/packages/plugin-evm/README.md index dc7c695e5a..7e3dda7a04 100644 --- a/packages/plugin-evm/README.md +++ b/packages/plugin-evm/README.md @@ -1,22 +1,44 @@ -# `@elizaos/plugin-evm` +# @elizaos/plugin-evm This plugin provides actions and providers for interacting with EVM-compatible chains. ---- +## Description -## Configuration +The EVM plugin provides comprehensive functionality for interacting with EVM-compatible chains, including token transfers, cross-chain bridging, and token swaps using LiFi integration. + +## Features + +- Multi-chain support with dynamic chain configuration +- Native token transfers +- Cross-chain token bridging via LiFi +- Token swapping on supported DEXs +- Wallet balance tracking +- Custom RPC endpoint configuration +- Automatic retry mechanisms +- Comprehensive transaction management -### Default Setup +## Installation -By default, **Ethereum mainnet** is enabled. To use it, simply add your private key to the `.env` file: +```bash +pnpm install @elizaos/plugin-evm +``` + +## Configuration + +### Required Environment Variables ```env +# Required EVM_PRIVATE_KEY=your-private-key-here + +# Optional - Custom RPC URLs +EVM_PROVIDER_URL=https://your-custom-mainnet-rpc-url +ETHEREUM_PROVIDER_=https://your-custom-rpc-url ``` -### Adding Support for Other Chains +### Chain Configuration -To enable support for additional chains, add them to the character config like this: +By default, **Ethereum mainnet** is enabled. To enable additional chains, add them to your character config: ```json "settings": { @@ -60,34 +82,168 @@ The **Wallet Provider** initializes with the **first chain in the list** as the - Creates **Public** and **Wallet clients** to interact with the supported chains. - Allows adding chains dynamically at runtime. ---- - ## Actions -### Transfer +### 1. Transfer -Transfer tokens from one address to another on any EVM-compatible chain. Just specify the: +Transfer native tokens on the same chain: -- **Amount** -- **Chain** -- **Recipient Address** +```typescript +// Example: Transfer 1 ETH +Transfer 1 ETH to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e +``` -**Example usage:** +### 2. Bridge + +Bridge tokens between different chains using LiFi: + +```typescript +// Example: Bridge ETH from Ethereum to Base +Bridge 1 ETH from Ethereum to Base +``` + +### 3. Swap + +Swap tokens on the same chain using LiFi: + +```typescript +// Example: Swap ETH for USDC +Swap 1 ETH for USDC on Base +``` + +## Development + +1. Clone the repository +2. Install dependencies: ```bash -Transfer 1 ETH to 0xRecipient on arbitrum. +pnpm install ``` ---- +3. Build the plugin: -## Contribution +```bash +pnpm run build +``` -The plugin contains tests. Whether you're using **TDD** or not, please make sure to run the tests before submitting a PR. +4. Run tests: -### Running Tests +```bash +pnpm test +``` -Navigate to the `plugin-evm` directory and run: +## API Reference + +### Core Components + +1. **WalletProvider** + - Manages wallet connections + - Handles chain switching + - Manages RPC endpoints + - Tracks balances + +2. **Actions** + - TransferAction: Native token transfers + - BridgeAction: Cross-chain transfers + - SwapAction: Same-chain token swaps + +## Future Enhancements + +1. **Cross-Chain Operations** + - Enhanced bridge aggregation + - Multi-chain transaction batching + - Cross-chain liquidity management + - Bridge fee optimization + - Chain-specific gas strategies + - Cross-chain messaging + +2. **DeFi Integration** + - Advanced swap routing + - Yield farming automation + - Liquidity pool management + - Position management tools + - MEV protection features + - Flash loan integration + +3. **Smart Contract Management** + - Contract deployment templates + - Verification automation + - Upgrade management + - Security analysis tools + - Gas optimization + - ABI management system + +4. **Token Operations** + - Batch transfer tools + - Token approval management + - Token metadata handling + - Custom token standards + - Token bridging optimization + - NFT support enhancement + +5. **Wallet Features** + - Multi-signature support + - Account abstraction + - Hardware wallet integration + - Social recovery options + - Transaction simulation + - Batch transaction processing + +6. **Network Management** + - Dynamic RPC management + - Network health monitoring + - Fallback provider system + - Custom network addition + - Gas price optimization + - Network analytics + +7. **Security Enhancements** + - Transaction validation + - Risk assessment tools + - Fraud detection + - Rate limiting + - Emergency shutdown + - Audit integration + +8. **Developer Tools** + - Enhanced debugging + - Testing framework + - Documentation generator + - CLI improvements + - Performance profiling + - Integration templates + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +The plugin contains tests. Whether you're using **TDD** or not, please make sure to run the tests before submitting a PR: ```bash pnpm test ``` + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Ethereum](https://ethereum.org/): Decentralized blockchain +- [LiFi](https://lifi.io/): Cross-chain bridge and swap service +- [viem](https://viem.sh/): Ethereum client library +- [wagmi](https://wagmi.sh/): Ethereum client library + +Special thanks to: +- [Ethereum Developer community](https://ethereum.org/developers/) +- The Eliza community for their contributions and feedback + +For more information about EVM capabilities: +- [Ethereum Documentation](https://ethereum.org/developers/) +- [LiFi Documentation](https://lifi.io) +- [viem Documentation](https://viem.sh) +- [wagmi Documentation](https://wagmi.sh) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-ferePro/README.md b/packages/plugin-ferePro/README.md new file mode 100644 index 0000000000..161aff3321 --- /dev/null +++ b/packages/plugin-ferePro/README.md @@ -0,0 +1,217 @@ +# @elizaos/plugin-ferepro + +A plugin for enabling WebSocket communication with FerePro API to provide AI-driven market insights within the ElizaOS ecosystem. + +## Description + +The FerePro plugin enables real-time communication with the FerePro API through WebSocket connections, providing market analysis, cryptocurrency comparisons, and financial insights. + +## Features + +- Real-time WebSocket communication +- Streaming and non-streaming response support +- Market data analysis and comparisons +- Cryptocurrency insights +- Debug mode for detailed responses +- Automatic connection management +- Comprehensive error handling +- Credit tracking and management + +## Installation + +```bash +pnpm install @elizaos/plugin-ferepro +``` + +## Configuration + +### Required Environment Variables + +```env +# Required +FERE_USER_ID=your-user-id-here # Default: 1a5b4a29-9d95-44c8-aef3-05a8e515f43e +``` + +## Usage + +### Basic Message Structure + +```typescript +{ + "message": "Your market query here", + "stream": boolean, // Optional: Enable streaming responses + "debug": boolean // Optional: Enable debug mode +} +``` + +### Example Queries + +1. Basic Market Query: +```typescript +// Get top cryptocurrencies +"What are the top 5 cryptocurrencies?" +``` + +2. Comparison Analysis: +```typescript +// Compare specific cryptocurrencies +"Compare Ethereum and Bitcoin for the past 6 months" +``` + +3. Historical Data: +```typescript +// Get historical performance +"Compare top 3 coins against Bitcoin in the last 3 months" +``` + +## Development + +1. Clone the repository +2. Install dependencies: +```bash +pnpm install +``` + +3. Build the plugin: +```bash +pnpm run build +``` + +4. Run in development mode: +```bash +pnpm run dev +``` + +## API Reference + +### Core Components + +1. **FereProService** + - Manages WebSocket connections + - Handles message sending/receiving + - Processes streaming responses + - Tracks credits and usage + +2. **Actions** + - SEND_FEREPRO_MESSAGE: Primary action for API communication + - Supports market queries and analysis requests + - Handles both streaming and non-streaming responses + +### Response Structure + +```typescript +interface ChatResponse { + answer: string; + chat_id: string; + representation?: Record[]; + agent_api_name: string; + query_summary: string; + agent_credits: number; + credits_available: number; +} +``` + +## Error Handling + +The plugin includes comprehensive error handling for: +- WebSocket connection issues +- Invalid message formats +- API response errors +- Credit limitation issues + + +## Common Issues & Troubleshooting + +### Connection Issues +1. **WebSocket Connection Failures** + - Verify your internet connection + - Check if the FerePro API service is available + - Ensure your FERE_USER_ID is valid and active + +2. **Message Timeout** + - The connection might time out for long-running queries + - Consider using streaming mode for large data requests + - Implement retry logic for important queries + +3. **Credit Depletion** + - Monitor credits_available in responses + - Set up alerts for low credit situations + - Contact FerePro support for credit top-up + +### Response Parsing +1. **Invalid Response Format** + - Check if the query is properly formatted + - Verify the message structure matches the API requirements + - Enable debug mode for detailed error information + +2. **Missing Data** + - Ensure the requested timeframe is valid + - Verify the cryptocurrencies exist in the database + - Check if you have access to the requested data tier + +## Safety & Best Practices + +### Security +1. **API Credentials** + - Never expose your FERE_USER_ID in public repositories + - Use environment variables for sensitive data + - Rotate credentials periodically if possible + +2. **Rate Limiting** + - Implement appropriate delays between requests + - Monitor credit usage to prevent unexpected depletion + - Cache responses when appropriate + +### Data Handling +1. **Response Validation** + - Always validate response data before processing + - Implement proper error handling for malformed data + - Log unexpected response formats for debugging + +2. **Stream Management** + - Close WebSocket connections properly after use + - Implement reconnection logic for dropped connections + - Handle partial responses in streaming mode + +### Best Practices +1. **Query Optimization** + - Keep queries focused and specific + - Use streaming for large data requests + - Implement caching for frequently requested data + +2. **Error Handling** + - Implement comprehensive error catching + - Log errors with appropriate context + - Provide meaningful error messages to users + +3. **Resource Management** + - Monitor WebSocket connection status + - Implement connection pooling for high-volume usage + - Clean up resources properly on service shutdown + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [IPFS](https://ipfs.tech/): InterPlanetary File System +- [Filecoin](https://filecoin.io/): Decentralized storage network +- [Web3.Storage](https://web3.storage/): Decentralized storage service + +Special thanks to: +- The Protocol Labs team for IPFS and Filecoin +- The Web3.Storage team +- The decentralized storage community +- The Eliza community for their contributions and feedback + +For more information about Ferepro capabilities: +- [IPFS Documentation](https://docs.ipfs.tech/) +- [Filecoin Documentation](https://docs.filecoin.io/) +- [Web3.Storage Documentation](https://web3.storage/docs/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-flow/README.md b/packages/plugin-flow/README.md index f258981ee9..23987c6cdd 100644 --- a/packages/plugin-flow/README.md +++ b/packages/plugin-flow/README.md @@ -1,13 +1,158 @@ # @elizaos/plugin-flow -This plugin provides basic actions and providers for interacting with the [Flow Blockchain](https://developers.flow.com/). +A plugin for interacting with the Flow blockchain within the ElizaOS ecosystem. -## Actions +## Description -### Transfer +This plugin provides essential functionality for interacting with the Flow blockchain, including native FLOW token transfers, fungible token transfers, and EVM token interactions. It offers a seamless way to manage Flow blockchain transactions through natural language commands. -name: `SEND_COIN` +## Installation -Transfer native FLOW token/arbitrary FTs/ERC20s on Flow from agent's wallet to another EVM address or Flow address. +```bash +pnpm install @elizaos/plugin-flow +``` + +## Configuration + +The plugin requires the following environment variables to be set: +```typescript +FLOW_ADDRESS= +FLOW_PRIVATE_KEY= +FLOW_NETWORK= +FLOW_ENDPOINT_URL= +``` + +## Usage + +### Basic Integration + +```typescript +import { flowPlugin } from '@elizaos/plugin-flow'; +``` + +### Example Usage + +The plugin supports natural language commands for token transfers: + +```typescript +"Send 5 FLOW to 0xa51d7fe9e0080662" +"Send 1 FLOW - A.1654653399040a61.FlowToken to 0xa2de93114bae3e73" +"Send 1000 FROTH - 0xb73bf8e6a4477a952e0338e6cc00cc0ce5ad04ba to 0x000000000000000000000002e44fbfbd00395de5" +``` + +## API Reference + +### Actions + +#### SEND_COIN + +Transfers native FLOW tokens, Cadence fungible tokens, or EVM tokens to specified addresses. + +**Aliases:** +- SEND_TOKEN +- SEND_TOKEN_ON_FLOW +- TRANSFER_TOKEN_ON_FLOW +- TRANSFER_TOKENS_ON_FLOW +- TRANSFER_FLOW +- SEND_FLOW +- PAY_BY_FLOW + +**Input Content:** +```typescript +interface TransferContent { + token: string | null; // null for native FLOW, Cadence identifier, or EVM address + amount: string; // Amount to transfer + to: string; // Recipient address (Flow or EVM) + matched: boolean; // Indicates if token and address types match +} +``` + +## Common Issues & Troubleshooting + +1. **Connection Issues** + - Verify network configuration (mainnet/testnet/emulator) + - Check RPC endpoint availability + - Ensure proper wallet configuration + +2. **Transaction Failures** + - Verify sufficient balance for transfers + - Check correct address format (Flow vs EVM) + - Confirm token contract compatibility + +3. **Authentication Issues** + - Validate private key format + - Verify wallet address matches private key + - Check network permissions + +## Security Best Practices + +1. **Key Management** + - Store private keys securely + - Use environment variables for sensitive data + - Never expose private keys in code or logs + +2. **Transaction Safety** + - Validate all addresses before transfers + - Implement proper error handling + - Check token compatibility before transfers + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +4. Run tests: + +```bash +pnpm run test +``` + +## Future Enhancements + +- Support for NFT transfers +- Enhanced error handling and recovery +- Additional Flow blockchain interactions +- Expanded token support + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Flow Blockchain](https://flow.com/): Decentralized layer 1 blockchain +- [@onflow/fcl](https://www.npmjs.com/package/@onflow/fcl): Flow Client Library +- [@onflow/types](https://www.npmjs.com/package/@onflow/types): Flow type system +- [Cadence](https://docs.onflow.org/cadence/): Smart contract programming language + +Special thanks to: +- The Dapper Labs team for developing Flow +- The Flow Developer community +- The FCL SDK maintainers +- The Cadence language designers +- The Eliza community for their contributions and feedback + +For more information about Flow capabilities: +- [Flow Documentation](https://docs.onflow.org/) +- [Flow Developer Portal](https://developers.flow.com/) +- [Flow Block Explorer](https://flowscan.org/) +- [Cadence Documentation](https://docs.onflow.org/cadence/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. -Message sample: `Send 5 FLOW to 0xa51d7fe9e0080662` diff --git a/packages/plugin-fuel/README.md b/packages/plugin-fuel/README.md new file mode 100644 index 0000000000..104a416a88 --- /dev/null +++ b/packages/plugin-fuel/README.md @@ -0,0 +1,147 @@ +# @elizaos/plugin-fuel + +A plugin for interacting with the Fuel blockchain within the ElizaOS ecosystem. + +## Description + +This plugin provides essential functionality for interacting with the Fuel blockchain, focusing on ETH transfers on the Fuel Ignition network. It offers a streamlined way to manage Fuel blockchain transactions through natural language commands. + +## Installation + +```bash +pnpm install @elizaos/plugin-fuel +``` + +## Configuration + +The plugin requires the following environment variables to be set: +```typescript +FUEL_PRIVATE_KEY= +FUEL_PROVIDER_URL= +``` + +## Usage + +### Basic Integration + +```typescript +import { fuelPlugin } from '@elizaos/plugin-fuel'; +``` + +### Example Usage + +The plugin supports natural language commands for ETH transfers: + +```typescript +"Transfer 1 ETH to 0x8F8afB12402C9a4bD9678Bec363E51360142f8443FB171655eEd55dB298828D1" +``` + +## API Reference + +### Actions + +#### TRANSFER + +Transfers ETH between addresses on the Fuel Ignition network. + +**Aliases:** +- TRANSFER_FUEL_ETH +- SEND_TOKENS + +**Input Content:** +```typescript +interface TransferParams { + toAddress: string; // Recipient's Fuel address + amount: string; // Amount of ETH to transfer +} +``` + +## Common Issues & Troubleshooting + +1. **Connection Issues** + - Verify provider URL is accessible + - Check network connectivity + - Ensure proper network configuration + +2. **Transaction Failures** + - Verify sufficient balance for transfers + - Check correct address format + - Ensure gas fees can be covered + +3. **Authentication Issues** + - Validate private key format + - Verify wallet configuration + - Check network permissions + +## Security Best Practices + +1. **Key Management** + - Store private keys securely + - Use environment variables for sensitive data + - Never expose private keys in code or logs + +2. **Transaction Safety** + - Validate recipient addresses + - Implement proper error handling + - Double-check transaction amounts + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +4. Run tests: + +```bash +pnpm test +``` + +## Future Enhancements + +- Support for token transfers +- Enhanced error handling and recovery +- Additional Fuel blockchain interactions +- Transaction status monitoring +- Balance tracking improvements + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Fuel Network](https://fuel.network/): High-performance modular execution layer +- [fuels-ts](https://github.com/FuelLabs/fuels-ts): TypeScript SDK for Fuel +- [Fuel Wallet](https://wallet.fuel.network/): Official Fuel wallet +- [Fuel GraphQL API](https://docs.fuel.network/docs/graphql/): Network interaction + +Special thanks to: +- The Fuel Labs team for developing the Fuel Network +- The Fuel Developer community +- The fuels-ts SDK maintainers +- The Eliza community for their contributions and feedback + +For more information about Fuel capabilities: +- [Fuel Documentation](https://docs.fuel.network/) +- [Fuel Developer Portal](https://developers.fuel.network/) +- [Fuel Network Dashboard](https://app.fuel.network/) +- [Fuel GitHub Repository](https://github.com/FuelLabs) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-gitbook/README.md b/packages/plugin-gitbook/README.md new file mode 100644 index 0000000000..b6bdd05b1a --- /dev/null +++ b/packages/plugin-gitbook/README.md @@ -0,0 +1,184 @@ +# @elizaos/plugin-gitbook + +A plugin for querying and retrieving information from GitBook documentation within the ElizaOS ecosystem. + +## Description + +This plugin enables seamless integration with GitBook documentation, allowing natural language queries to retrieve relevant documentation content. It features intelligent query validation, keyword-based filtering, and clean response formatting to provide accurate documentation answers. + +## Installation + +```bash +pnpm install @elizaos/plugin-gitbook +``` + +## Configuration + +### Environment Variables +```typescript +GITBOOK_SPACE_ID= +``` + +### Client Configuration (Optional) +You can customize the plugin's behavior by adding the following configuration to your character.json file: +```json +{ + "name": "YourCharacter", + "plugins": ["gitbook"], + "settings": { + "gitbook": { + "keywords": { + "projectTerms": ["term1", "term2"], // Optional: Project-specific terms to match + "generalQueries": ["custom1", "custom2"] // Optional: Additional query keywords + }, + "documentTriggers": ["docs", "documentation"] // Optional: Trigger words for documentation + } + } +} +``` + +The plugin will work with default settings if no configuration is provided, but adding custom configuration can help tailor the responses to your specific documentation needs. + +## Usage + +### Basic Integration + +```typescript +import { gitbookPlugin } from '@elizaos/plugin-gitbook'; +``` + +### Example Usage + +The plugin automatically processes natural language queries: + +```typescript +"How do I get started with the project?" +"What are the main features?" +"Explain how to configure the system" +``` + +## API Reference + +### Providers + +#### GitBook Provider + +Handles documentation queries and returns relevant information. + +**Response Type:** +```typescript +interface GitBookResponse { + answer?: { + text: string; + }; + error?: string; +} +``` + +**Configuration Types:** +```typescript +interface GitBookKeywords { + projectTerms?: string[]; // Project-specific terms + generalQueries?: string[]; // Additional query keywords +} + +interface GitBookClientConfig { + keywords?: GitBookKeywords; + documentTriggers?: string[]; // Trigger words for documentation +} +``` + +## Common Issues & Troubleshooting + +1. **Connection Issues** + - Verify GitBook Space ID is correct + - Check API endpoint accessibility + - Ensure proper network connectivity + +2. **Query Issues** + - Verify query contains valid keywords + - Check if query matches project terms + - Ensure proper query formatting + +3. **Response Issues** + - Validate GitBook API response format + - Check for rate limiting + - Verify content accessibility + +## Security Best Practices + +1. **API Configuration** + - Store Space ID securely + - Use environment variables + - Implement proper error handling + +2. **Query Validation** + - Sanitize input queries + - Validate keywords and triggers + - Clean response content + +3. **Response Handling** + - Implement proper error handling + - Validate response format + - Handle sensitive information appropriately + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +4. Run tests: + +```bash +pnpm test +``` + +## Future Enhancements + +- Enhanced query validation +- Support for multiple GitBook spaces +- Advanced search capabilities +- Custom response formatting +- Caching mechanism for frequent queries +- Support for authenticated endpoints + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [GitBook](https://www.gitbook.com/): Documentation and knowledge base platform +- [GitBook API](https://developer.gitbook.com/): Official GitBook REST API +- [Axios](https://axios-http.com/): Promise-based HTTP client +- [js-tiktoken](https://github.com/dqbd/tiktoken): Token counting for API responses + +Special thanks to: +- The GitBook team for their documentation platform +- The GitBook Developer Relations team +- The Axios maintainers for reliable HTTP requests +- The Eliza community for their contributions and feedback + +For more information about GitBook capabilities: +- [GitBook Documentation](https://docs.gitbook.com/) +- [GitBook API Reference](https://developer.gitbook.com/reference) +- [GitBook Integrations](https://docs.gitbook.com/integrations/git-sync) +- [GitBook Space Management](https://docs.gitbook.com/space/space-management) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-goat/README.md b/packages/plugin-goat/README.md index 6dca2160d5..5c99145284 100644 --- a/packages/plugin-goat/README.md +++ b/packages/plugin-goat/README.md @@ -1,24 +1,31 @@ -# GOAT Plugin +# @elizaos/plugin-goat + +A plugin for integrating blockchain capabilities through the GOAT (Great Onchain Agent Toolkit) framework within the ElizaOS ecosystem. + +## Description + [GOAT](https://ohmygoat.dev/) 🐐 (Great Onchain Agent Toolkit) is an open-source framework for adding blockchain tools such as wallets, being able to hold or trade tokens, or interacting with blockchain smart contracts, to your AI agent. This plugin integrates GOAT with Eliza, giving your agent the ability to interact with many different protocols. The current setup adds onchain capabilities to your agent to send and check balances of ETH and USDC. Add all the capabilities you need by adding more plugins (read below for more information)! -## Configure GOAT for your use case -1. Configure the chain you want to use by updating the `wallet.ts` file (see all available chains at [https://ohmygoat.dev/chains](https://ohmygoat.dev/chains)) -2. Add the plugins you need to your `getOnChainActions` function (uniswap, polymarket, etc. see all available plugins at [https://ohmygoat.dev/chains-wallets-plugins](https://ohmygoat.dev/chains-wallets-plugins)) -3. Build the project running `pnpm build` -4. Add the necessary environment variables to set up your wallet and plugins -5. Run your agent! +## Installation -## Common Issues -1. **Agent not executing an action**: - - If you are also using the EVM Plugin, sometimes the agent might confuse the action name with an EVM Plugin action name instead of the GOAT Plugin action. Removing the EVM Plugin should fix this issue. There is no need for you to use both plugins at the same time. - - If you are using Trump as a character it might be tricky to get them to perform any action since the character is full of prompts that aim to change the topic of the conversation. To fix this try using a different character or create your own with prompts that are more suitable to what the agent is supposed to do. +```bash +pnpm install @elizaos/plugin-goat +``` + +## Configuration + +### Environment Variables +```typescript +EVM_PRIVATE_KEY= +EVM_PROVIDER_URL= +``` -## Plugins -GOAT itself has several plugins for interacting with different protocols such as Polymarket, Uniswap, and more. (see all available plugins at [https://ohmygoat.dev/chains-wallets-plugins](https://ohmygoat.dev/chains-wallets-plugins)) +## Configure GOAT for your use case -You can easily add them by installing them and adding them to the `getOnChainActions` function: +1. Configure the chain you want to use by updating the `wallet.ts` file (see all available chains at [https://ohmygoat.dev/chains](https://ohmygoat.dev/chains)) +2. Add the plugins you need to your `getOnChainActions` function: ```typescript const tools = getOnChainActions({ @@ -33,14 +40,100 @@ const tools = getOnChainActions({ }) ``` -## Environment Variables Setup +See all available plugins at [https://ohmygoat.dev/chains-wallets-plugins](https://ohmygoat.dev/chains-wallets-plugins) + +## Common Issues & Troubleshooting + +1. **Agent not executing an action**: + - If you are also using the EVM Plugin, sometimes the agent might confuse the action name with an EVM Plugin action name instead of the GOAT Plugin action. Removing the EVM Plugin should fix this issue. There is no need for you to use both plugins at the same time. + - If you are using Trump as a character it might be tricky to get them to perform any action since the character is full of prompts that aim to change the topic of the conversation. To fix this try using a different character or create your own with prompts that are more suitable to what the agent is supposed to do. -To set up your environment variables, you will need to provide the following information: +2. **Wallet Connection Issues** + - Verify private key is correctly formatted + - Check RPC endpoint availability + - Ensure sufficient network balance -* `EVM_PRIVATE_KEY`: Your EVM wallet private key. -* `EVM_PROVIDER_URL`: Your RPC provider URL (e.g. Infura, Alchemy, etc.). +3. **Transaction Issues** + - Verify gas availability + - Check network congestion + - Confirm transaction parameters ## Wallets + GOAT supports many different wallets from key pairs to [Crossmint Smart Wallets](https://docs.crossmint.com/wallets/smart-wallets/overview) and Coinbase. Read more about wallets at [https://ohmygoat.dev/wallets](https://ohmygoat.dev/wallets). + +## Security Best Practices + +1. **Key Management** + - Store private keys securely + - Use environment variables + - Never expose keys in code + +2. **Transaction Safety** + - Implement transaction limits + - Validate recipient addresses + - Double-check transaction amounts + +3. **Network Security** + - Use secure RPC endpoints + - Implement rate limiting + - Monitor for suspicious activity + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: + +```bash +pnpm install +``` + +3. Build the plugin: + +```bash +pnpm run build +``` + +## Future Enhancements + +- Additional protocol integrations +- Multi-chain support +- Advanced transaction management +- Enhanced error handling +- Custom protocol adapters +- Smart contract interaction templates + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [GOAT](https://ohmygoat.dev/): Great Onchain Agent Toolkit +- [Crossmint](https://docs.crossmint.com/): Smart wallet infrastructure +- [Uniswap](https://docs.uniswap.org/): Decentralized exchange protocol +- [Polymarket](https://docs.polymarket.com/): Prediction market platform +- [ERC20](https://eips.ethereum.org/EIPS/eip-20): Token standard implementation + +Special thanks to: +- The GOAT development team for the onchain agent framework +- The Crossmint team for smart wallet solutions +- The Uniswap and Polymarket teams +- The Ethereum community for ERC standards +- The Eliza community for their contributions and feedback + +For more information about GOAT capabilities: +- [GOAT Documentation](https://ohmygoat.dev/) +- [Available Chains](https://ohmygoat.dev/chains) +- [Chains, Wallets & Plugins](https://ohmygoat.dev/chains-wallets-plugins) +- [Smart Wallet Documentation](https://docs.crossmint.com/wallets/smart-wallets/overview) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-icp/README.md b/packages/plugin-icp/README.md new file mode 100644 index 0000000000..7afd424351 --- /dev/null +++ b/packages/plugin-icp/README.md @@ -0,0 +1,222 @@ +# @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 + +```bash +pnpm install @elizaos/plugin-icp +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +INTERNET_COMPUTER_PRIVATE_KEY= +``` + +## Usage + +### Import and Register + +```typescript +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. + +```typescript +// 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. + +```typescript +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 + +```typescript +// 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 + +```typescript +// 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(idlFactory, canisterId, host?) +``` + +## Development Guide + +### Setting Up Development Environment + +1. Clone the repository +2. Install dependencies: +```bash +pnpm install +``` + +3. Build the plugin: +```bash +pnpm run build +``` + +4. Run tests: +```bash +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](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Internet Computer](https://internetcomputer.org/): Decentralized cloud computing platform +- [@dfinity/agent](https://www.npmjs.com/package/@dfinity/agent): ICP HTTP client and agent +- [@dfinity/candid](https://www.npmjs.com/package/@dfinity/candid): Candid interface description language +- [@dfinity/principal](https://www.npmjs.com/package/@dfinity/principal): Principal identifier handling +- [@dfinity/identity](https://www.npmjs.com/package/@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](https://internetcomputer.org/docs/) +- [DFINITY Developer Portal](https://smartcontracts.org/) +- [ICP Dashboard](https://dashboard.internetcomputer.org/) +- [Candid Documentation](https://internetcomputer.org/docs/current/developer-docs/build/candid/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-image-generation/README.md b/packages/plugin-image-generation/README.md new file mode 100644 index 0000000000..a793abb1a3 --- /dev/null +++ b/packages/plugin-image-generation/README.md @@ -0,0 +1,150 @@ +# @elizaos/plugin-image-generation + +Image generation plugin for Eliza OS that supports multiple AI image generation providers. + +## Features + +- Multi-provider support (OpenAI, Together AI, Heurist, FAL AI, Venice AI, Livepeer) +- Intelligent prompt enhancement +- Customizable image parameters +- Automatic image saving and management +- Support for various image formats and sizes +- Fallback provider chain for reliability + +## Installation + +```bash +pnpm install @elizaos/plugin-image-generation +``` + +## Configuration + +The plugin requires at least one of the following API keys: + +```env +ANTHROPIC_API_KEY=your-anthropic-key +TOGETHER_API_KEY=your-together-key +HEURIST_API_KEY=your-heurist-key +FAL_API_KEY=your-fal-key +OPENAI_API_KEY=your-openai-key +VENICE_API_KEY=your-venice-key +LIVEPEER_GATEWAY_URL=your-livepeer-url +``` + +## Usage + +### Basic Image Generation + +```typescript +import { imageGenerationPlugin } from '@elizaos/plugin-image-generation'; + +// Generate an image +const result = await eliza.execute({ + action: 'GENERATE_IMAGE', + content: 'A serene landscape with mountains' +}); +``` + +### Advanced Options + +```typescript +const result = await eliza.execute({ + action: 'GENERATE_IMAGE', + content: 'A futuristic cityscape', + options: { + width: 1024, + height: 1024, + count: 2, + negativePrompt: 'blurry, low quality', + numIterations: 50, + guidanceScale: 7.5, + seed: 12345 + } +}); +``` + +## Supported Image Parameters + +- `width`: Image width (default: 1024) +- `height`: Image height (default: 1024) +- `count`: Number of images to generate +- `negativePrompt`: What to avoid in the generation +- `numIterations`: Number of diffusion steps +- `guidanceScale`: How closely to follow the prompt +- `seed`: For reproducible results +- `modelId`: Specific model to use +- `stylePreset`: Visual style to apply +- `hideWatermark`: Toggle watermark visibility + +## Common Issues & Troubleshooting + +1. **API Key Validation** + - Ensure at least one provider API key is configured + - Check API key validity and quotas + +2. **Image Generation Failures** + - Verify prompt length and content + - Check provider service status + - Confirm supported image dimensions + +3. **File System Issues** + - Ensure write permissions for generatedImages directory + - Check available disk space + - Verify file path accessibility + +## Security Best Practices + +1. **API Key Management** + - Store keys in environment variables + - Never commit API keys to version control + - Rotate keys periodically + +2. **Content Safety** + - Implement content filtering + - Use provider safety settings + - Monitor generated content + +3. **File System Security** + - Sanitize filenames + - Limit access to generated files + - Regular cleanup of temporary files + +## Dependencies + +- @elizaos/core: workspace:* +- tsup: 8.3.5 + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [OpenAI DALL-E](https://openai.com/dall-e-3): Advanced image generation model +- [Together AI](https://www.together.ai/): AI model deployment platform +- [FAL AI](https://fal.ai/): Serverless AI infrastructure +- [Heurist](https://heurist.ai/): AI model optimization +- [Venice AI](https://venice.ai/): Image generation platform +- [Livepeer](https://livepeer.org/): Decentralized video infrastructure + +Special thanks to: +- The OpenAI team for DALL-E technology +- The Together AI team for model deployment tools +- The FAL AI team for serverless infrastructure +- The Heurist team for optimization capabilities +- The Venice AI and Livepeer teams +- The Eliza community for their contributions and feedback + +For more information about image generation capabilities: +- [DALL-E API Documentation](https://platform.openai.com/docs/guides/images) +- [Together AI Documentation](https://docs.together.ai/) +- [FAL AI Documentation](https://fal.ai/docs) +- [Heurist Documentation](https://docs.heurist.ai/) +- [Venice AI Platform](https://docs.venice.ai/) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + diff --git a/packages/plugin-intiface/README.md b/packages/plugin-intiface/README.md new file mode 100644 index 0000000000..c7a2acd049 --- /dev/null +++ b/packages/plugin-intiface/README.md @@ -0,0 +1,200 @@ +# @elizaos/plugin-intiface + +Intiface/Buttplug.io integration plugin for Eliza OS that enables control of intimate hardware devices. + +## Features + +- Support for multiple intimate hardware devices through Buttplug.io protocol +- Automatic device discovery and connection management +- Battery level monitoring for supported devices +- Vibration and rotation control (device-dependent) +- Graceful connection handling and cleanup +- Built-in device simulation for testing +- Support for customizable vibration patterns +- Automatic Intiface Engine management + +## Installation + +```bash +pnpm install @elizaos/plugin-intiface +``` + +## Configuration + +The plugin can be configured through environment variables or runtime settings: + +```env +INTIFACE_URL=ws://localhost:12345 +INTIFACE_NAME=Eliza Intiface Client +DEVICE_NAME=Lovense Nora +``` + +## Usage + +### Basic Device Control + +```typescript +import { intifacePlugin } from '@elizaos/plugin-intiface'; + +// Vibrate device +const result = await eliza.execute({ + action: 'VIBRATE', + content: { + strength: 0.5, // 0.0 to 1.0 + duration: 1000 // milliseconds + } +}); + +// Check battery level +const battery = await eliza.execute({ + action: 'BATTERY', + content: {} +}); +``` + +### Advanced Features + +```typescript +// Rotation control (for supported devices) +const result = await eliza.execute({ + action: 'ROTATE', + content: { + strength: 0.7, + duration: 2000 + } +}); +``` + +## Device Support + +The plugin supports various devices through the Buttplug protocol, including but not limited to: + +- Lovense devices (Nora, Max, etc.) +- WeVibe products +- Kiiroo devices +- Magic Motion products +- And many others supported by Buttplug.io + +## Testing + +The plugin includes a simulation mode for testing without physical hardware: + +```bash +pnpm test-via-bun +``` + +## Dependencies + +- Buttplug.io (v3.2.2) +- Intiface Engine +- WebSocket support + +## Troubleshooting + +### Common Issues + +1. **Connection Problems** + - Verify Intiface Engine is running (`ws://localhost:12345` by default) + - Check device Bluetooth is enabled and in pairing mode + - Ensure device is charged and within range + - Try restarting both device and Intiface Engine + +2. **Device Not Found** + - Confirm device is supported by Buttplug.io + - Try manual device pairing through Intiface Central first + - Check if device requires specific firmware version + - Verify device is not connected to another application + +3. **Command Failures** + - Check battery level is sufficient + - Ensure device is within supported range for command values + - Verify device supports the specific command (vibrate/rotate) + - Monitor Intiface Engine logs for detailed error messages + +4. **Performance Issues** + - Reduce command frequency if experiencing lag + - Check for Bluetooth interference + - Monitor system resources for potential bottlenecks + - Consider using wired connection if available + +## Security Best Practices + +1. **Device Privacy** + - Use secure WebSocket connections (wss://) when possible + - Don't expose Intiface Engine to public networks + - Regularly check for and apply firmware updates + - Monitor device connection status + +2. **Data Protection** + - Clear device pairing history when needed + - Don't store sensitive device information + - Use unique device names for identification + - Implement timeouts for idle connections + +3. **Access Control** + - Limit device control to authenticated users + - Implement command rate limiting + - Use device-specific permissions where applicable + - Monitor and log unusual command patterns + +4. **Network Security** + - Keep Intiface Engine behind firewall + - Use local connections when possible + - Implement connection timeouts + - Regular security audits of configurations + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + + +## Credits + +This plugin integrates with [Buttplug.io](https://buttplug.io) and [Intiface Engine](https://github.com/intiface/intiface-engine), developed by Nonpolynomial Labs, LLC. + +Special thanks to: +- The Buttplug.io team for developing the Buttplug.io protocol +- The Intiface Engine team for developing the Intiface Engine +- The Eliza community for their contributions and feedback. + +For more information about Buttplug.io and Intiface Engine: +- [Buttplug.io](https://buttplug.io) +- [Intiface Engine](https://github.com/intiface/intiface-engine) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. + + +Intiface is a Registered Trademark of Nonpolynomial Labs, LLC + +Buttplug and Intiface are BSD licensed. + + Copyright (c) 2016-2022, Nonpolynomial Labs, LLC + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + * Neither the name of buttplug nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + diff --git a/packages/plugin-multiversx/README.md b/packages/plugin-multiversx/README.md new file mode 100644 index 0000000000..90e1aa1fd4 --- /dev/null +++ b/packages/plugin-multiversx/README.md @@ -0,0 +1,178 @@ +# @elizaos/plugin-multiversx + +MultiversX blockchain integration plugin for Eliza OS that enables token management and transfers. + +## Overview + +This plugin aims to be the basis of all interactions with the MultiversX ecosystem. + +## Features + +- EGLD and ESDT token transfers +- Token creation and management +- Multiple network support (mainnet, devnet, testnet) +- Secure transaction signing +- Automatic nonce management +- Transaction status tracking +- Built-in denomination handling +- Comprehensive error handling + +## Adding a new action + +Reuse providers and utilities from the existing actions where possible. Add more utilities if you think they will be useful for other actions. + +1. Add the action to the `actions` directory. Try to follow the naming convention of the other actions. +2. Export the action in the `index.ts` file. + +## Installation + +```bash +pnpm install @elizaos/plugin-multiversx +``` + +## Configuration + +The plugin requires environment variables or runtime settings: + +```env +MVX_PRIVATE_KEY=your-wallet-private-key +MVX_NETWORK=devnet # mainnet, devnet, or testnet +``` + +## Usage + +### Token Transfer + +```typescript +import { multiversxPlugin } from '@elizaos/plugin-multiversx'; + +// Send EGLD +const result = await eliza.execute({ + action: 'SEND_TOKEN', + content: { + tokenAddress: 'erd1...', + amount: '1', + tokenIdentifier: 'EGLD' + } +}); + +// Send ESDT +const result = await eliza.execute({ + action: 'SEND_TOKEN', + content: { + tokenAddress: 'erd1...', + amount: '100', + tokenIdentifier: 'TEST-a1b2c3' + } +}); +``` + +### Token Creation + +```typescript +const result = await eliza.execute({ + action: 'CREATE_TOKEN', + content: { + tokenName: 'TestToken', + tokenTicker: 'TEST', + decimals: '18', + amount: '1000000' + } +}); +``` + +## Troubleshooting + +### Common Issues + +1. **Transaction Failures** + - Verify wallet has sufficient balance + - Check network configuration matches intended network + - Ensure correct token identifiers + - Verify recipient address format + +2. **Configuration Problems** + - Validate private key format + - Check network selection is valid + - Ensure environment variables are properly set + - Verify wallet permissions for token operations + +3. **Token Creation Issues** + - Check token name and ticker format + - Verify EGLD balance for issuance fee + - Ensure unique token identifiers + - Monitor transaction status + +4. **Network Connectivity** + - Verify network endpoint availability + - Check API rate limits + - Monitor network status + - Ensure proper network selection + +## Security Best Practices + +1. **Key Management** + - Never expose private keys in code + - Use environment variables for sensitive data + - Implement key rotation policies + - Monitor wallet activity + +2. **Transaction Safety** + - Validate all transaction parameters + - Implement transaction limits + - Use proper denomination handling + - Double-check recipient addresses + +3. **Network Security** + - Use secure network connections + - Implement retry mechanisms + - Monitor for suspicious activity + - Keep dependencies updated + +4. **Error Handling** + - Implement comprehensive error logging + - Handle network timeouts gracefully + - Validate all user inputs + - Provide clear error messages + +## Testing + +Run the test suite: + +```bash +pnpm test +``` + +Watch mode for development: + +```bash +pnpm test:watch +``` + +## Dependencies + +- @multiversx/sdk-core: ^13.15.0 +- bignumber.js: ^9.1.2 +- tsup: ^8.3.5 +- vitest: ^2.1.5 + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with the [MultiversX blockchain](https://multiversx.com/) using their official SDK. + +Special thanks to: +- The MultiversX team for developing the MultiversX blockchain +- The Eliza community for their contributions and feedback. + +For more information about MultiversX blockchain capabilities: +- [MultiversX Documentation](https://docs.multiversx.com/) +- [MultiversX Developer Portal](https://docs.multiversx.com/developers/getting-started/introduction) +- [MultiversX GitHub Repository](https://github.com/multiversx/mx-sdk-js) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-multiversx/readme.md b/packages/plugin-multiversx/readme.md deleted file mode 100644 index 0c26c8b537..0000000000 --- a/packages/plugin-multiversx/readme.md +++ /dev/null @@ -1,12 +0,0 @@ -# MultiversX Plugin - -## Overview - -This plugin aims to be the basis of all interactions with the MultiversX ecosystem. - -## Adding a new action - -Reuse providers and utilities from the existing actions where possible. Add more utilities if you think they will be useful for other actions. - -1. Add the action to the `actions` directory. Try to follow the naming convention of the other actions. -2. Export the action in the `index.ts` file. diff --git a/packages/plugin-near/README.md b/packages/plugin-near/README.md new file mode 100644 index 0000000000..fe3d6d5aad --- /dev/null +++ b/packages/plugin-near/README.md @@ -0,0 +1,210 @@ +# @elizaos/plugin-near + +NEAR Protocol integration plugin for Eliza OS that enables token management, transfers, and swaps using Ref Finance. + +## Overview + +This plugin aims to be the basis of all interactions with the NEAR ecosystem, providing seamless integration with NEAR Protocol and Ref Finance DEX. + +## Features + +- NEAR token transfers +- Token swaps via Ref Finance +- Multiple network support (mainnet, testnet) +- Secure transaction signing +- Automatic storage deposit handling +- Real-time price feeds +- Portfolio tracking and management +- Smart routing for optimal swaps +- Built-in denomination handling +- Comprehensive error handling + +## Installation + +```bash +pnpm install @elizaos/plugin-near +``` + +## Configuration + +The plugin requires environment variables or runtime settings: + +```env +NEAR_WALLET_SECRET_KEY=your-wallet-private-key +NEAR_WALLET_PUBLIC_KEY=your-wallet-public-key +NEAR_ADDRESS=your-account.near +NEAR_NETWORK=testnet # mainnet or testnet +RPC_URL=https://rpc.testnet.near.org +SLIPPAGE=0.01 # 1% slippage tolerance +``` + +## Usage + +### Token Transfer + +```typescript +import { nearPlugin } from '@elizaos/plugin-near'; + +// Send NEAR +const result = await eliza.execute({ + action: 'SEND_NEAR', + content: { + recipient: 'bob.near', + amount: '1.5' + } +}); +``` + +### Token Swap + +```typescript +const result = await eliza.execute({ + action: 'EXECUTE_SWAP_NEAR', + content: { + inputTokenId: 'wrap.near', + outputTokenId: 'token.v2.ref-finance.near', + amount: '10' + } +}); +``` +## API Reference + +### Actions + +#### `SEND_NEAR` +Transfers NEAR tokens to another account. + +```typescript +{ + action: 'SEND_NEAR', + content: { + recipient: string, // Recipient's NEAR account (e.g., "bob.near") + amount: string, // Amount to send (in NEAR) + tokenAddress?: string // Optional: for NEP-141 tokens + } +} +``` + +#### `EXECUTE_SWAP_NEAR` +Executes a token swap using Ref Finance. + +```typescript +{ + action: 'EXECUTE_SWAP_NEAR', + content: { + inputTokenId: string, // Input token contract (e.g., "wrap.near") + outputTokenId: string, // Output token contract + amount: string, // Amount to swap + slippageTolerance?: number // Optional: default from config + } +} +``` + +### Providers + +#### Wallet Provider +Provides wallet information and portfolio tracking. + +```typescript +const walletInfo = await eliza.getProvider('wallet'); +// Returns formatted portfolio including: +// - Account balance +// - Token balances +// - USD values +// - Market prices +``` + +## Troubleshooting + +### Common Issues + +1. **Transaction Failures** + - Check account balance + - Verify storage deposits + - Ensure sufficient gas + - Confirm slippage tolerance + +2. **Connection Problems** + - Verify RPC endpoint + - Check network selection + - Ensure valid credentials + - Monitor API rate limits + +3. **Swap Issues** + - Verify token pairs exist + - Check liquidity pools + - Confirm price impact + - Monitor slippage settings + +## Security Best Practices + +1. **Key Management** + - Store private keys securely + - Use environment variables + - Implement key rotation + - Monitor account activity + +2. **Transaction Safety** + - Validate all inputs + - Implement amount limits + - Double-check recipients + - Monitor transaction status + +3. **Network Security** + - Use secure RPC endpoints + - Implement retry mechanisms + - Monitor for suspicious activity + - Keep dependencies updated + +4. **Error Handling** + - Log all transaction attempts + - Handle timeouts gracefully + - Validate all user inputs + - Provide clear error messages + +## Testing + +Run the test suite: + +```bash +pnpm test +``` + +Watch mode for development: + +```bash +pnpm test:watch +``` + +## Dependencies + +- near-api-js: ^5.0.1 +- @ref-finance/ref-sdk: ^1.4.6 +- bignumber.js: ^9.1.2 +- node-cache: ^5.1.2 + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with: +- [NEAR Protocol](https://near.org/) +- [Ref Finance](https://ref.finance/) +- Official NEAR JavaScript API and SDKs + +Special thanks to: +- The NEAR Protocol team for developing the NEAR blockchain +- The Ref Finance team for developing the Ref Finance DEX +- The Eliza community for their contributions and feedback. + +For more information about NEAR blockchain capabilities: +- [NEAR Documentation](https://docs.near.org/) +- [NEAR Developer Portal](https://near.org/developers) +- [NEAR Network Dashboard](https://nearscan.io/) +- [NEAR GitHub Repository](https://github.com/nearprotocol/near-api-js) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-nft-generation/README.md b/packages/plugin-nft-generation/README.md new file mode 100644 index 0000000000..f7e953f2a5 --- /dev/null +++ b/packages/plugin-nft-generation/README.md @@ -0,0 +1,229 @@ +# @elizaos/plugin-nft-generation + +NFT collection generation plugin for Eliza OS that enables NFT creation, collection management, and verification on the Solana blockchain. + +## Overview + +This plugin provides comprehensive NFT functionality, including collection creation, NFT minting, and verification, with automatic image generation and metadata management. + +## Features + +- Automated NFT collection creation +- AI-powered image generation for NFTs +- Collection logo generation +- Metadata creation and management +- AWS S3 integration for asset storage +- Solana blockchain integration +- NFT verification system +- Automatic nonce management +- Comprehensive error handling + +## Installation + +```bash +pnpm install @elizaos/plugin-nft-generation +``` + +## Configuration + +The plugin requires environment variables or runtime settings: + +```env +# Solana Configuration +SOLANA_PUBLIC_KEY=your-wallet-public-key +SOLANA_PRIVATE_KEY=your-wallet-private-key +SOLANA_ADMIN_PUBLIC_KEY=admin-public-key +SOLANA_ADMIN_PRIVATE_KEY=admin-private-key +SOLANA_VERIFY_TOKEN=verification-token +SOLANA_CLUSTER=devnet # or mainnet-beta + +# AWS Configuration +AWS_ACCESS_KEY_ID=your-aws-access-key +AWS_SECRET_ACCESS_KEY=your-aws-secret-key +AWS_REGION=aws-region +AWS_S3_BUCKET=bucket-name +``` + +## API Reference + +### Collection Management + +#### `createCollection` +Creates a new NFT collection with an AI-generated logo. + +```typescript +const result = await createCollection({ + runtime: runtimeInstance, + collectionName: "MyCollection", + fee: 0.01 // Optional: royalty fee percentage +}); +``` + +#### `createNFT` +Mints a new NFT in an existing collection. + +```typescript +const nft = await createNFT({ + runtime: runtimeInstance, + collectionName: "MyCollection", + collectionAddress: "collection123", + collectionAdminPublicKey: "admin123", + collectionFee: 0.01, + tokenId: 1 +}); +``` + +#### `verifyNFT` +Verifies an NFT as part of a collection. + +```typescript +const verification = await verifyNFT({ + runtime: runtimeInstance, + collectionAddress: "collection123", + NFTAddress: "nft123" +}); +``` + +## REST API Endpoints + +### POST `/api/nft-generation/create-collection` +Creates a new collection with generated logo. + +### POST `/api/nft-generation/create-nft` +Mints a new NFT with generated artwork. + +### POST `/api/nft-generation/create-nft-metadata` +Generates metadata for an NFT. + +### POST `/api/nft-generation/verify-nft` +Verifies an NFT's collection membership. + +## Example Workflow + +The plugin provides a streamlined process for generating and verifying NFT collections: + +```typescript +import { createCollection, createNFT, verifyNFT } from "./handlers"; + +const runtime = initializeRuntime(); // Replace with actual IAgentRuntime initialization + +(async () => { + // Step 1: Create Collection + const collectionResult = await createCollection({ + runtime, + collectionName: "MyUniqueCollection", + }); + + console.log("Collection created:", collectionResult); + + // Step 2: Create an NFT in the Collection + const nftResult = await createNFT({ + runtime, + collectionName: "MyUniqueCollection", + collectionAddress: collectionResult.address, + collectionAdminPublicKey: collectionResult.collectionInfo.adminPublicKey, + collectionFee: 0.01, + tokenId: 1, + }); + + console.log("NFT created:", nftResult); + + // Step 3: Verify the NFT + const verificationResult = await verifyNFT({ + runtime, + collectionAddress: collectionResult.address, + NFTAddress: nftResult.address, + }); + console.log("NFT verified:", verificationResult); +})(); +``` + +## Example Prompts + +Here are some examples of user prompts to trigger NFT collection generation: + +- "Generate a collection named MyCollection." +- "Create a new NFT collection." +- "Compile an NFT collection for me." +- "Build a sci-fi themed collection." + +## Local Testing with TEE Simulator + +To test locally using a Trusted Execution Environment (TEE) simulator: + +1. Pull the simulator Docker image: +```bash +docker pull phalanetwork/tappd-simulator:latest +``` + +2. Run the simulator: +```bash +docker run --rm -p 8090:8090 phalanetwork/tappd-simulator:latest +``` + +3. Update your environment variable for the simulator: +```env +DSTACK_SIMULATOR_ENDPOINT="http://localhost:8090" +``` + +## Security Best Practices + +1. **Key Management** + - Store private keys securely + - Use environment variables + - Implement key rotation + - Monitor wallet activity + +2. **Asset Security** + - Secure S3 bucket configuration + - Implement proper CORS policies + - Use secure URLs for metadata + - Regular backup of assets + +3. **Transaction Safety** + - Validate all inputs + - Implement fee limits + - Double-check collection ownership + - Monitor transaction status + +4. **Error Handling** + - Log all operations + - Handle timeouts gracefully + - Validate metadata + - Provide clear error messages + +## Dependencies + +- @elizaos/core: workspace:* +- @elizaos/plugin-image-generation: workspace:* +- @elizaos/plugin-node: workspace:* +- @metaplex-foundation/mpl-token-metadata: ^3.3.0 +- @solana/web3.js: 1.95.5 +- express: 4.21.1 +- node-cache: 5.1.2 + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + + +## Credits + +This plugin integrates with: +- [Solana Blockchain](https://solana.com) +- [Metaplex Protocol](https://www.metaplex.com) +- AWS S3 for asset storage + +Special thanks to: +- The Solana ecosystem and all the open-source contributors who make these integrations possible. +- The Eliza community for their contributions and feedback. + +For more information about Solana blockchain capabilities: +- [Solana Documentation](https://docs.solana.com/) +- [Solana Developer Portal](https://solana.com/developers) +- [Solana Network Dashboard](https://solscan.io/) +- [Solana GitHub Repository](https://github.com/solana-labs/solana) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-nft-generation/Readme.md b/packages/plugin-nft-generation/Readme.md deleted file mode 100644 index 2944713942..0000000000 --- a/packages/plugin-nft-generation/Readme.md +++ /dev/null @@ -1,185 +0,0 @@ -### NFT Collection Generation Plugin - -A plugin for handling NFT collection generation, NFT creation, and verification on the Solana blockchain. - -## Handlers - -### createCollection -The createCollection handler generates an NFT collection logo, uploads it to AWS S3, and creates a Solana blockchain collection. - -#### Usage -```typescript -import { createCollection } from "./handlers/createCollection.ts"; - -const result = await createCollection({ - runtime: runtimeInstance, // An instance of IAgentRuntime - collectionName: "MyCollection", // The name of the collection - fee: 0.01, // (Optional) Fee for transactions -}); - -console.log("Collection created:", result); -``` - -#### Features - -Image Generation: Automatically generates a collection logo based on the provided name and theme. -AWS S3 Integration: Uploads the generated logo and metadata to AWS S3. -Solana Blockchain: Creates a collection with the generated logo and metadata on the Solana blockchain. -### createNFT -The createNFT handler generates individual NFTs for a collection. It includes metadata creation and uploads the NFT information to AWS S3. - -#### Usage - -```typescript -import { createNFT } from "./handlers/createNFT.ts"; - -const nftResult = await createNFT({ - runtime: runtimeInstance, - collectionName: "MyCollection", - collectionAddress: "collectionAddress123", - collectionAdminPublicKey: "adminPublicKey123", - collectionFee: 0.01, - tokenId: 1, -}); - -console.log("NFT created:", nftResult); -``` - -### verifyNFT - -The verifyNFT handler verifies an NFT against its collection using the Solana blockchain. - -#### Usage - -```typescript -import { verifyNFT } from "./handlers/verifyNFT.ts"; - -const verificationResult = await verifyNFT({ - runtime: runtimeInstance, - collectionAddress: "collectionAddress123", - NFTAddress: "NFTAddress123", -}); - -console.log("NFT verified:", verificationResult); -```` ---- - -### Example Workflow - -The plugin provides a streamlined process for generating and verifying NFT collections: - -```typescript -import { createCollection, createNFT, verifyNFT } from "./handlers"; - -const runtime = initializeRuntime(); // Replace with actual IAgentRuntime initialization - -(async () => { - // Step 1: Create Collection - const collectionResult = await createCollection({ - runtime, - collectionName: "MyUniqueCollection", - }); - - console.log("Collection created:", collectionResult); - - // Step 2: Create an NFT in the Collection - const nftResult = await createNFT({ - runtime, - collectionName: "MyUniqueCollection", - collectionAddress: collectionResult.address, - collectionAdminPublicKey: collectionResult.collectionInfo.adminPublicKey, - collectionFee: 0.01, - tokenId: 1, - }); - - console.log("NFT created:", nftResult); - - // Step 3: Verify the NFT - const verificationResult = await verifyNFT({ - runtime, - collectionAddress: collectionResult.address, - NFTAddress: nftResult.address, - }); - - console.log("NFT verified:", verificationResult); -})(); -``` - -### Configuration - -#### Environment Variables -``` -Ensure the following environment variables are set for proper functionality: - -Variable Name Description -AWS_ACCESS_KEY_ID AWS access key for S3 uploads -AWS_SECRET_ACCESS_KEY AWS secret key for S3 uploads -AWS_REGION AWS region where S3 is located -AWS_S3_BUCKET Name of the AWS S3 bucket -SOLANA_PUBLIC_KEY Public key for Solana blockchain -SOLANA_PRIVATE_KEY Private key for Solana blockchain -SOLANA_ADMIN_PUBLIC_KEY Admin public key for Solana operations -SOLANA_ADMIN_PRIVATE_KEY Admin private key for Solana operations -``` -#### Example Prompts - -Here are some examples of user prompts to trigger NFT collection generation: - -"Generate a collection named MyCollection." -"Create a new NFT collection." -"Compile an NFT collection for me." -"Build a sci-fi themed collection." - - -#### Local Testing with TEE Simulator - -To test locally using a Trusted Execution Environment (TEE) simulator, follow these steps: - -Pull the simulator Docker image: -``` bash -docker pull phalanetwork/tappd-simulator:latest -``` -Run the simulator: - -``` bash -docker run --rm -p 8090:8090 phalanetwork/tappd-simulator:latest -``` -Update your environment variable for the simulator: - -```env -DSTACK_SIMULATOR_ENDPOINT="http://localhost:8090" -``` - -#### Dependencies - -This plugin relies on the following services and libraries: - -[@elizaos/plugin-node] -[@elizaos/eliza] -[@elizaos/plugin-image-generation] -[@solana/web3.js] - -### Action Configuration - -#### GENERATE_COLLECTION -The action for generating NFT collections is configured with the following parameters: - -```typescript -const nftCollectionGeneration: Action = { - name: "GENERATE_COLLECTION", - description: "Generate an NFT collection for the message", - handler: async (runtime, message, state, options, callback) => { - // Implementation - }, - examples: [ - { - user: "{{user1}}", - content: { text: "Generate a collection named Galaxy." }, - }, - { - agent: "{{agentName}}", - content: { text: "The collection Galaxy has been successfully created." }, - }, - ], -}; -``` diff --git a/packages/plugin-node/README.md b/packages/plugin-node/README.md new file mode 100644 index 0000000000..a995168129 --- /dev/null +++ b/packages/plugin-node/README.md @@ -0,0 +1,302 @@ +# @elizaos/plugin-node + +Core Node.js plugin for Eliza OS that provides essential services and actions for file operations, media processing, and cloud integrations. + +## Overview + +The Node plugin serves as a foundational component of Eliza OS, bridging core Node.js capabilities with the Eliza ecosystem. It provides crucial services for file operations, media processing, speech synthesis, and cloud integrations, enabling both local and cloud-based functionality for Eliza agents. + + +## Features + +- **AWS S3 Integration**: File upload and management with AWS S3 +- **Browser Automation**: Web scraping and content extraction with Playwright +- **Image Processing**: Image description and analysis capabilities +- **PDF Processing**: PDF text extraction and parsing +- **Speech Synthesis**: Text-to-speech using ElevenLabs and VITS +- **Transcription**: Speech-to-text using various providers (OpenAI, Deepgram, Local) +- **Video Processing**: YouTube video download and transcription +- **LLaMA Integration**: Local LLM support with LLaMA models + +## Installation + +```bash +npm install @elizaos/plugin-node +``` + +## Configuration + +The plugin requires various environment variables depending on which services you plan to use: + +### Core Settings +```env +OPENAI_API_KEY=your_openai_api_key +``` + +### Voice Settings (Optional) +```env +ELEVENLABS_XI_API_KEY=your_elevenlabs_api_key +ELEVENLABS_MODEL_ID=eleven_monolingual_v1 +ELEVENLABS_VOICE_ID=your_voice_id +ELEVENLABS_VOICE_STABILITY=0.5 +ELEVENLABS_VOICE_SIMILARITY_BOOST=0.75 +ELEVENLABS_OPTIMIZE_STREAMING_LATENCY=0 +ELEVENLABS_OUTPUT_FORMAT=pcm_16000 +VITS_VOICE=en_US-hfc_female-medium +``` + +### AWS Settings (Optional) +```env +AWS_ACCESS_KEY_ID=your_aws_access_key +AWS_SECRET_ACCESS_KEY=your_aws_secret_key +AWS_REGION=your_aws_region +AWS_S3_BUCKET=your_s3_bucket +AWS_S3_UPLOAD_PATH=your_upload_path +``` + +## Usage + +```typescript +import { createNodePlugin } from "@elizaos/plugin-node"; + +// Initialize the plugin +const nodePlugin = createNodePlugin(); + +// Register with Eliza OS +elizaOS.registerPlugin(nodePlugin); +``` + +## Services + +### AwsS3Service +Handles file uploads and management with AWS S3. + +### BrowserService +Provides web scraping and content extraction capabilities using Playwright. + +### ImageDescriptionService +Processes and analyzes images to generate descriptions. + +### LlamaService +Provides local LLM capabilities using LLaMA models. + +### PdfService +Extracts and processes text content from PDF files. + +### SpeechService +Handles text-to-speech conversion using ElevenLabs and VITS. + +### TranscriptionService +Converts speech to text using various providers. + +### VideoService +Processes video content, including YouTube video downloads and transcription. + +## Actions + +### describeImage +Analyzes and generates descriptions for images. + +```typescript +// Example usage +const result = await runtime.executeAction("DESCRIBE_IMAGE", { + imageUrl: "path/to/image.jpg" +}); +``` + +## Dependencies + +The plugin requires several peer dependencies: +- `onnxruntime-node`: 1.20.1 +- `whatwg-url`: 7.1.0 + +And trusted dependencies: +- `onnxruntime-node`: 1.20.1 +- `sharp`: 0.33.5 + +## Safety & Security + +### File Operations +- **Path Sanitization**: All file paths are sanitized to prevent directory traversal attacks +- **File Size Limits**: Enforced limits on upload sizes +- **Type Checking**: Strict file type validation +- **Temporary File Cleanup**: Automatic cleanup of temporary files + +### API Keys & Credentials +- **Environment Isolation**: Sensitive credentials are isolated in environment variables +- **Access Scoping**: Services are initialized with minimum required permissions +- **Key Rotation**: Support for credential rotation without service interruption + +### Media Processing +- **Resource Limits**: Memory and CPU usage limits for media processing +- **Timeout Controls**: Automatic termination of long-running processes +- **Format Validation**: Strict media format validation before processing + +## Troubleshooting + +### Common Issues + +1. **Service Initialization Failures** +```bash +Error: Service initialization failed +``` +- Verify environment variables are properly set +- Check service dependencies are installed +- Ensure sufficient system permissions + +2. **Media Processing Errors** +```bash +Error: Failed to process media file +``` +- Verify file format is supported +- Check available system memory +- Ensure ffmpeg is properly installed + +3. **AWS S3 Connection Issues** +```bash +Error: AWS credentials not configured +``` +- Verify AWS credentials are set +- Check S3 bucket permissions +- Ensure correct region configuration + +### Debug Mode + +Enable debug logging for detailed troubleshooting: +```typescript +process.env.DEBUG = 'eliza:plugin-node:*'; +``` + +### System Requirements + +- Node.js 16.x or higher +- FFmpeg for media processing +- Minimum 4GB RAM recommended +- CUDA-compatible GPU (optional, for ML features) + +### Performance Optimization + +1. **Cache Management** + - Regular cleanup of `content_cache` directory + - Implement cache size limits + - Monitor disk usage + +2. **Memory Usage** + - Configure max buffer sizes + - Implement streaming for large files + - Monitor memory consumption + +3. **Concurrent Operations** + - Adjust queue size limits + - Configure worker threads + - Monitor process pool + +## Support + +For issues and feature requests, please: +1. Check the troubleshooting guide above +2. Review existing GitHub issues +3. Submit a new issue with: + - System information + - Error logs + - Steps to reproduce + +## Future Enhancements + +1. **File Operations** + - Enhanced streaming capabilities + - Advanced compression options + - Batch file processing + - File type detection + - Metadata management + - Version control integration + +2. **Media Processing** + - Additional video formats + - Advanced image processing + - Audio enhancement tools + - Real-time processing + - Quality optimization + - Format conversion + +3. **Cloud Integration** + - Multi-cloud support + - Advanced caching + - CDN optimization + - Auto-scaling features + - Cost optimization + - Backup automation + +4. **Speech Services** + - Additional voice models + - Language expansion + - Emotion detection + - Voice cloning + - Real-time synthesis + - Custom voice training + +5. **Browser Automation** + - Headless optimization + - Parallel processing + - Session management + - Cookie handling + - Proxy support + - Resource optimization + +6. **Security Features** + - Enhanced encryption + - Access control + - Audit logging + - Threat detection + - Rate limiting + - Compliance tools + +7. **Performance Optimization** + - Memory management + - CPU utilization + - Concurrent operations + - Resource pooling + - Cache strategies + - Load balancing + +8. **Developer Tools** + - Enhanced debugging + - Testing framework + - Documentation generator + - CLI improvements + - Monitoring tools + - Integration templates + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Node.js](https://nodejs.org/) - The core runtime environment +- [FFmpeg](https://ffmpeg.org/) - Media processing capabilities +- [ElevenLabs](https://elevenlabs.io/) - Voice synthesis +- [OpenAI](https://openai.com/) - Transcription and AI services +- [AWS S3](https://aws.amazon.com/s3/) - Cloud storage +- [Playwright](https://playwright.dev/) - Browser automation +- [LLaMA](https://github.com/facebookresearch/llama) - Local language models +- [VITS](https://github.com/jaywalnut310/vits) - Voice synthesis +- [Deepgram](https://deepgram.com/) - Speech recognition +- [Sharp](https://sharp.pixelplumbing.com/) - Image processing + +Special thanks to: +- The Node.js community and all the open-source contributors who make these integrations possible. +- The Eliza community for their contributions and feedback. + +For more information about Node.js capabilities: +- [Node.js Documentation](https://nodejs.org/en/docs/) +- [Node.js Developer Portal](https://nodejs.org/en/about/) +- [Node.js GitHub Repository](https://github.com/nodejs/node) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-solana/README.MD b/packages/plugin-solana/README.MD new file mode 100644 index 0000000000..ed4f95d198 --- /dev/null +++ b/packages/plugin-solana/README.MD @@ -0,0 +1,320 @@ +# @elizaos/plugin-solana + +Core Solana blockchain plugin for Eliza OS that provides essential services and actions for token operations, trading, and DeFi integrations. + +## Overview + +The Solana plugin serves as a foundational component of Eliza OS, bridging Solana blockchain capabilities with the Eliza ecosystem. It provides crucial services for token operations, trading, portfolio management, and DeFi integrations, enabling both automated and user-directed interactions with the Solana blockchain. + +## Features + +### Token Operations +- **Token Creation**: Deploy new tokens with customizable metadata +- **Token Transfers**: Send and receive tokens securely +- **Balance Management**: Track and manage token balances +- **Portfolio Analytics**: Real-time portfolio valuation and tracking + +### Trading Operations +- **Token Swaps**: Execute trades between tokens using Jupiter aggregator +- **Order Management**: Place and track token orders +- **Price Monitoring**: Real-time price feeds and historical data +- **Automated Trading**: Configurable trading strategies and automation + +### DeFi Integration +- **Liquidity Analysis**: Monitor and analyze pool liquidity +- **Market Making**: Automated market making capabilities +- **Yield Optimization**: Smart routing for optimal yields +- **Risk Management**: Advanced risk scoring and monitoring + +### Trust & Security +- **Trust Scoring**: Dynamic trust score calculation for tokens +- **Risk Assessment**: Real-time risk evaluation for trades +- **Performance Tracking**: Historical performance monitoring +- **Simulation Mode**: Test strategies without real transactions + +## Security Features + +### Access Control +- **Wallet Management**: Secure wallet key derivation and storage +- **Permission Scoping**: Granular control over trading permissions +- **TEE Integration**: Trusted Execution Environment support +- **Key Protection**: Secure private key handling + +### Risk Management +- **Trade Limits**: Configurable transaction limits +- **Slippage Protection**: Automatic slippage controls +- **Validation Checks**: Multi-level transaction validation +- **Simulation Support**: Pre-execution transaction simulation +## Installation + +```bash +npm install @elizaos/plugin-solana +``` + +## Configuration + +Configure the plugin by setting the following environment variables: + +```typescript +const solanaEnvSchema = { + WALLET_SECRET_SALT: string (optional), + WALLET_SECRET_KEY: string, + WALLET_PUBLIC_KEY: string, + SOL_ADDRESS: string, + SLIPPAGE: string, + RPC_URL: string, + HELIUS_API_KEY: string, + BIRDEYE_API_KEY: string +} +``` + +## Usage + +### Basic Setup +```typescript +import { solanaPlugin } from "@elizaos/plugin-solana"; + +// Initialize the plugin +const runtime = await initializeRuntime({ + plugins: [solanaPlugin] +}); +``` + +### Services + +#### TokenProvider +Manages token operations and information retrieval. +```typescript +const tokenProvider = new TokenProvider(tokenAddress, walletProvider, cacheManager); +await tokenProvider.getTokensInWallet(runtime); +``` + +#### WalletProvider +Handles wallet operations and portfolio management. +```typescript +const walletProvider = new WalletProvider(connection, publicKey); +await walletProvider.getFormattedPortfolio(runtime); +``` + +#### TrustScoreProvider +Evaluates and manages trust scores for tokens and trading activities. +```typescript +const trustScore = await runtime.getProvider("trustScore"); +``` +## Actions + +### executeSwap +Executes a token swap using Jupiter aggregator. + +```typescript +// Example usage +const result = await runtime.executeAction("EXECUTE_SWAP", { + inputTokenSymbol: "SOL", + outputTokenSymbol: "USDC", + amount: 0.1 +}); +``` + +### transferToken +Transfers tokens between wallets. + +```typescript +// Example usage +const result = await runtime.executeAction("TRANSFER_TOKEN", { + tokenAddress: "TokenAddressHere", + recipient: "RecipientAddressHere", + amount: "1000" +}); +``` + +### takeOrder +Places a buy order based on conviction level. + +```typescript +// Example usage +const result = await runtime.executeAction("TAKE_ORDER", { + ticker: "SOL", + contractAddress: "ContractAddressHere" +}); +``` + +### pumpfun +Creates and buys tokens on pump.fun. + +```typescript +// Example usage +const result = await runtime.executeAction("CREATE_AND_BUY_TOKEN", { + tokenMetadata: { + name: "TokenName", + symbol: "SYMBOL", + description: "Token description", + image_description: "Image description" + }, + buyAmountSol: 0.1 +}); +``` + +### fomo +Creates and buys tokens on fomo.fund. + +```typescript +// Example usage +const result = await runtime.executeAction("CREATE_AND_BUY_TOKEN", { + tokenMetadata: { + name: "TokenName", + symbol: "SYMBOL", + description: "Token description", + image_description: "Image description" + }, + buyAmountSol: 0.1, + requiredLiquidity: 1000 +}); +``` +### executeSwapForDAO +Executes token swaps for DAO operations. + +```typescript +// Example usage +const result = await runtime.executeAction("EXECUTE_SWAP_DAO", { + inputTokenSymbol: "SOL", + outputTokenSymbol: "USDC", + amount: 0.1 +}); +``` + +## Performance Optimization + +1. **Cache Management** + - Implement token data caching + - Configure cache TTL settings + - Monitor cache hit rates + +2. **RPC Optimization** + - Use connection pooling + - Implement request batching + - Monitor RPC usage + +3. **Transaction Management** + - Optimize transaction bundling + - Implement retry strategies + - Monitor transaction success rates + + +## System Requirements + +- Node.js 16.x or higher +- Solana CLI tools (optional) +- Minimum 4GB RAM recommended +- Stable internet connection +- Access to Solana RPC endpoint + +## Troubleshooting + +### Common Issues + +1. **Wallet Connection Failures** +```bash +Error: Failed to connect to wallet +``` +- Verify RPC endpoint is accessible +- Check wallet configuration settings +- Ensure proper network selection + +2. **Transaction Errors** +```bash +Error: Transaction simulation failed +``` +- Check account balances +- Verify transaction parameters +- Ensure proper fee configuration + +3. **Price Feed Issues** +```bash +Error: Unable to fetch price data +``` +- Verify API key configuration +- Check network connectivity +- Ensure price feed service status + +## Safety & Security +### Best Practices +1. **Environment Variables** + - Store sensitive keys in environment variables + - Use .env.example for non-sensitive defaults + - Never commit real credentials to version control + +2. **Transaction Limits** + - Set maximum transaction amounts + - Implement daily trading limits + - Configure per-token restrictions + +3. **Monitoring** + - Track failed transaction attempts + - Monitor unusual trading patterns + - Log security-relevant events + +4. **Recovery** + - Implement transaction rollback mechanisms + - Maintain backup RPC endpoints + - Document recovery procedures + + +## Performance Optimization + +1. **Cache Management** + - Implement token data caching + - Configure cache TTL settings + - Monitor cache hit rates + +2. **RPC Optimization** + - Use connection pooling + - Implement request batching + - Monitor RPC usage + +3. **Transaction Management** + - Optimize transaction bundling + - Implement retry strategies + - Monitor transaction success rates + +## Support + +For issues and feature requests, please: +1. Check the troubleshooting guide above +2. Review existing GitHub issues +3. Submit a new issue with: + - System information + - Error logs + - Steps to reproduce + - Transaction IDs (if applicable) + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Solana](https://solana.com/) - The core blockchain platform +- [Solana Web3.js](https://github.com/solana-labs/solana-web3.js) - Core Solana interactions +- [SPL Token](https://spl.solana.com/) - Token program interactions +- [Jupiter](https://jup.ag/) - Token swap aggregation +- [Birdeye](https://birdeye.so/) - Price feeds and analytics +- [Helius](https://helius.xyz/) - Enhanced RPC services +- [Anchor](https://project-serum.github.io/anchor/) - Smart contract framework +- [FOMO](https://fomo.fund/) - Token creation and trading +- [Pump.fun](https://pump.fun/) - Token creation and trading + +Special thanks to: +- The Solana ecosystem and all the open-source contributors who make these integrations possible. +- The Eliza community for their contributions and feedback. + +For more information about Solana blockchain capabilities: +- [Solana Documentation](https://docs.solana.com/) +- [Solana Developer Portal](https://solana.com/developers) +- [Solana Network Dashboard](https://solscan.io/) +- [Solana GitHub Repository](https://github.com/solana-labs/solana) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-starknet/README.md b/packages/plugin-starknet/README.md new file mode 100644 index 0000000000..b55ebf87b8 --- /dev/null +++ b/packages/plugin-starknet/README.md @@ -0,0 +1,156 @@ +# @elizaos/plugin-starknet + +Core Starknet blockchain plugin for Eliza OS that provides essential services and actions for token operations, trading, and DeFi integrations. + +## Overview + +The Starknet plugin serves as a foundational component of Eliza OS, bridging Starknet blockchain capabilities with the Eliza ecosystem. It provides crucial services for token operations, trading, portfolio management, and DeFi integrations, enabling both automated and user-directed interactions with the Starknet blockchain. + +## Features + +### Token Operations +- **Token Creation**: Deploy new unruggable tokens with customizable metadata +- **Token Transfers**: Send and receive tokens securely +- **Balance Management**: Track and manage token balances +- **Portfolio Analytics**: Real-time portfolio valuation and tracking + +### Trading Operations +- **Token Swaps**: Execute token swaps through aggregated DEX liquidity +- **Order Management**: Place and manage trading orders +- **Price Monitoring**: Track token prices and market movements +- **Trust Score Analysis**: Evaluate token and trader reliability + +### DeFi Integration +- **Liquidity Management**: Monitor and manage liquidity positions +- **Yield Optimization**: Track and optimize yield farming opportunities +- **Risk Assessment**: Analyze and monitor DeFi protocol risks +- **Performance Tracking**: Monitor investment performance metrics + +## Configuration + +The plugin requires the following environment variables: + +```typescript +STARKNET_ADDRESS=your_starknet_address +STARKNET_PRIVATE_KEY=your_private_key +STARKNET_RPC_URL=your_rpc_url +``` + +## Actions + +### deployToken +Deploys a new unruggable token on Starknet. + +```typescript +// Example usage +const result = await runtime.executeAction("DEPLOY_STARKNET_UNRUGGABLE_MEME_TOKEN", { + name: "TokenName", + symbol: "TKN", + owner: "OwnerAddressHere", + initialSupply: "1000000000000000000" +}); +``` + +### transferToken +Transfers tokens between wallets. + +```typescript +// Example usage +const result = await runtime.executeAction("TRANSFER_TOKEN", { + tokenAddress: "TokenAddressHere", + recipient: "RecipientAddressHere", + amount: "1000" +}); +``` + +### executeSwap +Executes a token swap on Starknet. + +```typescript +// Example usage +const result = await runtime.executeAction("EXECUTE_STARKNET_SWAP", { + sellTokenAddress: "SellTokenAddressHere", + buyTokenAddress: "BuyTokenAddressHere", + sellAmount: "1000000000000000000" +}); +``` + +### transferSubdomain +Creates and transfers a subdomain. + +```typescript +// Example usage +const result = await runtime.executeAction("CREATE_SUBDOMAIN", { + subdomain: "subdomain.domain.stark", + recipient: "RecipientAddressHere" +}); +``` + +## Security Considerations + +1. **Access Control** + - Validate transaction signers + - Implement role-based permissions + - Secure private key storage + +2. **Transaction Limits** + - Set maximum transaction amounts + - Implement daily trading limits + - Configure per-token restrictions + +3. **Monitoring** + - Track failed transaction attempts + - Monitor unusual trading patterns + - Log security-relevant events + +4. **Recovery** + - Implement transaction rollback mechanisms + - Maintain backup RPC endpoints + - Document recovery procedures + +## Performance Optimization + +1. **Cache Management** + - Implement token data caching + - Configure cache TTL settings + - Monitor cache hit rates + +2. **RPC Optimization** + - Use connection pooling + - Implement request batching + - Monitor RPC usage + +3. **Transaction Management** + - Batch similar transactions + - Optimize gas usage + - Handle transaction retries + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Starknet](https://starknet.io/) - The core blockchain platform +- [Starknet.js](https://github.com/starknet-io/starknet.js) - Core Starknet interactions +- [Unruggable](https://unruggable.meme/) - Token creation and security +- [Ekubo](https://www.ekubo.org/) - DEX integrations +- [Avnu](https://avnu.fi/) - Token swap aggregation +- [Birdeye](https://birdeye.so/) - Price feeds and analytics +- [Helius](https://helius.xyz/) - Enhanced RPC services + +Special thanks to: +- The Starknet ecosystem and all the open-source contributors who make these integrations possible. +- The Eliza community for their contributions and feedback. + +For more information about Starknet blockchain capabilities: +- [Starknet Documentation](https://docs.starknet.io/) +- [Starknet Developer Portal](https://starknet.io/developers) +- [Starknet Network Dashboard](https://starknet.io/dashboard) +- [Starknet GitHub Repository](https://github.com/starkware-libs/starknet) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-starknet/readme.md b/packages/plugin-starknet/readme.md deleted file mode 100644 index 799d6592ab..0000000000 --- a/packages/plugin-starknet/readme.md +++ /dev/null @@ -1,17 +0,0 @@ -# Starknet Plugin - -## Overview - -This plugin aims to be the basis of all interactions with the Starknet ecosystem. It contains utilities along with actions for DeFi protocols. - -## Adding a new action - -Reuse providers and utilities from the existing actions where possible. Add more utilities if you think they will be useful for other actions. - -1. Add the action to the `actions` directory. Try to follow the naming convention of the other actions. -2. Export the action in the `index.ts` file. - -## TODO: - -1. Ekubo DCA -2. Unruggable diff --git a/packages/plugin-story/README.md b/packages/plugin-story/README.md new file mode 100644 index 0000000000..9f8661626d --- /dev/null +++ b/packages/plugin-story/README.md @@ -0,0 +1,228 @@ +# @elizaos/plugin-story + +The Story Protocol plugin enables interaction with Story Protocol's IP management and licensing system on the Odyssey testnet. + +## Overview + +This plugin provides functionality to: +- Register IP assets on Story Protocol +- License IP assets +- Attach license terms to IP assets +- Query IP asset details and available licenses +- Manage wallet interactions with Story Protocol + +## Installation + +```bash +npm install @elizaos/plugin-story +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +STORY_PRIVATE_KEY=your_private_key +STORY_API_KEY=your_api_key +STORY_API_BASE_URL=https://api.story.xyz +PINATA_JWT=your_pinata_jwt_token +``` + +## Usage + +Import and register the plugin in your Eliza configuration: + +```typescript +import { storyPlugin } from "@elizaos/plugin-story"; + +export default { + plugins: [storyPlugin], + // ... other configuration +}; +``` + +## Features + +### Register IP + +Register a new IP asset on Story Protocol: + +```typescript +// Example conversation +User: "I want to register my IP titled 'My Story' with the description 'An epic tale'" +Assistant: "I'll help you register your IP on Story Protocol..." +``` + +### License IP + +License an existing IP asset: + +```typescript +// Example conversation +User: "I want to license IP Asset 0x1234...5678 with license terms ID 1" +Assistant: "I'll help you license that IP asset..." +``` + +### Attach Terms + +Attach license terms to an IP asset: + +```typescript +// Example conversation +User: "I want to attach commercial license terms with 10% revenue share to IP 0x1234...5678" +Assistant: "I'll help you attach those license terms..." +``` + +### Get IP Details + +Query details about an IP asset: + +```typescript +// Example conversation +User: "Get details for IP Asset 0x1234...5678" +Assistant: "Here are the details for that IP asset..." +``` + +### Get Available Licenses + +Query available licenses for an IP asset: + +```typescript +// Example conversation +User: "What licenses are available for IP Asset 0x1234...5678?" +Assistant: "Here are the available licenses..." +``` + +## API Reference + +### Actions + +- `REGISTER_IP`: Register a new IP asset +- `LICENSE_IP`: License an existing IP asset +- `ATTACH_TERMS`: Attach license terms to an IP +- `GET_IP_DETAILS`: Get details about an IP +- `GET_AVAILABLE_LICENSES`: Get available licenses for an IP + +### Providers + +- `storyWalletProvider`: Manages wallet interactions with Story Protocol + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +## Dependencies + +- `@story-protocol/core-sdk`: Core SDK for Story Protocol +- `@pinata/sdk`: IPFS pinning service +- `viem`: Ethereum interaction library +- Other standard dependencies listed in package.json + +## Future Enhancements + +The following features and improvements are planned for future releases: + +1. **IP Management** + - Batch IP registration + - Advanced metadata management + - IP relationship mapping + - Automated IP verification + - Collection management + - IP analytics dashboard + +2. **Licensing Features** + - Custom license templates + - License negotiation tools + - Automated royalty distribution + - Usage tracking system + - License violation detection + - Bulk licensing tools + +3. **Rights Management** + - Advanced permission systems + - Rights transfer automation + - Usage rights tracking + - Derivative works management + - Rights verification tools + - Dispute resolution system + +4. **Smart Contract Integration** + - Contract deployment templates + - Automated verification + - Contract upgrade system + - Security analysis tools + - Gas optimization + - Multi-signature support + +5. **Content Management** + - Media file handling + - Content versioning + - Distribution tracking + - Content authentication + - Storage optimization + - Format conversion tools + +6. **Revenue Management** + - Automated payments + - Revenue sharing tools + - Payment tracking + - Financial reporting + - Tax documentation + - Audit trail system + +7. **Developer Tools** + - Enhanced SDK features + - Testing framework + - Documentation generator + - CLI improvements + - Integration templates + - Performance monitoring + +8. **Analytics and Reporting** + - Usage statistics + - Revenue analytics + - License tracking + - Performance metrics + - Custom reporting + - Market analysis tools + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Story Protocol](https://www.story.xyz/): IP management and licensing platform +- [@story-protocol/core-sdk](https://www.npmjs.com/package/@story-protocol/core-sdk): Official Story Protocol SDK +- [@pinata/sdk](https://www.npmjs.com/package/@pinata/sdk): IPFS pinning service +- [viem](https://www.npmjs.com/package/viem): Ethereum interaction library + +Special thanks to: +- The Story Protocol team for developing the IP management platform +- The Story Protocol Developer community +- The Pinata team for IPFS infrastructure +- The Eliza community for their contributions and feedback + +For more information about Story Protocol capabilities: +- [Story Protocol Documentation](https://docs.story.xyz/) +- [Story Protocol Dashboard](https://app.story.xyz/) +- [Story Protocol Blog](https://www.story.xyz/blog) +- [Story Protocol GitHub](https://github.com/storyprotocol) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-sui/README.md b/packages/plugin-sui/README.md new file mode 100644 index 0000000000..a903f0dc69 --- /dev/null +++ b/packages/plugin-sui/README.md @@ -0,0 +1,165 @@ +# @elizaos/plugin-sui + +Core Sui blockchain plugin for Eliza OS that provides essential services and actions for token operations and wallet management. + +## Overview + +This plugin provides functionality to: +- Transfer SUI tokens between wallets +- Query wallet balances and portfolio values +- Track token prices and valuations +- Manage wallet interactions with the Sui network + +## Installation + +```bash +npm install @elizaos/plugin-sui +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +SUI_PRIVATE_KEY=your_private_key +SUI_NETWORK=mainnet|testnet|devnet|localnet +``` + +## Usage + +Import and register the plugin in your Eliza configuration: + +```typescript +import { suiPlugin } from "@elizaos/plugin-sui"; + +export default { + plugins: [suiPlugin], + // ... other configuration +}; +``` + +## Features + +### Send Token + +Transfer SUI tokens to another address: + +```typescript +// Example conversation +User: "Send 1 SUI to 0x4f2e63be8e7fe287836e29cde6f3d5cbc96eefd0c0e3f3747668faa2ae7324b0" +Assistant: "I'll send 1 SUI token now..." +``` + +### Check Wallet Balance + +Query wallet balance and portfolio value: + +```typescript +// Example conversation +User: "What's my wallet balance?" +Assistant: "Your wallet contains 10.5 SUI ($42.00 USD)..." +``` + +## API Reference + +### Actions + +- `SEND_TOKEN`: Transfer SUI tokens to another address +- `TRANSFER_TOKEN`: Alias for SEND_TOKEN +- `SEND_SUI`: Alias for SEND_TOKEN +- `PAY`: Alias for SEND_TOKEN + +### Providers + +- `walletProvider`: Manages wallet interactions with the Sui network, including balance queries and portfolio tracking + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +## Dependencies + +- `@mysten/sui`: Core Sui blockchain interaction library +- `bignumber.js`: Precise number handling +- `node-cache`: Caching implementation +- Other standard dependencies listed in package.json + +## Future Enhancements + +The following features and improvements are planned for future releases: + +1. **Transaction Management** + - Batch transaction processing + - Transaction simulation + - Gas optimization strategies + - Custom transaction builders + - Advanced error handling + +2. **Wallet Integration** + - Multi-wallet support + - Hardware wallet integration + - Social recovery options + - Account abstraction + - Transaction history tracking + +3. **Smart Contract Features** + - Contract deployment tools + - Move module templates + - Testing framework + - Upgrade management + - Security analysis + +4. **Token Operations** + - Batch token transfers + - NFT support enhancement + - Token metadata handling + - Custom token standards + - Collection management + +5. **Developer Tools** + - Enhanced debugging + - CLI improvements + - Documentation generator + - Integration templates + - Performance monitoring + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Sui Blockchain](https://sui.io/): Next-generation smart contract platform +- [@mysten/sui.js](https://www.npmjs.com/package/@mysten/sui.js): Official Sui SDK +- [bignumber.js](https://github.com/MikeMcl/bignumber.js/): Precise number handling +- [node-cache](https://www.npmjs.com/package/node-cache): Caching implementation + +Special thanks to: +- The Mysten Labs team for developing Sui +- The Sui Developer community +- The Sui SDK maintainers +- The Eliza community for their contributions and feedback + +For more information about Sui blockchain capabilities: +- [Sui Documentation](https://docs.sui.io/) +- [Sui Developer Portal](https://sui.io/developers) +- [Sui Network Dashboard](https://suiscan.xyz/) +- [Sui GitHub Repository](https://github.com/MystenLabs/sui) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-tee/README.md b/packages/plugin-tee/README.md index c66bebf852..32d281ff13 100644 --- a/packages/plugin-tee/README.md +++ b/packages/plugin-tee/README.md @@ -1,16 +1,50 @@ -# Plugin TEE +# @elizaos/plugin-tee -A plugin for handling Trusted Execution Environment (TEE) operations. +A plugin for handling Trusted Execution Environment (TEE) operations, providing secure key derivation and remote attestation capabilities. -## Providers +## Overview -This plugin includes several providers for handling different TEE-related operations. +This plugin provides functionality to: +- Generate secure keys within a TEE environment +- Derive Ed25519 keypairs for Solana +- Derive ECDSA keypairs for Ethereum +- Generate remote attestation quotes +- Manage wallet interactions with TEE-derived keys -### DeriveKeyProvider +## Installation + +```bash +npm install @elizaos/plugin-tee +``` -The `DeriveKeyProvider` allows for secure key derivation within a TEE environment. It supports deriving keys for both Solana (Ed25519) and Ethereum (ECDSA) chains. +## Configuration -#### Usage +The plugin requires the following environment variables: + +```env +TEE_MODE=LOCAL|DOCKER|PRODUCTION +WALLET_SECRET_SALT=your_secret_salt # Required for single agent deployments +DSTACK_SIMULATOR_ENDPOINT=your-endpoint-url # Optional, for simulator purposes +``` + +## Usage + +Import and register the plugin in your Eliza configuration: + +```typescript +import { teePlugin } from "@elizaos/plugin-tee"; + +export default { + plugins: [teePlugin], + // ... other configuration +}; +``` + +## Features + +### DeriveKeyProvider + +The `DeriveKeyProvider` allows for secure key derivation within a TEE environment: ```typescript import { DeriveKeyProvider } from "@elizaos/plugin-tee"; @@ -19,59 +53,52 @@ import { DeriveKeyProvider } from "@elizaos/plugin-tee"; const provider = new DeriveKeyProvider(); // Derive a raw key -try { - const rawKey = await provider.rawDeriveKey( - "/path/to/derive", - "subject-identifier" - ); - // rawKey is a DeriveKeyResponse that can be used for further processing - // to get the uint8Array do the following - const rawKeyArray = rawKey.asUint8Array(); -} catch (error) { - console.error("Raw key derivation failed:", error); -} +const rawKey = await provider.rawDeriveKey( + "/path/to/derive", + "subject-identifier" +); +// rawKey is a DeriveKeyResponse that can be used for further processing +const rawKeyArray = rawKey.asUint8Array(); // Derive a Solana keypair (Ed25519) -try { - const solanaKeypair = await provider.deriveEd25519Keypair( - "/path/to/derive", - "subject-identifier" - ); - // solanaKeypair can now be used for Solana operations -} catch (error) { - console.error("Solana key derivation failed:", error); -} +const solanaKeypair = await provider.deriveEd25519Keypair( + "/path/to/derive", + "subject-identifier" +); // Derive an Ethereum keypair (ECDSA) -try { - const evmKeypair = await provider.deriveEcdsaKeypair( - "/path/to/derive", - "subject-identifier" - ); - // evmKeypair can now be used for Ethereum operations -} catch (error) { - console.error("EVM key derivation failed:", error); -} +const evmKeypair = await provider.deriveEcdsaKeypair( + "/path/to/derive", + "subject-identifier" +); ``` ### RemoteAttestationProvider -The `RemoteAttestationProvider` allows for generating a remote attestation within a TEE environment. - -#### Usage +The `RemoteAttestationProvider` generates remote attestations within a TEE environment: ```typescript +import { RemoteAttestationProvider } from "@elizaos/plugin-tee"; + const provider = new RemoteAttestationProvider(); +const attestation = await provider.generateAttestation("your-report-data"); +``` -try { - const attestation = await provider.generateAttestation("your-report-data"); - console.log("Attestation:", attestation); -} catch (error) { - console.error("Failed to generate attestation:", error); -} +## Development + +### Building + +```bash +npm run build ``` -### Configuration +### Testing + +```bash +npm run test +``` + +## Local Development To get a TEE simulator for local testing, use the following commands: @@ -81,9 +108,115 @@ docker pull phalanetwork/tappd-simulator:latest docker run --rm -p 8090:8090 phalanetwork/tappd-simulator:latest ``` -When using the provider through the runtime environment, ensure the following settings are configured: +## Dependencies -```env -DSTACK_SIMULATOR_ENDPOINT="your-endpoint-url" # Optional, for simulator purposes if testing on mac or windows -WALLET_SECRET_SALT=your-secret-salt // Required to single agent deployments +- `@phala/dstack-sdk`: Core TEE functionality +- `@solana/web3.js`: Solana blockchain interaction +- `viem`: Ethereum interaction library +- Other standard dependencies listed in package.json + +## API Reference + +### Providers + +- `deriveKeyProvider`: Manages secure key derivation within TEE +- `remoteAttestationProvider`: Handles generation of remote attestation quotes +- `walletProvider`: Manages wallet interactions with TEE-derived keys + +### Types + +```typescript +enum TEEMode { + OFF = "OFF", + LOCAL = "LOCAL", // For local development with simulator + DOCKER = "DOCKER", // For docker development with simulator + PRODUCTION = "PRODUCTION" // For production without simulator +} + +interface RemoteAttestationQuote { + quote: string; + timestamp: number; +} ``` + +## Future Enhancements + +1. **Key Management** + - Advanced key derivation schemes + - Multi-party computation support + - Key rotation automation + - Backup and recovery systems + - Hardware security module integration + - Custom derivation paths + +2. **Remote Attestation** + - Enhanced quote verification + - Multiple TEE provider support + - Automated attestation renewal + - Policy management system + - Compliance reporting + - Audit trail generation + +3. **Security Features** + - Memory encryption improvements + - Side-channel protection + - Secure state management + - Access control systems + - Threat detection + - Security monitoring + +4. **Chain Integration** + - Multi-chain support expansion + - Cross-chain attestation + - Chain-specific optimizations + - Custom signing schemes + - Transaction privacy + - Bridge security + +5. **Developer Tools** + - Enhanced debugging capabilities + - Testing framework + - Simulation environment + - Documentation generator + - Performance profiling + - Integration templates + +6. **Performance Optimization** + - Parallel processing + - Caching mechanisms + - Resource management + - Latency reduction + - Throughput improvements + - Load balancing + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Phala Network](https://phala.network/): Confidential smart contract platform +- [@phala/dstack-sdk](https://www.npmjs.com/package/@phala/dstack-sdk): Core TEE functionality +- [@solana/web3.js](https://www.npmjs.com/package/@solana/web3.js): Solana blockchain interaction +- [viem](https://www.npmjs.com/package/viem): Ethereum interaction library +- [Intel SGX](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/overview.html): Trusted Execution Environment technology + +Special thanks to: +- The Phala Network team for their TEE infrastructure +- The Intel SGX team for TEE technology +- The dStack SDK maintainers +- The Eliza community for their contributions and feedback + +For more information about TEE capabilities: +- [Phala Documentation](https://docs.phala.network/) +- [Intel SGX Documentation](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/documentation.html) +- [TEE Security Best Practices](https://docs.phala.network/developers/phat-contract/security-notes) +- [dStack SDK Reference](https://docs.phala.network/developers/dstack-sdk) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-ton/README.md b/packages/plugin-ton/README.md new file mode 100644 index 0000000000..8b0497f098 --- /dev/null +++ b/packages/plugin-ton/README.md @@ -0,0 +1,235 @@ +# @elizaos/plugin-ton + +A plugin for handling TON (Telegram Open Network) blockchain operations, providing wallet management and transfer capabilities. + +## Overview + +This plugin provides functionality to: +- Manage TON wallets and key derivation +- Execute secure token transfers +- Query wallet balances and portfolio information +- Format and cache transaction data +- Interface with TON blockchain via RPC endpoints + +## Installation + +```bash +npm install @elizaos/plugin-ton +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +TON_PRIVATE_KEY=your_mnemonic_phrase # Required - wallet mnemonic words +TON_RPC_URL=your_rpc_endpoint # Optional - defaults to mainnet RPC +``` + +## Usage + +Import and register the plugin in your Eliza configuration: + +```typescript +import { tonPlugin } from "@elizaos/plugin-ton"; + +export default { + plugins: [tonPlugin], + // ... other configuration +}; +``` + +## Features + +### WalletProvider + +The `WalletProvider` manages wallet operations and portfolio tracking: + +```typescript +import { WalletProvider } from "@elizaos/plugin-ton"; + +// Initialize the provider +const provider = await initWalletProvider(runtime); + +// Get wallet balance +const balance = await provider.getWalletBalance(); + +// Get formatted portfolio +const portfolio = await provider.getFormattedPortfolio(runtime); +``` + +### TransferAction + +The `TransferAction` handles token transfers: + +```typescript +import { TransferAction } from "@elizaos/plugin-ton"; + +// Initialize transfer action +const action = new TransferAction(walletProvider); + +// Execute transfer +const hash = await action.transfer({ + recipient: "EQCGScrZe1xbyWqWDvdI6mzP-GAcAWFv6ZXuaJOuSqemxku4", + amount: "1.5" +}); +``` + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +## Dependencies + +- `@ton/ton`: Core TON blockchain functionality +- `@ton/crypto`: Cryptographic operations +- `bignumber.js`: Precise number handling +- `node-cache`: Caching functionality +- Other standard dependencies listed in package.json + +## API Reference + +### Providers + +- `walletProvider`: Manages TON wallet operations +- `nativeWalletProvider`: Handles native TON token operations + +### Types + +```typescript +interface TransferContent { + recipient: string; + amount: string | number; +} + +interface WalletPortfolio { + totalUsd: string; + totalNativeToken: string; +} + +interface Prices { + nativeToken: { usd: string }; +} +``` + +### Configuration Constants + +```typescript +const PROVIDER_CONFIG = { + MAINNET_RPC: "https://toncenter.com/api/v2/jsonRPC", + STONFI_TON_USD_POOL: "EQCGScrZe1xbyWqWDvdI6mzP-GAcAWFv6ZXuaJOuSqemxku4", + CHAIN_NAME_IN_DEXSCREENER: "ton", + MAX_RETRIES: 3, + RETRY_DELAY: 2000, + TON_DECIMAL: BigInt(1000000000) +}; +``` + +## Common Issues/Troubleshooting + +### Issue: Balance Fetching Failure +- **Cause**: Incorrect RPC endpoint or network connectivity issues +- **Solution**: Verify `TON_RPC_URL` and network connection + +### Issue: Transfer Fails +- **Cause**: Insufficient balance or invalid recipient address +- **Solution**: Ensure sufficient funds and valid recipient address format + +## Security Best Practices + +- Store private keys securely using environment variables +- Validate all input addresses and amounts +- Use proper error handling for blockchain operations +- Keep dependencies updated for security patches + +## Future Enhancements + +1. **Wallet Management** + - Multi-wallet support + - Hardware wallet integration + - Advanced key management + - Batch transaction processing + - Custom wallet contracts + - Recovery mechanisms + +2. **Smart Contract Integration** + - Contract deployment tools + - FunC contract templates + - Testing framework + - Upgrade management + - Gas optimization + - Security analysis + +3. **Token Operations** + - Jetton creation tools + - NFT support enhancement + - Token metadata handling + - Collection management + - Batch transfers + - Token standards + +4. **DeFi Features** + - DEX integration + - Liquidity management + - Yield farming tools + - Price feed integration + - Swap optimization + - Portfolio tracking + +5. **Developer Tools** + - Enhanced debugging + - CLI improvements + - Documentation generator + - Integration templates + - Performance monitoring + - Testing utilities + +6. **Network Features** + - Workchain support + - Sharding optimization + - RPC management + - Network monitoring + - Archive node integration + - Custom endpoints + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [TON Blockchain](https://ton.org/): The Open Network blockchain platform +- [@ton/ton](https://www.npmjs.com/package/@ton/ton): Core TON blockchain functionality +- [@ton/crypto](https://www.npmjs.com/package/@ton/crypto): Cryptographic operations +- [bignumber.js](https://github.com/MikeMcl/bignumber.js/): Precise number handling +- [node-cache](https://github.com/node-cache/node-cache): Caching functionality + +Special thanks to: +- The TON Foundation for developing and maintaining the TON blockchain +- The TON Developer community +- The TON SDK maintainers +- The Eliza community for their contributions and feedback + +For more information about TON blockchain capabilities: +- [TON Documentation](https://docs.ton.org/) +- [TON Developer Portal](https://ton.org/dev) +- [TON Whitepaper](https://ton.org/whitepaper.pdf) +- [TON API Reference](https://ton.org/docs/#/api) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-ton/Readme.md b/packages/plugin-ton/Readme.md deleted file mode 100644 index 604ac490a9..0000000000 --- a/packages/plugin-ton/Readme.md +++ /dev/null @@ -1,124 +0,0 @@ -# Plugin TON - -A plugin for handling TON (Telegram Open Network) blockchain operations, such as wallet management and transfers. - -## Overview and Purpose - -The Plugin TON provides a streamlined interface to interact with the TON blockchain. It simplifies wallet management and facilitates secure, efficient transfers while maintaining compatibility with TypeScript and modern JavaScript development practices. - -## Installation - -Install the plugin using npm: - -```bash -npm install plugin-ton -``` - -## Configuration Requirements - -Ensure your environment is set up with the necessary configuration files and environment variables. Update the `src/enviroment.ts` file or set environment variables directly for sensitive information. - -### Environment Variables - -| Variable Name | Description | -| ------------------------ | ------------------------------------- | -| `TON_API_ENDPOINT` | API endpoint for interacting with TON | -| `TON_WALLET_PRIVATE_KEY` | Private key for wallet operations | - -## Usage Examples - -### Importing the Plugin - -```typescript -import { WalletProvider, TransferAction } from 'plugin-ton'; - -// Initialize wallet provider -const wallet = new WalletProvider('YOUR_PRIVATE_KEY'); - -// Fetch wallet balance -const balance = await wallet.getBalance(); -console.log('Wallet Balance:', balance); - -// Transfer TON coins -const transfer = new TransferAction(wallet); -await transfer.execute({ - to: 'RECIPIENT_ADDRESS', - amount: 10, -}); -console.log('Transfer successful'); -``` - -## API Reference - -### WalletProvider - -#### Methods: - -- `constructor(privateKey: string)` - Initializes the wallet with a private key. -- `getBalance(): Promise` - Retrieves the wallet balance. - -### TransferAction - -#### Methods: - -- `constructor(wallet: WalletProvider)` - Initializes the transfer action. -- `execute({ to: string, amount: number }): Promise` - Executes a transfer of TON coins. - -## Common Issues/Troubleshooting - -### Issue: Balance Fetching Failure - -- **Cause**: Incorrect API endpoint or private key. -- **Solution**: Verify `TON_API_ENDPOINT` and private key in your configuration. - -### Issue: Transfer Fails - -- **Cause**: Insufficient balance or invalid recipient address. -- **Solution**: Ensure sufficient funds and a valid recipient address. - -## Additional Documentation - -### Examples Folder Documentation - -The examples folder includes sample scripts demonstrating wallet initialization, balance checking, and transfers. Use these as a starting point for your integration. - -### Testing Guide Expansion - -Run tests using the following command: - -```bash -npm test -``` - -The `src/tests/wallet.test.ts` file provides unit tests for wallet functionality. Add tests for additional features as needed. - -### Plugin Development Guide - -1. Clone the repository. -2. Run `npm install` to install dependencies. -3. Use `tsup` for building the project: `npm run build`. -4. Add new features in the `src` directory. - -### Security Best Practices - -- **Key Management**: Use environment variables for sensitive information like private keys. -- **Testing**: Validate all inputs to prevent injection attacks. -- **Dependencies**: Regularly update dependencies to patch vulnerabilities. - -### Performance Optimization Guide - -- Use efficient data structures for large transactions. -- Avoid unnecessary API calls by caching frequent responses. -- Use async/await for optimal asynchronous operations. - -## Contributing - -1. Fork the repository. -2. Create your feature branch (`git checkout -b feature/amazing-feature`). -3. Commit your changes (`git commit -m 'Add some amazing feature'`). -4. Push to the branch (`git push origin feature/amazing-feature`). -5. Open a Pull Request. - -## License - -MIT diff --git a/packages/plugin-trustdb/README.md b/packages/plugin-trustdb/README.md new file mode 100644 index 0000000000..5d8b3acf26 --- /dev/null +++ b/packages/plugin-trustdb/README.md @@ -0,0 +1,214 @@ +# @elizaos/plugin-trustdb + +A plugin for managing trust scores and performance metrics in a secure database, providing recommender tracking and token performance analysis capabilities. + +## Overview + +This plugin provides functionality to: +- Track and manage recommender trust scores +- Monitor token performance metrics +- Record and analyze trading performance +- Maintain historical metrics data +- Handle transaction records and validations + +## Installation + +```bash +npm install @elizaos/plugin-trustdb +``` + +## Configuration + +The plugin uses SQLite as its database backend and requires proper initialization: + +```typescript +import { TrustScoreDatabase } from "@elizaos/plugin-trustdb"; +import Database from "better-sqlite3"; + +const db = new Database("path/to/database.sqlite"); +const trustDB = new TrustScoreDatabase(db); +``` + +## Usage + +Import and use the TrustDB functionality in your application: + +```typescript +import { TrustScoreDatabase } from "@elizaos/plugin-trustdb"; + +// Initialize database +const trustDB = new TrustScoreDatabase(db); + +// Add a recommender +const recommender = { + id: "uuid", + address: "wallet-address", + telegramId: "telegram-id" +}; +trustDB.addRecommender(recommender); + +// Track token performance +const performance = { + tokenAddress: "token-address", + priceChange24h: 10.5, + volumeChange24h: 25.3, + // ... other metrics +}; +trustDB.upsertTokenPerformance(performance); +``` + +## Features + +### TrustScoreDatabase + +The main database manager providing comprehensive tracking and analysis: + +```typescript +// Get or create a recommender +const recommender = await trustDB.getOrCreateRecommender({ + address: "wallet-address", + telegramId: "user-id" +}); + +// Update recommender metrics +trustDB.updateRecommenderMetrics({ + recommenderId: "uuid", + trustScore: 85.5, + totalRecommendations: 10, + // ... other metrics +}); +``` + +### Performance Tracking + +```typescript +// Add trade performance +trustDB.addTradePerformance({ + token_address: "address", + recommender_id: "uuid", + buy_price: 1.0, + // ... other trade details +}, false); + +// Get token performance +const tokenMetrics = trustDB.getTokenPerformance("token-address"); +``` + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +### Linting + +```bash +npm run lint +``` + +## Dependencies + +- `better-sqlite3`: SQLite database interface +- `uuid`: Unique identifier generation +- `dompurify`: HTML sanitization +- Other standard dependencies listed in package.json + +## API Reference + +### Core Interfaces + +```typescript +interface Recommender { + id: string; + address: string; + solanaPubkey?: string; + telegramId?: string; + discordId?: string; + twitterId?: string; + ip?: string; +} + +interface RecommenderMetrics { + recommenderId: string; + trustScore: number; + totalRecommendations: number; + successfulRecs: number; + avgTokenPerformance: number; + riskScore: number; + consistencyScore: number; + virtualConfidence: number; + lastActiveDate: Date; + trustDecay: number; + lastUpdated: Date; +} + +interface TokenPerformance { + tokenAddress: string; + symbol: string; + priceChange24h: number; + volumeChange24h: number; + // ... other performance metrics +} +``` + +### Database Methods + +- `addRecommender`: Add new recommender to database +- `getRecommenderMetrics`: Retrieve recommender performance metrics +- `updateRecommenderMetrics`: Update recommender metrics +- `upsertTokenPerformance`: Add or update token performance +- `getTokenPerformance`: Retrieve token performance metrics +- Many more specialized methods for tracking and analysis + +## Common Issues/Troubleshooting + +### Issue: Database Connection Errors +- **Cause**: Incorrect database path or permissions +- **Solution**: Verify database path and file permissions + +### Issue: Data Consistency +- **Cause**: Concurrent database access +- **Solution**: Use proper transaction handling + +## Security Best Practices + +- Implement proper database backup procedures +- Use parameterized queries to prevent SQL injection +- Validate all input data before storage +- Maintain regular database maintenance +- Keep dependencies updated for security patches + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3): High-performance SQLite3 driver +- [uuid](https://github.com/uuidjs/uuid): UUID generation +- [DOMPurify](https://github.com/cure53/DOMPurify): HTML sanitization library + +Special thanks to: +- The better-sqlite3 team for their excellent database driver +- The UUID.js maintainers for reliable identifier generation +- The DOMPurify team for security-focused sanitization tools +- The Eliza community for their contributions and feedback + +For more information about database management and security: +- [SQLite Documentation](https://www.sqlite.org/docs.html) +- [Database Security Best Practices](https://www.sqlite.org/security.html) +- [Data Sanitization Guide](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-twitter/README.md b/packages/plugin-twitter/README.md new file mode 100644 index 0000000000..1bea72c20f --- /dev/null +++ b/packages/plugin-twitter/README.md @@ -0,0 +1,257 @@ +# @elizaos/plugin-twitter + +A plugin for Twitter/X integration, providing automated tweet posting capabilities with character-aware content generation. + +## Overview + +This plugin provides functionality to: +- Compose context-aware tweets +- Post tweets to Twitter/X platform +- Handle authentication and session management +- Support premium Twitter features +- Manage tweet length restrictions + +## Installation + +```bash +npm install @elizaos/plugin-twitter +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +TWITTER_USERNAME=your_username +TWITTER_PASSWORD=your_password +TWITTER_EMAIL=your_email # Optional: for 2FA +TWITTER_2FA_SECRET=your_2fa_secret # Optional: for 2FA +TWITTER_PREMIUM=false # Optional: enables premium features +TWITTER_DRY_RUN=false # Optional: test without posting +``` + +## Usage + +Import and register the plugin in your Eliza configuration: + +```typescript +import { twitterPlugin } from "@elizaos/plugin-twitter"; + +export default { + plugins: [twitterPlugin], + // ... other configuration +}; +``` + +## Features + +### Tweet Composition + +The plugin uses context-aware templates to generate appropriate tweets: + +```typescript +import { postAction } from "@elizaos/plugin-twitter"; + +// Tweet will be composed based on context and character limits +const result = await postAction.handler(runtime, message, state); +``` + +### Tweet Posting + +```typescript +// Post with automatic content generation +await postAction.handler(runtime, message, state); + +// Dry run mode (for testing) +process.env.TWITTER_DRY_RUN = "true"; +await postAction.handler(runtime, message, state); +``` + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +### Development Mode + +```bash +npm run dev +``` + +## Dependencies + +- `@elizaos/core`: Core Eliza functionality +- `agent-twitter-client`: Twitter API client +- `tsup`: Build tool +- Other standard dependencies listed in package.json + +## API Reference + +### Core Interfaces + +```typescript +interface TweetContent { + text: string; +} + +// Tweet Schema +const TweetSchema = z.object({ + text: z.string().describe("The text of the tweet") +}); + +// Action Interface +interface Action { + name: "POST_TWEET"; + similes: string[]; + description: string; + validate: (runtime: IAgentRuntime, message: Memory, state?: State) => Promise; + handler: (runtime: IAgentRuntime, message: Memory, state?: State) => Promise; + examples: Array>; +} +``` + +### Plugin Methods + +- `postAction.handler`: Main method for posting tweets +- `postAction.validate`: Validates Twitter credentials +- `composeTweet`: Internal method for tweet generation +- `postTweet`: Internal method for tweet posting + +## Common Issues/Troubleshooting + +### Issue: Authentication Failures +- **Cause**: Invalid credentials or 2FA configuration +- **Solution**: Verify credentials and 2FA setup + +### Issue: Tweet Length Errors +- **Cause**: Content exceeds Twitter's character limit +- **Solution**: Enable TWITTER_PREMIUM for extended tweets or ensure content is within limits + +### Issue: Rate Limiting +- **Cause**: Too many requests in short time +- **Solution**: Implement proper request throttling + +## Security Best Practices + +- Store credentials securely using environment variables +- Use 2FA when possible +- Implement proper error handling +- Keep dependencies updated +- Use dry run mode for testing +- Monitor Twitter API usage + +## Template System + +The plugin uses a sophisticated template system for tweet generation: + +```typescript +const tweetTemplate = ` +# Context +{{recentMessages}} + +# Topics +{{topics}} + +# Post Directions +{{postDirections}} + +# Recent interactions +{{recentPostInteractions}} + +# Task +Generate a tweet that: +1. Relates to the recent conversation +2. Matches the character's style +3. Is concise and engaging +4. Must be UNDER 180 characters +5. Speaks from the perspective of {{agentName}} +`; +``` + +## Future Enhancements + +1. **Content Generation** + - Advanced context awareness + - Multi-language support + - Style customization + - Hashtag optimization + - Media generation + - Thread composition + +2. **Engagement Features** + - Auto-reply system + - Engagement analytics + - Follower management + - Interaction scheduling + - Sentiment analysis + - Community management + +3. **Tweet Management** + - Thread management + - Tweet scheduling + - Content moderation + - Archive management + - Delete automation + - Edit optimization + +4. **Analytics Integration** + - Performance tracking + - Engagement metrics + - Audience insights + - Trend analysis + - ROI measurement + - Custom reporting + +5. **Authentication** + - OAuth improvements + - Multi-account support + - Session management + - Rate limit handling + - Security enhancements + - Backup mechanisms + +6. **Developer Tools** + - Enhanced debugging + - Testing framework + - Documentation generator + - Integration templates + - Error handling + - Logging system + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Twitter/X API](https://developer.twitter.com/en/docs): Official Twitter platform API +- [agent-twitter-client](https://www.npmjs.com/package/agent-twitter-client): Twitter API client library +- [Zod](https://github.com/colinhacks/zod): TypeScript-first schema validation + +Special thanks to: +- The Twitter/X Developer Platform team +- The agent-twitter-client maintainers for API integration tools +- The Eliza community for their contributions and feedback + +For more information about Twitter/X integration capabilities: +- [Twitter API Documentation](https://developer.twitter.com/en/docs) +- [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard) +- [Twitter API Best Practices](https://developer.twitter.com/en/docs/twitter-api/rate-limits) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-video-generation/README.md b/packages/plugin-video-generation/README.md new file mode 100644 index 0000000000..07ec6d7e39 --- /dev/null +++ b/packages/plugin-video-generation/README.md @@ -0,0 +1,262 @@ +# @elizaos/plugin-video-generation + +A plugin for AI-powered video generation using Luma AI, providing automated video creation capabilities from text prompts. + +## Overview + +This plugin provides functionality to: +- Generate videos from text descriptions +- Handle video generation requests through Luma AI +- Manage API authentication and responses +- Cache and serve generated videos +- Monitor generation progress + +## Installation + +```bash +npm install @elizaos/plugin-video-generation +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +LUMA_API_KEY=your_luma_api_key # Required: API key for Luma AI +``` + +## Usage + +Import and register the plugin in your Eliza configuration: + +```typescript +import { videoGenerationPlugin } from "@elizaos/plugin-video-generation"; + +export default { + plugins: [videoGenerationPlugin], + // ... other configuration +}; +``` + +## Features + +### Video Generation + +The plugin uses Luma AI's API to generate videos from text prompts: + +```typescript +import { videoGeneration } from "@elizaos/plugin-video-generation"; + +// Generate video from prompt +const result = await videoGeneration.handler(runtime, { + content: { text: "Generate a video of a sunset on the beach" } +}, state, {}, callback); +``` + +### Progress Monitoring + +```typescript +// The plugin automatically handles progress monitoring +const result = await generateVideo(prompt, runtime); +if (result.success) { + console.log("Video URL:", result.data); +} else { + console.error("Generation failed:", result.error); +} +``` + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +### Development Mode + +```bash +npm run dev +``` + +## Dependencies + +- `@elizaos/core`: Core Eliza functionality +- `tsup`: Build tool +- Other standard dependencies listed in package.json + +## API Reference + +### Core Interfaces + +```typescript +interface Action { + name: "GENERATE_VIDEO"; + similes: string[]; + description: string; + validate: (runtime: IAgentRuntime, message: Memory) => Promise; + handler: (runtime: IAgentRuntime, message: Memory, state: State, options: any, callback: HandlerCallback) => Promise; + examples: Array>; +} + +interface GenerationResult { + success: boolean; + data?: string; + error?: string; +} +``` + +### Plugin Methods + +- `generateVideo`: Main method for video generation +- `videoGeneration.handler`: Action handler for video requests +- `videoGeneration.validate`: Validates API key and requirements + +## Common Issues/Troubleshooting + +### Issue: API Authentication Failures +- **Cause**: Invalid or missing Luma API key +- **Solution**: Verify LUMA_API_KEY environment variable + +### Issue: Generation Timeouts +- **Cause**: Long generation times or network issues +- **Solution**: Implement proper timeout handling and retry logic + +### Issue: File Storage Errors +- **Cause**: Insufficient permissions or disk space +- **Solution**: Verify file system permissions and available storage + +## Security Best Practices + +- Store API keys securely using environment variables +- Implement proper error handling +- Keep dependencies updated +- Monitor API usage and rate limits +- Validate input prompts +- Secure file storage handling + +## Constants + +The plugin uses predefined constants for API configuration: + +```typescript +export const LUMA_CONSTANTS = { + API_URL: "https://api.lumalabs.ai/dream-machine/v1/generations", + API_KEY_SETTING: "LUMA_API_KEY" +}; +``` + +## Example Usage + +```typescript +// Basic video generation +const videoPrompt = "Create a video of a futuristic city at night"; +const result = await generateVideo(videoPrompt, runtime); + +// With callback handling +videoGeneration.handler(runtime, { + content: { text: videoPrompt } +}, state, {}, (response) => { + console.log("Generation status:", response); +}); +``` + +## Future Enhancements + +1. **Generation Features** + - Advanced style control + - Multi-scene composition + - Custom duration settings + - Resolution options + - Frame rate control + - Audio integration + +2. **Video Editing** + - Scene transitions + - Text overlay tools + - Effect templates + - Color correction + - Motion tracking + - Timeline editing + +3. **Asset Management** + - Asset library + - Template system + - Style presets + - Resource optimization + - Version control + - Batch processing + +4. **Quality Improvements** + - Enhanced resolution + - Frame interpolation + - Artifact reduction + - Stability features + - Lighting optimization + - Detail enhancement + +5. **Performance Optimization** + - Generation speed + - Resource usage + - Parallel processing + - Caching system + - Queue management + - Load balancing + +6. **Export Options** + - Multiple formats + - Compression settings + - Streaming support + - Progressive loading + - Thumbnail generation + - Metadata handling + +7. **Developer Tools** + - API expansion + - Testing framework + - Documentation generator + - Debug visualization + - Performance monitoring + - Integration templates + +8. **AI Features** + - Style transfer + - Scene understanding + - Content awareness + - Motion synthesis + - Character animation + - Environment generation + +We welcome community feedback and contributions to help prioritize these enhancements. + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Luma AI](https://lumalabs.ai/): Advanced AI-powered video generation platform +- [Luma Dream Machine](https://lumalabs.ai/dream-machine): Text-to-video generation API +- [Node.js Fetch API](https://nodejs.org/api/fetch.html): HTTP request handling + +Special thanks to: +- The Luma Labs team for providing the video generation API +- The Luma AI research team for their groundbreaking work in AI video generation +- The Eliza community for their contributions and feedback + +For more information about video generation capabilities and tools: +- [Luma AI Documentation](https://docs.lumalabs.ai/) +- [Dream Machine API Reference](https://lumalabs.ai/docs/dream-machine) +- [Video Generation Best Practices](https://lumalabs.ai/docs/best-practices) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. diff --git a/packages/plugin-web-search/README.md b/packages/plugin-web-search/README.md new file mode 100644 index 0000000000..0414ff058b --- /dev/null +++ b/packages/plugin-web-search/README.md @@ -0,0 +1,207 @@ +# @elizaos/plugin-web-search + +A plugin for powerful web search capabilities, providing efficient search query handling and result processing through a customizable API interface. + +## Overview + +This plugin provides functionality to: +- Execute web search queries with customizable parameters +- Process and format search results +- Handle search API authentication +- Manage token limits and response sizes +- Optimize query performance + +## Installation + +```bash +npm install @elizaos/plugin-web-search +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +TAVILY_API_KEY=your_api_key # Required: API key for search service +``` + +## Usage + +Import and register the plugin in your Eliza configuration: + +```typescript +import { webSearchPlugin } from "@elizaos/plugin-web-search"; + +export default { + plugins: [webSearchPlugin], + // ... other configuration +}; +``` + +## Features + +### Web Search + +The plugin provides comprehensive web search capabilities: + +```typescript +import { webSearch } from "@elizaos/plugin-web-search"; + +// Execute a search query +const result = await webSearch.handler(runtime, { + content: { text: "What is the latest news about AI?" } +}, state, {}, callback); +``` + +### Token Management + +```typescript +// The plugin automatically handles token limits +const DEFAULT_MAX_WEB_SEARCH_TOKENS = 4000; + +// Example of token-limited response +const response = MaxTokens(searchResult, DEFAULT_MAX_WEB_SEARCH_TOKENS); +``` + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +### Development Mode + +```bash +npm run dev +``` + +## Dependencies + +- `@elizaos/core`: Core Eliza functionality +- `js-tiktoken`: Token counting and management +- `tsup`: Build tool +- Other standard dependencies listed in package.json + +## API Reference + +### Core Interfaces + +```typescript +interface Action { + name: "WEB_SEARCH"; + similes: string[]; + description: string; + validate: (runtime: IAgentRuntime, message: Memory) => Promise; + handler: (runtime: IAgentRuntime, message: Memory, state: State, options: any, callback: HandlerCallback) => Promise; + examples: Array>; +} + +interface SearchResult { + title: string; + url: string; + answer?: string; + results?: Array<{ + title: string; + url: string; + }>; +} +``` + +### Plugin Methods + +- `webSearch.handler`: Main method for executing searches +- `generateWebSearch`: Core search generation function +- `MaxTokens`: Token limit management function +- `getTotalTokensFromString`: Token counting utility + +## Common Issues/Troubleshooting + +### Issue: API Authentication Failures +- **Cause**: Invalid or missing Tavily API key +- **Solution**: Verify TAVILY_API_KEY environment variable + +### Issue: Token Limit Exceeded +- **Cause**: Search results exceeding maximum token limit +- **Solution**: Results are automatically truncated to fit within limits + +### Issue: Search Rate Limiting +- **Cause**: Too many requests in short time +- **Solution**: Implement proper request throttling + +## Security Best Practices + +- Store API keys securely using environment variables +- Validate all search inputs +- Implement proper error handling +- Keep dependencies updated +- Monitor API usage and rate limits +- Use HTTPS for API communication + +## Example Usage + +```typescript +// Basic search +const searchQuery = "Latest developments in quantum computing"; +const results = await generateWebSearch(searchQuery, runtime); + +// With formatted response +if (results && results.results.length) { + const formattedResponse = `${results.answer}\n\nFor more details, check out:\n${ + results.results.map((result, index) => + `${index + 1}. [${result.title}](${result.url})` + ).join('\n') + }`; +} +``` + +## Configuration Options + +### Token Management + +```typescript +const DEFAULT_MODEL_ENCODING = "gpt-3.5-turbo"; +const DEFAULT_MAX_WEB_SEARCH_TOKENS = 4000; +``` + +### Search Actions + +The plugin includes multiple search action similes: +- SEARCH_WEB +- INTERNET_SEARCH +- LOOKUP +- QUERY_WEB +- FIND_ONLINE +- And more... + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [Tavily API](https://tavily.com/): Advanced search and content analysis API +- [js-tiktoken](https://github.com/dqbd/tiktoken): Token counting for API responses +- [Zod](https://github.com/colinhacks/zod): TypeScript-first schema validation + +Special thanks to: +- The Eliza community for their contributions and feedback + +For more information about the search capabilities and tools: +- [Tavily API Documentation](https://docs.tavily.com/) +- [Token Management Guide](https://github.com/dqbd/tiktoken#readme) +- [Search API Best Practices](https://docs.tavily.com/docs/guides/best-practices) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-whatsapp/README.md b/packages/plugin-whatsapp/README.md new file mode 100644 index 0000000000..a81c80b0ce --- /dev/null +++ b/packages/plugin-whatsapp/README.md @@ -0,0 +1,220 @@ +# @elizaos/plugin-whatsapp + +A plugin for integrating WhatsApp Cloud API with your application, providing comprehensive messaging capabilities and webhook handling. + +## Overview + +This plugin provides functionality to: +- Send text and template messages via WhatsApp +- Handle incoming webhook events +- Manage message status updates +- Process message delivery notifications +- Handle authentication and session management + +## Installation + +```bash +npm install @elizaos/plugin-whatsapp +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +WHATSAPP_ACCESS_TOKEN=your_access_token # Required: WhatsApp Cloud API access token +WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id # Required: WhatsApp business phone number ID +WHATSAPP_WEBHOOK_TOKEN=your_webhook_token # Optional: Webhook verification token +WHATSAPP_BUSINESS_ID=your_business_id # Optional: Business account ID +``` + +## Usage + +### Basic Setup + +```typescript +import { WhatsAppPlugin } from "@elizaos/plugin-whatsapp"; + +const whatsappPlugin = new WhatsAppPlugin({ + accessToken: 'your_access_token', + phoneNumberId: 'your_phone_number_id', + webhookVerifyToken: 'your_webhook_verify_token', + businessAccountId: 'your_business_account_id' +}); +``` + +### Sending Messages + +```typescript +// Send a text message +await whatsappPlugin.sendMessage({ + type: 'text', + to: '1234567890', + content: 'Hello from WhatsApp!' +}); + +// Send a template message +await whatsappPlugin.sendMessage({ + type: 'template', + to: '1234567890', + content: { + name: 'hello_world', + language: { + code: 'en' + } + } +}); +``` + +### Handling Webhooks + +```typescript +// Verify webhook +app.get('/webhook', (req, res) => { + const verified = await whatsappPlugin.verifyWebhook(req.query['hub.verify_token']); + if (verified) { + res.send(req.query['hub.challenge']); + } else { + res.sendStatus(403); + } +}); + +// Handle webhook events +app.post('/webhook', (req, res) => { + await whatsappPlugin.handleWebhook(req.body); + res.sendStatus(200); +}); +``` + +## Features + +- Send text messages +- Send template messages +- Webhook verification +- Webhook event handling +- Message status updates + +## Error Handling + +The plugin throws errors in the following cases: + +```typescript +try { + await whatsappPlugin.sendMessage({ + type: 'text', + to: '1234567890', + content: 'Hello!' + }); +} catch (error) { + console.error('Failed to send message:', error.message); +} +``` + +Common error cases: +- Invalid configuration +- Failed message sending +- Webhook verification failure +- Invalid webhook payload + +## Best Practices + +1. Always validate phone numbers before sending messages +2. Use template messages for first-time messages to users +3. Store message IDs for tracking delivery status +4. Implement proper error handling +5. Set up webhook retry mechanisms +6. Keep your access tokens secure + +## API Reference + +### Core Interfaces + +```typescript +interface WhatsAppConfig { + accessToken: string; + phoneNumberId: string; + webhookVerifyToken?: string; + businessAccountId?: string; +} + +interface WhatsAppMessage { + type: 'text' | 'template'; + to: string; + content: string | WhatsAppTemplate; +} + +interface WhatsAppTemplate { + name: string; + language: { + code: string; + }; + components?: Array<{ + type: string; + parameters: Array<{ + type: string; + text?: string; + }>; + }>; +} +``` + +### Plugin Methods + +- `sendMessage`: Send WhatsApp messages +- `handleWebhook`: Process incoming webhook events +- `verifyWebhook`: Verify webhook authenticity +- Message and status handlers + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +### Linting + +```bash +npm run lint +``` + +## Security Best Practices + +- Store credentials securely using environment variables +- Validate all phone numbers before sending messages +- Use template messages for first-time contacts +- Implement proper error handling +- Keep dependencies updated +- Monitor API usage and rate limits +- Use HTTPS for all API communication + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api): Meta's official WhatsApp Business Platform +- [Axios](https://axios-http.com/): Promise-based HTTP client for API requests +- [Meta for Developers](https://developers.facebook.com/): Meta's developer platform and tools + +Special thanks to: +- The Eliza community for their contributions and feedback + +For more information about WhatsApp Cloud API and its capabilities, visit: +- [WhatsApp Business Platform Documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/overview) +- [Meta for Developers Blog](https://developers.facebook.com/blog/) +- [WhatsApp Business API GitHub](https://github.com/WhatsApp/WhatsApp-Business-API-Setup-Scripts) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file diff --git a/packages/plugin-whatsapp/Readme.md b/packages/plugin-whatsapp/Readme.md deleted file mode 100644 index 9324a5705c..0000000000 --- a/packages/plugin-whatsapp/Readme.md +++ /dev/null @@ -1,154 +0,0 @@ -# WhatsApp Cloud API Plugin - -A plugin for integrating WhatsApp Cloud API with your application. - -## Installation - - - -npm install @eliza/plugin-whatsapp - -## Configuration - -typescript -import { WhatsAppPlugin } from '@eliza/plugin-whatsapp'; -const whatsappPlugin = new WhatsAppPlugin({ -accessToken: 'your_access_token', -phoneNumberId: 'your_phone_number_id', -webhookVerifyToken: 'your_webhook_verify_token', -businessAccountId: 'your_business_account_id' -}); - -## Usage - -### Sending Messages - -typescript -// Send a text message -await whatsappPlugin.sendMessage({ -type: 'text', -to: '1234567890', -content: 'Hello from WhatsApp!' -}); -// Send a template message -await whatsappPlugin.sendMessage({ -type: 'template', -to: '1234567890', -content: { -name: 'hello_world', -language: { -code: 'en' -} -} -}); - -### Handling Webhooks - -typescript -// Verify webhook -app.get('/webhook', (req, res) => { -const verified = await whatsappPlugin.verifyWebhook(req.query['hub.verify_token']); -if (verified) { -res.send(req.query['hub.challenge']); -} else { -res.sendStatus(403); -} -}); -// Handle webhook events -app.post('/webhook', (req, res) => { -await whatsappPlugin.handleWebhook(req.body); -res.sendStatus(200); -}); - -## Features - -- Send text messages -- Send template messages -- Webhook verification -- Webhook event handling -- Message status updates - -## API Reference - -### WhatsAppPlugin - -#### Constructor - -- `config: WhatsAppConfig` - Configuration object for the plugin - -#### Methods - -- `sendMessage(message: WhatsAppMessage): Promise` - Send a WhatsApp message -- `handleWebhook(event: WhatsAppWebhookEvent): Promise` - Process incoming webhook events -- `verifyWebhook(token: string): Promise` - Verify webhook token - -### Types - -typescript -interface WhatsAppConfig { -accessToken: string; -phoneNumberId: string; -webhookVerifyToken?: string; -businessAccountId?: string; -} -interface WhatsAppMessage { -type: 'text' | 'template'; -to: string; -content: string | WhatsAppTemplate; -} -interface WhatsAppTemplate { -name: string; -language: { -code: string; -}; -components?: Array<{ -type: string; -parameters: Array<{ -type: string; -text?: string; -}>; -}>; -} - -## Error Handling - -The plugin throws errors in the following cases: - -- Invalid configuration -- Failed message sending -- Webhook verification failure -- Invalid webhook payload - -Example error handling: - -typescript -try { -await whatsappPlugin.sendMessage({ -type: 'text', -to: '1234567890', -content: 'Hello!' -}); -} catch (error) { -console.error('Failed to send message:', error.message); -} - -## Best Practices - -1. Always validate phone numbers before sending messages -2. Use template messages for first-time messages to users -3. Store message IDs for tracking delivery status -4. Implement proper error handling -5. Set up webhook retry mechanisms -6. Keep your access tokens secure - -## Contributing - -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add some amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request - -## License - -MIT diff --git a/packages/plugin-zksync-era/README.md b/packages/plugin-zksync-era/README.md new file mode 100644 index 0000000000..8a122cfadb --- /dev/null +++ b/packages/plugin-zksync-era/README.md @@ -0,0 +1,218 @@ +# @elizaos/plugin-zksync-era + +A plugin for integrating ZKSync Era blockchain operations with your application, providing token transfer capabilities and transaction management. + +## Overview + +This plugin provides functionality to: +- Execute token transfers on ZKSync Era +- Handle smart account operations +- Manage transaction signing and submission +- Support multiple token standards +- Process transaction receipts and confirmations + +## Installation + +```bash +npm install @elizaos/plugin-zksync-era +``` + +## Configuration + +The plugin requires the following environment variables: + +```env +ZKSYNC_ADDRESS=your_address # Required: Your ZKSync wallet address +ZKSYNC_PRIVATE_KEY=your_private_key # Required: Your wallet's private key +``` + +## Usage + +### Basic Setup + +```typescript +import { zksyncEraPlugin } from "@elizaos/plugin-zksync-era"; + +const plugin = zksyncEraPlugin; +``` + +### Token Transfers + +```typescript +// Transfer tokens +await transfer.handler(runtime, { + content: { + tokenAddress: "0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4", // USDC + recipient: "0xCCa8009f5e09F8C5dB63cb0031052F9CB635Af62", + amount: "100" + } +}, state); +``` + +## Features + +### Supported Tokens + +The plugin includes pre-configured addresses for common tokens: +```typescript +const TOKENS = { + ZK: "0x5A7d6b2F92C77FAD6CCaBd7EE0624E64907Eaf3E", + ETH: "0x000000000000000000000000000000000000800A", + USDC: "0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4" +}; +``` + +### Smart Account Integration + +```typescript +const web3 = new Web3(); +web3.registerPlugin(new ZKsyncPlugin( + Web3ZKsyncL2.initWithDefaultProvider(types.Network.Mainnet) +)); + +const smartAccount = new web3.ZKsync.SmartAccount({ + address: PUBLIC_KEY, + secret: PRIVATE_KEY +}); +``` + +## Error Handling + +The plugin includes comprehensive error handling: + +```typescript +try { + const transferTx = await smartAccount.transfer({ + to: recipient, + token: tokenAddress, + amount: amount + }); + const receipt = await transferTx.wait(); +} catch (error) { + console.error("Transfer failed:", error.message); +} +``` + +Common error cases: +- Invalid configuration +- Insufficient balance +- Network issues +- Invalid addresses +- Failed transactions + +## Best Practices + +1. Always validate addresses before transactions +2. Keep private keys secure +3. Monitor transaction status +4. Implement proper error handling +5. Use appropriate gas settings +6. Keep track of transaction receipts + +## API Reference + +### Core Interfaces + +```typescript +interface TransferContent { + tokenAddress: string; + recipient: string; + amount: string | number; +} + +interface ZKsyncConfig { + ZKSYNC_ADDRESS: string; + ZKSYNC_PRIVATE_KEY: string; +} +``` + +### Plugin Methods + +- `transfer`: Execute token transfers +- `validateZKsyncConfig`: Validate configuration +- Transaction status monitoring +- Receipt handling + +## Development + +### Building + +```bash +npm run build +``` + +### Testing + +```bash +npm run test +``` + +## Security Best Practices + +- Store private keys securely using environment variables +- Validate all addresses before transactions +- Implement proper error handling +- Keep dependencies updated +- Monitor transaction status +- Use secure RPC endpoints +- Implement proper gas management + +## Example Usage + +```typescript +// Initialize plugin +const zksync = zksyncEraPlugin; + +// Execute transfer +try { + await transfer.handler(runtime, { + content: { + tokenAddress: TOKENS.USDC, + recipient: "0xCCa8009f5e09F8C5dB63cb0031052F9CB635Af62", + amount: "100" + } + }, state); +} catch (error) { + console.error('Transfer failed:', error.message); +} +``` + +## Validation + +The plugin includes validation for: +- Wallet addresses +- Token addresses +- Transaction amounts +- Configuration parameters +- Network status + +## Dependencies + +- `@elizaos/core`: Core Eliza functionality +- `web3`: Web3 library for blockchain interaction +- `web3-plugin-zksync`: ZKSync Era integration +- Other standard dependencies listed in package.json + +## Contributing + +Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. + +## Credits + +This plugin integrates with and builds upon several key technologies: + +- [ZKSync Era](https://zksync.io/): Layer 2 scaling solution for Ethereum +- [Web3.js](https://web3js.org/): Ethereum JavaScript API +- [web3-plugin-zksync](https://www.npmjs.com/package/web3-plugin-zksync): Official ZKSync plugin for Web3.js + +Special thanks to: +- The Eliza community for their contributions and feedback + +For more information about ZKSync Era and its capabilities, visit: +- [ZKSync Documentation](https://docs.zksync.io/) +- [Matter Labs Blog](https://blog.matter-labs.io/) +- [ZKSync GitHub](https://github.com/matter-labs/zksync-era) + +## License + +This plugin is part of the Eliza project. See the main project repository for license information. \ No newline at end of file