@projectsolo/solo-mission-mcp 0.21.13 → 0.22.0

package/src/tools/solana.ts

@@ -1,13 +1,9 @@
 /**
- * Solana funding tools.
+ * Solana funding tools — the only on-chain path this package exposes.
  *
- * Originally additive: every existing tool behaved identically, `create_mission` without `chain`
- * still created a Base mission, and an agent that never touched Solana needed no wallet configured.
- * That is no longer true as of the private-beta migration to Solana — the backend now returns 503
- * for any on-chain mission that resolves to `chain: 'base'`, including the pre-Solana default of
- * omitting `chain` entirely. An agent that wants a paid/on-chain mission must pass `chain: 'solana'`
- * explicitly and configure a wallet; only free off-chain missions (no `budget`) work with no chain
- * configuration at all. See create_mission's own description for the current, authoritative state.
+ * A paid mission (one with a `budget`) is escrowed on Solana: `create_mission` always sends
+ * `chain: 'solana'` for it, and funding or refunding it needs a wallet configured here. Free
+ * off-chain missions (no `budget`) need no wallet and no chain configuration at all.
  *
  * 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
@@ -21,13 +17,13 @@ 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.',
+      'Read the Solana escrow deployment: program id, cluster, RPC endpoint, accepted mints and their decimals, the minimum first payout, and escrow_interface — the program interface funding transactions use. This server verifies only escrow_interface \'v2\' and refuses to fund against anything else. 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.",
+      "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 is easy to miss. 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: {
@@ -42,11 +38,11 @@ export const solanaTools: Tool[] = [
   {
     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.",
+      "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 or deadline, an extra instruction, an account that is not the program-derived address, a raised fee ceiling, a lottery co-signer that is not the program's Operator — and returns the discrepancies instead.\n\nThe escrow program id is pinned in this package per cluster (SOLO_SOLANA_PROGRAM_ID can pin another) and the API's program_id must match it; the mint's decimals, which scale expected_budget, are read from chain.\n\nEscrow interface v2 (the only one this server verifies; get_solana_config reports it):\n- max_fee_bps: create_task carries the highest platform fee the escrow may take. It must equal the fee rate create_mission quoted you (mission.solana_quoted_fee_bps). If the program's fee has risen above it by the time the transaction lands, create_task fails with FeeAboveSponsorMax instead of charging you more; cancel the mission and create a new one for a fresh quote.\n- Lottery co-signature: a mission with lottery_winner_count > 0 must be co-signed by the platform Operator, so the transaction arrives already signed by it. This tool checks that the co-signer is the Operator in the program's on-chain Config (read directly from the cluster, not from the API), that its ed25519 signature is valid over the exact message, and that you, not the Operator, pay the fee. It then adds ONLY your signature and leaves the Operator's untouched; any change to the bytes would invalidate it. A non-lottery transaction must carry no co-signer.\n\nCall create_mission with a budget first and pass that mission's id here. Fund it within 24 hours: an unfunded mission is cancelled automatically at funding_params.expires_at. A media_review mission needs at least one ready track (add_mission_track) before funding, or this returns 409 before anything is signed.",
     inputSchema: {
       type: 'object',
       properties: {
-        mission_id: { type: 'string', description: 'Mission created with chain="solana".' },
+        mission_id: { type: 'string', description: 'A paid (budget-bearing) mission from create_mission, still in pending_funding.' },
         expected_budget: {
           type: 'number',
           description:
@@ -55,7 +51,13 @@ export const solanaTools: Tool[] = [
         expected_mint: {
           type: 'string',
           description:
-            'The mint you expect the budget to be taken in. Verified before signing. Defaults to the deployment payout mint.',
+            "The mint you expect the budget to be taken in. Verified before signing. Defaults to the mint create_mission recorded for this mission (its funding_params.mint).",
+        },
+        expected_max_fee_bps: {
+          type: 'integer',
+          minimum: 0,
+          description:
+            "The platform fee rate, in basis points, that create_mission quoted you: its response's mission.solana_quoted_fee_bps. Verified against the transaction's max_fee_bps before signing. Defaults to the quote recorded on the mission.",
         },
         dry_run: {
           type: 'boolean',
@@ -69,7 +71,7 @@ export const solanaTools: Tool[] = [
   {
     name: 'refund_solana_mission',
     description:
-      "Get a Solana mission's escrowed funds back to the sponsor. Covers all three routes: cancel (while funded, before hiring closes), emergency_refund (once the settlement deadline passes and the platform has not settled), and claim_refund (leftover budget after a partial settle).\n\nSame flow as funding: the backend builds the transaction, this tool VERIFIES it, signs locally, and submits. Your key never leaves this process.\n\nCall with no action to ask what is currently available — the response lists the legal actions for the mission's state rather than guessing. Without this tool a funded Solana mission's money was unreachable except by hand-assembling an Anchor instruction, for which Solana has no `cast send` equivalent.",
+      "Get a Solana mission's escrowed funds back to the sponsor. Covers all three routes:\n- cancel: while the task is funded and strictly before qualify_deadline (the end of the hiring window). The escrow program refuses a cancel from qualify_deadline on (TooLateToCancel), even one built earlier, because by then the participants' work is done.\n- emergency_refund: once settlement_deadline has passed and the platform has not settled. It stays available after the cancel cut-off, and a pause does not block it.\n- claim_refund: leftover budget after a settle (mission status refundable).\n\nSame flow as funding: the backend builds the transaction, this tool VERIFIES it, signs locally, and submits. Your key never leaves this process.\n\nCall with no action to ask what is currently available — the response lists the legal actions for the mission's state rather than guessing. If the backend or the chain rejects an action, the response says which one did, names the program error, and lists the actions that remain.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -113,26 +115,64 @@ export function toRawAmount(amount: number, decimals: number): string {
 
 export const SOLANA_TOOL_NAMES = new Set(solanaTools.map((t) => t.name));
 
+interface SolanaConfigResponse {
+  cluster?: string;
+  program_id: string;
+  rpc_url: string;
+  mints: Record<string, string>;
+  decimals: Record<string, number>;
+  escrow_interface?: string;
+}
+
+/** The mission fields the Solana tools read, as `GET /agent/missions/:id` returns them. */
+interface SolanaMissionRecord {
+  token_address?: string;
+  onchain_status?: string;
+  qualify_deadline?: number;
+  settlement_deadline?: number;
+  lottery_winner_count?: number;
+  lottery_prize_per_winner_raw?: string;
+  seed_commit?: string;
+  solana_quoted_fee_bps?: number;
+}
+
+/** The body of an API error (`ApiResponseError.data`), with the shapes other clients use kept. */
+function apiErrorBody(e: any): { message?: string; available_actions?: string[]; [k: string]: unknown } {
+  return e?.data ?? e?.response?.data ?? e?.body ?? {};
+}
+
+const CANCEL_CUTOFF_RULE =
+  'cancel is refused on chain from qualify_deadline on (TooLateToCancel, error 6125); ' +
+  'emergency_refund opens once settlement_deadline has passed without a settlement.';
+
 export async function handleSolanaTool(
   name: string,
   args: Record<string, any>,
 ): Promise<unknown> {
   const { apiGet, apiPost } = await import('../api/client.js');
+  const { resolvePinnedProgram, resolveTrustedRpc, solanaRpcUrl } = await import(
+    '../solana/deployment.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'
-      );
+      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress, KEY_STORAGE_GUIDANCE } =
+        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',
+            recommended:
+              'SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE — a keyfile ' +
+              'encrypted with `openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256`, plus a ' +
+              'separate passphrase file (chmod 600 both)',
+            alternative:
+              'SOLO_SOLANA_KEYPAIR_PATH — path to a plaintext `solana-keygen` keyfile, e.g. ' +
+              '~/.config/solana/id.json (chmod 600)',
+            key_storage: KEY_STORAGE_GUIDANCE,
           },
           what_you_need:
             'SOL for transaction fees and account rent, plus the payout token for the budget. ' +
