feat: guides

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<string> {
+    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<string> {
+    // 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<string> {
+    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<number> {
+    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
+
+---

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.
+
+--- 

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