@projectsolo/solo-mission-mcp 0.19.2 → 0.20.1

package/src/solana/wallet.ts

@@ -0,0 +1,142 @@
+/**
+ * The agent's Solana wallet.
+ *
+ * An agent needs SOL as well as USDC to sponsor a Solana mission, and that is new — on Base it
+ * needed only ETH for gas and USDC for the budget. The rent line has no EVM analogue:
+ *
+ *   Task account rent      ~0.00374 SOL   ($0.374)  — partly recovered on close_task
+ *   TaskVault token account ~0.00204 SOL   ($0.204)  — recovered in full on close_task
+ *   transaction fees        ~0.00004 SOL   ($0.004)
+ *   ---------------------------------------------------------------------
+ *   locked during a mission ~0.00582 SOL   (~$0.58)
+ *   permanent cost          ~0.00239 SOL   (~$0.24)  — the on-chain archive, kept on purpose
+ *
+ * That ~$0.24 never comes back, and it buys the on-chain evidence that makes the escrow and the
+ * frozen participant list checkable by anyone. On a $10 mission that is 2.4%; on a $1,000 mission,
+ * 0.024%.
+ *
+ * KEY HANDLING. The keypair stays in this process and is used to sign locally. It is never sent to
+ * the Solo API — the backend builds transactions and submits them, but only the agent can authorise
+ * one. That is the whole point of the partial-signing flow: a compromised backend cannot move a
+ * sponsor's funds, because it never holds the signing key.
+ */
+
+import { readFileSync } from 'fs';
+
+export interface SolanaWallet {
+  publicKey: string;
+  /** 64-byte ed25519 secret. Kept in-process; never transmitted. */
+  secretKey: Uint8Array;
+}
+
+export class SolanaWalletUnavailable extends Error {
+  constructor(reason: string) {
+    super(
+      `Solana wallet unavailable: ${reason}\n\n` +
+        'Set one of:\n' +
+        '  SOLO_SOLANA_KEYPAIR       - JSON byte array, as `solana-keygen` writes it\n' +
+        '  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json)\n\n' +
+        'The wallet needs SOL for rent and fees, and USDC for the mission budget. Rent is a\n' +
+        'refundable deposit, not a fee: most of it returns when the task is closed.',
+    );
+    this.name = 'SolanaWalletUnavailable';
+  }
+}
+
+function parseKeypairBytes(raw: string): Uint8Array {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith('[')) {
+    throw new SolanaWalletUnavailable(
+      'value is not a JSON byte array — this is the format `solana-keygen new` writes',
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new SolanaWalletUnavailable('value looks like a JSON array but does not parse');
+  }
+  if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === 'number')) {
+    throw new SolanaWalletUnavailable('JSON array must contain only numbers');
+  }
+  const bytes = Uint8Array.from(parsed as number[]);
+  // 64 bytes = 32 seed + 32 public. A 32-byte value is the seed alone, which signs but yields a
+  // different address — surfacing later as "wrong sponsor" rather than as a key problem.
+  if (bytes.length !== 64) {
+    throw new SolanaWalletUnavailable(
+      `expected 64 bytes, got ${bytes.length}` +
+        (bytes.length === 32 ? ' — this is the seed alone, not the full keypair' : ''),
+    );
+  }
+  return bytes;
+}
+
+/**
+ * Loads the agent's wallet.
+ *
+ * Read at call time, not at module load, so a tool that never touches Solana works in a process
+ * with no wallet configured at all — an agent running Base missions should not need one.
+ */
+export async function loadSolanaWallet(): Promise<SolanaWallet> {
+  const inline = process.env.SOLO_SOLANA_KEYPAIR;
+  const path = process.env.SOLO_SOLANA_KEYPAIR_PATH;
+
+  let raw: string;
+  if (inline && inline.trim() !== '') {
+    raw = inline;
+  } else if (path && path.trim() !== '') {
+    try {
+      raw = readFileSync(path.replace(/^~/, process.env.HOME ?? '~'), 'utf8');
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${path}: ${(e as Error).message}`);
+    }
+  } else {
+    throw new SolanaWalletUnavailable('neither SOLO_SOLANA_KEYPAIR nor SOLO_SOLANA_KEYPAIR_PATH is set');
+  }
+
+  const secretKey = parseKeypairBytes(raw);
+  const { Keypair } = await import('@solana/web3.js');
+  const kp = Keypair.fromSecretKey(secretKey);
+  return { publicKey: kp.publicKey.toBase58(), secretKey };
+}
+
+/** Whether a Solana wallet is configured, without throwing. */
+export function hasSolanaWallet(): boolean {
+  return Boolean(
+    (process.env.SOLO_SOLANA_KEYPAIR ?? '').trim() ||
+      (process.env.SOLO_SOLANA_KEYPAIR_PATH ?? '').trim(),
+  );
+}
+
+/**
+ * The associated token account for a mint — where the wallet's USDC actually lives.
+ *
+ * An agent commonly has SOL but no token account, because one is only created when tokens first
+ * arrive. `create_task` reads the sponsor's token account, so funding fails if it does not exist —
+ * and the error names the account, not the missing balance, which is confusing enough to be worth
+ * checking for explicitly.
+ */
+export async function associatedTokenAddress(mint: string, owner: string): Promise<string> {
+  const { PublicKey } = await import('@solana/web3.js');
+  const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+  const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+  const [address] = PublicKey.findProgramAddressSync(
+    [new PublicKey(owner).toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), new PublicKey(mint).toBuffer()],
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+  );
+  return address.toBase58();
+}
+
+/** Signs a base64 transaction built by the backend, returning it base64-encoded. */
+export async function signTransaction(
+  transactionBase64: string,
+  wallet: SolanaWallet,
+): Promise<string> {
+  const { Keypair, Transaction } = await import('@solana/web3.js');
+  const kp = Keypair.fromSecretKey(wallet.secretKey);
+  const tx = Transaction.from(Buffer.from(transactionBase64, 'base64'));
+  // partialSign, not sign: the transaction may carry other signature slots, and `sign` would
+  // discard them.
+  tx.partialSign(kp);
+  return tx.serialize().toString('base64');
+}

package/src/tools/solana.ts

@@ -0,0 +1,254 @@
+/**
+ * Solana funding tools.
+ *
+ * Additive. Every existing tool behaves identically, `create_mission` without `chain` still creates
+ * a Base mission, and an agent that never touches Solana needs no wallet configured. That matters
+ * because this is a published package with third-party consumers: a breaking change to the funding
+ * shape would break integrations we cannot see, cannot test, and cannot fix.
+ *
+ * The funding flow is deliberately ONE tool, not three. Build → verify → sign → submit as separate
+ * calls would let an agent skip the verify step, and the verify step is what makes signing an opaque
+ * transaction safe. `fund_solana_mission` refuses to sign on any mismatch and returns the problems
+ * instead.
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const solanaTools: Tool[] = [
+  {
+    name: 'get_solana_config',
+    description:
+      'Read the Solana escrow deployment: program id, cluster, RPC endpoint, accepted mints and their decimals, and the minimum first payout. Call this before funding so you use a whitelisted mint — a mint that is not whitelisted is rejected on chain, not by the API. Requires no wallet.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'get_solana_wallet',
+    description:
+      "Show your Solana wallet address and its balances. Reports SOL (needed for transaction fees and for account rent) and the token balance for a given mint (the mission budget). Use this before funding: an agent needs BOTH, and the rent line has no equivalent on Base. Rent is a refundable deposit, not a fee — most of it returns when the task is closed. If no wallet is configured this explains how to set one up.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mint: {
+          type: 'string',
+          description:
+            'Mint to report a balance for. Defaults to the deployment payout mint from get_solana_config.',
+        },
+      },
+    },
+  },
+  {
+    name: 'fund_solana_mission',
+    description:
+      "Fund a Solana mission end to end: the backend builds the escrow transaction, this tool DECODES AND VERIFIES it against the parameters you expect, signs it locally with your wallet, and submits it. Your key never leaves this process.\n\nVerification is not optional and cannot be skipped. On Solana the backend builds the transaction rather than publishing a parameter set for you to rebuild, so without a decode you would be signing bytes you cannot read. This tool refuses to sign if anything differs from what you expect — a substituted mint, an altered budget, an extra instruction, a vault that is not a program-derived address — and returns the discrepancies instead.\n\nCall create_mission with chain='solana' first; pass that mission's id here.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mission_id: { type: 'string', description: 'Mission created with chain="solana".' },
+        expected_budget: {
+          type: 'number',
+          description:
+            'The total budget in whole tokens (e.g. 10 for 10 USDC) you expect to escrow. Verified against the transaction before signing. Pass what you intended, NOT what the API told you — comparing the API to itself proves nothing.',
+        },
+        expected_mint: {
+          type: 'string',
+          description:
+            'The mint you expect the budget to be taken in. Verified before signing. Defaults to the deployment payout mint.',
+        },
+        dry_run: {
+          type: 'boolean',
+          description:
+            'Build and verify, then stop without signing or submitting. Use this to inspect what would be signed. Nothing is escrowed and no fee is paid.',
+        },
+      },
+      required: ['mission_id', 'expected_budget'],
+    },
+  },
+];
+
+/**
+ * Whole tokens to smallest units, without floating point.
+ *
+ * `10.5 * 1e6` is exact, but `0.07 * 1e6` is 70000.00000000001 and truncates to 69999 — a silent
+ * one-unit shortfall that makes the on-chain budget check fail with an error naming neither the
+ * amount nor the cause. Done as a decimal-string shift instead.
+ */
+export function toRawAmount(amount: number, decimals: number): string {
+  const s = amount.toString();
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new Error(`amount must be a non-negative decimal number, got ${s}`);
+  }
+  const [whole, frac = ''] = s.split('.');
+  if (frac.length > decimals) {
+    throw new Error(
+      `amount ${s} has ${frac.length} decimal places but the mint has only ${decimals}`,
+    );
+  }
+  return (whole + frac.padEnd(decimals, '0')).replace(/^0+(?=\d)/, '');
+}
+
+export const SOLANA_TOOL_NAMES = new Set(solanaTools.map((t) => t.name));
+
+export async function handleSolanaTool(
+  name: string,
+  args: Record<string, any>,
+): Promise<unknown> {
+  const { apiGet, apiPost } = await import('../api/client.js');
+
+  switch (name) {
+    case 'get_solana_config':
+      return apiGet('/agent/solana/config');
+
+    case 'get_solana_wallet': {
+      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress } = await import(
+        '../solana/wallet.js'
+      );
+      if (!hasSolanaWallet()) {
+        return {
+          configured: false,
+          how_to_configure: {
+            option_1: 'SOLO_SOLANA_KEYPAIR — JSON byte array, as `solana-keygen new` writes it',
+            option_2: 'SOLO_SOLANA_KEYPAIR_PATH — path to that file, e.g. ~/.config/solana/id.json',
+          },
+          what_you_need:
+            'SOL for transaction fees and account rent, plus the payout token for the budget. ' +
+            'Rent is a refundable deposit, not a fee — most of it returns on close_task. ' +
+            'Roughly $0.58 is locked per mission and about $0.24 is permanent, which buys the ' +
+            'on-chain record that makes the escrow verifiable by anyone.',
+        };
+      }
+
+      const wallet = await loadSolanaWallet();
+      const cfg = (await apiGet('/agent/solana/config')) as {
+        rpc_url: string;
+        mints: Record<string, string>;
+        decimals: Record<string, number>;
+      };
+      const symbol = Object.keys(cfg.mints)[0];
+      const mint = args.mint ?? cfg.mints[symbol];
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+
+      // Read balances directly from the cluster rather than through our API. An agent checking
+      // whether it can afford a mission should not have to trust us for the answer.
+      const rpc = async (method: string, params: unknown[]) => {
+        const res = await fetch(cfg.rpc_url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+        });
+        return (await res.json()) as { result?: any; error?: { message: string } };
+      };
+
+      const solRes = await rpc('getBalance', [wallet.publicKey]);
+      const tokRes = await rpc('getTokenAccountBalance', [tokenAccount]);
+      const lamports = solRes.result?.value ?? 0;
+      const decimals = cfg.decimals[symbol] ?? 6;
+
+      return {
+        configured: true,
+        address: wallet.publicKey,
+        sol: lamports / 1e9,
+        // A token account only exists once tokens first arrive. create_task reads it, so funding
+        // fails without one — and the on-chain error names the account rather than the missing
+        // balance, which is confusing enough to call out explicitly.
+        token_account: tokenAccount,
+        token_account_exists: !tokRes.error,
+        token_balance: tokRes.result?.value?.uiAmountString ?? '0',
+        mint,
+        can_pay_fees: lamports > 10_000_000, // ~0.01 SOL — comfortably covers rent plus fees
+        note:
+          lamports === 0
+            ? 'No SOL. Funding will fail with "Attempt to debit an account but found no record of a prior credit", which does not mention SOL.'
+            : undefined,
+        _decimals: decimals,
+      };
+    }
+
+    case 'fund_solana_mission': {
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import(
+        '../solana/wallet.js'
+      );
+      const { verifyFundingTransaction } = await import('../solana/verify.js');
+
+      const wallet = await loadSolanaWallet();
+      const cfg = (await apiGet('/agent/solana/config')) as {
+        program_id: string;
+        mints: Record<string, string>;
+        decimals: Record<string, number>;
+      };
+      const symbol = Object.keys(cfg.mints)[0];
+      const mint = args.expected_mint ?? cfg.mints[symbol];
+      const decimals = cfg.decimals[symbol] ?? 6;
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+
+      const built = (await apiPost(
+        `/agent/solana/missions/${args.mission_id}/funding-transaction`,
+        { sponsor_wallet: wallet.publicKey, sponsor_token_account: tokenAccount },
+      )) as {
+        transaction_base64: string;
+        task_id: string;
+        declared: Record<string, any>;
+        accounts: Record<string, string>;
+      };
+
+      const expectedBudgetRaw = toRawAmount(args.expected_budget, decimals);
+
+      const verdict = await verifyFundingTransaction({
+        transaction_base64: built.transaction_base64,
+        declared: built.declared as any,
+        accounts: built.accounts as any,
+        expected: {
+          budget_raw: expectedBudgetRaw,
+          // base_pool is derived by the backend from reward × max_humans. The agent's check on it
+          // is the quoted value against the encoded bytes, which verifyFundingTransaction does —
+          // asserting a locally recomputed figure would require duplicating that arithmetic here
+          // and would fail on a legitimately rounded reward.
+          base_pool_raw: String(built.declared.base_pool),
+          lottery_winner_count: Number(built.declared.lottery_winner_count),
+          lottery_prize_per_winner_raw: String(built.declared.lottery_prize_per_winner),
+          qualify_deadline: Number(built.declared.qualify_deadline),
+          settlement_deadline: Number(built.declared.settlement_deadline),
+          mint,
+          sponsor: wallet.publicKey,
+        },
+        expected_program_id: cfg.program_id,
+      });
+
+      if (!verdict.ok) {
+        // Hard stop. A mismatch means the backend built something other than what was quoted, and
+        // signing would authorise that difference.
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: verdict.problems,
+          summary: verdict.summary,
+          what_this_means:
+            'The transaction does not match what you asked for, so it was NOT signed and nothing ' +
+            'was escrowed. This is the verifier doing its job. Do not retry blindly — the ' +
+            'discrepancy above is either a bug or an attempt to have you authorise something else.',
+        };
+      }
+
+      if (args.dry_run) {
+        return {
+          funded: false,
+          dry_run: true,
+          verified: true,
+          task_id: built.task_id,
+          summary: verdict.summary,
+          would_escrow: `${args.expected_budget} (${expectedBudgetRaw} raw) of ${mint}`,
+        };
+      }
+
+      const signed = await signTransaction(built.transaction_base64, wallet);
+      const confirmed = await apiPost(
+        `/agent/solana/missions/${args.mission_id}/confirm-funding`,
+        { signed_transaction: signed, task_id: built.task_id },
+      );
+
+      return { funded: true, verified: true, ...(confirmed as Record<string, unknown>) };
+    }
+
+    default:
+      throw new Error(`Unknown Solana tool: ${name}`);
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,4 @@
+import { defineConfig } from 'vitest/config'
+// Node environment, unit-scoped. What needs covering is transaction decoding and the refusal
+// logic — the part that can lose an agent's funds.
+export default defineConfig({ test: { environment: 'node', include: ['src/**/*.test.ts'] } })