Skip to content

1.x fixes - automated updates #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lalalune wants to merge 1 commit into
base: main
Choose a base branch
from
Open

1.x fixes - automated updates #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 75 additions & 126 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 wallet address starting with 0x>
FLOW_PRIVATE_KEY=<Private key for the Flow wallet starting with 0x>
FLOW_NETWORK=<Network to connect to: "mainnet", "testnet", or "emulator" (optional, defaults to "mainnet")>
FLOW_ENDPOINT_URL=<Custom RPC endpoint URL (optional)>
```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.
147 changes: 74 additions & 73 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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."
}