diff --git a/guides/add_your_own_tool.md b/guides/add_your_own_tool.md new file mode 100644 index 0000000..63d1172 --- /dev/null +++ b/guides/add_your_own_tool.md @@ -0,0 +1,179 @@ +# How to Add Your Own Tool + +Extending the **Solana Agent Kit** with custom tools allows you to add specialized functionalities tailored to your needs. This guide walks you through creating and integrating a new tool into the existing framework. + +## Overview + +1. Create a new tool file +2. Implement the tool class +3. Implement supporting functions in SolanaAgentKit +4. Export the new tool +5. Integrate the tool into the agent +6. Use the custom tool + +## Implementation Guide + +### 1. Create a New Tool File + +Create a new TypeScript file in the `src/tools/` directory for your tool (e.g., `custom_tool.ts`). + +### 2. Implement the Tool Class + +```typescript:src/tools/custom_tool.ts +import { Tool } from "langchain/tools"; +import { SolanaAgentKit } from "../agent"; + +export class CustomTool extends Tool { + name = "custom_tool"; + description = "Description of what the custom tool does."; + + constructor(private solanaKit: SolanaAgentKit) { + super(); + } + + protected async _call(input: string): Promise { + try { + const result = await this.solanaKit.customFunction(input); + return JSON.stringify({ + status: "success", + message: "Custom tool executed successfully", + data: result, + }); + } catch (error: any) { + return JSON.stringify({ + status: "error", + message: error.message, + code: error.code || "UNKNOWN_ERROR", + }); + } + } +} +``` + +### 3. Add Supporting Functions to SolanaAgentKit + +```typescript:src/agent/index.ts +export class SolanaAgentKit { + // ... existing code ... + + async customFunction(input: string): Promise { + // Implement your custom functionality + return `Processed input: ${input}`; + } +} +``` + +### 4. Export the Tool + +```typescript:src/tools/index.ts +export * from "./request_faucet_funds"; +export * from "./deploy_token"; +export * from "./custom_tool"; // Add your new tool +``` + +### 5. Integrate with Agent + +```typescript:src/langchain/index.ts +import { CustomTool } from "../tools/custom_tool"; + +export function createSolanaTools(agent: SolanaAgentKit) { + return [ + // ... existing tools ... + new CustomTool(agent), + ]; +} +``` + +### 6. Usage Example + +```typescript +import { SolanaAgentKit, createSolanaTools } from "solana-agent-kit"; + +const agent = new SolanaAgentKit( + "your-wallet-private-key-as-base58", + "https://api.mainnet-beta.solana.com", + "your-openai-api-key" +); + +const tools = createSolanaTools(agent); +const customTool = tools.find(tool => tool.name === "custom_tool"); + +if (customTool) { + const result = await customTool._call("your-input"); + console.log(result); +} +``` + +## Best Practices + +- Implement robust error handling +- Add security checks for sensitive operations +- Document your tool's purpose and usage +- Write tests for reliability +- Keep tools focused on single responsibilities + +## Example: Token Price Fetching Tool + +Here's a complete example of implementing a tool to fetch token prices: + +```typescript:src/tools/fetch_token_price.ts +import { Tool } from "langchain/tools"; +import { SolanaAgentKit } from "../agent"; + +export class FetchTokenPriceTool extends Tool { + name = "fetch_token_price"; + description = "Fetches the current price of a specified token."; + + constructor(private solanaKit: SolanaAgentKit) { + super(); + } + + protected async _call(tokenSymbol: string): Promise { + try { + const price = await this.solanaKit.getTokenPrice(tokenSymbol); + return JSON.stringify({ + status: "success", + message: `Price fetched successfully for ${tokenSymbol}.`, + data: { token: tokenSymbol, price }, + }); + } catch (error: any) { + return JSON.stringify({ + status: "error", + message: error.message, + code: error.code || "UNKNOWN_ERROR", + }); + } + } +} +``` + +Add the supporting function to SolanaAgentKit: + +```typescript:src/agent/index.ts +export class SolanaAgentKit { + async getTokenPrice(tokenSymbol: string): Promise { + const mockPrices: { [key: string]: number } = { + SOL: 150, + USDC: 1, + USDT: 1, + BONK: 0.5, + }; + + if (!mockPrices[tokenSymbol.toUpperCase()]) { + throw new Error(`Price for token symbol ${tokenSymbol} not found.`); + } + + return mockPrices[tokenSymbol.toUpperCase()]; + } +} +``` + +## Need Help? + +If you encounter any issues while implementing your custom tool: + +- Open an issue in the repository +- Contact the maintainer +- Check existing tools for implementation examples + +--- \ No newline at end of file diff --git a/guides/setup_locally.md b/guides/setup_locally.md new file mode 100644 index 0000000..8acfd1e --- /dev/null +++ b/guides/setup_locally.md @@ -0,0 +1,83 @@ +# How to Setup Locally + +Setting up the **Solana Agent Kit** on your local machine involves cloning the repository, installing dependencies, configuring environment variables, and building the project. Follow the steps below to get started. + +## Prerequisites + +- **Node**: Ensure you have Node version 23.x or higher installed. You can download it from [Node Official Website](https://nodejs.org/). +- **Package Manager**: Node's package manager comes bundled with Node. Verify installation by running `npm -v`. +- **Git**: Ensure Git is installed and configured. Download from [Git Official Website](https://git-scm.com/). + +## Step-by-Step Guide + +1. **Clone the Repository** + ```bash + git clone https://github.com/yourusername/solana-agent-kit.git + ``` + +2. **Navigate to the Project Directory** + ```bash + cd solana-agent-kit + ``` + +3. **Install Dependencies** + + The project uses `pnpm` for package management. Install all necessary dependencies by running: + ```bash + pnpm install + ``` + +4. **Configure Environment Variables** + + Create a `.env` file in the root directory of the project to store your environment variables securely. This file should include the following variables: + ```env + OPENAI_API_KEY=your_openai_api_key_here + RPC_URL=your_rpc_url + SOLANA_PRIVATE_KEY=your_solana_private_key_here + ``` + + - **OPENAI_API_KEY**: Your OpenAI API key for generating images and interacting with OpenAI services. + - **RPC_URL**: Your RPC_URL for Solana blockchain interactions. + - **SOLANA_PRIVATE_KEY**: Your Solana wallet's private key in base58 format. + + **Note:** Ensure that the `.env` file is added to `.gitignore` to prevent exposing sensitive information. + +5. **Build the Project** + + Compile the TypeScript code to JavaScript using the build script: + ```bash + pnpm run build + ``` + + This will generate the compiled files in the `dist/` directory. + +6. **Generate Documentation (Optional)** + + If you wish to generate the project documentation, use the following command: + ```bash + pnpm run docs + ``` + + The documentation will be available in the `docs/` directory. + +--- + +**Additional Information:** + +- **Git Configuration:** Ensure that Git is properly configured with your user name and email. You can set them using: + ```bash + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + ``` + +- **Verifying Installation:** + + After installing dependencies and building the project, you can verify the installation by running: + ```bash + pnpm run build + pnpm run test + ``` + + Ensure that all tests pass successfully. + +--- \ No newline at end of file diff --git a/guides/test_it_out.md b/guides/test_it_out.md new file mode 100644 index 0000000..02f8151 --- /dev/null +++ b/guides/test_it_out.md @@ -0,0 +1,107 @@ +# How to Test It Out + +Testing the **Solana Agent Kit** ensures that all functionalities are working as expected. You can run automated tests or interact with the agent in different modes to verify its operations. + +## Running Automated Tests + +The project includes a test script located at `test/index.ts`. To execute the tests: + +1. **Ensure Dependencies are Installed** + - If you haven't installed the dependencies yet, refer to the [Setup Locally](./setup_locally.md) guide. + +2. **Run the Test Script** + ```bash + pnpm run test + ``` + This will run the `test/index.ts` script using `ts-node`. Ensure that your environment variables are correctly set in the `.env` file before running the tests. + +## Interactive Modes + +### Available Modes +1. **Chat Mode** + - Allows you to interact with the agent in a conversational manner. + +2. **Autonomous Mode** + - Enables the agent to perform actions on the blockchain autonomously at regular intervals. + +### Starting the Agent + +1. **Launch the Agent** + ```bash + pnpm start + ``` + +2. **Select Your Mode** + - For Chat Mode: Enter `1` or `chat` + - For Autonomous Mode: Enter `2` or `auto` + +### Using Each Mode + +#### Chat Mode +- Start chatting by entering prompts after the `Prompt:` indicator +- Type `exit` to end the chat session + +#### Autonomous Mode +- The agent executes predefined actions every 10 seconds +- Actions and outputs are displayed in the console + +## Code Examples + +### Token Deployment +```typescript +import { deploy_token } from "solana-agent-kit"; + +const result = await deploy_token( + agent, + 9, // decimals + 1000000 // initial supply +); + +console.log("Token Mint Address:", result.mint.toString()); +``` + +### NFT Collection Creation +```typescript +import { deploy_collection } from "solana-agent-kit"; + +const collection = await deploy_collection(agent, { + name: "My NFT Collection", + uri: "https://arweave.net/metadata.json", + royaltyBasisPoints: 500, // 5% + creators: [ + { + address: "creator-wallet-address", + percentage: 100, + }, + ], +}); +``` + +## Best Practices + +### Environment Setup +- Verify `.env` file contains correct and secure values +- Ensure all required environment variables are set + +### Testing +- Maintain comprehensive test coverage +- Monitor console logs during testing +- Clean up test assets after deployment + +## Troubleshooting + +### Test Failures + +#### Missing Environment Variables +- **Issue:** Tests fail due to missing environment variables +- **Solution:** Check `.env` file for all required variables + +#### Network Problems +- **Issue:** Network-related errors +- **Solution:** Verify internet connection and Solana RPC endpoint accessibility + +### Agent Issues + +#### Startup Problems +- **Issue:** Agent doesn't prompt for mode selection +- **Solution:** Verify successful build and dependency installation \ No newline at end of file