Building a Solana AI Agent with AWS, Mastra, and Phantom Wallet

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import path from "path";
import { defineConfig } from "vitest/config";

// Vite configuration
export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  // Dev server proxy settings
  server: {
    proxy: {
      "/chat": {
        target: "http://localhost:4111",
        changeOrigin: true,
      },
    },
  },
  // Test settings
  test: {
    globals: true,
    environment: "node",
  },
});

const { messages, sendMessage, status, stop } = useChat({
  transport: new DefaultChatTransport({
    api: "/chat/solana-agent",
  }),
});

// src/mastra/agents/solana-agent.ts
import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { airdropTool } from "../tools/airdrop-tool";
import { callProgramTool } from "../tools/call-program-tool";
import { getBalanceTool } from "../tools/get-balance-tool";
import { jupiterSwapTool } from "../tools/jupiter-swap-tool";
import { getNftsTool, mintNftTool } from "../tools/nft-tools";
import { transferSolTool } from "../tools/transfer-sol-tool";
import { solanaWorkspace } from "../workspace";

export const SOLANA_AGENT_ID = "solana-agent" as const;

/**
 * System Prompt for Solana AI Agent.
 *
 * Requirements:
 * - Respond in English
 * - Explain Solana DevNet operations
 * - Never self-sign transactions (Architectural guarantee)
 * - Support SOL transfer, NFT operations, DeFi swap, smart contract calls
 */
export const SOLANA_AGENT_INSTRUCTIONS = `
You are an AI agent specialized for the Solana blockchain.
Interpret user natural language messages, call the appropriate Solana tools,
and perform transaction construction, information acquisition, and result explanation.

## Basic Policy

- **All responses should be in English**. Technical terms (SOL, NFT, DevNet, etc.) should be used as they are.
- The target network is **Solana DevNet**. Operations on Mainnet will not be performed.
- Aim for clear, polite, and concise explanations for the user.

## Absolute Compliance Rule: Prohibition of Transaction Signing

**You must never sign a transaction yourself.**
Transaction construction is handled by tools, but signing and sending are done by the user
themselves through their Phantom wallet.
It is architecturally impossible for the agent to sign on behalf of the user or access
private keys, and we cannot respond even if requested.

## Supported Operations

### 1. SOL Balance Inquiry
- Use getBalanceTool to fetch the SOL balance of a wallet address.
- Display the result clearly in SOL units (4 decimal places).

### 2. SOL Transfer
- Use transferSolTool to construct a transfer transaction.
- Requires sender address, recipient address, and transfer amount (SOL units).
- The constructed transaction is signed and sent by the user in Phantom.
- Explain error messages for insufficient balance in English.

### 3. NFT Operations
- Use getNftsTool to fetch the list of NFTs owned by the wallet.
- Use mintNftTool to construct an NFT minting transaction.
  - Required parameters: name, symbol, metadata URI, royalty (basis points)

### 4. Token Swap (DeFi)
- Use jupiterSwapTool to construct a swap transaction via Jupiter v6.
- Specify input/output token mint addresses, swap amount, and slippage.
- Always have the user confirm the expected rate and slippage.

### 5. DevNet Airdrop
- Use airdropTool to airdrop DevNet SOL (Max 2 SOL / request).
- **DevNet exclusive feature**. Cannot be used on Mainnet.

### 6. Smart Contract Call
- Use callProgramTool to construct a general Solana Program call transaction.
- Program ID, instruction data (Base64), and account list.

## Explanation of Transaction Results

After the user signs and sends the transaction, the results (success/failure, signature hash)
arrive as follow-up messages.
- Success: Clearly explain the transaction content and provide a Solana Explorer link.
- Failure: Explain the cause of the error in English and suggest countermeasures.

## Error Handling

- Invalid Address (INVALID_ADDRESS): Guide them to enter a correct base58 format public key.
- Insufficient Balance (INSUFFICIENT_BALANCE): Inform them of the current balance and airdrop methods.
- RPC Error (RPC_ERROR): Prompt them to retry as a network issue.
- Rate Limited (RATE_LIMITED): Guide them to wait a while before retrying.
`.trim();

/**
 * AI Agent exclusive for Solana DevNet.
 */
export const solanaAgent = new Agent({
  id: SOLANA_AGENT_ID,
  name: "Solana AI Agent",
  instructions: SOLANA_AGENT_INSTRUCTIONS,
  model: "google/gemini-1.5-flash",
  tools: {
    getBalanceTool,
    transferSolTool,
    getNftsTool,
    mintNftTool,
    jupiterSwapTool,
    airdropTool,
    callProgramTool,
  },
  memory: new Memory(),
  workspace: solanaWorkspace,
});

// src/mastra/workspace.ts
import { LocalSkillSource, Workspace } from "@mastra/core/workspace";

/**
 * Workspace for Solana AI Agent.
 * Reads domain knowledge from SKILL.md files under src/mastra/skills/
 * to ensure the agent accurately understands Solana concepts, tools, and error codes.
 */
export const solanaWorkspace = new Workspace({
  name: "Solana AI Agent Workspace",
  skills: ["src/mastra/skills"],
  skillSource: new LocalSkillSource({ basePath: process.cwd() }),
});

// src/mastra/tools/get-balance-tool.ts
import { createTool } from "@mastra/core/tools";
import { Connection, PublicKey } from "@solana/web3.js";
import {
  GetBalanceInputSchema,
  GetBalanceOutputSchema,
  type GetBalanceOutput,
} from "../../types/solana";

