@blindmarket/mcp-server 0.5.0 → 0.6.0

package/dist/rent.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { Contract, Interface, JsonRpcProvider, formatUnits, parseUnits } from 'ethers';
+import { Contract, Interface, JsonRpcProvider, formatUnits, keccak256, parseUnits, toUtf8Bytes } from 'ethers';
 import { aesDecrypt, aesEncrypt, derivePublicKeyHex, eciesDecrypt, eciesEncrypt, generateAesKey, sha256Hex } from './crypto.js';
-import { createQuote, consumeQuote, getSpend, putSpend, updateSpend } from './state.js';
+import { createQuote, consumeQuote, getSpend, putSpend, updateSpend, } from './state.js';
 import { createSettlementResolver, isErc20Settlement, rpcFor, rpcEnvName, } from './settlement.js';
 // Read-only view of BlindEscrow.getTask, for reading a task's state directly
 // from the chain that holds it. Field order matches contracts/BlindEscrow.sol;
@@ -28,6 +28,18 @@ const ESCROW_READ_ABI = [
  * machine, so retries resume instead of double-funding.
  */
 const ZERO_TOKEN = '0x0000000000000000000000000000000000000000';
+// The only calls the backend builds for this process to sign or relay:
+// backend/src/services/escrow.ts (createTask, cancelTask, claimTimeout,
+// submitEvidence). verifyTarget checks where a transaction goes, but the
+// escrow address comes from the same backend, so a hostile answer could name
+// the token as the escrow and hand over an approve; the call, its arguments
+// and its value are what bound it (security audit run 1, C41).
+const ESCROW_CALLS = new Interface([
+    'function createTask(bytes32 taskHash, address token, uint256 amount, string category, string locationZone, uint256 duration)',
+    'function submitEvidence(uint256 taskId, bytes32 evidenceHash)',
+    'function cancelTask(uint256 taskId)',
+    'function claimTimeout(uint256 taskId)',
+]);
 const GAS_LIMIT = 1000000n; // matches the canonical rent script
 // Auto-verify releases the payment, so the bar can't be "one character" — but
 // 40 made a correct 30-character URL unpayable. 20 is the platform floor
@@ -45,6 +57,66 @@ function ok(data) {
 function fail(code, message) {
     return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: { code, message } }) }] };
 }
