diff --git a/README.md b/README.md index 46a78fb..357bd0a 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,114 @@ -# @elizaos/plugin-flow +# @elizaos-plugins/plugin-flow -A plugin for interacting with the Flow blockchain within the ElizaOS ecosystem. +## Overview -## Description +The `@elizaos-plugins/plugin-flow` is a plugin for ElizaOS that integrates with the Flow blockchain, enabling seamless interactions and transactions. This plugin leverages the Flow ecosystem's capabilities to enhance the functionality of ElizaOS agents. -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. +## Table of Contents + +- [Installation](#installation) +- [Configuration](#configuration) +- [Usage Examples](#usage-examples) +- [Actions and Providers](#actions-and-providers) +- [Troubleshooting](#troubleshooting) +- [Contributing](#contributing) ## Installation +To install the `@elizaos-plugins/plugin-flow`, you need to have Node.js and npm installed on your machine. You can install the plugin using npm or yarn: + ```bash -pnpm install @elizaos/plugin-flow +npm install @elizaos-plugins/plugin-flow ``` -## Configuration - -The plugin requires the following environment variables to be set: +or -```typescript -FLOW_ADDRESS= -FLOW_PRIVATE_KEY= -FLOW_NETWORK= -FLOW_ENDPOINT_URL= +```bash +yarn add @elizaos-plugins/plugin-flow ``` -## Usage +## Configuration -### Basic Integration +This plugin does not require any specific environment variables for its basic operation. However, ensure that you have the following dependencies installed, as they are essential for the plugin's functionality: -```typescript -import { flowPlugin } from "@elizaos/plugin-flow"; -``` +- `@onflow/config` +- `@onflow/fcl` +- `@onflow/typedefs` +- `bignumber.js` +- `bs58` -### Example Usage +You can install these dependencies using npm: -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"; +```bash +npm install @onflow/config @onflow/fcl @onflow/typedefs bignumber.js bs58 ``` -## API Reference - -### Actions - -#### SEND_COIN - -Transfers native FLOW tokens, Cadence fungible tokens, or EVM tokens to specified addresses. +## Usage Examples -**Aliases:** - -- SEND_TOKEN -- SEND_TOKEN_ON_FLOW -- TRANSFER_TOKEN_ON_FLOW -- TRANSFER_TOKENS_ON_FLOW -- TRANSFER_FLOW -- SEND_FLOW -- PAY_BY_FLOW - -**Input Content:** +Here is a practical example of how to use the `@elizaos-plugins/plugin-flow` in your ElizaOS agent: ```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 +import { createAgent } from 'elizaos'; +import { FlowPlugin } from '@elizaos-plugins/plugin-flow'; + +const flowPlugin = new FlowPlugin(); + +const agent = createAgent({ + name: "FlowAgent", + bio: "An agent that interacts with the Flow blockchain.", + plugins: [flowPlugin], +}); + +// Example of sending a transaction +async function sendTransaction() { + const transaction = { + // Define your transaction details here + }; + + try { + const result = await agent.plugins.flow.sendTransaction(transaction); + console.log("Transaction successful:", result); + } catch (error) { + console.error("Transaction failed:", error); + } } -``` - -## 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 +sendTransaction(); ``` -4. Run tests: +## Actions and Providers -```bash -pnpm run test -``` +### Actions -## Future Enhancements +The `@elizaos-plugins/plugin-flow` plugin provides various actions that allow agents to interact with the Flow blockchain. Some of the key actions include: -- Support for NFT transfers -- Enhanced error handling and recovery -- Additional Flow blockchain interactions -- Expanded token support +- `sendTransaction`: Sends a transaction to the Flow blockchain. +- `getAccount`: Retrieves account information from the Flow blockchain. -## Contributing +### Providers -Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. +The plugin does not define any specific providers. It primarily interacts with the Flow blockchain through the actions mentioned above. -## Credits +## Troubleshooting -This plugin integrates with and builds upon several key technologies: +If you encounter issues while using the `@elizaos-plugins/plugin-flow`, consider the following troubleshooting steps: -- [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 +1. **Check Dependencies**: Ensure that all required dependencies are installed correctly. +2. **Network Issues**: Verify your internet connection and ensure that the Flow blockchain is accessible. +3. **Error Messages**: Pay attention to error messages returned by the plugin. They often provide clues to the underlying issue. +4. **Consult Documentation**: Refer to the official Flow documentation for more information on transactions and account management. -Special thanks to: +## Contributing -- 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 +Contributions to the `@elizaos-plugins/plugin-flow` are welcome! If you would like to contribute, please follow these guidelines: -For more information about Flow capabilities: +1. Fork the repository. +2. Create a new branch for your feature or bug fix. +3. Make your changes and commit them with clear messages. +4. Push your branch and create a pull request. -- [Flow Documentation](https://docs.onflow.org/) -- [Flow Developer Portal](https://developers.flow.com/) -- [Flow Block Explorer](https://flowscan.io/) -- [Cadence Documentation](https://docs.onflow.org/cadence/) +For any questions or discussions, feel free to open an issue in the repository. -## License +--- -This plugin is part of the Eliza project. See the main project repository for license information. +This README provides a comprehensive overview of the `@elizaos-plugins/plugin-flow`, including installation, configuration, usage examples, actions, troubleshooting, and contributing guidelines. For further assistance, please refer to the ElizaOS documentation or the Flow blockchain documentation. \ No newline at end of file diff --git a/package.json b/package.json index b32f91a..9bdde83 100644 --- a/package.json +++ b/package.json @@ -1,76 +1,77 @@ { - "name": "@elizaos-plugins/plugin-flow", - "version": "0.1.9", - "type": "module", - "main": "dist/index.js", - "module": "dist/index.js", - "types": "dist/index.d.ts", - "exports": { - "./package.json": "./package.json", - ".": { - "import": { - "@elizaos/source": "./src/index.ts", - "types": "./dist/index.d.ts", - "default": "./dist/index.js" - } - } - }, - "files": [ - "dist" - ], - "dependencies": { - "@onflow/config": "1.5.1", - "@onflow/fcl": "1.13.1", - "@onflow/typedefs": "1.4.0", - "bignumber.js": "9.1.2", - "bs58": "6.0.0", - "elliptic": "6.6.1", - "node-cache": "5.1.2", - "sha3": "2.1.4", - "uuid": "11.0.3", - "zod": "3.23.8" - }, - "devDependencies": { - "@biomejs/biome": "1.9.4", - "@types/elliptic": "6.4.18", - "@types/uuid": "10.0.0", - "tsup": "8.3.5", - "vitest": "2.1.9" - }, - "scripts": { - "lines": "find . \\( -name '*.cdc' -o -name '*.ts' \\) -not -path '*/node_modules/*' -not -path '*/tests/*' -not -path '*/deps/*' -not -path '*/dist/*' -not -path '*/imports*' | xargs wc -l", - "build": "tsup --format esm --dts", - "dev": "tsup --format esm --dts --watch", - "test": "vitest run", - "lint": "biome lint .", - "lint:fix": "biome check --apply .", - "format": "biome format .", - "format:fix": "biome format --write ." - }, - "peerDependencies": { - "whatwg-url": "7.1.0" - }, - "agentConfig": { - "pluginType": "elizaos:client:1.0.0", - "pluginParameters": { - "FLOW_ADDRESS": { - "type": "string", - "description": "Flow native address is required and must start with 0x" - }, - "FLOW_PRIVATE_KEY": { - "type": "string", - "description": "Flow private key for the address is required and must start with 0x" - }, - "FLOW_NETWORK": { - "type": "string", - "default": "mainnet", - "description": "Optional network specification" - }, - "FLOW_ENDPOINT_URL": { - "type": "string", - "default": "https://rest-mainnet.onflow.org", - "description": "Optional Flow RPC endpoint URL" - } - } + "name": "@elizaos-plugins/plugin-flow", + "version": "0.1.9", + "type": "module", + "main": "dist/index.js", + "module": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + "./package.json": "./package.json", + ".": { + "import": { + "@elizaos/source": "./src/index.ts", + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } } + }, + "files": [ + "dist" + ], + "dependencies": { + "@onflow/config": "1.5.1", + "@onflow/fcl": "1.13.1", + "@onflow/typedefs": "1.4.0", + "bignumber.js": "9.1.2", + "bs58": "6.0.0", + "elliptic": "6.6.1", + "node-cache": "5.1.2", + "sha3": "2.1.4", + "uuid": "11.0.3", + "zod": "3.23.8" + }, + "devDependencies": { + "@biomejs/biome": "1.9.4", + "@types/elliptic": "6.4.18", + "@types/uuid": "10.0.0", + "tsup": "8.3.5", + "vitest": "2.1.9" + }, + "scripts": { + "lines": "find . \\( -name '*.cdc' -o -name '*.ts' \\) -not -path '*/node_modules/*' -not -path '*/tests/*' -not -path '*/deps/*' -not -path '*/dist/*' -not -path '*/imports*' | xargs wc -l", + "build": "tsup --format esm --dts", + "dev": "tsup --format esm --dts --watch", + "test": "vitest run", + "lint": "biome lint .", + "lint:fix": "biome check --apply .", + "format": "biome format .", + "format:fix": "biome format --write ." + }, + "peerDependencies": { + "whatwg-url": "7.1.0" + }, + "agentConfig": { + "pluginType": "elizaos:client:1.0.0", + "pluginParameters": { + "FLOW_ADDRESS": { + "type": "string", + "description": "Flow native address is required and must start with 0x" + }, + "FLOW_PRIVATE_KEY": { + "type": "string", + "description": "Flow private key for the address is required and must start with 0x" + }, + "FLOW_NETWORK": { + "type": "string", + "default": "mainnet", + "description": "Optional network specification" + }, + "FLOW_ENDPOINT_URL": { + "type": "string", + "default": "https://rest-mainnet.onflow.org", + "description": "Optional Flow RPC endpoint URL" + } + } + }, + "description": "Integrates Flow blockchain capabilities into ElizaOS agents for seamless transaction management." } \ No newline at end of file