@@ -143,11 +183,7 @@ export async function handleSolanaTool(
       }
 
       const wallet = await loadSolanaWallet();
-      const cfg = (await apiGet('/agent/solana/config')) as {
-        rpc_url: string;
-        mints: Record<string, string>;
-        decimals: Record<string, number>;
-      };
+      const cfg = (await apiGet('/agent/solana/config')) as SolanaConfigResponse;
       const symbol = Object.keys(cfg.mints)[0];
       const mint = args.mint ?? cfg.mints[symbol];
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
@@ -155,7 +191,7 @@ export async function handleSolanaTool(
       // 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, {
+        const res = await fetch(solanaRpcUrl(cfg), {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
@@ -192,17 +228,79 @@ export async function handleSolanaTool(
       const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import(
         '../solana/wallet.js'
       );
-      const { verifyFundingTransaction } = await import('../solana/verify.js');
+      const { verifyFundingTransaction, readEscrowConfig, readMintDecimals, SUPPORTED_ESCROW_INTERFACE } =
+        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 cfg = (await apiGet('/agent/solana/config')) as SolanaConfigResponse;
+
+      // Decoding against the wrong layout would compare the wrong bytes. Refuse before anything is
+      // built rather than verify a transaction this version cannot read.
+      if (cfg.escrow_interface !== SUPPORTED_ESCROW_INTERFACE) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            `the deployment reports escrow_interface ${JSON.stringify(cfg.escrow_interface)}; this ` +
+              `version of @projectsolo/solo-mission-mcp verifies only '${SUPPORTED_ESCROW_INTERFACE}' ` +
+              'funding transactions',
+          ],
+          what_this_means:
+            'Nothing was built, signed or escrowed. This server cannot decode the funding ' +
+            'transaction the deployment would build, so it will not sign one. Use a version of ' +
+            'this package that supports the reported escrow interface.',
+        };
+      }
+
+      // The program is pinned here, not taken from the API: every derived address and the
+      // co-signer check hang off it, and the API is the party being checked.
+      const pin = resolvePinnedProgram(cfg);
+      const rpc = resolveTrustedRpc(cfg);
+      if ('problem' in pin || 'problem' in rpc) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            ...('problem' in pin ? [pin.problem] : []),
+            ...('problem' in rpc ? [rpc.problem] : []),
+          ],
+          what_this_means: 'Nothing was built, signed or escrowed.',
+        };
+      }
+      const rpcUrl = rpc.rpc_url;
+
+      // The mission as create_mission recorded it — the quote the agent was shown, including the
+      // fee rate (solana_quoted_fee_bps) that max_fee_bps must equal, and the mint.
+      const { mission } = (await apiGet(`/agent/missions/${args.mission_id}`)) as {
+        mission?: SolanaMissionRecord;
       };
