@projectsolo/solo-mission-mcp 0.21.13 → 0.22.0

package/src/solana/wire.ts

@@ -0,0 +1,264 @@
+/**
+ * The Solana legacy transaction wire format, decoded and signed without re-serialising anything.
+ *
+ * WHY NOT `Transaction.from(...).partialSign(...).serialize()`. web3.js rebuilds the message from
+ * its own model of the instructions and only reuses the original bytes while that model still
+ * matches. For a v2 lottery funding transaction the platform Operator has ALREADY signed the exact
+ * message; any re-compilation that reorders an account or drops a signature slot invalidates the
+ * co-signature, and the program then rejects the create with `LotteryRequiresOperator` or the
+ * runtime with a signature failure. Working on the wire bytes makes the guarantee structural: the
+ * agent writes 64 bytes into its own slot and nothing else changes.
+ *
+ * Layout (legacy only; a versioned message has the high bit of its first byte set):
+ *
+ *   shortvec(n) | n × 64-byte signatures | message
+ *   message = numRequiredSignatures u8 | numReadonlySigned u8 | numReadonlyUnsigned u8
+ *           | shortvec(k) | k × 32-byte keys | recentBlockhash 32
+ *           | shortvec(i) | i × (programIdIndex u8 | shortvec(a) | a × u8 | shortvec(d) | d bytes)
+ *
+ * Signatures are ed25519 over the exact message bytes, in the order of the first
+ * `numRequiredSignatures` account keys. The first key is the fee payer.
+ */
+
+import { createPrivateKey, createPublicKey, sign, verify } from 'crypto';
+
+export interface WireInstruction {
+  programIdIndex: number;
+  accountIndexes: number[];
+  data: Buffer;
+}
+
+export interface WireTransaction {
+  signatures: Buffer[];
+  /** Byte offset of the first signature in the serialized transaction. */
+  signatureOffset: number;
+  /** The exact bytes every signature covers. */
+  message: Buffer;
+  header: {
+    numRequiredSignatures: number;
+    numReadonlySigned: number;
+    numReadonlyUnsigned: number;
+  };
+  /** Base58. The first `numRequiredSignatures` are the signers, in signature order. */
+  accountKeys: string[];
+  recentBlockhash: string;
+  instructions: WireInstruction[];
+}
+
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+/** Bitcoin-alphabet base58, as Solana uses for keys, signatures and blockhashes. */
+export function base58Encode(bytes: Uint8Array): string {
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  const digits: number[] = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] << 8;
+      digits[j] = carry % 58;
+      carry = (carry / 58) | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = (carry / 58) | 0;
+    }
+  }
+  let out = '1'.repeat(zeros);
+  for (let i = digits.length - 1; i >= 0; i--) out += BASE58_ALPHABET[digits[i]];
+  return out;
+}
+
+export function base58Decode(s: string): Buffer {
+  let zeros = 0;
+  while (zeros < s.length && s[zeros] === '1') zeros++;
+  const bytes: number[] = [];
+  for (let i = zeros; i < s.length; i++) {
+    let carry = BASE58_ALPHABET.indexOf(s[i]);
+    if (carry < 0) throw new Error(`invalid base58 character ${JSON.stringify(s[i])}`);
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+  return Buffer.concat([Buffer.alloc(zeros), Buffer.from(bytes.reverse())]);
+}
+
+function readShortVec(buf: Buffer, offset: number): { value: number; next: number } {
+  let value = 0;
+  for (let i = 0; i < 3; i++) {
+    const byte = buf[offset + i];
+    if (byte === undefined) throw new Error('truncated transaction');
+    value |= (byte & 0x7f) << (7 * i);
+    if ((byte & 0x80) === 0) return { value, next: offset + i + 1 };
+  }
+  throw new Error('malformed compact-u16 length');
+}
+
+function take(buf: Buffer, offset: number, length: number): Buffer {
+  if (offset + length > buf.length) throw new Error('truncated transaction');
+  return buf.subarray(offset, offset + length);
+}
+
+/**
+ * Decodes a serialized legacy transaction. Throws on anything malformed, versioned, or carrying
+ * trailing bytes — a verifier must not accept bytes it only partly understood.
+ */
+export function parseWireTransaction(raw: Buffer): WireTransaction {
+  const { value: sigCount, next: signatureOffset } = readShortVec(raw, 0);
+  const signatures: Buffer[] = [];
+  let o = signatureOffset;
+  for (let i = 0; i < sigCount; i++, o += 64) signatures.push(take(raw, o, 64));
+
+  const message = raw.subarray(o);
+  if (message.length < 3) throw new Error('truncated transaction');
+  if ((message[0] & 0x80) !== 0) {
+    throw new Error('versioned transaction message — only legacy funding transactions are expected');
+  }
+  const header = {
+    numRequiredSignatures: message[0],
+    numReadonlySigned: message[1],
+    numReadonlyUnsigned: message[2],
+  };
+  if (header.numRequiredSignatures !== sigCount) {
+    throw new Error(
+      `transaction carries ${sigCount} signature slots for ${header.numRequiredSignatures} required signers`,
+    );
+  }
+
+  let m = 3;
+  const keys = readShortVec(message, m);
+  m = keys.next;
+  const accountKeys: string[] = [];
+  for (let i = 0; i < keys.value; i++, m += 32) accountKeys.push(base58Encode(take(message, m, 32)));
+  if (header.numRequiredSignatures > accountKeys.length) {
+    throw new Error('more required signers than account keys');
+  }
+  const recentBlockhash = base58Encode(take(message, m, 32));
+  m += 32;
+
+  const ixCount = readShortVec(message, m);
+  m = ixCount.next;
+  const instructions: WireInstruction[] = [];
+  for (let i = 0; i < ixCount.value; i++) {
+    const programIdIndex = take(message, m, 1)[0];
+    m += 1;
+    const accts = readShortVec(message, m);
+    m = accts.next;
+    const accountIndexes = [...take(message, m, accts.value)];
+    m += accts.value;
+    const dataLen = readShortVec(message, m);
+    m = dataLen.next;
+    const data = Buffer.from(take(message, m, dataLen.value));
+    m += dataLen.value;
+    for (const idx of [programIdIndex, ...accountIndexes]) {
+      if (idx >= accountKeys.length) throw new Error(`instruction references account ${idx} of ${accountKeys.length}`);
+    }
+    instructions.push({ programIdIndex, accountIndexes, data });
+  }
+  if (m !== message.length) {
+    throw new Error(`${message.length - m} unexpected trailing bytes after the message`);
+  }
+
+  return { signatures, signatureOffset, message, header, accountKeys, recentBlockhash, instructions };
+}
+
+/** Whether the key at `index` must sign, per the legacy message header. */
+export function isSignerIndex(tx: WireTransaction, index: number): boolean {
+  return index < tx.header.numRequiredSignatures;
+}
+
+/** Whether the key at `index` is writable, per the legacy message header. */
+export function isWritableIndex(tx: WireTransaction, index: number): boolean {
+  const { numRequiredSignatures, numReadonlySigned, numReadonlyUnsigned } = tx.header;
+  if (index < numRequiredSignatures) return index < numRequiredSignatures - numReadonlySigned;
+  return index < tx.accountKeys.length - numReadonlyUnsigned;
+}
+
+export function isEmptySignature(sig: Buffer): boolean {
+  return sig.every((b) => b === 0);
+}
+
+// DER prefixes that wrap a raw 32-byte ed25519 key for node:crypto (RFC 8410).
+const SPKI_ED25519_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+
+/** ed25519 verification of `signature` over `message` by the base58 `publicKey`. */
+export function ed25519Verify(signature: Buffer, message: Buffer, publicKey: string): boolean {
+  try {
+    const raw = base58Decode(publicKey);
+    if (raw.length !== 32 || signature.length !== 64) return false;
+    const key = createPublicKey({
+      key: Buffer.concat([SPKI_ED25519_PREFIX, raw]),
+      format: 'der',
+      type: 'spki',
+    });
+    return verify(null, message, key, signature);
+  } catch {
+    return false;
+  }
+}
+
+/** ed25519 signature over `message` with a Solana 64-byte secret key (seed ‖ public key). */
+export function ed25519Sign(message: Buffer, secretKey: Uint8Array): Buffer {
+  const key = createPrivateKey({
+    key: Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(secretKey.subarray(0, 32))]),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  return sign(null, message, key);
+}
+
+/** The base58 public key a 64-byte Solana secret key's seed actually derives. */
+export function publicKeyOfSecret(secretKey: Uint8Array): string {
+  const key = createPrivateKey({
+    key: Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(secretKey.subarray(0, 32))]),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  const spki = createPublicKey(key).export({ format: 'der', type: 'spki' });
+  return base58Encode(spki.subarray(spki.length - 32));
+}
+
+/**
+ * Adds `secretKey`'s signature to its own slot of a serialized transaction and returns the new
+ * bytes. Every other byte — the message and every other signature, including a co-signature
+ * already present — is left exactly as it was, and that is asserted before returning.
+ */
+export function addOwnSignature(raw: Buffer, secretKey: Uint8Array, publicKey: string): Buffer {
+  if (publicKeyOfSecret(secretKey) !== publicKey) {
+    throw new Error('the wallet secret key does not derive its own public key — refusing to sign');
+  }
+  const tx = parseWireTransaction(raw);
+  const signers = tx.accountKeys.slice(0, tx.header.numRequiredSignatures);
+  const index = signers.indexOf(publicKey);
+  if (index < 0) {
+    throw new Error(
+      `refusing to sign: ${publicKey} is not a required signer of this transaction ` +
+        `(signers: ${signers.join(', ') || 'none'})`,
+    );
+  }
+  const signature = ed25519Sign(tx.message, secretKey);
+  const out = Buffer.from(raw);
+  signature.copy(out, tx.signatureOffset + 64 * index);
+
+  // Post-conditions: same length, same message, every other slot untouched, ours verifies.
+  const after = parseWireTransaction(out);
+  if (out.length !== raw.length || !after.message.equals(tx.message)) {
+    throw new Error('signing altered the transaction message — refusing to return it');
+  }
+  for (let i = 0; i < tx.signatures.length; i++) {
+    if (i !== index && !after.signatures[i].equals(tx.signatures[i])) {
+      throw new Error(`signing altered signature slot ${i} — refusing to return it`);
+    }
+  }
+  if (!ed25519Verify(after.signatures[index], after.message, publicKey)) {
+    throw new Error('the new signature does not verify — refusing to return it');
+  }
+  return out;
+}

package/src/tools/missions.ts

@@ -26,7 +26,7 @@ const RESPONSE_SCHEMA_PROPERTY = {
     'media_review has always used for track ratings, generalized to any mission type. ' +
     'media_review defaults to a canonical two-question schema when this is omitted at creation — ' +
     'literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", ' +
-    'required: false } — so read/append against those exact ids if you rely on the default rather ' +
+    'required: true } — so read/append against those exact ids if you rely on the default rather ' +
     'than supplying your own schema. Every other type has no default (stays fully manual/chat-based ' +
     'unless you set this).',
   items: {
@@ -63,7 +63,16 @@ const RESPONSE_SCHEMA_PROPERTY = {
       },
       label: { type: 'string', description: 'Question text shown to the human (max 200 chars). For the checkbox kind this is the checkbox\'s own clickable text, not a separate heading.' },
       help: { type: 'string', description: 'Optional helper text shown under the label (max 500 chars).' },
-      required: { type: 'boolean', description: 'Whether this question must be answered to complete the mission.' },
+      required: {
+        type: 'boolean',
+        description:
+          'Whether this question must be answered to complete the mission. A required: false question ' +
+          'does NOT block mission completion or finalize_qualification\'s auto-qualification — both ' +
+          'derive purely from the required questions, so an optional question left blank (or still ' +
+          'being typed into) will not stop either from firing the instant the required ones are ' +
+          'answered. If every question in the schema should actually be answered, mark them all ' +
+          'required: true; reserve required: false for a genuinely optional/skippable field.',
+      },
       options: {
         type: 'array',
         items: { type: 'string' },
@@ -79,7 +88,22 @@ const RESPONSE_SCHEMA_PROPERTY = {
 export const missionTools: Tool[] = [
   {
     name: 'create_mission',
-    description: 'Create a new mission. Off-chain missions (no budget field) are always free — no payment, no escrow. For paid missions, include the budget field AND chain: \'solana\' — the response will contain funding_params for fund_solana_mission. Base (EscrowVault) on-chain missions are closed to new creation during the Solana private beta migration: any budget-bearing request that resolves to chain \'base\' (including the pre-Solana default of omitting chain) now returns 503, not a created mission — always pass chain: \'solana\' explicitly for a paid mission.',
+    description:
+      'Create a new mission. Off-chain missions (no budget field) are always free — no payment, no escrow. ' +
+      'Include the budget field for a paid mission escrowed on Solana: it is created in pending_funding, and ' +
+      'you then fund it with fund_solana_mission (pass the returned mission id). Solana is the only chain ' +
+      '(the backend also defaults a missing chain to solana, and this tool always sends it). ' +
+      'A paid mission\'s response includes funding_params: chain (\'solana\'), cluster, program_id, rpc_url, ' +
+      'mint, token_address (same as mint), token_decimals, amount_raw, base_pool, ' +
+      'lottery_reward_per_winner_raw, lottery_winner_count, qualify_deadline, settlement_deadline, seed_commit ' +
+      'and expires_at. There is no escrow address or task id yet: the program assigns those when the mission ' +
+      'is funded. expires_at is creation + 24 hours — a mission still unfunded then is cancelled automatically. ' +
+      'You do not need to build anything from funding_params; fund_solana_mission does the whole funding step. ' +
+      'The response\'s mission.solana_quoted_fee_bps is the platform fee rate you were quoted: the escrow ' +
+      'transaction carries it as max_fee_bps, the most the program may charge, and fund_solana_mission refuses ' +
+      'to sign any other value. A paid lottery (lottery_winner_count > 0) is funded with a transaction the platform ' +
+      'Operator has already co-signed; fund_solana_mission verifies that co-signature before adding yours. ' +
+      'Paid-mission deadlines follow the escrow program\'s rules — see hiring_duration_hours and work_duration_hours.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -90,8 +114,8 @@ export const missionTools: Tool[] = [
         },
         chain: {
           type: 'string',
-          enum: ['base', 'solana'],
-          description: 'Which chain escrows a paid (budget-bearing) mission. \'base\' is currently closed to new creation and returns 503 — pass \'solana\' for any on-chain mission. Ignored for off-chain missions (no budget field).',
+          enum: ['solana'],
+          description: 'Optional. Solana is the only chain: a paid (budget-bearing) mission is always sent with chain \'solana\' whether or not you set this. Ignored for off-chain missions (no budget field).',
         },
         title: { type: 'string', description: 'Mission title (max 100 chars)' },
         description: { type: 'string', description: 'Detailed mission description (max 2000 chars). Supports Markdown — use ## headings, - bullet lists, and **bold** to structure your content. The platform renders it as formatted text.' },
@@ -108,14 +132,14 @@ export const missionTools: Tool[] = [
         reward_usdt: { type: 'number', minimum: 0, description: 'Deprecated — ignored for off-chain missions (which are always free). Has no effect. Omit this field.' },
         max_participants: { type: 'number', minimum: 1, description: 'Maximum number of participants' },
         expires_in_hours: { type: 'number', minimum: 1, description: 'Hours until mission expires' },
-        budget: { type: 'number', description: 'Total mission budget in USDC. Enables on-chain escrow — pair with chain: \'solana\' (Base is closed to new creation, see chain). Must satisfy: base_reward * max_humans + lottery_prize_per_winner * lottery_winner_count <= budget.' },
+        budget: { type: 'number', description: 'Total mission budget in USDC. Enables on-chain escrow on Solana (fund it afterwards with fund_solana_mission). Must also cover the platform fee, which is reserved out of the budget: base_reward * max_humans + lottery_prize_per_winner * lottery_winner_count + floor(budget * fee_bps / 10000) <= budget (equality passes). fee_bps is read from the Solana escrow program\'s on-chain config, not a fixed rate (currently 0 on devnet). A 400 for this rule states the rate in use; a 503 means the rate could not be read, nothing was created, and you should retry shortly. Both the backend and the Solana escrow program enforce this.' },
         max_humans: { type: 'number', minimum: 1, description: 'On-chain: maximum number of participants (both base-reward and lottery entrants).' },
         base_reward: { type: 'number', minimum: 0, description: 'Per-participant base reward in USDC paid to every qualified human. Defaults to 0. Set to 0 for pure-lottery missions.' },
         reward_per_human: { type: 'number', minimum: 0, description: 'Deprecated — use base_reward instead.' },
-        lottery_winner_count: { type: 'integer', minimum: 1, description: 'Number of winners randomly selected from all qualified participants. Must be <= max_humans. Must be paired with lottery_prize_per_winner. Winners are chosen deterministically from the on-chain seed reveal — auditable by anyone.' },
+        lottery_winner_count: { type: 'integer', minimum: 1, description: 'Number of winners randomly selected from all qualified participants. Must be <= max_humans. Must be paired with lottery_prize_per_winner. For a paid mission the draw happens on chain at settlement: final_entropy = keccak256(seed_reveal ‖ entropy_hash), where seed_reveal opens the seed_commit fixed at funding and entropy_hash is the SlotHashes sysvar bank hash of the first produced slot after finalize_qualification, stored on the Task by record_entropy (settle captures it if nobody recorded it). It is NOT the blockhash getBlock returns for that slot, so recompute a draw from the Task account\'s entropy_hash, not from getBlock. The platform Operator co-signs a lottery\'s funding transaction (the escrow program requires it).' },
         lottery_prize_per_winner: { type: 'number', minimum: 0, description: 'Additional prize in USDC paid to each lottery winner on top of base_reward. Must be paired with lottery_winner_count.' },
-        hiring_duration_hours: { type: 'number', minimum: 0.0166, description: 'How long (hours) the mission accepts applications and the agent hires/rejects. The hiring window closes at now + hiring_duration_hours. Finalize-qualification cannot be called before this. Backend floor is 60s (0.0166h), same for every chain — see work_duration_hours for the reasoning.' },
-        work_duration_hours: { type: 'number', minimum: 0.0166, description: 'How long (hours) hired participants have to complete the work. Agent must call settle_mission before this period ends. Backend floor is 60s (0.0166h) for every chain — this is a flat sanity check against a near-zero window, not a guarantee of a legal settlement window on every chain: Base\'s own EscrowVault contract separately enforces its own fixed 1-hour minimum regardless of what this floor allows through, so a too-short Base mission still fails downstream (at finalize_qualification, or on-chain) instead of being caught at creation.' },
+        hiring_duration_hours: { type: 'number', minimum: 0.0166, description: 'How long (hours) the mission accepts applications and the agent hires/rejects. The hiring window closes at now + hiring_duration_hours. Finalize-qualification cannot be called before this. Closing hiring does NOT end the work: hired humans keep voting and submitting answers after it (see work_duration_hours). Backend floor is 60s (0.0166h) — see work_duration_hours for what that floor does and does not guarantee. For a paid mission the end of the hiring window is the escrow\'s qualify_deadline: it may be at most 180 days ahead, and it is the cancel cut-off — refund_solana_mission\'s cancel is refused on chain from qualify_deadline on (TooLateToCancel).' },
+        work_duration_hours: { type: 'number', minimum: 0.0166, description: 'How long (hours) hired participants have to complete the work: settlement_deadline = end of the hiring window + work_duration_hours. Agent must call settle_mission before this period ends. Humans can vote and submit answers while the mission is active: on-chain until max(qualify_deadline, settlement_deadline − 1260s), i.e. about 21 minutes before settlement_deadline; off-chain until finalize. Either way, finalize_qualification closes submissions. Backend floor is 60s (0.0166h) — a sanity check against a near-zero window, not a guarantee the escrow accepts it. For a paid mission the Solana escrow program separately requires settlement_deadline >= qualify_deadline + min_review_window + finalize grace, and settlement_deadline <= qualify_deadline + 90 days. min_review_window is the program\'s configured review window and the finalize grace equals its floor (10 seconds each on the current devnet build; the floor is 1 hour on a production build). create_mission checks both against the live program config and returns 400 on a violation; the program enforces them again when the escrow is funded, and finalize_qualification must still leave min_review_window before settlement_deadline.' },
         auto_accept_applicants: { type: 'boolean', description: 'Defaults to true — applicants are automatically hired when they apply, no manual hire_participant call needed, first-come first-served up to max_humans, face verification still required. Pass false to opt into manual review instead (see hire_participant for how unreviewed applicants are still handled once the hiring window closes).' },
         response_schema: RESPONSE_SCHEMA_PROPERTY,
       },
@@ -167,21 +191,9 @@ export const missionTools: Tool[] = [
       required: ['mission_id'],
     },
   },
-  {
-    name: 'confirm_funding',
-    description: 'Base (EscrowVault) only — Solana missions use fund_solana_mission instead, which confirms as part of the same call. Base is currently closed to new mission creation, so this only applies to a Base mission created before that change. After calling createTask() on the EscrowVault contract, confirm the funding via the SOLO API. The backend verifies the transaction on-chain. Mission transitions from pending_funding → active. tx_hash is optional — backend reconciles from the contract if omitted. For media_review missions: returns 409 if no tracks are confirmed yet — call add_mission_track first. Also returns 409 if the on-chain task\'s budget, lottery, deadline, or seed_commit values do not match what create_mission originally quoted (e.g. createTask() was called with hand-typed or re-derived values instead of the exact funding_params fields) — unlike the "not yet FUNDED" 409, this one is NOT retryable: the task_id can never be confirmed. Call cancelTask() on-chain to reclaim the full escrow, then call create_mission again.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mission_id: { type: 'string' },
-        tx_hash: { type: 'string', description: 'Transaction hash of createTask() call (optional)' },
-      },
-      required: ['mission_id'],
-    },
-  },
   {
     name: 'hire_participant',
-    description: 'Accept a human applicant for a mission. Only applied humans can be hired. Hired humans can start work via conversations. Only valid while mission is active. IMPORTANT: silence is not neutral — an applicant you never call this (or reject_participant) on is automatically hired once the hiring window closes (up to max_humans, oldest applied_at first). If you do not want someone, you must call reject_participant before the deadline.',
+    description: 'Accept a human applicant for a mission. Only applied humans can be hired. Hired humans can start work via conversations. Only valid while mission is active. IMPORTANT: silence is not neutral — an applicant you never call this (or reject_participant) on is automatically hired (up to max_humans, oldest applied_at first). That does NOT happen when the hiring window closes. For an on-chain mission it happens in the window just before settlement_deadline (roughly 21 to 1 minutes before it), in the same pass that auto-finalizes and settles. For an off-chain mission it happens at expires_at. If you do not want someone, call reject_participant before then.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -193,7 +205,7 @@ export const missionTools: Tool[] = [
   },
   {
     name: 'reject_participant',
-    description: 'Reject a human applicant or hired participant. Valid for applied or hired status, before finalize_qualification is called. This is the ONLY way to exclude someone — the platform auto-hires overdue applicants and auto-qualifies overdue hired participants by default (silence = go), so if you do not explicitly reject someone before their deadline, they end up hired/qualified/paid.',
+    description: 'Reject a human applicant or hired participant. Valid for applied or hired status, before finalize_qualification is called. This is the ONLY way to exclude someone — the platform auto-hires remaining applicants and auto-qualifies hired participants by default (silence = go), so anyone you do not explicitly reject ends up hired, qualified and paid. That happens in the window just before settlement_deadline for an on-chain mission (roughly 21 to 1 minutes before it) and at expires_at for an off-chain mission, not when the hiring window closes.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -205,7 +217,7 @@ export const missionTools: Tool[] = [
   },
   {
     name: 'finalize_qualification',
-    description: 'Lock in the qualified participants after reviewing their work. If the mission has a response_schema (media_review always does, by default or explicitly; any other type only if you set one via create_mission/update_mission_questions), pass an empty body — qualified_human_uids is ignored and the backend auto-qualifies anyone who completed it (every ready track for media_review, a full submission for other types). Otherwise provide an explicit list of UIDs whose work was accepted. For on-chain missions, the backend calls finalizeQualification() on EscrowVault. Mission transitions to qualifying. If you never call this, the platform does it for you shortly after the hiring window closes, qualifying every hired participant you did not explicitly reject_participant (silence = go) — call reject_participant first for anyone whose work should NOT be paid.',
+    description: 'Lock in the qualified participants after reviewing their work. If the mission has a response_schema (media_review always does, by default or explicitly; any other type only if you set one via create_mission/update_mission_questions), pass an empty body — qualified_human_uids is ignored and the backend auto-qualifies anyone who completed it (every ready track for media_review, a full submission for other types). Otherwise provide an explicit list of UIDs whose work was accepted. For on-chain missions, the backend records the qualified set on the Solana escrow program. Mission transitions to qualifying. If you never call this, the platform does it for you (silence = go), qualifying every hired participant you did not explicitly reject_participant. It does NOT happen when the hiring window closes. For an on-chain mission it happens in a short window just before settlement_deadline (roughly 21 to 1 minutes before it), where the platform also auto-hires any remaining applicants, finalizes and settles in one pass. For an off-chain mission it happens at expires_at. Call reject_participant first for anyone whose work should NOT be paid.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -221,7 +233,7 @@ export const missionTools: Tool[] = [
   },
   {
     name: 'settle_mission',
-    description: 'Settle the mission after finalize_qualification. For on-chain missions, calls settleTask() on EscrowVault only (aggregate payout numbers, no per-wallet computation); mission transitions to completed or refundable. IMPORTANT: status alone cannot tell you whether anyone was paid — a mission with 8/10 slots filled (2 slots\' budget refunded) and one with 0/10 filled (the whole budget refunded) both land on \'refundable\'/\'refunded\'. Check the settlement_outcome field on the response instead: \'completed\' (fully spent, no refund), \'completed_refundable\' (real participants were paid, only the unfilled slots refund), or \'no_payout_refunded\' (nobody qualified, the entire budget bounces). Rewards are NOT immediately claimable — a separate batched process publishes the Merkle root that makes them claimable, gated by a review window currently defaulting to about 10 seconds (minimized pre-launch; will lengthen to an hour or more once real funds are at stake). Check GET /human/rewards for actual claimable status rather than assuming a fixed delay. For free (off-chain) missions, marks qualified participants as completed — no payment is involved; settlement_outcome is always \'completed\' there. If you never call this, the platform settles on your behalf shortly after finalize_qualification (auto or manual) — you do not get a second chance to change who is qualified at that point, so reject anyone unwanted before finalize, not after.',
+    description: 'Settle the mission after finalize_qualification. For on-chain missions, the backend settles the Solana escrow with aggregate payout numbers only (no per-wallet computation); mission transitions to completed or refundable. A \'refundable\' mission is holding leftover budget for you: claim it with refund_solana_mission, action: \'claim_refund\' (the mission then moves to refunded). IMPORTANT: status alone cannot tell you whether anyone was paid — a mission with 8/10 slots filled (2 slots\' budget refunded) and one with 0/10 filled (the whole budget refunded) both land on \'refundable\'/\'refunded\'. Check the settlement_outcome field on the response instead: \'completed\' (fully spent, no refund), \'completed_refundable\' (real participants were paid, only the unfilled slots refund), or \'no_payout_refunded\' (nobody qualified, the entire budget bounces). Rewards are NOT immediately claimable — a separate batched process publishes the Merkle root that makes them claimable, gated by a review window currently defaulting to about 10 seconds (minimized pre-launch; will lengthen to an hour or more once real funds are at stake). Check GET /human/solana/rewards for actual claimable status rather than assuming a fixed delay. For free (off-chain) missions, marks qualified participants as completed — no payment is involved; settlement_outcome is always \'completed\' there. You may settle at any time after finalize_qualification and before settlement_deadline; there is no need to wait. If you never call this, the platform settles on your behalf, but NOT right after finalize: for an on-chain mission it happens in the window just before settlement_deadline (roughly 21 to 1 minutes before it), and for an off-chain mission at expires_at. Who is qualified is fixed at finalize, so reject anyone unwanted before finalize, not after.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -232,7 +244,16 @@ export const missionTools: Tool[] = [
   },
   {
     name: 'cancel_mission',
-    description: 'Cancel an off-chain mission directly. Valid when status is active or qualifying. For on-chain missions, use get_cancel_params instead.',
+    description:
+      'Cancel a mission that holds no escrowed funds: an off-chain mission (status active or qualifying), or ' +
+      'an unfunded Solana mission still in pending_funding. For a Solana mission the backend first checks the ' +
+      'chain: if it finds an escrow that was created but never confirmed, it returns 409 with that task_id and ' +
+      'does not cancel — use refund_solana_mission with action: \'cancel\' then. For a funded mission also use ' +
+      'refund_solana_mission with action: \'cancel\': it returns the escrowed budget to you and moves the mission ' +
+      'to cancelled, but only strictly before qualify_deadline (the end of the hiring window) — the escrow program ' +
+      'refuses a cancel from then on (TooLateToCancel), and the remaining exit is emergency_refund once ' +
+      'settlement_deadline passes without a settlement. An unfunded Solana mission you leave alone is cancelled automatically at its ' +
+      'funding_params.expires_at (creation + 24 hours).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -241,78 +262,9 @@ export const missionTools: Tool[] = [
       required: ['mission_id'],
     },
   },
-  {
-    name: 'get_cancel_params',
-    description: 'Get on-chain transaction parameters to cancel a funded mission via cancelTask() on EscrowVault. Only valid before qualify_deadline. After qualify_deadline, use get_emergency_refund_params instead.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mission_id: { type: 'string' },
-      },
-      required: ['mission_id'],
-    },
-  },
-  {
-    name: 'confirm_cancel',
-    description: 'After executing cancelTask() on EscrowVault, confirm the cancellation on the SOLO platform. Mission transitions to cancelled.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mission_id: { type: 'string' },
-        tx_hash: { type: 'string', description: 'Transaction hash of cancelTask() (optional)' },
-      },
-      required: ['mission_id'],
-    },
-  },
-  {
-    name: 'get_emergency_refund_params',
-    description: 'Get on-chain transaction parameters to force-refund a mission after the settlement_deadline has passed without settlement. Returns eligible: true with params if eligible, or eligible: false with retry_after if not yet past the deadline.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mission_id: { type: 'string' },
-      },
-      required: ['mission_id'],
-    },
-  },
-  {
-    name: 'confirm_emergency_refund',
-    description: 'After executing emergencyRefund() on EscrowVault, confirm on the SOLO platform. Mission transitions to cancelled.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mission_id: { type: 'string' },
-        tx_hash: { type: 'string', description: 'Transaction hash of emergencyRefund() (optional)' },
-      },
-      required: ['mission_id'],
-    },
-  },
-  {
-    name: 'get_refund_params',
-    description: 'Get on-chain transaction parameters to claim unused budget via claimRefund() on EscrowVault. Only valid when mission is in refundable state (settled with leftover budget).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mission_id: { type: 'string' },
-      },
-      required: ['mission_id'],
-    },
-  },
-  {
-    name: 'confirm_refund',
-    description: 'After executing claimRefund() on EscrowVault, confirm the refund on the SOLO platform. Mission transitions to refunded.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        mission_id: { type: 'string' },
-        tx_hash: { type: 'string', description: 'Transaction hash of claimRefund() (optional)' },
-      },
-      required: ['mission_id'],
-    },
-  },
   {
     name: 'rate_participant',
-    description: 'Leave a rating and optional comment for a mission participant. Requires the mission to be settled (completed, refundable, or refunded) and must be submitted within 7 days of mission completion. Limited to one rating per participant per mission; calling again overwrites the previous rating/comment.',
+    description: 'Leave a rating and optional comment for a mission participant. Allowed for every settled outcome (mission status completed, refundable or refunded), within 7 days of settlement. Limited to one rating per participant per mission; calling again overwrites the previous rating/comment.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -328,8 +280,14 @@ export const missionTools: Tool[] = [
 
 export async function handleMissionTool(name: string, args: Record<string, any>): Promise<unknown> {
   switch (name) {
-    case 'create_mission':
-      return apiPost('/agent/missions', args);
+    case 'create_mission': {
+      // Solana is the only chain. The backend still treats a missing `chain` on a budget-bearing
+      // request as the retired default and rejects it with 503, so a paid mission always carries
+      // chain: 'solana' no matter what the caller passed. `budget !== undefined` mirrors the
+      // backend's own on-chain test; `chain` is dropped from an off-chain request, where it is unused.
+      const { chain: _chain, ...body } = args;
+      return apiPost('/agent/missions', body.budget !== undefined ? { ...body, chain: 'solana' } : body);
+    }
 
     case 'list_missions': {
       const params: Record<string, any> = {};
@@ -345,9 +303,6 @@ export async function handleMissionTool(name: string, args: Record<string, any>)
     case 'update_mission_questions':
       return apiPatch(`/agent/missions/${args.mission_id}/questions`, { response_schema: args.response_schema });
 
-    case 'confirm_funding':
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-funding`, { tx_hash: args.tx_hash });
-
     case 'hire_participant':
       return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/hire`);
 
@@ -365,24 +320,6 @@ export async function handleMissionTool(name: string, args: Record<string, any>)
     case 'cancel_mission':
       return apiPost(`/agent/missions/${args.mission_id}/cancel`);
 
-    case 'get_cancel_params':
-      return apiGet(`/agent/missions/${args.mission_id}/cancel-params`);
-
-    case 'confirm_cancel':
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-cancel`, { tx_hash: args.tx_hash });
-
-    case 'get_emergency_refund_params':
-      return apiGet(`/agent/missions/${args.mission_id}/emergency-refund-params`);
-
-    case 'confirm_emergency_refund':
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-emergency-refund`, { tx_hash: args.tx_hash });
-
-    case 'get_refund_params':
-      return apiGet(`/agent/missions/${args.mission_id}/refund-params`);
-
-    case 'confirm_refund':
-      return apiPost(`/agent/missions/${args.mission_id}/confirm-refund`, { tx_hash: args.tx_hash });
-
     case 'rate_participant':
       return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/comment`, {
         rating: args.rating,