Modularize Solana agent tools package

Author: trilltino

packages/solana-agent-tools/README.md

@@ -22,6 +22,20 @@ while the example that loads the plugin into SAK runs on Node 22.
 go through the existing repo path: devnet guard, `policy.enforce()`, explicit user approval,
 simulation/signing UX, ledger receipt, and UI transaction surface.
 
+## Source layout
+
+| File | Responsibility |
+|---|---|
+| `src/constants.ts` | Public ids used by read tools (`SOL_MINT`, `USDC_MINT`, `TOKEN_PROGRAM_ID`). |
+| `src/types.ts` | Shared interfaces for connections, prices, balances, wallets, and transfer-intent simulation. |
+| `src/connection.ts` | Dependency injection for the guarded devnet connection and mocked fetch. |
+| `src/wallet.ts` | Read-only wallet facade; every signer method throws. |
+| `src/balances.ts` | SOL and SPL token balance reads. |
+| `src/prices.ts` | Jupiter Price API V3 and Pyth Hermes reads. |
+| `src/intent.ts` | Non-executable transfer-intent simulation through the repo policy gate. |
+| `src/tools.ts` | Stable facade that composes the allowlisted tools. |
+| `src/sak.ts` | Solana Agent Kit-compatible plugin/action adapter. |
+
 ## Solana Agent Kit
 
 ```ts

packages/solana-agent-tools/src/balances.ts

@@ -0,0 +1,73 @@
+import { LAMPORTS_PER_SOL, PublicKey } from '@solana/web3.js'
+import { TOKEN_PROGRAM_ID } from './constants.js'
+import { resolveConnection } from './connection.js'
+import type { SolanaAgentToolOptions, TokenBalance, WalletBalance } from './types.js'
+
+interface ParsedTokenAmount {
+  mint?: string
+  owner?: string
+  amount?: string
+  decimals?: number
+  uiAmount?: number | null
+  uiAmountString?: string
+}
+
+function tokenAmountInfo(parsed: unknown): ParsedTokenAmount | null {
+  if (!parsed || typeof parsed !== 'object') return null
+  const info = (parsed as { info?: unknown }).info
+  if (!info || typeof info !== 'object') return null
+  const tokenAmount = (info as { tokenAmount?: unknown }).tokenAmount
+  if (!tokenAmount || typeof tokenAmount !== 'object') return null
+  const t = tokenAmount as Record<string, unknown>
+  return {
+    mint: typeof (info as Record<string, unknown>).mint === 'string'
+      ? String((info as Record<string, unknown>).mint)
+      : undefined,
+    owner: typeof (info as Record<string, unknown>).owner === 'string'
+      ? String((info as Record<string, unknown>).owner)
+      : undefined,
+    amount: typeof t.amount === 'string' ? t.amount : undefined,
+    decimals: typeof t.decimals === 'number' ? t.decimals : undefined,
+    uiAmount: typeof t.uiAmount === 'number' || t.uiAmount === null ? t.uiAmount : undefined,
+    uiAmountString: typeof t.uiAmountString === 'string' ? t.uiAmountString : undefined,
+  }
+}
+
+/** Read a wallet's SOL balance through the repo's guarded devnet connection. */
+export async function readWalletBalance(
+  address: string,
+  opts: SolanaAgentToolOptions = {},
+): Promise<WalletBalance> {
+  const pubkey = new PublicKey(address)
+  const lamports = await resolveConnection(opts).getBalance(pubkey)
+  return {
+    address: pubkey.toBase58(),
+    lamports,
+    sol: lamports / LAMPORTS_PER_SOL,
+    cluster: 'devnet',
+  }
+}
+
+/** Read parsed SPL token balances for an owner without touching signing or transfer APIs. */
+export async function readTokenBalances(
+  owner: string,
+  opts: SolanaAgentToolOptions = {},
+): Promise<TokenBalance[]> {
+  const ownerKey = new PublicKey(owner)
+  const accounts = await resolveConnection(opts).getParsedTokenAccountsByOwner(ownerKey, {
+    programId: TOKEN_PROGRAM_ID,
+  })
+  return accounts.value.flatMap((entry): TokenBalance[] => {
+    const parsed = tokenAmountInfo(entry.account.data.parsed)
+    if (!parsed?.mint || !parsed.amount || parsed.decimals == null || parsed.uiAmountString == null) return []
+    return [{
+      account: entry.pubkey.toBase58(),
+      mint: parsed.mint,
+      owner: parsed.owner ?? ownerKey.toBase58(),
+      amount: parsed.amount,
+      decimals: parsed.decimals,
+      uiAmount: parsed.uiAmount ?? null,
+      uiAmountString: parsed.uiAmountString,
+    }]
+  })
+}

packages/solana-agent-tools/src/connection.ts

@@ -0,0 +1,12 @@
+import { DEVNET_RPC, solanaConnection } from '@pay/agent-runtime'
+import type { ReadonlySolanaConnection, SolanaAgentToolOptions } from './types.js'
+
+/** Resolve the guarded devnet connection unless a test/example injects a read-only connection. */
+export function resolveConnection(opts: SolanaAgentToolOptions): ReadonlySolanaConnection {
+  return opts.connection ?? solanaConnection(opts.rpcUrl ?? DEVNET_RPC)
+}
+
+/** Resolve the fetch implementation, letting tests and examples mock external price providers. */
+export function resolveFetch(opts: SolanaAgentToolOptions): typeof fetch {
+  return opts.fetch ?? fetch
+}

packages/solana-agent-tools/src/constants.ts

@@ -0,0 +1,10 @@
+import { PublicKey } from '@solana/web3.js'
+
+/** Wrapped SOL mint id used for read-only price lookups. */
+export const SOL_MINT = 'So11111111111111111111111111111111111111112'
+
+/** USDC mint id used as a read-only Jupiter price alias. */
+export const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+
+/** SPL Token program id for parsed token-account balance reads. */
+export const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')

packages/solana-agent-tools/src/intent.ts

@@ -0,0 +1,70 @@
+import {
+  LAMPORTS_PER_SOL,
+  PublicKey,
+  SystemProgram,
+  type TransactionInstruction,
+} from '@solana/web3.js'
+import { enforce } from '@pay/agent-runtime'
+import type { TransferIntentInput, TransferIntentSimulation } from './types.js'
+
+function instructionShape(ix: TransactionInstruction): TransferIntentSimulation['instruction'] {
+  return {
+    programId: ix.programId.toBase58(),
+    dataBase64: Buffer.from(ix.data).toString('base64'),
+    keys: ix.keys.map((k) => ({
+      pubkey: k.pubkey.toBase58(),
+      isSigner: k.isSigner,
+      isWritable: k.isWritable,
+    })),
+  }
+}
+
+/**
+ * Build an instruction-shaped SOL transfer intent without returning a signable transaction.
+ *
+ * This is for agent reasoning and UI review only. It runs the repo policy gate when provided and
+ * always returns `executable: false`.
+ */
+export async function simulateTransferIntent(
+  input: TransferIntentInput,
+): Promise<TransferIntentSimulation> {
+  if (input.amountSol <= 0) throw new Error('amountSol must be positive')
+  const buyer = new PublicKey(input.buyer)
+  const recipient = new PublicKey(input.recipient)
+  const lamports = Math.round(input.amountSol * LAMPORTS_PER_SOL)
+  const policyDecision = input.policy
+    ? enforce({
+        kind: 'deposit',
+        round: input.round ?? 0,
+        service: input.service,
+        amountSol: input.amountSol,
+        payout: recipient.toBase58(),
+        ...(input.awardedPriceSol != null ? { awardedPriceSol: input.awardedPriceSol } : {}),
+        ...(input.spentSol != null ? { spentSol: input.spentSol } : {}),
+        ...(input.lastDepositAt != null ? { lastDepositAt: input.lastDepositAt } : {}),
+        ...(input.now != null ? { now: input.now } : {}),
+      }, input.policy)
+    : { ok: true, violations: [] }
+  const ix = SystemProgram.transfer({
+    fromPubkey: buyer,
+    toPubkey: recipient,
+    lamports,
+  })
+  if (input.reference) ix.keys.push({ pubkey: new PublicKey(input.reference), isSigner: false, isWritable: false })
+  return {
+    kind: 'transfer-intent',
+    executable: false,
+    cluster: 'devnet',
+    service: input.service,
+    buyer: buyer.toBase58(),
+    recipient: recipient.toBase58(),
+    amountSol: input.amountSol,
+    lamports,
+    ...(input.reference ? { reference: input.reference } : {}),
+    policyDecision,
+    reason: policyDecision.ok
+      ? 'dry-run only: no signature requested and no transaction broadcast'
+      : `blocked by policy: ${policyDecision.violations.join('; ')}`,
+    instruction: instructionShape(ix),
+  }
+}

packages/solana-agent-tools/src/prices.ts

@@ -0,0 +1,78 @@
+import { SOL_MINT, USDC_MINT } from './constants.js'
+import { resolveFetch } from './connection.js'
+import type { PythPrice, SolanaAgentToolOptions, TokenPrice } from './types.js'
+
+function aliasMint(id: string): string {
+  const token = id.trim()
+  if (/^sol$/i.test(token)) return SOL_MINT
+  if (/^usdc$/i.test(token)) return USDC_MINT
+  return token
+}
+
+/** Fetch a read-only USD token price from Jupiter Price API V3. */
+export async function fetchTokenPrice(
+  id: string,
+  opts: SolanaAgentToolOptions = {},
+): Promise<TokenPrice> {
+  const mint = aliasMint(id)
+  const base = opts.jupiterPriceBaseUrl ?? 'https://api.jup.ag/price/v3'
+  const url = new URL(base)
+  url.searchParams.set('ids', mint)
+  const headers: Record<string, string> = {}
+  const apiKey = opts.jupiterApiKey ?? process.env.JUPITER_API_KEY
+  if (apiKey) headers['x-api-key'] = apiKey
+  const res = await resolveFetch(opts)(url, { headers })
+  if (!res.ok) throw new Error(`Jupiter price ${res.status}: ${(await res.text()).slice(0, 160)}`)
+  const body = await res.json() as Record<string, unknown>
+  const item = body[mint]
+  if (!item || typeof item !== 'object') throw new Error(`Jupiter price missing for ${mint}`)
+  const o = item as Record<string, unknown>
+  const usdPrice = Number(o.usdPrice)
+  if (!Number.isFinite(usdPrice)) throw new Error(`Jupiter price for ${mint} has no numeric usdPrice`)
+  return {
+    id: mint,
+    usdPrice,
+    ...(typeof o.decimals === 'number' ? { decimals: o.decimals } : {}),
+    ...(typeof o.blockId === 'number' ? { blockId: o.blockId } : {}),
+    ...(typeof o.liquidity === 'number' ? { liquidity: o.liquidity } : {}),
+    ...(typeof o.priceChange24h === 'number' ? { priceChange24h: o.priceChange24h } : {}),
+    ...(typeof o.createdAt === 'string' ? { createdAt: o.createdAt } : {}),
+    provider: 'jupiter',
+  }
+}
+
+/** Fetch a read-only latest price update from Pyth Hermes. */
+export async function fetchPythPrice(
+  priceFeedId: string,
+  opts: SolanaAgentToolOptions = {},
+): Promise<PythPrice> {
+  const id = priceFeedId.trim().replace(/^0x/i, '')
+  if (!/^[0-9a-fA-F]{64}$/.test(id)) throw new Error('Pyth priceFeedId must be a 32-byte hex string')
+  const base = opts.pythHermesBaseUrl ?? 'https://hermes.pyth.network/v2/updates/price/latest'
+  const url = new URL(base)
+  url.searchParams.append('ids[]', id)
+  const res = await resolveFetch(opts)(url)
+  if (!res.ok) throw new Error(`Pyth Hermes ${res.status}: ${(await res.text()).slice(0, 160)}`)
+  const body = await res.json() as { parsed?: Array<{ id?: string; price?: Record<string, unknown> }> }
+  const parsed = body.parsed?.find((p) => p.id?.replace(/^0x/i, '').toLowerCase() === id.toLowerCase())
+  const price = parsed?.price
+  if (!price) throw new Error(`Pyth price missing for ${id}`)
+  const rawPrice = String(price.price ?? '')
+  const exponent = Number(price.expo)
+  const confidenceRaw = String(price.conf ?? '')
+  const publishTime = Number(price.publish_time)
+  const scaled = Number(rawPrice) * 10 ** exponent
+  const confidence = Number(confidenceRaw) * 10 ** exponent
+  if (!Number.isFinite(scaled) || !Number.isFinite(confidence) || !Number.isFinite(publishTime)) {
+    throw new Error(`Pyth price for ${id} is malformed`)
+  }
+  return {
+    id,
+    price: scaled,
+    rawPrice,
+    confidence,
+    exponent,
+    publishTime,
+    provider: 'pyth-hermes',
+  }
+}

packages/solana-agent-tools/src/sak.ts

@@ -11,6 +11,7 @@ export interface SdkActionExample {
   explanation: string
 }
 
+/** Minimal action shape shared by Solana Agent Kit, OpenAI tools, and LangChain adapters. */
 export interface SdkAction {
   name: string
   similes: string[]
@@ -20,6 +21,7 @@ export interface SdkAction {
   handler(agent: unknown, input: Record<string, unknown>): Promise<Record<string, unknown>>
 }
 
+/** SAK-compatible plugin shape for the read-only tool table. */
 export interface ReadonlySolanaToolsPlugin {
   name: 'pay-readonly-solana-tools'
   methods: ReadonlySolanaAgentTools
@@ -56,6 +58,7 @@ function actionResult(value: object): Record<string, unknown> {
   return value as unknown as Record<string, unknown>
 }
 
+/** Create the five allowlisted SAK-style actions backed by `ReadonlySolanaAgentTools`. */
 export function createReadonlySolanaActions(tools: ReadonlySolanaAgentTools): SdkAction[] {
   return [
     {
@@ -135,6 +138,7 @@ export function createReadonlySolanaActions(tools: ReadonlySolanaAgentTools): Sd
   ]
 }
 
+/** Create a Solana Agent Kit-compatible plugin without requesting signing authority from SAK. */
 export function createReadonlySolanaPlugin(
   tools: ReadonlySolanaAgentTools = createSolanaAgentTools(),
 ): ReadonlySolanaToolsPlugin {