-      const symbol = Object.keys(cfg.mints)[0];
-      const mint = args.expected_mint ?? cfg.mints[symbol];
-      const decimals = cfg.decimals[symbol] ?? 6;
+      if (!mission) {
+        return {
+          funded: false,
+          error: `Could not read mission ${args.mission_id} — call get_mission to check it exists.`,
+        };
+      }
+
+      // The mission's own mint unless the agent names one: get_solana_config lists both USDC and
+      // TEST_USDC, and the backend can be configured to create missions in either, so the first
+      // listed mint is a guess that refuses a mission created in the other.
+      const mint: string =
+        args.expected_mint ?? mission.token_address ?? cfg.mints[Object.keys(cfg.mints)[0]];
+      // Scales expected_budget, so it is read from the mint account, not from the API.
+      let decimals: number;
+      try {
+        decimals = await readMintDecimals(rpcUrl, mint);
+      } catch (e) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            `cannot read mint ${mint}'s decimals from chain, which expected_budget is scaled by: ` +
+              (e as Error).message,
+          ],
+          what_this_means: 'Nothing was built, signed or escrowed.',
+        };
+      }
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
 
       const built = (await apiPost(
@@ -213,14 +311,43 @@ export async function handleSolanaTool(
         task_id: string;
         declared: Record<string, any>;
         accounts: Record<string, string>;
+        escrow_interface?: string;
+        message_sha256?: string;
       };
 
+      // Config straight from the cluster, at the PDA derived from the pinned program id: a lottery
+      // co-signer must be Config.operator, and the API is not the one to vouch for that.
+      let onchainConfig = null;
+      let onchainConfigError: string | undefined;
+      try {
+        onchainConfig = await readEscrowConfig(rpcUrl, pin.program_id);
+      } catch (e) {
+        onchainConfigError = (e as Error).message;
+      }
+
+      let quotedFeeBps: number | undefined;
+      let feeQuoteSource: string;
+      if (args.expected_max_fee_bps !== undefined) {
+        quotedFeeBps = Number(args.expected_max_fee_bps);
+        feeQuoteSource = 'expected_max_fee_bps argument';
+      } else if (typeof mission.solana_quoted_fee_bps === 'number') {
+        quotedFeeBps = mission.solana_quoted_fee_bps;
+        feeQuoteSource = 'mission.solana_quoted_fee_bps (the create_mission quote)';
+      } else {
+        // A mission created before quotes were recorded: the backend then quotes the live rate.
+        quotedFeeBps = onchainConfig?.fee_bps;
+        feeQuoteSource = 'on-chain Config.fee_bps (the mission has no recorded quote)';
+      }
+
       const expectedBudgetRaw = toRawAmount(args.expected_budget, decimals);
 
       const verdict = await verifyFundingTransaction({
         transaction_base64: built.transaction_base64,
+        escrow_interface: built.escrow_interface,
+        task_id: String(built.task_id),
         declared: built.declared as any,
         accounts: built.accounts as any,
+        message_sha256: built.message_sha256,
         expected: {
           budget_raw: expectedBudgetRaw,
           // base_pool is derived by the backend from reward × max_humans. The agent's check on it
@@ -228,14 +355,21 @@ export async function handleSolanaTool(
           // 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),
+          // The rest is what create_mission recorded, not what the funding response says: whether
+          // this is a lottery decides whether a co-signer is required at all.
+          lottery_winner_count: Number(mission.lottery_winner_count ?? 0),
+          lottery_prize_per_winner_raw: String(mission.lottery_prize_per_winner_raw ?? '0'),
+          qualify_deadline: Number(mission.qualify_deadline),
+          settlement_deadline: Number(mission.settlement_deadline),
+          seed_commit: mission.seed_commit,
+          max_fee_bps: quotedFeeBps,
           mint,
           sponsor: wallet.publicKey,
+          sponsor_token_account: tokenAccount,
         },
-        expected_program_id: cfg.program_id,
+        expected_program_id: pin.program_id,
+        onchain_config: onchainConfig,
+        onchain_config_error: onchainConfigError,
       });
 
       if (!verdict.ok) {
@@ -245,7 +379,9 @@ export async function handleSolanaTool(
           funded: false,
           refused_to_sign: true,
           problems: verdict.problems,
+          warnings: verdict.warnings,
           summary: verdict.summary,
+          fee_quote_source: feeQuoteSource,
           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 ' +
@@ -260,38 +396,63 @@ export async function handleSolanaTool(
           verified: true,
           task_id: built.task_id,
           summary: verdict.summary,
+          warnings: verdict.warnings,
+          fee_quote_source: feeQuoteSource,
           would_escrow: `${args.expected_budget} (${expectedBudgetRaw} raw) of ${mint}`,
         };
       }
 
+      // Adds only our signature; a lottery's Operator co-signature is carried through unchanged.
       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 },
-      );
+      let confirmed: unknown;
+      try {
+        confirmed = await apiPost(`/agent/solana/missions/${args.mission_id}/confirm-funding`, {
+          signed_transaction: signed,
+          task_id: built.task_id,
+        });
+      } catch (e: any) {
+        const { escrowErrorFromMessage } = await import('../solana/escrowErrors.js');
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        return {
+          funded: false,
+          verified: true,
+          signed: true,
+          status: e?.status,
+          message,
+          program_error: escrowErrorFromMessage(message) ?? undefined,
+          ...(body.funding_mismatch ? { funding_mismatch: body.funding_mismatch } : {}),
+          ...(body.task_id ? { task_id: body.task_id } : {}),
+        };
+      }
 
-      return { funded: true, verified: true, ...(confirmed as Record<string, unknown>) };
+      return {
+        funded: true,
+        verified: true,
+        lottery: verdict.summary.lottery,
+        operator_cosigned: verdict.summary.operator_signature === 'valid',
+        max_fee_bps: verdict.summary.max_fee_bps,
+        ...(confirmed as Record<string, unknown>),
+      };
     }
 
     case 'refund_solana_mission': {
       const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import(
         '../solana/wallet.js'
       );
+      const { escrowErrorFromMessage } = await import('../solana/escrowErrors.js');
       const wallet = await loadSolanaWallet();
-      const cfg = (await apiGet('/agent/solana/config')) as {
-        program_id: string;
-        mints: Record<string, string>;
-      };
+      const cfg = (await apiGet('/agent/solana/config')) as SolanaConfigResponse;
       // The mission's ACTUAL mint, not a guessed default — get_solana_config's mints always
       // includes both the production payout mint (USDC) and TEST_USDC, and a mission is funded
       // in exactly one of them. Guessing (the previous code preferred TEST_USDC whenever present)
       // computes the wrong associated-token-account for any mission funded in the other one, and
       // the refund/cancel/emergency-refund transaction then fails on-chain with
       // AccountNotInitialized — confirmed live against a real USDC-funded mission.
-      const mission = (await apiGet(`/agent/missions/${args.mission_id}`)) as {
-        mission?: { token_address?: string };
+      const { mission } = (await apiGet(`/agent/missions/${args.mission_id}`)) as {
+        mission?: SolanaMissionRecord;
       };
-      const mint = mission.mission?.token_address;
+      const mint = mission?.token_address;
       if (!mint) {
         return {
           refunded: false,
@@ -299,6 +460,13 @@ export async function handleSolanaTool(
         };
       }
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+      const deadlines = {
+        qualify_deadline: mission?.qualify_deadline,
+        settlement_deadline: mission?.settlement_deadline,
+        ...(mission?.qualify_deadline !== undefined
+          ? { cancel_cutoff: new Date(mission.qualify_deadline * 1000).toISOString() }
+          : {}),
+      };
 
       // No action: ask what is legal rather than guessing and getting a 409. Uses a deliberately
       // invalid action so the backend answers with available_actions for this mission's state.
@@ -314,41 +482,91 @@ export async function handleSolanaTool(
           // ApiResponseError carries the parsed body on `.data`; the other shapes are kept for
           // any client that wraps differently. Reading only the latter silently yielded an empty
           // available_actions, i.e. a false "nothing is refundable" on a mission that could cancel.
-          const body: any = e?.data ?? e?.response?.data ?? e?.body ?? {};
+          const body = apiErrorBody(e);
           return {
             available_actions: body.available_actions ?? [],
             why_not_claim_refund: body.message,
+            ...deadlines,
             note:
               (body.available_actions?.length ?? 0) === 0
-                ? 'Nothing is refundable right now. cancel needs the hiring window still open; ' +
-                  'emergency_refund needs the settlement deadline to have passed.'
-                : 'Re-run with one of available_actions.',
+                ? `Nothing is refundable right now. ${CANCEL_CUTOFF_RULE}`
+                : `Re-run with one of available_actions. ${CANCEL_CUTOFF_RULE}`,
           };
         }
       }
 
-      const built = (await apiPost(
-        `/agent/solana/missions/${args.mission_id}/refund-transaction`,
-        {
+      // The program refuses a cancel from qualify_deadline on. Checked here too, so a cancel is
+      // never signed only to be rejected on chain.
+      const nowSec = Math.floor(Date.now() / 1000);
+      if (
+        args.action === 'cancel' &&
+        typeof mission?.qualify_deadline === 'number' &&
+        nowSec >= mission.qualify_deadline
+      ) {
+        return {
+          refunded: false,
+          rejected_by: 'client',
+          action: 'cancel',
+          message:
+            `qualify_deadline (${deadlines.cancel_cutoff}) has passed by this machine's clock, so the ` +
+            'escrow program would refuse this cancel (TooLateToCancel). Nothing was built or signed.',
+          ...deadlines,
+          what_to_do: CANCEL_CUTOFF_RULE,
+        };
+      }
+
+      // The refund must be for the pinned program, not whichever one the API names.
+      const pin = resolvePinnedProgram(cfg);
+      if ('problem' in pin) {
+        return {
+          refunded: false,
+          refused_to_sign: true,
+          problems: [pin.problem],
+          what_this_means: 'Nothing was built, signed or moved.',
+        };
+      }
+
+      let built: { transaction_base64: string; task_id: string; cancel_deadline?: string };
+      try {
+        built = (await apiPost(
+          `/agent/solana/missions/${args.mission_id}/refund-transaction`,
+          {
+            action: args.action,
+            sponsor_wallet: wallet.publicKey,
+            sponsor_token_account: tokenAccount,
+          },
+        )) as { transaction_base64: string; task_id: string; cancel_deadline?: string };
+      } catch (e: any) {
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        return {
+          refunded: false,
+          rejected_by: 'backend',
           action: args.action,
-          sponsor_wallet: wallet.publicKey,
-          sponsor_token_account: tokenAccount,
-        },
-      )) as { transaction_base64: string; task_id: string };
+          status: e?.status,
+          message,
+          available_actions: body.available_actions ?? [],
+          program_error: escrowErrorFromMessage(message) ?? undefined,
+          ...deadlines,
+          what_to_do: CANCEL_CUTOFF_RULE,
+        };
+      }
 
       // Verify before signing, same rule as funding: a headless agent has no wallet UI, so an
       // unverified blob is bytes it cannot read. A refund moves the WHOLE escrow, so the checks
       // that matter are that it is our program, we are the only signer, and the tokens land in our
-      // own token account.
-      const { Transaction, PublicKey } = await import('@solana/web3.js');
+      // own token account. The three refund instructions kept their v1 layout in the v2 interface
+      // (no arguments; sponsor, config, task, vault, sponsor_token_account, token_program and the
+      // two event accounts), so these checks are unchanged.
+      const { Transaction } = await import('@solana/web3.js');
       const tx = Transaction.from(Buffer.from(built.transaction_base64, 'base64'));
       const problems: string[] = [];
       if (tx.instructions.length !== 1) {
         problems.push(`expected 1 instruction, found ${tx.instructions.length}`);
       }
       const ix = tx.instructions[0];
-      if (ix?.programId?.toBase58() !== cfg.program_id) {
-        problems.push(`program is ${ix?.programId?.toBase58()}, expected ${cfg.program_id}`);
+      if (ix?.programId?.toBase58() !== pin.program_id) {
+        problems.push(`program is ${ix?.programId?.toBase58()}, expected ${pin.program_id}`);
       }
       const signers = (ix?.keys ?? []).filter((k) => k.isSigner).map((k) => k.pubkey.toBase58());
       if (signers.length !== 1 || signers[0] !== wallet.publicKey) {
@@ -365,7 +583,6 @@ export async function handleSolanaTool(
       if ((ix?.data?.length ?? 0) !== 8) {
         problems.push(`instruction data is ${ix?.data?.length} bytes, expected 8`);
       }
-      void PublicKey;
 
       if (problems.length > 0) {
         return {
@@ -386,14 +603,36 @@ export async function handleSolanaTool(
           action: args.action,
           task_id: built.task_id,
           destination: tokenAccount,
+          ...(built.cancel_deadline ? { cancel_deadline: built.cancel_deadline } : {}),
         };
       }
 
       const signed = await signTransaction(built.transaction_base64, wallet);
-      const confirmed = await apiPost(
-        `/agent/solana/missions/${args.mission_id}/confirm-refund`,
-        { signed_transaction: signed, action: args.action },
-      );
+      let confirmed: unknown;
+      try {
+        confirmed = await apiPost(`/agent/solana/missions/${args.mission_id}/confirm-refund`, {
+          signed_transaction: signed,
+          action: args.action,
+        });
+      } catch (e: any) {
+        // The backend maps a cancel landing at or after qualify_deadline to 409 TooLateToCancel
+        // with available_actions; any other on-chain failure arrives as 400 "refund transaction
+        // failed: <RPC error>", which is where the program error code is.
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        const programError = escrowErrorFromMessage(message);
+        return {
+          refunded: false,
+          rejected_by: programError || /transaction failed/i.test(message) ? 'chain' : 'backend',
+          action: args.action,
+          status: e?.status,
+          message,
+          program_error: programError ?? undefined,
+          available_actions: body.available_actions,
+          ...deadlines,
+          what_to_do: programError?.what_to_do ?? CANCEL_CUTOFF_RULE,
+        };
+      }
       return { refunded: true, verified: true, ...(confirmed as Record<string, unknown>) };
     }
 

package/src/tools/tracks.ts

@@ -11,7 +11,7 @@ export const trackTools: Tool[] = [
       'multi-MB file as base64 in the tool call can exceed the calling agent\'s own tool-call or context limits, ' +
       'causing a silent client-side failure before any request reaches the API) OR inline as file_base64 (fine for ' +
       'small images). Exactly one of the two is required. ' +
-      'For on-chain missions, call this BEFORE confirm_funding — uploads are blocked once the mission is active. ' +
+      'For on-chain missions, call this BEFORE fund_solana_mission — uploads are blocked once the mission is active. ' +
       'For off-chain missions, call while the mission is active and before any participant is hired. ' +
       'The item becomes visible to hired participants once confirmed.',
     inputSchema: {