@projectsolo/solo-mission-mcp 0.21.14 → 0.22.0

package/src/solana/verify.ts

@@ -1,11 +1,10 @@
 /**
  * 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.
+ * WHY THIS IS MANDATORY, NOT DEFENSIVE. An agent that built the funding instruction itself from
+ * published parameters could check every field before signing. Solana funding instead 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
@@ -13,12 +12,24 @@
  * 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.
+ * WHAT THIS DOES AND DOES NOT PROVE. It decodes the instruction data and compares every field with
+ * the agent's own expectations, and it checks every account the instruction touches, by position,
+ * against addresses it derives itself. So it catches a backend that quoted one budget and built
+ * another, a substituted mint, a redirected vault, a raised fee ceiling, a co-signer that is not
+ * the program's Operator, 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.
+ *
+ * ESCROW INTERFACE v2 ONLY (solo-escrow-solana u1.1.0, `main` 4376bac). Relative to v1:
+ *   - `create_task` data gains a trailing `max_fee_bps: u16` (N-2). It must equal the fee rate
+ *     the agent was quoted, so the platform cannot raise the fee between quote and execution.
+ *   - The accounts gain an optional `operator` signer after `system_program` (SE-02). It is the
+ *     program id — Anchor's `None` — for a non-lottery task, and the Operator, as a signer, for a
+ *     lottery task. A lottery transaction arrives already co-signed by the Operator; this checks
+ *     that the co-signer is the on-chain `Config.operator` and that its ed25519 signature is valid
+ *     over the exact message the agent is about to sign.
+ * A deployment reporting any other interface is refused rather than decoded against the wrong
+ * layout.
  *
  * 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,
@@ -26,8 +37,60 @@
  * 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 {
+import { createHash } from 'crypto';
+import {
+  base58Decode,
+  base58Encode,
+  ed25519Verify,
+  isEmptySignature,
+  isSignerIndex,
+  isWritableIndex,
+  parseWireTransaction,
+  type WireTransaction,
+} from './wire.js';
+
+/** The only program interface this verifier decodes. */
+export const SUPPORTED_ESCROW_INTERFACE = 'v2';
+
+/**
+ * Discriminators from solo-escrow-solana u1.1.0 `idl/solo_escrow.json`. Byte-checked against the
+ * vendored IDL excerpt in `verify.test.ts`.
+ */
+export const DISCRIMINATORS = {
+  create_task: [194, 80, 6, 180, 232, 127, 48, 171],
+  cancel_task: [69, 228, 134, 187, 134, 105, 238, 48],
+  emergency_refund: [188, 73, 52, 195, 137, 70, 180, 147],
+  claim_refund: [15, 16, 30, 161, 255, 228, 97, 60],
+  /** The `Config` ACCOUNT discriminator (first 8 bytes of its data). */
+  Config: [155, 12, 170, 224, 30, 250, 204, 130],
+} as const;
+
+/** `create_task`'s accounts in IDL order (v2). The instruction must list exactly these. */
+export const CREATE_TASK_V2_ACCOUNTS = [
+  'sponsor',
+  'config',
+  'whitelist',
+  'mint',
+  'task',
+  'vault',
+  'sponsor_token_account',
+  'token_program',
+  'system_program',
+  'operator',
+  'event_authority',
+  'program',
+] as const;
+
+/** 8 discriminator | budget u64 | base_pool u64 | lottery_winner_count u32
+ *  | lottery_prize_per_winner u64 | qualify_deadline i64 | settlement_deadline i64
+ *  | seed_commit [u8; 32] | max_fee_bps u16 */
+export const CREATE_TASK_V2_DATA_LENGTH = 8 + 8 + 8 + 4 + 8 + 8 + 8 + 32 + 2;
+
+export const TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+export const SYSTEM_PROGRAM_ID = '11111111111111111111111111111111';
+
+/** What the backend says the transaction encodes (`declared` in the funding response). */
+export interface DeclaredFunding {
   /** 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;
@@ -38,6 +101,10 @@ export interface ExpectedFunding {
   settlement_deadline: string;
   /** 64 hex chars, no 0x. */
   seed_commit: string;
+  /** v2: the fee ceiling encoded as `create_task`'s `max_fee_bps`. */
+  max_fee_bps?: number;
+  /** v2: whether the platform Operator co-signed (lottery tasks only). */
+  operator_cosigned?: boolean;
 }
 
 export interface FundingAccounts {
@@ -51,10 +118,29 @@ export interface FundingAccounts {
   sponsor_token_account: string;
 }
 
+/** The escrow program's `Config` account, as read from chain. */
+export interface EscrowConfigState {
+  address: string;
+  admin: string;
+  operator: string;
+  guardian: string;
+  treasury: string;
+  fee_bps: number;
+  min_review_window: number;
+  paused: boolean;
+  task_counter: string;
+}
+
 export interface VerifyInput {
   transaction_base64: string;
-  declared: ExpectedFunding;
+  /** `escrow_interface` from the funding response. Anything but 'v2' is refused. */
+  escrow_interface: string | undefined;
+  /** `task_id` from the funding response; the task and vault PDAs are derived from it. */
+  task_id: string;
+  declared: DeclaredFunding;
   accounts: FundingAccounts;
+  /** v2 lottery: the hash of the co-signed message, as the backend recorded it. */
+  message_sha256?: string;
   /** What the agent asked for, independent of what the backend replied. */
   expected: {
     budget_raw: string;
@@ -63,29 +149,206 @@ export interface VerifyInput {
     lottery_prize_per_winner_raw: string;
     qualify_deadline: number;
     settlement_deadline: number;
+    /** Hex, with or without 0x. Optional: compared when known. */
+    seed_commit?: string;
+    /** The fee rate the agent was quoted (create_mission's `solana_quoted_fee_bps`). */
+    max_fee_bps: number | undefined;
     mint: string;
     sponsor: string;
+    /** The token account the agent asked the budget to be taken from. */
+    sponsor_token_account: 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;
+  /** `Config` read from chain (`readEscrowConfig`), or null when the read failed. Needed to check a
+   *  lottery co-signer; a non-lottery transaction does not depend on it. */
+  onchain_config: EscrowConfigState | null;
+  onchain_config_error?: string;
 }
 
 export interface VerifyResult {
   ok: boolean;
   /** Every discrepancy found, not just the first — an agent debugging this wants the whole list. */
   problems: string[];
+  /** Not a reason to refuse, but likely to make the transaction fail on chain. */
+  warnings: string[];
   /** What the transaction actually contains, for logging even on success. */
   summary: {
+    escrow_interface: string | undefined;
     program_id: string;
     instruction_count: number;
     signers: string[];
+    fee_payer: string | null;
     budget: string;
     mint: string;
     task: string;
+    lottery: boolean;
+    max_fee_bps: number | null;
+    operator: string | null;
+    operator_signature: 'valid' | 'invalid' | 'missing' | 'not_required';
+    message_sha256: string | null;
+  };
+}
+
+/** The fields of a v2 `create_task` instruction, decoded. */
+export interface CreateTaskV2Fields {
+  budget: string;
+  base_pool: string;
+  lottery_winner_count: number;
+  lottery_prize_per_winner: string;
+  qualify_deadline: string;
+  settlement_deadline: string;
+  seed_commit: string;
+  max_fee_bps: number;
+}
+
+/** Decodes v2 `create_task` instruction data. Throws if it is not exactly that instruction. */
+export function decodeCreateTaskV2(data: Buffer): CreateTaskV2Fields {
+  if (!data.subarray(0, 8).equals(Buffer.from(DISCRIMINATORS.create_task))) {
+    throw new Error(
+      `instruction discriminator is ${data.subarray(0, 8).toString('hex')}, not create_task's ` +
+        Buffer.from(DISCRIMINATORS.create_task).toString('hex'),
+    );
+  }
+  if (data.length !== CREATE_TASK_V2_DATA_LENGTH) {
+    throw new Error(
+      `create_task data is ${data.length} bytes, expected ${CREATE_TASK_V2_DATA_LENGTH} for the v2 ` +
+        'interface' +
+        (data.length === CREATE_TASK_V2_DATA_LENGTH - 2 ? ' (84 bytes is the v1 layout, without max_fee_bps)' : ''),
+    );
+  }
+  return {
+    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'),
+    max_fee_bps: data.readUInt16LE(84),
+  };
+}
+
+/**
+ * Decodes the escrow `Config` account:
+ *   8 discriminator | admin 32 | operator 32 | guardian 32 | treasury 32 | fee_bps u16 (136)
+ *   | min_review_window i64 (138) | paused bool (146) | task_counter u64 (147)
+ */
+export function decodeEscrowConfig(data: Buffer, address: string): EscrowConfigState {
+  if (data.length < 155) throw new Error(`Config account is ${data.length} bytes, too short`);
+  if (!data.subarray(0, 8).equals(Buffer.from(DISCRIMINATORS.Config))) {
+    throw new Error('account at the Config address does not carry the Config discriminator');
+  }
+  const key = (o: number) => base58Encode(data.subarray(o, o + 32));
+  return {
+    address,
+    admin: key(8),
+    operator: key(40),
+    guardian: key(72),
+    treasury: key(104),
+    fee_bps: data.readUInt16LE(136),
+    min_review_window: Number(data.readBigInt64LE(138)),
+    paused: data[146] !== 0,
+    task_counter: data.readBigUInt64LE(147).toString(),
   };
 }
 
+/** The Config PDA, `[b"config"]` under the program. */
+export async function configAddress(programId: string): Promise<string> {
+  const { PublicKey } = await import('@solana/web3.js');
+  return PublicKey.findProgramAddressSync([Buffer.from('config')], new PublicKey(programId))[0].toBase58();
+}
+
+interface RpcAccount {
+  owner: string;
+  data: [string, string];
+}
+
+/**
+ * `getAccountInfo` (base64, confirmed). Public RPC endpoints rate-limit hard (devnet answers
+ * "Connection rate limits exceeded"), and a transient failure would refuse a legitimate funding, so
+ * rate limits, 5xx and network errors are retried — and nothing else.
+ */
+async function getAccountInfo(
+  rpcUrl: string,
+  address: string,
+  { attempts = 3, backoffMs = 500 }: { attempts?: number; backoffMs?: number } = {},
+): Promise<RpcAccount | null> {
+  type RpcBody = { result?: { value: RpcAccount | null }; error?: { message: string } };
+  let lastError = '';
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const res = await fetch(rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'getAccountInfo',
+          params: [address, { encoding: 'base64', commitment: 'confirmed' }],
+        }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      if (res.status === 429 || res.status >= 500) {
+        lastError = `HTTP ${res.status}`;
+      } else {
+        const body = (await res.json()) as RpcBody;
+        if (!body.error) return body.result?.value ?? null;
+        if (!/rate limit|too many/i.test(body.error.message)) {
+          throw new Error(`RPC getAccountInfo(${address}) failed: ${body.error.message}`);
+        }
+        lastError = body.error.message;
+      }
+    } catch (e) {
+      if ((e as Error).message.startsWith('RPC getAccountInfo')) throw e;
+      lastError = (e as Error).message;
+    }
+    if (attempt < attempts) await new Promise((r) => setTimeout(r, backoffMs * attempt));
+  }
+  throw new Error(`RPC getAccountInfo(${address}) failed: ${lastError}`);
+}
+
+/**
+ * Reads the escrow `Config` straight from the cluster. The address is derived here from the pinned
+ * program id — never taken from the backend — and the account must be owned by that program.
+ */
+export async function readEscrowConfig(
+  rpcUrl: string,
+  programId: string,
+  opts: { attempts?: number; backoffMs?: number } = {},
+): Promise<EscrowConfigState> {
+  const address = await configAddress(programId);
+  const value = await getAccountInfo(rpcUrl, address, opts);
+  if (!value) throw new Error(`Config account ${address} does not exist on this cluster`);
+  if (value.owner !== programId) {
+    throw new Error(`Config account ${address} is owned by ${value.owner}, not the program ${programId}`);
+  }
+  return decodeEscrowConfig(Buffer.from(value.data[0], 'base64'), address);
+}
+
+/**
+ * A mint's decimals, read from the SPL Token mint account (82 bytes; `decimals` at 44,
+ * `is_initialized` at 45). `expected_budget` is scaled by this, so it must not come from the API:
+ * a reported 9 for a 6-decimal mint would make an agent that meant 10 approve 10,000.
+ */
+export async function readMintDecimals(
+  rpcUrl: string,
+  mint: string,
+  opts: { attempts?: number; backoffMs?: number } = {},
+): Promise<number> {
+  const value = await getAccountInfo(rpcUrl, mint, opts);
+  if (!value) throw new Error(`mint ${mint} does not exist on this cluster`);
+  if (value.owner !== TOKEN_PROGRAM_ID) {
+    throw new Error(`mint ${mint} is owned by ${value.owner}, not the SPL Token program`);
+  }
+  const data = Buffer.from(value.data[0], 'base64');
+  if (data.length !== 82 || data[45] !== 1) {
+    throw new Error(`account ${mint} is not an initialized SPL Token mint`);
+  }
+  return data[44];
+}
+
 const eqAmount = (a: string, b: string): boolean => {
   try {
     return BigInt(a) === BigInt(b);
@@ -94,17 +357,57 @@ const eqAmount = (a: string, b: string): boolean => {
   }
 };
 
+const hex = (s: string | undefined) => String(s ?? '').replace(/^0x/i, '').toLowerCase();
+
 /**
- * Verifies a funding transaction. Returns every problem rather than throwing on the first.
+ * Verifies a v2 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 { PublicKey } = await import('@solana/web3.js');
   const problems: string[] = [];
+  const warnings: string[] = [];
+  const e = input.expected;
+  const d = input.declared;
+  const expectLottery = e.lottery_winner_count > 0;
 
-  const tx = Transaction.from(Buffer.from(input.transaction_base64, 'base64'));
+  const summary: VerifyResult['summary'] = {
+    escrow_interface: input.escrow_interface,
+    program_id: '(none)',
+    instruction_count: 0,
+    signers: [],
+    fee_payer: null,
+    budget: d.budget,
+    mint: input.accounts.mint,
+    task: input.accounts.task,
+    lottery: expectLottery,
+    max_fee_bps: null,
+    operator: null,
+    operator_signature: expectLottery ? 'missing' : 'not_required',
+    message_sha256: null,
+  };
+  const done = (): VerifyResult => ({ ok: problems.length === 0, problems, warnings, summary });
+
+  if (input.escrow_interface !== SUPPORTED_ESCROW_INTERFACE) {
+    problems.push(
+      `the funding response reports escrow_interface ${JSON.stringify(input.escrow_interface)}; this ` +
+        `verifier decodes only the ${SUPPORTED_ESCROW_INTERFACE} create_task layout`,
+    );
+  }
+
+  let tx: WireTransaction;
+  try {
+    tx = parseWireTransaction(Buffer.from(input.transaction_base64, 'base64'));
+  } catch (err) {
+    problems.push(`the transaction does not decode: ${(err as Error).message}`);
+    return done();
+  }
+  summary.instruction_count = tx.instructions.length;
+  summary.signers = tx.accountKeys.slice(0, tx.header.numRequiredSignatures);
+  summary.fee_payer = tx.accountKeys[0] ?? null;
+  summary.message_sha256 = createHash('sha256').update(tx.message).digest('hex');
 
   // ---- structure ------------------------------------------------------------------------------
   // Exactly one instruction. An extra one is the cheapest way to hide something — a token transfer
@@ -115,9 +418,9 @@ export async function verifyFundingTransaction(input: VerifyInput): Promise<Veri
         'additional instructions would be authorised by the same signature',
     );
   }
-
   const ix = tx.instructions[0];
-  const programId = ix?.programId?.toBase58() ?? '(none)';
+  const programId = ix ? tx.accountKeys[ix.programIdIndex] : '(none)';
+  summary.program_id = programId;
   if (programId !== input.expected_program_id) {
     problems.push(`program is ${programId}, expected ${input.expected_program_id}`);
   }
@@ -128,63 +431,206 @@ export async function verifyFundingTransaction(input: VerifyInput): Promise<Veri
     );
   }
 
-  // ---- 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) {
+  if (
+    input.message_sha256 !== undefined &&
+    input.message_sha256.toLowerCase() !== summary.message_sha256
+  ) {
     problems.push(
-      `expected the sponsor ${input.expected.sponsor} to be the only signer, found [${signers.join(', ')}]`,
+      `the response's message_sha256 ${input.message_sha256} is not the hash of this transaction's ` +
+        `message (${summary.message_sha256}) — confirm-funding would not recognise it`,
     );
   }
-  if (tx.feePayer?.toBase58() !== input.expected.sponsor) {
+
+  // ---- the parameters in the bytes -------------------------------------------------------------
+  let encoded: CreateTaskV2Fields | null = null;
+  try {
+    encoded = decodeCreateTaskV2(ix?.data ?? Buffer.alloc(0));
+    summary.max_fee_bps = encoded.max_fee_bps;
+    summary.lottery = encoded.lottery_winner_count > 0;
+  } catch (err) {
+    problems.push(`${(err as Error).message} — this is not the instruction it claims to be`);
+  }
+
+  // ---- accounts, by position -------------------------------------------------------------------
+  // Derived here from the pinned program id, never taken from the backend's `accounts` block.
+  const program = new PublicKey(input.expected_program_id);
+  const pda = (...seeds: Buffer[]) => PublicKey.findProgramAddressSync(seeds, program)[0].toBase58();
+  let taskId: bigint | null = null;
+  try {
+    taskId = BigInt(input.task_id);
+    if (taskId < 0n || taskId > 0xffffffffffffffffn) throw new Error('out of range');
+  } catch {
+    problems.push(`task_id ${JSON.stringify(input.task_id)} is not a u64`);
+    taskId = null;
+  }
+  const u64le = (v: bigint) => {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(v);
+    return b;
+  };
+  let mintKey: Buffer | null = null;
+  try {
+    mintKey = base58Decode(e.mint);
+    if (mintKey.length !== 32) mintKey = null;
+  } catch {
+    mintKey = null;
+  }
+  if (!mintKey) problems.push(`expected mint ${e.mint} is not a valid address`);
+
+  const operatorSlot = CREATE_TASK_V2_ACCOUNTS.indexOf('operator');
+  const want: Record<(typeof CREATE_TASK_V2_ACCOUNTS)[number], string | null> = {
+    sponsor: e.sponsor,
+    config: pda(Buffer.from('config')),
+    whitelist: mintKey ? pda(Buffer.from('whitelist'), mintKey) : null,
+    mint: e.mint,
+    task: taskId !== null ? pda(Buffer.from('task'), u64le(taskId)) : null,
+    vault: taskId !== null ? pda(Buffer.from('vault'), u64le(taskId)) : null,
+    sponsor_token_account: e.sponsor_token_account,
+    token_program: TOKEN_PROGRAM_ID,
+    system_program: SYSTEM_PROGRAM_ID,
+    operator: null, // checked below: depends on lottery vs not
+    event_authority: pda(Buffer.from('__event_authority')),
+    program: input.expected_program_id,
+  };
+
+  const ixKeys = (ix?.accountIndexes ?? []).map((i) => tx.accountKeys[i]);
+  if (ix && ixKeys.length !== CREATE_TASK_V2_ACCOUNTS.length) {
     problems.push(
-      `fee payer is ${tx.feePayer?.toBase58() ?? '(unset)'}, expected ${input.expected.sponsor}`,
+      `create_task lists ${ixKeys.length} accounts, expected ${CREATE_TASK_V2_ACCOUNTS.length} ` +
+        `(${CREATE_TASK_V2_ACCOUNTS.join(', ')})`,
     );
+  } else if (ix) {
+    CREATE_TASK_V2_ACCOUNTS.forEach((name, i) => {
+      const expectedKey = want[name];
+      if (expectedKey !== null && ixKeys[i] !== expectedKey) {
+        problems.push(`account #${i} (${name}) is ${ixKeys[i]}, expected ${expectedKey}`);
+      }
+    });
+    if (!isSignerIndex(tx, ix.accountIndexes[0]) || !isWritableIndex(tx, ix.accountIndexes[0])) {
+      problems.push('the sponsor account is not a writable signer');
+    }
   }
 
-  // ---- 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],
+  // The backend's own description of the accounts must agree with what the bytes say.
+  for (const [label, quoted, derived] of [
+    ['task', input.accounts.task, want.task],
+    ['vault', input.accounts.vault, want.vault],
+    ['config', input.accounts.config, want.config],
+    ['whitelist', input.accounts.whitelist, want.whitelist],
   ] as const) {
-    if (!keyList.includes(expected)) {
-      problems.push(`${label} ${expected} does not appear in the transaction's accounts`);
+    if (derived !== null && quoted !== derived) {
+      problems.push(
+        `quoted ${label} ${quoted} is not the program-derived address ${derived} — ` +
+          'an address that is not the PDA may be a wallet somebody holds the key to',
+      );
     }
   }
-  if (input.accounts.mint !== input.expected.mint) {
-    problems.push(`quoted mint ${input.accounts.mint}, expected ${input.expected.mint}`);
+  if (input.accounts.mint !== e.mint) {
+    problems.push(`quoted mint ${input.accounts.mint}, expected ${e.mint}`);
+  }
+  if (input.accounts.sponsor !== e.sponsor) {
+    problems.push(`quoted sponsor ${input.accounts.sponsor}, expected ${e.sponsor}`);
   }
-  // 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.sponsor_token_account !== e.sponsor_token_account) {
+    problems.push(
+      `quoted sponsor_token_account ${input.accounts.sponsor_token_account}, expected ${e.sponsor_token_account}`,
+    );
+  }
+  // A vault equal to the sponsor's own token account would mean the budget never leaves their
+  // control — funded on paper, not escrowed.
   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`);
+
+  // ---- fee payer and signers -------------------------------------------------------------------
+  // The sponsor pays the fee and the rent. The Operator co-signs a lottery but must never be the
+  // fee payer: that would make the platform the payer of record for the sponsor's escrow.
+  const feePayer = tx.accountKeys[0];
+  if (feePayer !== e.sponsor) {
+    const who =
+      input.onchain_config && feePayer === input.onchain_config.operator ? ' (the Operator)' : '';
+    problems.push(`fee payer is ${feePayer ?? '(unset)'}${who}, expected the sponsor ${e.sponsor}`);
+  }
+
+  const operatorKey = ix && ixKeys.length === CREATE_TASK_V2_ACCOUNTS.length ? ixKeys[operatorSlot] : undefined;
+  const operatorIndex = ix?.accountIndexes[operatorSlot];
+  const signers = summary.signers;
+
+  if (d.operator_cosigned !== undefined && d.operator_cosigned !== expectLottery) {
+    problems.push(
+      `the response says operator_cosigned=${d.operator_cosigned}, but this is ` +
+        (expectLottery ? 'a lottery task, which must be co-signed' : 'not a lottery task, which must not be'),
+    );
+  }
+
+  if (!expectLottery) {
+    // Anchor's None for the optional operator is the program id itself, which cannot sign.
+    if (operatorKey !== undefined && operatorKey !== input.expected_program_id) {
+      problems.push(
+        `the operator slot holds ${operatorKey}; a non-lottery create_task must pass the program id ` +
+          `${input.expected_program_id} (no co-signer)`,
+      );
+    }
+    if (signers.length !== 1 || signers[0] !== e.sponsor) {
+      problems.push(
+        `expected the sponsor ${e.sponsor} to be the only signer, found [${signers.join(', ')}]`,
+      );
+    }
+  } else {
+    summary.operator = operatorKey ?? null;
+    const cfg = input.onchain_config;
+    if (!cfg) {
+      problems.push(
+        'cannot check the lottery co-signer: the on-chain Config.operator could not be read' +
+          (input.onchain_config_error ? ` (${input.onchain_config_error})` : ''),
+      );
+    } else if (operatorKey !== cfg.operator) {
+      problems.push(
+        `the co-signer in the operator slot is ${operatorKey ?? '(none)'}, but the on-chain ` +
+          `Config.operator is ${cfg.operator}`,
+      );
+    }
+    if (operatorKey !== undefined && operatorKey === e.sponsor) {
+      problems.push('the operator slot holds the sponsor itself — the co-signature would be the agent\'s own');
+    }
+    const expectedSigners = operatorKey ? [e.sponsor, operatorKey] : [e.sponsor];
+    if (signers.length !== 2 || signers[0] !== expectedSigners[0] || signers[1] !== expectedSigners[1]) {
+      problems.push(
+        `expected exactly two signers, the sponsor ${e.sponsor} (fee payer) and the Operator ` +
+          `${operatorKey ?? '(none)'}, found [${signers.join(', ')}]`,
+      );
+    }
+    if (operatorIndex === undefined || !isSignerIndex(tx, operatorIndex)) {
+      problems.push('the operator slot is not a signer — a lottery create_task needs the Operator to sign');
+      summary.operator_signature = 'missing';
+    } else {
+      const sig = tx.signatures[operatorIndex];
+      if (isEmptySignature(sig)) {
+        summary.operator_signature = 'missing';
+        problems.push(
+          'the Operator co-signature is missing — a lottery create_task without it fails on chain ' +
+            '(LotteryRequiresOperator), and an agent-added signature cannot fix that',
+        );
+      } else if (!ed25519Verify(sig, tx.message, operatorKey as string)) {
+        summary.operator_signature = 'invalid';
+        problems.push(
+          'the Operator signature does not verify over this message — the transaction was altered ' +
+            'after it was co-signed, or the signature is not the Operator\'s',
+        );
+      } else {
+        summary.operator_signature = 'valid';
       }
     }
-  } 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) {
+  if (Number(d.lottery_winner_count) !== e.lottery_winner_count) {
     problems.push(
       `lottery_winner_count is ${d.lottery_winner_count}, expected ${e.lottery_winner_count}`,
     );
@@ -204,35 +650,35 @@ export async function verifyFundingTransaction(input: VerifyInput): Promise<Veri
   }
   if (!/^[0-9a-f]{64}$/i.test(d.seed_commit)) {
     problems.push(`seed_commit is not 32 bytes of hex: ${d.seed_commit}`);
+  } else if (e.seed_commit !== undefined && hex(d.seed_commit) !== hex(e.seed_commit)) {
+    problems.push(`seed_commit is ${d.seed_commit}, expected ${hex(e.seed_commit)}`);
+  }
+  // N-2: the ceiling must be exactly the quote. A higher one lets the fee rise before the
+  // transaction lands; a lower one would fail on chain for no reason the agent caused.
+  if (typeof e.max_fee_bps !== 'number' || !Number.isInteger(e.max_fee_bps)) {
+    problems.push('no quoted fee rate to check max_fee_bps against — refusing to sign an unchecked fee ceiling');
+  } else if (d.max_fee_bps === undefined) {
+    problems.push('the funding response does not declare max_fee_bps — not a v2 funding transaction');
+  } else if (Number(d.max_fee_bps) !== e.max_fee_bps) {
+    problems.push(`max_fee_bps is ${d.max_fee_bps}, expected the quoted fee rate ${e.max_fee_bps}`);
   }
 
   // ---- 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>) {
+  if (encoded) {
+    for (const key of Object.keys(encoded) as Array<keyof CreateTaskV2Fields>) {
       const inBytes = String(encoded[key]);
-      const quoted = String((d as unknown as Record<string, unknown>)[key]);
+      const quotedRaw = (d as unknown as Record<string, unknown>)[key];
+      if (quotedRaw === undefined) continue; // reported above
+      const quoted = String(quotedRaw);
       const same =
-        key === 'seed_commit' || key === 'lottery_winner_count'
-          ? inBytes.toLowerCase() === quoted.toLowerCase()
-          : eqAmount(inBytes, quoted);
+        key === 'seed_commit'
+          ? inBytes === hex(quoted)
+          : key === 'lottery_winner_count' || key === 'max_fee_bps'
+            ? Number(inBytes) === Number(quoted)
+            : eqAmount(inBytes, quoted);
       if (!same) {
         problems.push(
           `the transaction encodes ${key}=${inBytes} but the response quoted ${quoted} — ` +
@@ -240,18 +686,33 @@ export async function verifyFundingTransaction(input: VerifyInput): Promise<Veri
         );
       }
     }
+    if (typeof e.max_fee_bps === 'number' && encoded.max_fee_bps !== e.max_fee_bps) {
+      problems.push(
+        `the transaction encodes max_fee_bps=${encoded.max_fee_bps}, not the quoted fee rate ${e.max_fee_bps}`,
+      );
+    }
+    if ((encoded.lottery_winner_count > 0) !== expectLottery) {
+      problems.push(
+        `the transaction encodes lottery_winner_count=${encoded.lottery_winner_count}, ` +
+          `expected ${e.lottery_winner_count}`,
+      );
+    }
   }
 
-  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,
-    },
-  };
+  // ---- courtesy: things the program would reject anyway ---------------------------------------
+  const cfg = input.onchain_config;
+  if (cfg && encoded) {
+    if (cfg.fee_bps > encoded.max_fee_bps) {
+      warnings.push(
+        `the program's fee is now ${cfg.fee_bps} bps, above this transaction's max_fee_bps ` +
+          `${encoded.max_fee_bps}: create_task will fail with FeeAboveSponsorMax (6132). Cancel the ` +
+          'mission and create a new one to get a fresh quote.',
+      );
+    }
+    if (cfg.paused) {
+      warnings.push('the escrow program is paused: create_task will fail until it is unpaused.');
+    }
+  }
+
+  return done();
 }