+/**
+ * Throw TX_MISMATCH, before anything is signed or relayed, unless the
+ * backend's unsigned `tx` is exactly `fn` (canonically encoded) with
+ * arguments `argsOk` accepts, and names no value other than `value`. Only
+ * `to` and `data` are ever forwarded, so a value the backend names is never
+ * sent; a wrong one still means the transaction is not the one asked for.
+ */
+function assertEscrowCall(tx, fn, argsOk, what, value = 0n) {
+    const data = typeof tx.data === 'string' ? tx.data.toLowerCase() : '';
+    let ok = false;
+    try {
+        const args = ESCROW_CALLS.decodeFunctionData(fn, data);
+        ok = ESCROW_CALLS.encodeFunctionData(fn, args).toLowerCase() === data && argsOk(args);
+    }
+    catch { /* another function, or not ABI data at all */ }
+    if (ok && tx.value != null) {
+        try {
+            ok = BigInt(tx.value) === value;
+        }
+        catch {
+            ok = false;
+        }
+    }
+    if (!ok) {
+        const e = new Error(`backend built ${what} that is not the ${fn} call this spend asked for (another function, other arguments, or a value). Nothing was sent.`);
+        e.code = 'TX_MISMATCH';
+        throw e;
+    }
+}
+const QUOTE_REQUIRED_MESSAGE = 'Get a quote first (call without confirm), then re-call with confirm=true and the returned quoteId (quotes are single-use and expire after 10 minutes)';
+/** Why a confirm was refused against its quote. Nothing was uploaded,
+ *  approved or sent by then. `why` replaces the generic list of what changed. */
+function quoteRefused(check, tool, why) {
+    if (check.code === 'QUOTE_REQUIRED')
+        return fail('QUOTE_REQUIRED', QUOTE_REQUIRED_MESSAGE);
+    return fail('QUOTE_MISMATCH', `Nothing was sent: ${why ?? `this confirm would spend something other than quote ${check.quote.quoteId} (changed: ${check.changed.join(', ')})`}. ` +
+        `That quote is now used up. Call ${tool} again without confirm to get a new quote, check it, then confirm with the new quoteId.`);
+}
+/** The chain, escrow, token and wallet a spend moves money on, for its quote binding. */
+function settlementFields(s, payFrom) {
+    return {
+        chain: s.mode,
+        chainId: s.chainId ?? null,
+        escrow: s.escrowAddress ? s.escrowAddress.toLowerCase() : null,
+        token: isErc20Settlement(s) ? s.token.address.toLowerCase() : ZERO_TOKEN,
+        payFrom: payFrom.toLowerCase(),
+    };
+}
+/** How the network a spend was recorded on differs from the one `s` settles
+ *  on now, or null. A chain key keeps its name when the backend moves it to
+ *  another network (Arc Testnet 5042002 and Arc mainnet 5042 are both 'arc'),
+ *  so the record's chain id decides. A record written before records kept one
+ *  cannot be checked. */
+function networkChange(record, s) {
+    if (s.chainId === undefined || record.chainId === s.chainId)
+        return null;
+    return record.chainId === undefined
+        ? `was recorded without a chain id, so it cannot be checked against ${s.mode} on chain ${s.chainId}`
+        : `started on ${s.mode} chain ${record.chainId}, but the backend's ${s.mode} is chain ${s.chainId} now`;
+}
 export function registerRentTools(server, cfg, walletCtx) {
     /** Every authenticated call funnels through api(), so this is the one place
      *  the missing-key case needs handling. Without it the caller gets the
@@ -253,7 +325,7 @@ export function registerRentTools(server, cfg, walletCtx) {
     /** Wait for a relayed tx to land. A plain hash can be polled for its receipt;
      *  a user-op hash cannot (getTransactionReceipt is always null for it), so
      *  that case returns at once and the caller confirms by on-chain STATE —
-     *  see ensureAllowance and waitCancelled. */
+     *  see ensureAllowance and waitLanded. */
     async function waitRelayed(s, hash, isUserOp) {
         if (isUserOp)
             return;
@@ -345,6 +417,14 @@ export function registerRentTools(server, cfg, walletCtx) {
                 e.code = 'SETTLEMENT_CHANGED';
                 throw e;
             }
+            // Nor on another network under the same key: the spend was quoted and
+            // confirmed for the one it started on.
+            const moved = networkChange(record, s);
+            if (moved) {
+                const e = new Error(`spend ${record.idempotencyKey} ${moved}. Nothing was funded yet (stage ${record.stage}): start a new spend with a new idempotencyKey.`);
+                e.code = 'SETTLEMENT_CHANGED';
+                throw e;
+            }
             const refused = await notPostingChain(s);
             if (refused)
                 throw refused;
@@ -374,6 +454,15 @@ export function registerRentTools(server, cfg, walletCtx) {
                 throw e;
             }
             await verifyTarget(s, unsignedTx.to, 'createTask');
+            // And it must be this spend's createTask: its task hash, token, amount
+            // and duration (the amount is what was approved above, or the value sent below).
+            const amount = BigInt(record.amountWei);
+            const token = isErc20Settlement(s) ? s.token.address : ZERO_TOKEN;
+            assertEscrowCall(unsignedTx, 'createTask', (a) => String(a[0]).toLowerCase() === String(record.taskHash).toLowerCase()
+                && String(a[1]).toLowerCase() === token.toLowerCase()
+                && a[2] === amount
+                && a[4] === 'global'
+                && a[5] === BigInt(record.durationSecs ?? 3600), 'createTask', isErc20Settlement(s) ? 0n : amount);
             if (isErc20Settlement(s)) {
                 const { hash, isUserOp, gas } = await sendErc20(s, { to: unsignedTx.to, data: unsignedTx.data }, nonce);
                 // Persist BEFORE waiting, same reasoning as the 0G branch below.
@@ -442,7 +531,7 @@ export function registerRentTools(server, cfg, walletCtx) {
     // ── rent_service ──────────────────────────────────────────────────────────
     server.registerTool('rent_service', {
         title: 'Rent an Agent Service',
-        description: 'Hire a listed agent service for one call: encrypts your prompt locally (unless privacy=public), funds escrow, and pins the task to the provider agent. Escrow is paid on the backend\'s posting chain: USDC on Arc signed by the local wallet (BLINDMARKET_PRIVATE_KEY, which must own BLINDMARKET_API_KEY; gas is also USDC), USDC on Base through the backend relay (no private key needed), or native 0G from the local wallet. wallet_status shows which. TWO-STEP: first call returns a price quote + quoteId; re-call with confirm=true and that quoteId to actually spend. Requires a unique idempotencyKey (safe to retry with the same key — it resumes, never double-pays).',
+        description: 'Hire a listed agent service for one call: encrypts your prompt locally (unless privacy=public), funds escrow, and pins the task to the provider agent. Escrow is paid on the backend\'s posting chain: USDC on Arc signed by the local wallet (BLINDMARKET_PRIVATE_KEY, which must own BLINDMARKET_API_KEY; gas is also USDC), USDC on Base through the backend relay (no private key needed), or native 0G from the local wallet. wallet_status shows which. TWO-STEP: first call returns a price quote + quoteId; re-call with the SAME arguments plus confirm=true and that quoteId to actually spend (a confirm that differs from its quote, or a listing re-priced since the quote, is refused with QUOTE_MISMATCH and nothing is sent). Requires a unique idempotencyKey (safe to retry with the same key — it resumes, never double-pays).',
         inputSchema: {
             serviceId: z.number().int().positive().describe('Service id from browse_services / get_service'),
             prompt: z.string().min(1).max(100_000).describe('What you want the agent to do'),
@@ -496,8 +585,22 @@ export function registerRentTools(server, cfg, walletCtx) {
             return fail('PRICE_UNITS_SUSPECT', `service ${serviceId} lists price_raw=${priceRaw} which is ${formatUnits(priceRaw, s.decimals)} ${s.symbol} — this looks like an 18-decimal 0G price on a ${s.symbol} chain. Not sending. Re-list the service in ${s.symbol} base units.`);
         }
         const price = formatUnits(priceRaw, s.decimals);
+        // Exactly what this call would spend, derived after every lookup above
+        // and before anything is uploaded or sent. The quote stores it and the
+        // confirm must match it: a provider can re-price its listing between
+        // the two calls, and the confirm call carries no price of its own.
+        const spend = {
+            ...settlementFields(s, payFrom),
+            idempotencyKey,
+            serviceId: String(serviceId),
+            listingId: String(service.id),
+            agent: String(service.agent_address).toLowerCase(),
+            priceRaw: priceRaw.toString(),
+            privacy: isPublic ? 'public' : 'private',
+            prompt: sha256Hex(Buffer.from(prompt, 'utf8')),
+        };
         if (!confirm) {
-            const quote = createQuote('rent', { serviceId, price, currency: s.symbol });
+            const quote = createQuote('rent', { serviceId, price, currency: s.symbol }, spend);
             return ok({
                 quote: {
                     service: { id: service.id, name: service.name, agent: service.agent_address },
@@ -512,8 +615,12 @@ export function registerRentTools(server, cfg, walletCtx) {
                 next: `Re-call rent_service with confirm=true, quoteId="${quote.quoteId}", and the SAME idempotencyKey to execute this spend.`,
             });
         }
-        if (!quoteId || !consumeQuote(quoteId, 'rent')) {
-            return fail('QUOTE_REQUIRED', 'Get a quote first (call without confirm), then re-call with confirm=true and the returned quoteId (quotes are single-use and expire after 10 minutes)');
+        const check = consumeQuote(quoteId, 'rent', spend);
+        if (!check.ok) {
+            const repriced = check.code === 'QUOTE_MISMATCH' && check.changed.includes('priceRaw')
+                ? `the listing's price changed from ${check.quote.summary.price} ${check.quote.summary.currency} to ${price} ${s.symbol} since the quote`
+                : undefined;
+            return quoteRefused(check, 'rent_service', repriced);
         }
         try {
             // Prepare the brief blob (the canonical script's steps 1-3).
@@ -550,8 +657,10 @@ export function registerRentTools(server, cfg, walletCtx) {
                 verificationMode: 'auto',
                 verificationCriteria: RENTAL_VERIFICATION_CRITERIA,
                 requiredCapabilities: [],
-                amountWei: String(service.price_raw),
+                // The quoted price, which the binding above just matched.
+                amountWei: priceRaw.toString(),
                 settlement: s.mode,
+                chainId: s.chainId,
                 token: isErc20Settlement(s) ? s.token.address : ZERO_TOKEN,
                 durationSecs: 3600,
                 createdAt: new Date().toISOString(),
@@ -560,7 +669,7 @@ export function registerRentTools(server, cfg, walletCtx) {
             putSpend(record);
             const done = await fundAndIndex(record);
             const polled = await pollPosted(done.taskHash, waitSeconds ?? 45);
-            return ok({ ...done, ...polled });
+            return ok({ ...done, escrowed: { amount: price, amountRaw: priceRaw.toString(), currency: s.symbol }, ...polled });
         }
         catch (err) {
             const code = err.code;
@@ -573,7 +682,7 @@ export function registerRentTools(server, cfg, walletCtx) {
     // ── post_task ─────────────────────────────────────────────────────────────
     server.registerTool('post_task', {
         title: 'Post a Task to the Open Market',
-        description: 'Post a task any matching agent can pick up: encrypts the brief locally and wraps its key to every registered matching executor (or posts it in plaintext with privacy=public), then funds escrow. Escrow is paid on the backend\'s posting chain: USDC on Arc signed by the local wallet (BLINDMARKET_PRIVATE_KEY, which must own BLINDMARKET_API_KEY; gas is also USDC), USDC on Base through the backend relay (no private key needed), or native 0G from the local wallet. wallet_status shows which. TWO-STEP quote/confirm like rent_service; requires a unique idempotencyKey.',
+        description: 'Post a task any matching agent can pick up: encrypts the brief locally and wraps its key to every registered matching executor (or posts it in plaintext with privacy=public), then funds escrow. Escrow is paid on the backend\'s posting chain: USDC on Arc signed by the local wallet (BLINDMARKET_PRIVATE_KEY, which must own BLINDMARKET_API_KEY; gas is also USDC), USDC on Base through the backend relay (no private key needed), or native 0G from the local wallet. wallet_status shows which. TWO-STEP quote/confirm like rent_service: confirm with the same arguments, or it is refused with QUOTE_MISMATCH; requires a unique idempotencyKey.',
         inputSchema: {
             instructions: z.string().min(1).max(100_000).describe('The task brief'),
             amount: z.string().regex(/^\d+(\.\d+)?$/).optional().describe('Escrow amount in the settlement token (e.g. "2.5" — USDC on Base, 0G on 0G) — paid to the worker (90%) on verified completion'),
@@ -619,8 +728,19 @@ export function registerRentTools(server, cfg, walletCtx) {
         catch {
             return fail('AMOUNT_INVALID', `"${amountStr}" is not a valid ${s.symbol} amount — at most ${s.decimals} decimal places.`);
         }
+        const durationSecs = durationSeconds ?? 86400;
+        // What this call would spend, bound into the quote (see rent_service).
+        const spend = {
+            ...settlementFields(s, payFrom),
+            idempotencyKey,
+            amountRaw: amountWei.toString(),
+            durationSecs,
+            capabilities: JSON.stringify(capabilities ?? []),
+            privacy: isPublic ? 'public' : 'private',
+            instructions: sha256Hex(Buffer.from(instructions, 'utf8')),
+        };
         if (!confirm) {
-            const quote = createQuote('post', { amount: amountStr, currency: s.symbol });
+            const quote = createQuote('post', { amount: amountStr, currency: s.symbol }, spend);
             return ok({
                 quote: {
                     escrow: amountStr,
@@ -635,9 +755,9 @@ export function registerRentTools(server, cfg, walletCtx) {
                 next: `Re-call post_task with confirm=true, quoteId="${quote.quoteId}", and the SAME idempotencyKey to execute this spend.`,
             });
         }
-        if (!quoteId || !consumeQuote(quoteId, 'post')) {
-            return fail('QUOTE_REQUIRED', 'Get a quote first (call without confirm), then re-call with confirm=true and the returned quoteId (quotes are single-use and expire after 10 minutes)');
-        }
+        const check = consumeQuote(quoteId, 'post', spend);
+        if (!check.ok)
+            return quoteRefused(check, 'post_task');
         try {
             const plaintext = Buffer.from(instructions, 'utf8');
             let blobB64;
@@ -684,14 +804,21 @@ export function registerRentTools(server, cfg, walletCtx) {
                 requiredCapabilities: capabilities ?? [],
                 amountWei: amountWei.toString(),
                 settlement: s.mode,
+                chainId: s.chainId,
                 token: isErc20Settlement(s) ? s.token.address : ZERO_TOKEN,
-                durationSecs: durationSeconds ?? 86400,
+                durationSecs,
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
             };
             putSpend(record);
             const done = await fundAndIndex(record);
-            return ok({ ...done, wrappedTo: wrappedKeys ? Object.keys(wrappedKeys).length : 0, privacy: record.privacy, hint: 'Use poll_task_result to wait for the deliverable.' });
+            return ok({
+                ...done,
+                escrowed: { amount: formatUnits(amountWei, s.decimals), amountRaw: amountWei.toString(), currency: s.symbol },
+                wrappedTo: wrappedKeys ? Object.keys(wrappedKeys).length : 0,
+                privacy: record.privacy,
+                hint: 'Use poll_task_result to wait for the deliverable.',
+            });
         }
         catch (err) {
             const code = err.code;
@@ -722,6 +849,11 @@ export function registerRentTools(server, cfg, walletCtx) {
     //   Disputed (6)                      → claimTimeout, but only once
     //                                       DISPUTE_WINDOW has elapsed
     //
+    // On an upgraded escrow, claimTimeout on a Submitted task (work delivered
+    // before the deadline, never judged) refunds nothing: it sends the task for
+    // review and leaves it Disputed (security audit run 1, C18). A failed
+    // (Verified) task refunds only after the worker's 3-day appeal window.
+    //
     // So the quote step reads the live status first and refuses a path the
     // contract would reject, rather than letting the caller burn gas to find out.
     //
@@ -810,18 +942,30 @@ export function registerRentTools(server, cfg, walletCtx) {
     function refundAmount(detail) {
         return formatUnits(BigInt(detail.amount), detail.decimals ?? 18);
     }
-    /** The refund has landed when the task reads Cancelled on-chain. Checking
+    /** What a cancel_task / claim_timeout confirm may send, for its quote binding. */
+    function refundFields(s, payFrom, idempotencyKey, detail) {
+        return {
+            ...settlementFields(s, payFrom),
+            idempotencyKey,
+            taskId: String(detail.taskId),
+            taskHash: String(detail.taskHash).toLowerCase(),
+            amountRaw: String(detail.amount),
+        };
+    }
+    /** The refund has landed when the task reads one of `settled` on-chain:
+     *  Cancelled, or for a claim on a Submitted task also Disputed (sent for
+     *  review; an escrow from before that change refunds it instead). Checking
      *  state rather than a receipt is what makes a relayed user-op decidable
      *  (there is no receipt to poll), and it is a cheap truth check for the
-     *  local-signing path too. */
-    async function waitCancelled(s, taskId) {
+     *  local-signing path too. Resolves to the status it read. */
+    async function waitLanded(s, taskId, settled) {
         for (let i = 0; i < 30; i++) {
             const detail = await loadTask(s, String(taskId)).catch(() => null);
-            if (detail && Number(detail.status) === 5)
-                return;
+            if (detail && settled.includes(Number(detail.status)))
+                return Number(detail.status);
             await new Promise((r) => setTimeout(r, 3000));
         }
-        const e = new Error(`task ${taskId} still not Cancelled on-chain after 90s — retry with the same idempotencyKey to keep waiting`);
+        const e = new Error(`task ${taskId} still not ${settled.map(statusName).join(' or ')} on-chain after 90s — retry with the same idempotencyKey to keep waiting`);
         e.code = 'REFUND_PENDING';
         throw e;
     }
@@ -839,6 +983,18 @@ export function registerRentTools(server, cfg, walletCtx) {
             e.code = 'SETTLEMENT_CHANGED';
             throw e;
         }
+        // Nor on another network under the same key, where the task id names
+        // another task. Only a refund that would still sign needs a chain id on
+        // record; a sent one waits for its own transaction.
+        const moved = networkChange(record, s);
+        if (moved && (record.stage === 'created' || record.chainId !== undefined)) {
+            const e = new Error(`refund ${record.idempotencyKey} ${moved}. ` +
+                (record.stage === 'created'
+                    ? 'Nothing was sent: quote the refund again with a new idempotencyKey.'
+                    : `Its transaction ${record.txHash} was sent on chain ${record.chainId}.`));
+            e.code = 'SETTLEMENT_CHANGED';
+            throw e;
+        }
         if (record.stage === 'created') {
             const route = record.kind === 'cancel' ? 'cancel' : 'timeout';
             // Task ids repeat across chains: name this one (the backend knows
@@ -849,6 +1005,8 @@ export function registerRentTools(server, cfg, walletCtx) {
             // broadcasts on, stop here — relaying a 0G refund onto another chain
             // lands on an address with no escrow and burns the gas.
             await verifyTarget(s, unsignedTx.to, `${route}Task`);
+            // And exactly this refund, for this task, with no value.
+            assertEscrowCall(unsignedTx, record.kind === 'cancel' ? 'cancelTask' : 'claimTimeout', (a) => a[0] === BigInt(taskId), `${route}Task`);
             if (isErc20Settlement(s)) {
                 const { hash, isUserOp, gas } = await sendErc20(s, { to: unsignedTx.to, data: unsignedTx.data });
                 // Persist BEFORE waiting, same reasoning as the 0G branch below.
@@ -881,9 +1039,12 @@ export function registerRentTools(server, cfg, walletCtx) {
         else {
             throw new Error(`Spend record ${record.idempotencyKey} is at stage '${record.stage}' with no txHash — cannot resume safely`);
         }
-        await waitCancelled(s, taskId);
-        updateSpend(record.idempotencyKey, { stage: 'confirmed' });
-        return { taskId, txHash: txHash, gas: record.gas, listingClosed: await confirmRefund(s, taskId, txHash, record.isUserOp ?? false) };
+        const landed = await waitLanded(s, taskId, record.kind === 'timeout' && record.fromStatus === 2 ? [5, 6] : [5]);
+        const outcome = landed === 6 ? 'escalate' : 'refund';
+        updateSpend(record.idempotencyKey, { stage: 'confirmed', outcome });
+        // Sent for review: the task stays live and there is no refund to confirm.
+        const listingClosed = outcome === 'escalate' ? false : await confirmRefund(s, taskId, txHash, record.isUserOp ?? false);
+        return { taskId, txHash: txHash, gas: record.gas, listingClosed, outcome };
     }
     /** Tell the backend the refund landed (POST /tasks/:id/confirm-tx): it
      *  checks the receipt and takes the task off the market, which otherwise
@@ -919,7 +1080,10 @@ export function registerRentTools(server, cfg, walletCtx) {
                 resumed: true,
                 taskId: existing.taskId,
                 txHash: existing.txHash,
-                hint: 'Already refunded — this idempotencyKey completed earlier.',
+                ...(existing.outcome ? { outcome: existing.outcome } : {}),
+                hint: existing.outcome === 'escalate'
+                    ? 'Already sent for review — this idempotencyKey completed earlier. Nothing was refunded.'
+                    : 'Already refunded — this idempotencyKey completed earlier.',
             });
         }
         try {
@@ -961,8 +1125,11 @@ export function registerRentTools(server, cfg, walletCtx) {
                 : ' The escrow is already settled — nothing to reclaim.';
             return fail('WRONG_REFUND_PATH', `Task ${detail.taskId} is ${statusName(status)}, and cancelTask only accepts Funded tasks.${alt}`);
         }
+        // The task (and its escrow) this refund is for, bound into the quote: a
+        // confirm naming another task is refused rather than refunding it.
+        const spend = refundFields(s, payFrom, idempotencyKey, detail);
         if (!confirm) {
-            const quote = createQuote('cancel', { taskId: detail.taskId });
+            const quote = createQuote('cancel', { taskId: detail.taskId }, spend);
             return ok({
                 quote: {
                     action: 'cancelTask',
@@ -976,15 +1143,16 @@ export function registerRentTools(server, cfg, walletCtx) {
                 next: `Re-call cancel_task with confirm=true, quoteId="${quote.quoteId}", and the SAME idempotencyKey to send it.`,
             });
         }
-        if (!quoteId || !consumeQuote(quoteId, 'cancel')) {
-            return fail('QUOTE_REQUIRED', 'Get a quote first (call without confirm), then re-call with confirm=true and the returned quoteId (quotes are single-use and expire after 10 minutes)');
-        }
+        const check = consumeQuote(quoteId, 'cancel', spend);
+        if (!check.ok)
+            return quoteRefused(check, 'cancel_task');
         try {
             const record = {
                 idempotencyKey,
                 kind: 'cancel',
                 stage: 'created',
                 settlement: s.mode,
+                chainId: s.chainId,
                 taskId: Number(detail.taskId),
                 taskHash: detail.taskHash,
                 amountWei: detail.amount,
@@ -1001,7 +1169,7 @@ export function registerRentTools(server, cfg, walletCtx) {
     });
     server.registerTool('claim_timeout', {
         title: 'Reclaim Escrow After the Deadline',
-        description: 'Reclaim the escrow on a task that WAS assigned but never completed, once its deadline has passed (status Assigned, Submitted, or Verified-failed). For a task no worker ever picked up, use cancel_task instead — it needs no deadline. TWO-STEP quote/confirm; requires a unique idempotencyKey.',
+        description: 'Reclaim the escrow on a task that WAS assigned but never completed, once its deadline has passed (status Assigned, or Verified-failed once the worker\'s 3-day appeal window has passed). On a Submitted task (work delivered before the deadline, never judged) it sends the task for review instead and refunds nothing: an admin rules, and with no ruling within 14 days the worker is paid; the result says outcome "escalate". For a task no worker ever picked up, use cancel_task instead — it needs no deadline. TWO-STEP quote/confirm; requires a unique idempotencyKey.',
         inputSchema: {
             task: z.string().min(1).describe('Task id (e.g. "51") or the 0x task hash returned by post_task'),
             idempotencyKey: z.string().min(8).max(128).describe('Unique key for this refund — reuse it on retries'),
@@ -1036,8 +1204,9 @@ export function registerRentTools(server, cfg, walletCtx) {
         if (now < deadline) {
             return fail('DEADLINE_NOT_REACHED', `Task ${detail.taskId} is still live until ${new Date(Number(deadline) * 1000).toISOString()} — claimTimeout reverts before then.`);
         }
+        const spend = refundFields(s, payFrom, idempotencyKey, detail);
         if (!confirm) {
-            const quote = createQuote('timeout', { taskId: detail.taskId });
+            const quote = createQuote('timeout', { taskId: detail.taskId }, spend);
             return ok({
                 quote: {
                     action: 'claimTimeout',
@@ -1049,22 +1218,26 @@ export function registerRentTools(server, cfg, walletCtx) {
                     settlement: s.mode,
                     // DISPUTE_WINDOW is enforced on-chain and disputedAt is not exposed
                     // here, so a disputed task can still revert after this quote.
-                    ...(status === 6 ? { note: 'Task is Disputed — this only succeeds once the on-chain DISPUTE_WINDOW has elapsed since the dispute was raised, otherwise it reverts with DisputeWindowActive.' } : {}),
+                    ...(status === 6 ? { note: 'Task is Disputed — this only succeeds once the on-chain DISPUTE_WINDOW has elapsed since the dispute was raised, otherwise it reverts with DisputeWindowActive. Delivered work that was sent for review never returns to you by timeout.' } : {}),
+                    ...(status === 2 ? { note: 'The work was delivered before the deadline and never judged. The escrow sends it for review instead of refunding you: an admin rules, and with no ruling within 14 days the worker is paid. (An escrow from before that change refunds it.)' } : {}),
+                    ...(status === 3 ? { note: "The work failed verification. This reverts with AppealWindowActive until the worker's 3-day appeal window after the verdict has passed." } : {}),
                     quoteId: quote.quoteId,
                 },
                 next: `Re-call claim_timeout with confirm=true, quoteId="${quote.quoteId}", and the SAME idempotencyKey to send it.`,
             });
         }
-        if (!quoteId || !consumeQuote(quoteId, 'timeout')) {
-            return fail('QUOTE_REQUIRED', 'Get a quote first (call without confirm), then re-call with confirm=true and the returned quoteId (quotes are single-use and expire after 10 minutes)');
-        }
+        const check = consumeQuote(quoteId, 'timeout', spend);
+        if (!check.ok)
+            return quoteRefused(check, 'claim_timeout');
         try {
             const record = {
                 idempotencyKey,
                 kind: 'timeout',
                 stage: 'created',
                 settlement: s.mode,
+                chainId: s.chainId,
                 taskId: Number(detail.taskId),
+                fromStatus: status,
                 taskHash: detail.taskHash,
                 amountWei: detail.amount,
                 createdAt: new Date().toISOString(),
@@ -1072,6 +1245,9 @@ export function registerRentTools(server, cfg, walletCtx) {
             };
             putSpend(record);
             const done = await sendRefund(record);
+            if (done.outcome === 'escalate') {
+                return ok({ ...done, hint: 'Sent for review: nothing was refunded. An admin rules on the delivered work; with no ruling within 14 days the worker is paid.' });
+            }
             return ok({ ...done, refunded: refundAmount(detail), hint: 'Escrow returned to the posting wallet.' });
         }
         catch (err) {
@@ -1104,7 +1280,7 @@ export function registerRentTools(server, cfg, walletCtx) {
         title: 'Fetch a Task Brief',
         description: "Download a task's brief by rootHash (accept_task returns it). Public briefs come back as text. For a PRIVATE brief pass the wrappedKey accept_task returned: it is decrypted with BLINDMARKET_PRIVATE_KEY, which must be the key whose public half you registered (wallet_status shows it as executorPublicKey).",
         inputSchema: {
-            rootHash: z.string().min(32).max(80).describe('rootHash from accept_task or list_open_tasks'),
+            rootHash: z.string().min(32).max(80).describe('rootHash from accept_task (browse_a2a_tasks also shows it for a public task)'),
             wrappedKey: z.string().optional().describe('ECIES-wrapped AES key from accept_task (hex, no 0x). Required for private briefs.'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
@@ -1222,6 +1398,17 @@ export function registerRentTools(server, cfg, walletCtx) {
                 }
                 const tx = sub.unsignedSubmitEvidence;
                 await verifyTarget(s, tx.to, 'submitEvidence');
+                // A zero-value submitEvidence for this task, committing THIS output
+                // (keccak256 of the JSON /submit hashes, backend/src/routes/a2a.ts).
+                // /rebroadcast re-sends the first stored output, so there only the
+                // task is checked.
+                const evidence = keccak256(toUtf8Bytes(JSON.stringify({ output })));
+                assertEscrowCall(tx, 'submitEvidence', (a) => a[0] === BigInt(detail.taskId) && (healed || String(a[1]).toLowerCase() === evidence), 'submitEvidence');
+                // The chain it is signed for is this process's, never the backend's.
+                const pinned = s.chainId ?? walletCtx?.chainId;
+                if (tx.chainId !== undefined && pinned !== undefined && Number(tx.chainId) !== pinned) {
+                    return fail('CHAIN_MISMATCH', `The backend built submitEvidence for chain ${tx.chainId}, but this process settles ${s.mode} on chain ${pinned}. Nothing was sent.`);
+                }
                 if (s.payment === 'relay-erc20') {
                     const sent = await relaySend(s, { to: tx.to, data: tx.data });
                     submitTxHash = sent.hash;
@@ -1247,12 +1434,13 @@ export function registerRentTools(server, cfg, walletCtx) {
                         return fail('WALLET_MISMATCH', `The backend assigned this task to ${tx.from} (the wallet behind BLINDMARKET_API_KEY), but BLINDMARKET_PRIVATE_KEY is ${walletCtx.wallet.address}. submitEvidence is worker-only — set the private key of ${tx.from}.`);
                     }
                     // 0G: sign locally, exactly as fundAndIndex does for createTask.
-                    // The backend pins chainId onto the tx; ethers refuses to send it
-                    // if this wallet's provider is on a different network — the guard
-                    // against a Base tx reaching a 0G signer.
+                    // The chain id is pinned from this process's settlement (checked
+                    // against the backend's above); ethers refuses to send it if this
+                    // wallet's provider is on a different network — the guard against
+                    // a Base tx reaching a 0G signer.
                     const tx0g = await walletCtx.wallet.sendTransaction({
                         to: tx.to, data: tx.data, gasLimit: GAS_LIMIT,
-                        ...(tx.chainId !== undefined ? { chainId: tx.chainId } : {}),
+                        ...(pinned !== undefined ? { chainId: pinned } : {}),
                     });
                     submitTxHash = tx0g.hash;
                     await tx0g.wait();
@@ -1322,6 +1510,34 @@ export function registerRentTools(server, cfg, walletCtx) {
             throw coded('WRONG_RPC', `${envName} serves chain ${served}, not ${chain} (${chainId}). Nothing was paid.`);
         return walletCtx.wallet.connect(provider);
     }
+    /**
+     * The backend cannot find a deploy fee recorded before records kept its
+     * chain id, so it may have been paid on another network. Its receipt on the
+     * fee chain's RPC decides the answer, which never sends the caller back into
+     * a retry that cannot succeed. Found there, the backend has not seen it yet:
+     * the record takes that chain id, and the same key finishes the deploy.
+     */
+    async function unchainedFeeNotFound(idempotencyKey, hash, fee) {
+        let found = null;
+        if (fee) {
+            try {
+                const w = await walletOn(fee.chain, fee.chainId);
+                found = (await w.provider.getTransactionReceipt(hash))?.status === 1;
+            }
+            catch { /* not checkable from here */ }
+        }
+        if (fee && found) {
+            if (fee.chainId !== undefined)
+                updateSpend(idempotencyKey, { chainId: fee.chainId });
+            return fail('DEPLOY_FEE_NOT_FOUND', `The deploy fee ${hash} is on ${fee.chain}, but the backend has not seen it yet. Retry with the same idempotencyKey in a minute; nothing is paid again.`);
+        }
+        if (fee && found === false) {
+            return fail('SETTLEMENT_CHANGED', `The deploy fee ${hash} was recorded without its chain, and it is not on ${fee.chain}${fee.chainId !== undefined ? ` (chain ${fee.chainId})` : ''}, where the backend takes the fee now: it was paid on another network and does not count here. ` +
+                `Nothing was paid again: deploy with a new idempotencyKey to pay on ${fee.chain}.`);
+        }
+        return fail('DEPLOY_FEE_NOT_FOUND', `The backend cannot find the deploy fee ${hash}, which was recorded without its chain, and it could not be checked here. It may have been paid on another network, where it does not count. ` +
+            'Nothing was paid again: find where it landed before paying with a new idempotencyKey.');
+    }
     server.registerTool('deploy_agent', {
         title: 'Deploy a Hosted Agent',
         description: "Deploy a hosted agent that runs on BlindMarket and takes tasks, owned by the API key's wallet. Deploying costs a fee (1 USDC on Arc on production), paid as one USDC transfer on Arc from the local wallet (BLINDMARKET_PRIVATE_KEY), which must be the API key's owner. The model provider's key is read from this server's environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY or GEMINI_API_KEY; none for 0g-compute), never passed as an argument. TWO-STEP quote/confirm like post_task; requires a unique idempotencyKey, and a retry with the same key never pays twice.",
@@ -1397,14 +1613,26 @@ export function registerRentTools(server, cfg, walletCtx) {
             return ok({ resumed: true, agentId: existing.agentId, feeTxHash: existing.txHash, hint: 'Already deployed with this idempotencyKey.' });
         }
         if (existing?.stage === 'sent' && existing.txHash) {
-            // Paid before: finish the deploy with that payment.
+            // Paid before: finish the deploy with that payment. It counts only on
+            // the network it was paid on, and a chain keeps its key when the
+            // backend moves it to another one, so the chain ids decide.
+            const current = await api('GET', '/api/v1/agents/deploy-fee').catch(() => null);
+            const currentFee = current?.required && current.method === 'transfer' ? current : null;
+            if (existing.chainId !== undefined && currentFee?.chainId !== undefined && currentFee.chainId !== existing.chainId) {
+                return fail('SETTLEMENT_CHANGED', `The deploy fee for ${idempotencyKey} was paid on chain ${existing.chainId} (${existing.txHash}), but the backend takes it on chain ${currentFee.chainId} now, where that payment does not count. ` +
+                    `Nothing was paid again: deploy with a new idempotencyKey to pay on chain ${currentFee.chainId}.`);
+            }
             try {
                 const agent = await deploy(existing.txHash);
                 updateSpend(idempotencyKey, { stage: 'confirmed', agentId: agent.id });
                 return ok({ resumed: true, ...summary(agent), feeTxHash: existing.txHash });
             }
             catch (err) {
-                return fail(err.code ?? 'DEPLOY_FAILED', `${err.message}.${paidNote()}`);
+                const code = err.code;
+                if (code === 'DEPLOY_FEE_NOT_FOUND' && existing.chainId === undefined) {
+                    return unchainedFeeNotFound(idempotencyKey, existing.txHash, currentFee);
+                }
+                return fail(code ?? 'DEPLOY_FAILED', `${err.message}.${paidNote()}`);
             }
         }
         let terms;
@@ -1419,6 +1647,24 @@ export function registerRentTools(server, cfg, walletCtx) {
         }
         const fee = terms.required ? terms : null;
         const feeText = fee ? `${formatUnits(BigInt(fee.amountRaw), fee.decimals).replace(/\.0$/, '')} USDC` : 'none';
+        // The fee terms and the agent this call would pay for, bound into the
+        // quote: the confirm re-reads the terms, and pays only what was quoted.
+        const spend = {
+            idempotencyKey,
+            payFrom: walletCtx.wallet.address.toLowerCase(),
+            name,
+            provider,
+            model,
+            instructions: sha256Hex(Buffer.from(instructions, 'utf8')),
+            skills: JSON.stringify(skillSlugs ?? []),
+            feeRequired: fee !== null,
+            feeChain: fee?.chain ?? null,
+            feeChainId: fee?.chainId ?? null,
+            feeToken: fee ? String(fee.token).toLowerCase() : null,
+            feeRecipient: fee ? String(fee.recipient).toLowerCase() : null,
+            feeAmountRaw: fee ? String(fee.amountRaw) : null,
+            feeDecimals: fee?.decimals ?? null,
+        };
         if (!confirm) {
             const invalid = await validate();
             if (invalid)
@@ -1436,7 +1682,7 @@ export function registerRentTools(server, cfg, walletCtx) {
                     }
                 }
             }
-            const quote = createQuote('deploy', { name, provider, model, fee: feeText });
+            const quote = createQuote('deploy', { name, provider, model, fee: feeText }, spend);
             return ok({
                 quote: {
                     agent: { name, provider, model, skills: skillSlugs ?? [] },
@@ -1450,8 +1696,12 @@ export function registerRentTools(server, cfg, walletCtx) {
                 next: `Re-call deploy_agent with confirm=true, quoteId="${quote.quoteId}", and the SAME idempotencyKey to ${fee ? 'pay the fee and ' : ''}deploy.`,
             });
         }
-        if (!quoteId || !consumeQuote(quoteId, 'deploy')) {
-            return fail('QUOTE_REQUIRED', 'Get a quote first (call without confirm), then re-call with confirm=true and the returned quoteId (quotes are single-use and expire after 10 minutes)');
+        const check = consumeQuote(quoteId, 'deploy', spend);
+        if (!check.ok) {
+            const feeChanged = check.code === 'QUOTE_MISMATCH' && check.changed.some((k) => k.startsWith('fee'))
+                ? `the deploy fee changed since the quote (quoted ${check.quote.summary.fee}, now ${feeText}${fee ? ` to ${fee.recipient} on ${fee.chain}` : ''})`
+                : undefined;
+            return quoteRefused(check, 'deploy_agent', feeChanged);
         }
         try {
             const now = new Date().toISOString();
@@ -1466,7 +1716,7 @@ export function registerRentTools(server, cfg, walletCtx) {
                 if (invalid)
                     return invalid;
                 const w = await walletOn(fee.chain, fee.chainId);
-                putSpend({ idempotencyKey, kind: 'deploy', stage: 'created', settlement: fee.chain, token: fee.token, amountWei: fee.amountRaw, createdAt: now, updatedAt: now });
+                putSpend({ idempotencyKey, kind: 'deploy', stage: 'created', settlement: fee.chain, chainId: fee.chainId, token: fee.token, amountWei: fee.amountRaw, createdAt: now, updatedAt: now });
                 const data = new Interface(['function transfer(address to, uint256 amount) returns (bool)'])
                     .encodeFunctionData('transfer', [fee.recipient, BigInt(fee.amountRaw)]);
                 const tx = await w.sendTransaction({ to: fee.token, data });
@@ -1491,6 +1741,7 @@ export function registerRentTools(server, cfg, walletCtx) {
             updateSpend(idempotencyKey, { stage: 'confirmed', agentId: agent.id });
             return ok({
                 ...summary(agent),
+                fee: feeText,
                 feeTxHash,
                 hint: agent.started ? 'The agent is running.' : 'The agent was created but did not start — start it with start_agent.',
             });