@projectsolo/solo-mission-mcp 0.19.2 → 0.20.1

package/src/index.ts

@@ -18,8 +18,9 @@ import { conversationTools, handleConversationTool } from './tools/conversations
 import { realtimeTools, handleRealtimeTool } from './tools/realtime.js';
 import { agentTools, handleAgentTool } from './tools/agent.js';
 import { trackTools, handleTrackTool } from './tools/tracks.js';
+import { solanaTools, SOLANA_TOOL_NAMES, handleSolanaTool } from './tools/solana.js';
 
-const ALL_TOOLS = [...agentTools, ...missionTools, ...humanTools, ...conversationTools, ...realtimeTools, ...trackTools];
+const ALL_TOOLS = [...agentTools, ...missionTools, ...humanTools, ...conversationTools, ...realtimeTools, ...trackTools, ...solanaTools];
 
 const AGENT_TOOL_NAMES = new Set(agentTools.map((t) => t.name));
 const MISSION_TOOL_NAMES = new Set(missionTools.map((t) => t.name));
@@ -55,6 +56,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       result = await handleRealtimeTool(name, args as Record<string, any>);
     } else if (TRACK_TOOL_NAMES.has(name)) {
       result = await handleTrackTool(name, args as Record<string, any>);
+    } else if (SOLANA_TOOL_NAMES.has(name)) {
+      result = await handleSolanaTool(name, args as Record<string, any>);
     } else {
       return {
         content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/src/scripts/check-tools-against-spec.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env tsx
+/**
+ * Release gate: fails if solo-firebase's live OpenAPI spec documents a route that no
+ * MCP tool in this package actually calls.
+ *
+ * Companion to solo_firebase#196 (mission-api now serves GET /agent/openapi.json,
+ * generated live from its own route annotations) and solo_mission_web#156 (the same
+ * gate for the /developers page). Without something on this side checking against it,
+ * a live spec existing doesn't stop these tools from drifting the same way the docs
+ * page did in solo_mission_web#154.
+ *
+ * Direction of the check, and why: this package's tool set is intentionally BIGGER
+ * than what the spec currently covers (36 tools vs. 19 annotated operations — most of
+ * solo-firebase's mission-api routes aren't annotated yet, see solo_firebase#196's
+ * "next steps"). Checking "every REST call in this package must appear in the spec"
+ * would fail on every one of those un-annotated routes for no real reason. Checking
+ * the other direction — "every route the spec DOES document must be called by
+ * something here" — only walks the spec's small, well-defined set, so it stays
+ * meaningful without needing a maintained allowlist of which tools are in scope.
+ *
+ * Extraction is static regex over src/tools/*.ts (same approach as solo-firebase's own
+ * openapiSpecConformance.test.ts and solo-mission-web's check-dev-docs-against-spec.mjs
+ * — no runtime app boot, no live network call except the one spec fetch), matching
+ * apiGet/apiPost/apiPut/apiDelete/publicApiPost call sites, tolerating the generic type
+ * argument (apiPost<T>(...)) and multi-line calls actually used in this codebase.
+ * Template-literal interpolations (${args.mission_id}) and OpenAPI {id}-style path
+ * params are both normalized to a generic :param token and compared positionally —
+ * exact param names don't need to match, only path shape.
+ *
+ * Usage: npx tsx src/scripts/check-tools-against-spec.ts
+ * Override the spec URL (e.g. against a local/staging backend) with SPEC_URL=...
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOLS_DIR = join(__dirname, '../tools');
+const SPEC_URL = process.env.SPEC_URL ?? 'https://api.mission.projectsolo.ai/agent/openapi.json';
+
+const METHOD_BY_FN: Record<string, string> = {
+  apiGet: 'GET',
+  apiPost: 'POST',
+  apiPut: 'PUT',
+  apiDelete: 'DELETE',
+  publicApiPost: 'POST',
+};
+
+function normalizeParams(path: string): string {
+  return path
+    .split('?')[0] // strip query strings (e.g. the upload-url ?content_type=... calls)
+    .replace(/\$\{[^}]*\}/g, ':param') // template-literal interpolations
+    .replace(/\{[^}]*\}/g, ':param'); // OpenAPI {param} style, for symmetry if ever mixed in
+}
+
+/** Every "METHOD normalizedPath" this package's tools actually call, from any tools/*.ts file. */
+function extractCalledRoutes(): Set<string> {
+  const routes = new Set<string>();
+  const files = readdirSync(TOOLS_DIR).filter((f) => f.endsWith('.ts'));
+  const fnNames = Object.keys(METHOD_BY_FN).join('|');
+  // Matches both the common case — a string/template literal passed straight into the
+  // call — and an identifier (e.g. apiPost(path)) built from a `const path = \`...\``
+  // a line or two earlier, which conversations.ts's upload-url tools both do (the path
+  // there needs a query string appended, so it's assembled before the call).
+  const directCallPattern = new RegExp(`\\b(${fnNames})\\s*(?:<[^>]*>)?\\s*\\(\\s*(\`|'|")((?:(?!\\2).)*)\\2`, 'gs');
+  const indirectCallPattern = new RegExp(`\\b(${fnNames})\\s*(?:<[^>]*>)?\\s*\\(\\s*([A-Za-z_$][A-Za-z0-9_$]*)\\s*[,)]`, 'g');
+  const constAssignPattern = /const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(`|'|")((?:(?!\2).)*)\2/gs;
+
+  for (const file of files) {
+    const source = readFileSync(join(TOOLS_DIR, file), 'utf8');
+
+    let match: RegExpExecArray | null;
+    while ((match = directCallPattern.exec(source)) !== null) {
+      const [, fnName, , rawPath] = match;
+      routes.add(`${METHOD_BY_FN[fnName]} ${normalizeParams(rawPath)}`);
+    }
+
+    const localPaths = new Map<string, string>();
+    while ((match = constAssignPattern.exec(source)) !== null) {
+      const [, varName, , rawValue] = match;
+      if (rawValue.startsWith('/')) localPaths.set(varName, rawValue);
+    }
+    while ((match = indirectCallPattern.exec(source)) !== null) {
+      const [, fnName, varName] = match;
+      const rawPath = localPaths.get(varName);
+      if (rawPath) routes.add(`${METHOD_BY_FN[fnName]} ${normalizeParams(rawPath)}`);
+    }
+  }
+  return routes;
+}
+
+/** Every "METHOD normalizedPath" the live spec documents. */
+async function fetchSpecRoutes(): Promise<string[]> {
+  const res = await fetch(SPEC_URL);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${SPEC_URL}: HTTP ${res.status}`);
+  }
+  const spec = (await res.json()) as { paths?: Record<string, Record<string, unknown>> };
+  const routes: string[] = [];
+  for (const [openApiPath, operations] of Object.entries(spec.paths ?? {})) {
+    const normalizedPath = normalizeParams(openApiPath);
+    for (const method of Object.keys(operations)) {
+      routes.push(`${method.toUpperCase()} ${normalizedPath}`);
+    }
+  }
+  return routes;
+}
+
+const called = extractCalledRoutes();
+if (called.size < 10) {
+  // Sanity check on the extraction itself — if the call-site shape changes and the
+  // regex stops matching, fail loudly instead of silently passing on a near-empty set.
+  console.error(`Only extracted ${called.size} called routes from src/tools/*.ts — expected 15+. Regex may be out of sync with the call-site shape.`);
+  process.exit(1);
+}
+
+let specRoutes: string[];
+try {
+  specRoutes = await fetchSpecRoutes();
+} catch (err) {
+  console.error(`Could not verify tool coverage against the live API spec: ${(err as Error).message}`);
+  process.exit(1);
+}
+
+const uncalled = specRoutes.filter((route) => !called.has(route) && !route.endsWith('/agent/openapi.json'));
+
+if (uncalled.length > 0) {
+  console.error("The live API spec documents routes that no tool in src/tools/*.ts calls:");
+  for (const route of uncalled) console.error(`  - ${route}`);
+  console.error(`\nSpec source: ${SPEC_URL}`);
+  console.error("Either a tool's REST call was changed/removed without updating this check's");
+  console.error('expectations, or the backend added something here that this package should');
+  console.error('expose a tool for.');
+  process.exit(1);
+}
+
+console.log(`OK: all ${specRoutes.length} spec-documented routes are called by at least one tool.`);

package/src/solana/fixtures/funding-transaction.json

@@ -0,0 +1,26 @@
+{
+  "note": "Real unsigned funding transaction from a devnet build. Regenerate via solo-firebase.",
+  "transaction_base64": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAYLBn/X5KDAn7qqA/To43J65jX78KnAaVCjVCRbz+mYBCgnoBchO2eGZuluIN1pWEEMoHQ4k7mn6xBq3fZc15Wq5l1iIspDEk7t/bB/Zl6fY+JPqVmMKxgM2AOUhUOv0xHDeqmxgXEbeQff54UY/FVyYjrgBnMBpdqqqbxSvY/zNlm7EfkLCeFhyL4FowTI4EcRrQqdoqcQGVgWSmDjzuigLQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEcYq0VKhiU4ktY09qsij+rs+4b6Yt6VTnLfH9HKPyLcmlwpi3dEh8irDXYuBeelr9ra81Js5JF779Op1Y4ebznilsPINlCy+dlo0+WnBLgmlHMRNxcGJTTgj45SCbOkTxBwQrSJibjN7eiWjtGYLfQwfBf0s2Q6KtbBFFOSJw2EG3fbh12Whk9nL4UbO63msHLSF7V9bN5E6jPWFfv8AqTAL9uQNYRTTcBtK4JgAZhwS5nf9015fN/JiocFYjUg8AQYLAAIICQQBAwoFBwZUwlAGtOh/MKuAlpgAAAAAAICWmAAAAAAAAAAAAAAAAAAAAAAAXISfagAAAADs/KBqAAAAAFewZMVt1ZTMRLwAu4YKXz3zJhH7CWS8TDfikv6h314J",
+  "declared": {
+    "budget": "10000000",
+    "base_pool": "10000000",
+    "lottery_winner_count": 0,
+    "lottery_prize_per_winner": "0",
+    "qualify_deadline": "1788839004",
+    "settlement_deadline": "1788935404",
+    "seed_commit": "57b064c56dd594cc44bc00bb860a5f3df32611fb0964bc4c37e292fea1df5e09"
+  },
+  "accounts": {
+    "program_id": "2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a",
+    "config": "7HXi3y1i3p4LVV3WGV6R4CM7waxNAXrjCX6SRSUcjEca",
+    "task": "DbF8pG81oyMbSv9YrBdjL9sNcsDZJxCg4G55uMjk64gt",
+    "vault": "3fgV8JmKJ4HBue1bPNL6vwXPqVVwXArMGbbiAWVQKNR3",
+    "whitelist": "97xTnhyGDmJkZsoNtcm7gjV48yfaBstijFDqiUFru7Jr",
+    "mint": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E",
+    "sponsor": "SNWfcT9xHa6EgXc6UTSfDj1gCVjeZw8NtmNLqxq7X1Z",
+    "sponsor_token_account": "9FppNm8rDAukTaBVg2fHSjYxZpXNp6YvDcHgPmn1Tm9i"
+  },
+  "program_id": "2CPC5V63FDs7SdWu89iSYYsTEpqBwuQeYuA9ASzuSo8a",
+  "sponsor": "SNWfcT9xHa6EgXc6UTSfDj1gCVjeZw8NtmNLqxq7X1Z",
+  "mint": "ECXjKm8nNMYFaUuv19DRxSqMKDckmddgKhBHrjHWU73E"
+}

package/src/solana/verify.test.ts

@@ -0,0 +1,179 @@
+/**
+ * The verifier is the one thing standing between an agent and signing bytes it cannot read, so it
+ * is tested against a REAL transaction built by the deployed program's own backend rather than a
+ * synthetic one. A hand-built fixture would encode my assumptions about the layout twice and agree
+ * with itself.
+ *
+ * `fixtures/funding-transaction.json` is captured from a devnet funding run.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import {
+  verifyFundingTransaction,
+  type VerifyInput,
+  type ExpectedFunding,
+  type FundingAccounts,
+} from './verify'
+import { toRawAmount } from '../tools/solana'
+
+const fx = JSON.parse(
+  readFileSync(join(__dirname, 'fixtures', 'funding-transaction.json'), 'utf8'),
+) as {
+  transaction_base64: string
+  declared: ExpectedFunding
+  accounts: FundingAccounts
+  program_id: string
+  sponsor: string
+  mint: string
+}
+
+const baseInput = (): VerifyInput => ({
+  transaction_base64: fx.transaction_base64,
+  declared: fx.declared,
+  accounts: fx.accounts,
+  expected: {
+    budget_raw: String(fx.declared.budget),
+    base_pool_raw: String(fx.declared.base_pool),
+    lottery_winner_count: Number(fx.declared.lottery_winner_count),
+    lottery_prize_per_winner_raw: String(fx.declared.lottery_prize_per_winner),
+    qualify_deadline: Number(fx.declared.qualify_deadline),
+    settlement_deadline: Number(fx.declared.settlement_deadline),
+    mint: fx.mint,
+    sponsor: fx.sponsor,
+  },
+  expected_program_id: fx.program_id,
+})
+
+describe('accepts a genuine transaction', () => {
+  it('passes with no problems', async () => {
+    const r = await verifyFundingTransaction(baseInput())
+    expect(r.problems).toEqual([])
+    expect(r.ok).toBe(true)
+  })
+
+  it('reports what it actually saw, for logging even on success', async () => {
+    const r = await verifyFundingTransaction(baseInput())
+    expect(r.summary.program_id).toBe(fx.program_id)
+    expect(r.summary.instruction_count).toBe(1)
+    expect(r.summary.signers).toEqual([fx.sponsor])
+  })
+})
+
+describe('refuses when the agent expected something else', () => {
+  it('catches an altered budget', async () => {
+    const input = baseInput()
+    input.expected.budget_raw = '999999999'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/budget/)
+  })
+
+  it('catches a substituted mint', async () => {
+    const input = baseInput()
+    input.expected.mint = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/mint/)
+  })
+
+  it('catches a different program, even when every parameter matches', async () => {
+    const input = baseInput()
+    input.expected_program_id = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/program/)
+  })
+
+  it('catches a sponsor who is not the signer', async () => {
+    const input = baseInput()
+    input.expected.sponsor = '4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/signer|fee payer/i)
+  })
+
+  it('reports every problem, not just the first', async () => {
+    // An agent debugging this wants the whole list, not one at a time.
+    const input = baseInput()
+    input.expected.budget_raw = '1'
+    input.expected.mint = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'
+    const r = await verifyFundingTransaction(input)
+    expect(r.problems.length).toBeGreaterThan(1)
+  })
+})
+
+describe('refuses when the backend quoted one thing and built another', () => {
+  it('catches a declared budget that disagrees with the encoded bytes', async () => {
+    // The strongest check: everything else compares the backend's JSON against the agent's
+    // expectations, which a lying backend controls both halves of. This compares the JSON against
+    // the instruction data actually being signed.
+    const input = baseInput()
+    input.declared = { ...fx.declared, budget: '1' }
+    input.expected.budget_raw = '1'
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/described one thing and built another/)
+  })
+
+  it('catches a declared deadline that disagrees with the bytes', async () => {
+    const input = baseInput()
+    input.declared = { ...fx.declared, settlement_deadline: '1' }
+    input.expected.settlement_deadline = 1
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/described one thing and built another/)
+  })
+})
+
+describe('structural refusals', () => {
+  it('catches a vault equal to the sponsor token account', async () => {
+    // Would mean the budget never leaves the sponsor's control — funded on paper, not escrowed.
+    const input = baseInput()
+    input.accounts = { ...fx.accounts, vault: fx.accounts.sponsor_token_account }
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/not be escrowed/)
+  })
+
+  it('catches a vault that is not a program-derived address', async () => {
+    // An on-curve "vault" is a wallet somebody holds the key to.
+    const input = baseInput()
+    input.accounts = { ...fx.accounts, vault: fx.sponsor }
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/program-derived|holds its key/)
+  })
+
+  it('catches a malformed seed commit', async () => {
+    const input = baseInput()
+    input.declared = { ...fx.declared, seed_commit: 'nope' }
+    const r = await verifyFundingTransaction(input)
+    expect(r.ok).toBe(false)
+    expect(r.problems.join(' ')).toMatch(/seed_commit/)
+  })
+})
+
+describe('toRawAmount avoids the float trap', () => {
+  it('converts whole and fractional amounts exactly', () => {
+    expect(toRawAmount(10, 6)).toBe('10000000')
+    expect(toRawAmount(10.5, 6)).toBe('10500000')
+    expect(toRawAmount(0.5, 6)).toBe('500000')
+  })
+
+  it('handles the amount that float multiplication gets wrong', () => {
+    // 0.07 * 1e6 is 70000.00000000001 in IEEE 754 and truncates to 69999 — a silent one-unit
+    // shortfall whose on-chain rejection names neither the amount nor the cause.
+    expect(toRawAmount(0.07, 6)).toBe('70000')
+    expect(toRawAmount(0.29, 6)).toBe('290000')
+    expect(toRawAmount(1.005, 6)).toBe('1005000')
+  })
+
+  it('rejects more precision than the mint has', () => {
+    expect(() => toRawAmount(1.0000001, 6)).toThrow(/decimal places/)
+  })
+
+  it('rejects a negative amount', () => {
+    expect(() => toRawAmount(-1, 6)).toThrow()
+  })
+})

package/src/solana/verify.ts

@@ -0,0 +1,257 @@
+/**
+ * Decodes a funding transaction and checks it against what the agent asked for.
+ *
+ * WHY THIS IS MANDATORY, NOT DEFENSIVE. On Base an agent builds `createTask` itself from published
+ * parameters, so it can verify every field against the API response and the contract ABI before
+ * signing. Solana funding uses partial signing — the backend builds, the agent signs, the backend
+ * submits — which removes a whole class of integration breakage but hands the agent an opaque
+ * base64 blob.
+ *
+ * A human signing in Phantom gets that blob decoded for free by their wallet UI. **An agent has no
+ * wallet UI.** So without this, "the agent authorises exactly what it signs" is technically true and
+ * practically meaningless: it would be authorising bytes it cannot read. The design freeze calls
+ * this the least settled decision in the whole plan and makes the verifier a requirement of the
+ * flow, not an optional extra.
+ *
+ * WHAT THIS DOES AND DOES NOT PROVE. It re-encodes the instruction data from the agent's own
+ * parameters and compares bytes, and it checks the accounts the transaction touches. So it catches a
+ * backend that quoted one budget and built another, a substituted mint, a redirected vault, or a
+ * different program entirely. It does NOT prove the backend will submit the transaction it showed
+ * you — but it cannot usefully alter one afterwards either, because any change invalidates the
+ * signature.
+ *
+ * This reintroduces a dependency on the instruction layout, which partial signing was meant to
+ * remove. The difference is where that dependency lives: inside a package we version and ship,
+ * rather than as a contract every third party reimplements. That is the whole point, and it is
+ * honest to say the shape dependency is reduced rather than eliminated.
+ */
+
+/** What the agent believes it is funding. Every field is compared. */
+export interface ExpectedFunding {
+  /** Smallest-unit strings, as the API returns them. Compared as bigints so "10" and "10.0" or a
+   *  leading zero cannot slip past a string equality check. */
+  budget: string;
+  base_pool: string;
+  lottery_winner_count: number;
+  lottery_prize_per_winner: string;
+  qualify_deadline: string;
+  settlement_deadline: string;
+  /** 64 hex chars, no 0x. */
+  seed_commit: string;
+}
+
+export interface FundingAccounts {
+  program_id: string;
+  config: string;
+  task: string;
+  vault: string;
+  whitelist: string;
+  mint: string;
+  sponsor: string;
+  sponsor_token_account: string;
+}
+
+export interface VerifyInput {
+  transaction_base64: string;
+  declared: ExpectedFunding;
+  accounts: FundingAccounts;
+  /** What the agent asked for, independent of what the backend replied. */
+  expected: {
+    budget_raw: string;
+    base_pool_raw: string;
+    lottery_winner_count: number;
+    lottery_prize_per_winner_raw: string;
+    qualify_deadline: number;
+    settlement_deadline: number;
+    mint: string;
+    sponsor: string;
+  };
+  /** The program the agent expects. Pinned so a transaction pointed at a different program is
+   *  rejected even if every parameter matches. */
+  expected_program_id: string;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  /** Every discrepancy found, not just the first — an agent debugging this wants the whole list. */
+  problems: string[];
+  /** What the transaction actually contains, for logging even on success. */
+  summary: {
+    program_id: string;
+    instruction_count: number;
+    signers: string[];
+    budget: string;
+    mint: string;
+    task: string;
+  };
+}
+
+const eqAmount = (a: string, b: string): boolean => {
+  try {
+    return BigInt(a) === BigInt(b);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Verifies a funding transaction. Returns every problem rather than throwing on the first.
+ *
+ * REFUSE TO SIGN when `ok` is false. The caller must treat this as a hard stop — a mismatch means
+ * the backend built something other than what was quoted, and signing it authorises that difference.
+ */
+export async function verifyFundingTransaction(input: VerifyInput): Promise<VerifyResult> {
+  const { Transaction, PublicKey } = await import('@solana/web3.js');
+  const problems: string[] = [];
+
+  const tx = Transaction.from(Buffer.from(input.transaction_base64, 'base64'));
+
+  // ---- structure ------------------------------------------------------------------------------
+  // Exactly one instruction. An extra one is the cheapest way to hide something — a token transfer
+  // appended after create_task would be signed by the same signature.
+  if (tx.instructions.length !== 1) {
+    problems.push(
+      `expected exactly 1 instruction, found ${tx.instructions.length} — ` +
+        'additional instructions would be authorised by the same signature',
+    );
+  }
+
+  const ix = tx.instructions[0];
+  const programId = ix?.programId?.toBase58() ?? '(none)';
+  if (programId !== input.expected_program_id) {
+    problems.push(`program is ${programId}, expected ${input.expected_program_id}`);
+  }
+  if (programId !== input.accounts.program_id) {
+    problems.push(
+      `transaction program ${programId} disagrees with the quoted accounts.program_id ` +
+        `${input.accounts.program_id}`,
+    );
+  }
+
+  // ---- the only signer must be us --------------------------------------------------------------
+  const signers = (ix?.keys ?? []).filter((k) => k.isSigner).map((k) => k.pubkey.toBase58());
+  if (signers.length !== 1 || signers[0] !== input.expected.sponsor) {
+    problems.push(
+      `expected the sponsor ${input.expected.sponsor} to be the only signer, found [${signers.join(', ')}]`,
+    );
+  }
+  if (tx.feePayer?.toBase58() !== input.expected.sponsor) {
+    problems.push(
+      `fee payer is ${tx.feePayer?.toBase58() ?? '(unset)'}, expected ${input.expected.sponsor}`,
+    );
+  }
+
+  // ---- the accounts the money moves between ----------------------------------------------------
+  const keyList = (ix?.keys ?? []).map((k) => k.pubkey.toBase58());
+  for (const [label, expected] of [
+    ['mint', input.expected.mint],
+    ['sponsor', input.expected.sponsor],
+  ] as const) {
+    if (!keyList.includes(expected)) {
+      problems.push(`${label} ${expected} does not appear in the transaction's accounts`);
+    }
+  }
+  if (input.accounts.mint !== input.expected.mint) {
+    problems.push(`quoted mint ${input.accounts.mint}, expected ${input.expected.mint}`);
+  }
+  // The task and its vault are PDAs the program derives; they cannot be verified without repeating
+  // the derivation, but they MUST be distinct and must both be present. A vault equal to the
+  // sponsor's own token account would mean the budget never leaves their control.
+  if (input.accounts.vault === input.accounts.sponsor_token_account) {
+    problems.push('escrow vault equals the sponsor token account — the budget would not be escrowed');
+  }
+  try {
+    // Both must be off-curve, i.e. genuine PDAs with no private key. An on-curve "vault" is a
+    // wallet somebody holds the key to.
+    for (const [label, addr] of [
+      ['task', input.accounts.task],
+      ['vault', input.accounts.vault],
+    ] as const) {
+      if (PublicKey.isOnCurve(new PublicKey(addr).toBytes())) {
+        problems.push(`${label} ${addr} is not a program-derived address — someone holds its key`);
+      }
+    }
+  } catch {
+    problems.push('task or vault is not a valid address');
+  }
+
+  // ---- the parameters --------------------------------------------------------------------------
+  const d = input.declared;
+  const e = input.expected;
+  if (!eqAmount(d.budget, e.budget_raw)) {
+    problems.push(`budget is ${d.budget}, expected ${e.budget_raw}`);
+  }
+  if (!eqAmount(d.base_pool, e.base_pool_raw)) {
+    problems.push(`base_pool is ${d.base_pool}, expected ${e.base_pool_raw}`);
+  }
+  if (d.lottery_winner_count !== e.lottery_winner_count) {
+    problems.push(
+      `lottery_winner_count is ${d.lottery_winner_count}, expected ${e.lottery_winner_count}`,
+    );
+  }
+  if (!eqAmount(d.lottery_prize_per_winner, e.lottery_prize_per_winner_raw)) {
+    problems.push(
+      `lottery_prize_per_winner is ${d.lottery_prize_per_winner}, expected ${e.lottery_prize_per_winner_raw}`,
+    );
+  }
+  if (!eqAmount(d.qualify_deadline, String(e.qualify_deadline))) {
+    problems.push(`qualify_deadline is ${d.qualify_deadline}, expected ${e.qualify_deadline}`);
+  }
+  if (!eqAmount(d.settlement_deadline, String(e.settlement_deadline))) {
+    problems.push(
+      `settlement_deadline is ${d.settlement_deadline}, expected ${e.settlement_deadline}`,
+    );
+  }
+  if (!/^[0-9a-f]{64}$/i.test(d.seed_commit)) {
+    problems.push(`seed_commit is not 32 bytes of hex: ${d.seed_commit}`);
+  }
+
+  // ---- the declared parameters must match the bytes actually being signed ----------------------
+  // The strongest check here. Everything above compares the backend's own JSON description against
+  // the agent's expectations; this compares that description against the instruction data itself, so
+  // a backend cannot quote correct parameters and encode different ones.
+  const data = ix?.data ?? Buffer.alloc(0);
+  if (data.length !== 8 + 8 + 8 + 4 + 8 + 8 + 8 + 32) {
+    problems.push(
+      `instruction data is ${data.length} bytes, expected 84 for create_task — ` +
+        'this is not the instruction it claims to be',
+    );
+  } else {
+    const encoded = {
+      budget: data.readBigUInt64LE(8).toString(),
+      base_pool: data.readBigUInt64LE(16).toString(),
+      lottery_winner_count: data.readUInt32LE(24),
+      lottery_prize_per_winner: data.readBigUInt64LE(28).toString(),
+      qualify_deadline: data.readBigInt64LE(36).toString(),
+      settlement_deadline: data.readBigInt64LE(44).toString(),
+      seed_commit: data.subarray(52, 84).toString('hex'),
+    };
+    for (const key of Object.keys(encoded) as Array<keyof typeof encoded>) {
+      const inBytes = String(encoded[key]);
+      const quoted = String((d as unknown as Record<string, unknown>)[key]);
+      const same =
+        key === 'seed_commit' || key === 'lottery_winner_count'
+          ? inBytes.toLowerCase() === quoted.toLowerCase()
+          : eqAmount(inBytes, quoted);
+      if (!same) {
+        problems.push(
+          `the transaction encodes ${key}=${inBytes} but the response quoted ${quoted} — ` +
+            'the backend described one thing and built another',
+        );
+      }
+    }
+  }
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    summary: {
+      program_id: programId,
+      instruction_count: tx.instructions.length,
+      signers,
+      budget: d.budget,
+      mint: input.accounts.mint,
+      task: input.accounts.task,
+    },
+  };
+}