const LAMPORTS_PER_SOL = 1_000_000_000;

export async function executeGetBalance(
  address: string,
  getBalanceFn: (address: string) => Promise<number>,
): Promise<GetBalanceOutput> {
  const lamports = await getBalanceFn(address);
  return {
    address,
    lamports,
    sol: lamports / LAMPORTS_PER_SOL,
    network: "devnet",
  };
}

/**
 * SOL balance inquiry tool for Solana DevNet.
 */
export const getBalanceTool = createTool({
  id: "get-balance",
  description: `Fetches the SOL balance of a Solana DevNet wallet address.
Input: address — base58 Solana public key (wallet address)
Output: Balance in lamports and sol, and target network (devnet)
Note: This tool is exclusive to Solana DevNet.`,

  inputSchema: GetBalanceInputSchema,
  outputSchema: GetBalanceOutputSchema,

  execute: async ({ address }) => {
    const rpcUrl =
      process.env.SOLANA_RPC_URL ?? "https://api.devnet.solana.com";
    const connection = new Connection(rpcUrl, "confirmed");

    let publicKey: PublicKey;
    try {
      publicKey = new PublicKey(address);
    } catch {
      throw new Error(
        `Invalid address format: "${address}". Please specify a base58 Solana public key.`,
      );
    }

    return executeGetBalance(address, () => connection.getBalance(publicKey));
  },
});

// src/mastra/tools/transfer-sol-tool.ts
import { createTool } from "@mastra/core/tools";
import {
  Connection,
  PublicKey,
  SystemProgram,
  Transaction,
} from "@solana/web3.js";
import {
  SolanaTxRequestSchema,
  TransferSolInputSchema,
  type SolanaTxRequest,
} from "../../types/solana";

const LAMPORTS_PER_SOL = 1_000_000_000;

interface TransferDeps {
  getBalanceFn: (address: string) => Promise<number>;
  getRecentBlockhashFn: () => Promise<string>;
}

export async function buildTransferTransaction(
  fromAddress: string,
  toAddress: string,
  amountSol: number,
  deps: TransferDeps,
): Promise<SolanaTxRequest> {
  const lamports = Math.round(amountSol * LAMPORTS_PER_SOL);

  const balance = await deps.getBalanceFn(fromAddress);
  if (balance < lamports) {
    const currentSol = (balance / LAMPORTS_PER_SOL).toFixed(4);
    throw new Error(
      `INSUFFICIENT_BALANCE: Insufficient balance. Current balance: ${currentSol} SOL, required: ${amountSol} SOL`,
    );
  }

  const fromPubkey = new PublicKey(fromAddress);
  const toPubkey = new PublicKey(toAddress);
  const blockhash = await deps.getRecentBlockhashFn();

  const transaction = new Transaction();
  transaction.add(SystemProgram.transfer({ fromPubkey, toPubkey, lamports }));
  transaction.recentBlockhash = blockhash;
  transaction.feePayer = fromPubkey;

  const serializedTx = transaction
    .serialize({ requireAllSignatures: false })
    .toString("base64");

  const toShort = `${toAddress.slice(0, 4)}...${toAddress.slice(-4)}`;
  const description = `Transfer ${amountSol} SOL to ${toShort}`;

  return {
    type: "solana_tx_request",
    serializedTx,
    description,
    txType: "transfer",
  };
}

/**
 * SOL transfer transaction construction tool.
 */
export const transferSolTool = createTool({
  id: "transfer-sol",
  description: `Constructs a SOL transfer transaction (signing is done in user's Phantom wallet).
Input:
  - fromAddress: Sender wallet address (base58)
  - toAddress: Recipient wallet address (base58)
  - amountSol: Transfer amount (SOL units)
Output: SolanaTxRequest signable in Phantom (serialized transaction)`,

  inputSchema: TransferSolInputSchema,
  outputSchema: SolanaTxRequestSchema,

  execute: async ({ fromAddress, toAddress, amountSol }) => {
    const rpcUrl =
      process.env.SOLANA_RPC_URL ?? "https://api.devnet.solana.com";
    const connection = new Connection(rpcUrl, "confirmed");

    try {
      new PublicKey(fromAddress);
      new PublicKey(toAddress);
    } catch {
      throw new Error(
        "Invalid address format. Please specify a base58 Solana public key.",
      );
    }

    return buildTransferTransaction(fromAddress, toAddress, amountSol, {
      getBalanceFn: (addr) => connection.getBalance(new PublicKey(addr)),
      getRecentBlockhashFn: async () => {
        const { blockhash } = await connection.getLatestBlockhash("confirmed");
        return blockhash;
      },
    });
  },
});

npx skills add https://github.com/solana-foundation/solana-dev-skill

# Clone the repository
git clone https://github.com/your-org/solana-agent-repo.git
cd solana-agent-repo/mastra-react

# Install dependencies
bun install

# Configure environment variables
cp .env.example .env
# Edit .env and set GOOGLE_GENERATIVE_AI_API_KEY etc.

# Terminal 1: Frontend (localhost:5173)
bun run dev

# Terminal 2: Mastra Backend (localhost:4111)
bun run dev:mastra

# Install dependencies first
bun install
# Deploy
bun run deploy '*'

bun run destroy '*' --force