@blindmarket/sdk 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 This package is 0.x: a minor version may contain breaking changes. They are
 listed here with how to migrate.
 
+## 0.8.0
+
+### Breaking / behaviour changes
+
+- **Escrow calls are verified before signing (C41).** `sdk/src/escrowCalls.ts`
+  decodes the backend-built tx before anything is signed and checks it is
+  exactly the expected function (`createTask`, `cancelTask`/`claimTimeout`,
+  `submitEvidence`) with the expected arguments, canonical calldata with no
+  trailing bytes, targeting the escrow from `/health/settlement` for the named
+  chain, carrying no value (except a native `createTask` where value must equal
+  the computed amount), and — for `/submit` — an evidence hash equal to
+  `keccak256(JSON.stringify(resultData))`. Only `{ to, data }` is signed.
+  Anything else fails with `ESCROW_MISMATCH`, `TX_MISMATCH`, `CHAIN_MISMATCH`
+  or `CHAIN_UNKNOWN` before any signature.
+- **`deliverResult` reads `/health/settlement` first** to resolve the escrow.
+- **`WorkerRuntime` applies `minReward` when picking tasks (C40).** Browse
+  skips listings whose reward is missing, malformed, not 6-decimal USDC, or
+  below the floor. Values of 10^12 or more are treated as legacy 18-decimal
+  and divided down. Unset, `''` or `'0'` means no floor. Requires the backend
+  `/accept` gate from #89 (403 `BELOW_MIN_REWARD`); a runtime with `minReward`
+  set claims nothing until listings carry `meta.reward`, so deploy the backend
+  first.
+- **`start()` validates `minReward`.** A non-whole-number floor throws.
+- **Timeout-claim escalation (C18).** After the escrow upgrade, `claimTimeout`
+  on a Submitted task sends delivered work for review instead of refunding.
+  `RefundResult.outcome` reports `'escalate'` (from `POST /tasks/:id/timeout`).
+- **`list_open_tasks` / `listTasks()` list the legacy 0G registry** and point
+  to `browse_a2a_tasks`. `fetch_brief` no longer says a `rootHash` comes from
+  `list_open_tasks`.
+
 ## 0.7.0
 
 ### Changes

package/README.md

@@ -170,6 +170,11 @@ await bb.cancelAndRefund(task.taskId!);
 await bb.reclaimAfterTimeout(task.taskId!);
 ```
 
+`reclaimAfterTimeout()` refunds a task whose worker never delivered. Work that
+was delivered before the deadline and never judged is not refunded: the
+escrow sends the task for review (an admin rules, and with no ruling within
+14 days the worker is paid), and the result says `outcome: 'escalate'`.
+
 If the process dies after the escrow is funded but before the task is listed,
 nothing is lost: `onFunded` got the funding hash, and any error after funding
 carries it (`err.txHash`) with the listing body in `err.body.indexParams`.
@@ -180,6 +185,19 @@ The lower-level builders are unchanged: `createTask()`, `cancelTask()` and
 `claimTimeout()` return unsigned transactions, now with the `chain` and
 `chainId` to send them on.
 
+**What the client signs.** `postTask()`, `cancelAndRefund()`,
+`reclaimAfterTimeout()` and `deliverResult()` sign transactions the backend
+builds, so each one is decoded and checked first: it must be exactly the call
+asked for (`createTask` with this task hash, token, amount, zone and duration;
+`cancelTask` / `claimTimeout` for this task id; `submitEvidence` for this task,
+committing the result just sent) on the escrow `/health/settlement` lists for
+the chain, with no value (`postTask` sends the amount it computed on a native
+chain), and a refund must be on the chain you named. Only `to` and `data` are
+signed; gas, fee, nonce, type and chain id fields from the backend are dropped.
+Anything else throws before signing: `ESCROW_MISMATCH` (another target),
+`TX_MISMATCH` (another function or arguments, or a value), `CHAIN_MISMATCH`
+(another chain) or `CHAIN_UNKNOWN` (a chain with no listed escrow).
+
 ```ts
 const tasks = await bb.listTasks();
 const detail = await bb.getTask(taskId);
@@ -272,7 +290,9 @@ const { rootHash, wrappedKey, privacy } = accepted;
 // Deliver: /submit → sign + broadcast submitEvidence → /finalize.
 // submitResult() alone only BUILDS the unsigned tx and marks the task
 // 'submitted'; stopping there strands it. deliverResult() does all three and
-// heals a stranded task through rebroadcast().
+// heals a stranded task through rebroadcast(). It signs only a zero-value
+// submitEvidence on the task chain's escrow committing this result (see
+// "What the client signs" above).
 await bb.deliverResult(taskId, { output: 'Task completed successfully' });
 
 // Manual healing, if you drive submitResult()/finalize() yourself:
@@ -340,8 +360,18 @@ it fails the task before running your handler if the response names a chain it
 has no RPC for (that task is already assigned — this only covers rows with no
 `meta.chain`).
 
+**What keeps the runtime off tasks below its floor.** With `minReward` set (a
+whole number of USDC base units: `'1000000'` is 1 USDC), browse claims only
+listings whose recorded reward (`meta.reward`, written by the backend from the
+funding event) is in USDC and at least `minReward`. A listing with no recorded
+reward, or one in another unit, is skipped: a poster can escrow a single base
+unit, and the handler run and the `submitEvidence` gas are yours. Newer
+backends also refuse such an `/accept` (403 `BELOW_MIN_REWARD`). Without
+`minReward` (or with `'0'`) every task is claimed, as before; in restore mode
+the floor the executor is registered with applies.
+
 The loop it runs: browse (`{ meta, state }` entries, `open` only, skipping a
-chain it did not declare) → `/accept` → decrypt → `executeTask` →
+chain it did not declare or a task below `minReward`) → `/accept` → decrypt → `executeTask` →
 `deliverResult()` (submit, sign, finalize, with `/rebroadcast` healing). How
 `/accept` failures are handled:
 

package/dist/chain/abi/BlindEscrow.json

@@ -1109,5 +1109,159 @@
         ],
         "stateMutability": "view",
         "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "AppealWindowActive",
+        "type": "error"
+    },
+    {
+        "inputs": [],
+        "name": "DisputeWindowActive",
+        "type": "error"
+    },
+    {
+        "inputs": [],
+        "name": "EscalatedForAdjudication",
+        "type": "error"
+    },
+    {
+        "inputs": [],
+        "name": "NotEscalated",
+        "type": "error"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "internalType": "uint256",
+                "name": "taskId",
+                "type": "uint256"
+            }
+        ],
+        "name": "UnjudgedWorkEscalated",
+        "type": "event"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "internalType": "uint256",
+                "name": "taskId",
+                "type": "uint256"
+            },
+            {
+                "indexed": false,
+                "internalType": "uint256",
+                "name": "workerPayout",
+                "type": "uint256"
+            },
+            {
+                "indexed": false,
+                "internalType": "uint256",
+                "name": "platformFee",
+                "type": "uint256"
+            }
+        ],
+        "name": "UnjudgedWorkReleased",
+        "type": "event"
+    },
+    {
+        "inputs": [],
+        "name": "APPEAL_WINDOW",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [],
+        "name": "DISPUTE_WINDOW",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "uint256",
+                "name": "taskId",
+                "type": "uint256"
+            }
+        ],
+        "name": "effectiveDeadline",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "uint256",
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "name": "failedVerdictAt",
+        "outputs": [
+            {
+                "internalType": "uint256",
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "uint256",
+                "name": "taskId",
+                "type": "uint256"
+            }
+        ],
+        "name": "releaseUnjudgedWork",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "uint256",
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "name": "unjudgedEscalation",
+        "outputs": [
+            {
+                "internalType": "bool",
+                "name": "",
+                "type": "bool"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
     }
 ]

package/dist/escrowCalls.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The only transactions a backend may hand this client to sign.
+ *
+ * The backend builds createTask, submitEvidence, cancelTask and claimTimeout
+ * for the client's own key to sign. Whoever answers at `apiBase` (a
+ * compromised or malicious backend, an untrusted apiBase, a network attacker
+ * on plain http) controls that JSON, so a client that signs it as given signs
+ * anything: a native transfer, an ERC-20 approve or transfer, on any chain it
+ * has an RPC for. Before a key signs, the transaction is decoded and checked
+ * to be exactly the escrow call the caller asked for, with zero value (or the
+ * escrow amount the client computed itself), and only `{ to, data }` is kept.
+ * Gas, fee, nonce, type and chainId fields from the backend are never
+ * forwarded (security audit run 1, C41).
+ *
+ * The escrow address itself comes from the same backend (/health/settlement),
+ * so the target check catches misrouting; the function, argument and value
+ * checks are what bound a malicious answer.
+ */
+import { ethers } from 'ethers';
+export declare const ESCROW_CALLS: ethers.Interface;
+export type EscrowFunction = 'createTask' | 'createTaskWithVerifier' | 'submitEvidence' | 'cancelTask' | 'claimTimeout';
+/**
+ * The evidence hash the backend commits for a result: keccak256 of the UTF-8
+ * JSON of `resultData`, exactly as POST /a2a/tasks/:id/submit computes it
+ * (backend/src/routes/a2a.ts). JSON.stringify of the parsed request body gives
+ * the same string the client serialized.
+ */
+export declare function evidenceHashOf(resultData: Record<string, unknown>): string;
+export interface ExpectedEscrowCall {
+    /** The escrow the transaction must target. */
+    escrow: string;
+    fn: EscrowFunction;
+    /** The decoded arguments must satisfy this. */
+    args: (args: ethers.Result) => boolean;
+    /** The only value the backend may name (default 0). A transaction that names none is fine: it is never forwarded. */
+    value?: bigint;
+    /** When the backend's transaction names a chainId, it must be this one. */
+    chainId?: number;
+}
+/**
+ * Check a backend-built transaction is exactly `expect`, and return the only
+ * fields the client signs. Throws, with nothing sent: ESCROW_MISMATCH for
+ * another target, CHAIN_MISMATCH for another chain id, TX_MISMATCH for
+ * another function, other arguments, non-canonical calldata or a value.
+ */
+export declare function checkEscrowCall(tx: unknown, expect: ExpectedEscrowCall, what: string): {
+    to: string;
+    data: string;
+};
+/** `id` as a uint256 task id, or undefined when it is not a whole number. */
+export declare function taskIdOf(id: unknown): bigint | undefined;

package/dist/escrowCalls.js

@@ -0,0 +1,95 @@
+/**
+ * The only transactions a backend may hand this client to sign.
+ *
+ * The backend builds createTask, submitEvidence, cancelTask and claimTimeout
+ * for the client's own key to sign. Whoever answers at `apiBase` (a
+ * compromised or malicious backend, an untrusted apiBase, a network attacker
+ * on plain http) controls that JSON, so a client that signs it as given signs
+ * anything: a native transfer, an ERC-20 approve or transfer, on any chain it
+ * has an RPC for. Before a key signs, the transaction is decoded and checked
+ * to be exactly the escrow call the caller asked for, with zero value (or the
+ * escrow amount the client computed itself), and only `{ to, data }` is kept.
+ * Gas, fee, nonce, type and chainId fields from the backend are never
+ * forwarded (security audit run 1, C41).
+ *
+ * The escrow address itself comes from the same backend (/health/settlement),
+ * so the target check catches misrouting; the function, argument and value
+ * checks are what bound a malicious answer.
+ */
+import { ethers } from 'ethers';
+import { ApiError } from './apiError.js';
+export const ESCROW_CALLS = new ethers.Interface([
+    'function createTask(bytes32 taskHash, address token, uint256 amount, string category, string locationZone, uint256 duration)',
+    'function createTaskWithVerifier(bytes32 taskHash, address token, uint256 amount, string category, string locationZone, uint256 duration, address verifierAgent)',
+    'function submitEvidence(uint256 taskId, bytes32 evidenceHash)',
+    'function cancelTask(uint256 taskId)',
+    'function claimTimeout(uint256 taskId)',
+]);
+/**
+ * The evidence hash the backend commits for a result: keccak256 of the UTF-8
+ * JSON of `resultData`, exactly as POST /a2a/tasks/:id/submit computes it
+ * (backend/src/routes/a2a.ts). JSON.stringify of the parsed request body gives
+ * the same string the client serialized.
+ */
+export function evidenceHashOf(resultData) {
+    return ethers.keccak256(ethers.toUtf8Bytes(JSON.stringify(resultData)));
+}
+/**
+ * Check a backend-built transaction is exactly `expect`, and return the only
+ * fields the client signs. Throws, with nothing sent: ESCROW_MISMATCH for
+ * another target, CHAIN_MISMATCH for another chain id, TX_MISMATCH for
+ * another function, other arguments, non-canonical calldata or a value.
+ */
+export function checkEscrowCall(tx, expect, what) {
+    const t = (tx !== null && typeof tx === 'object' ? tx : {});
+    if (typeof t.to !== 'string' || t.to.toLowerCase() !== expect.escrow.toLowerCase()) {
+        throw new ApiError(409, `${what}: the backend built the transaction for ${String(t.to)}, not the escrow ${expect.escrow}. Nothing was sent.`, undefined, 'ESCROW_MISMATCH');
+    }
+    if (expect.chainId !== undefined && t.chainId != null && Number(t.chainId) !== expect.chainId) {
+        throw new ApiError(409, `${what}: the backend built the transaction for chain ${String(t.chainId)}, not chain ${expect.chainId}. Nothing was sent.`, undefined, 'CHAIN_MISMATCH');
+    }
+    const data = typeof t.data === 'string' ? t.data.toLowerCase() : '';
+    let args;
+    try {
+        const decoded = ESCROW_CALLS.decodeFunctionData(expect.fn, data);
+        // Canonical ABI encoding only: nothing may ride along after the arguments.
+        if (ESCROW_CALLS.encodeFunctionData(expect.fn, decoded).toLowerCase() === data)
+            args = decoded;
+    }
+    catch {
+        // Another function, or not ABI data at all.
+    }
+    let valueOk = t.value == null;
+    if (!valueOk) {
+        try {
+            valueOk = ethers.getBigInt(t.value) === (expect.value ?? 0n);
+        }
+        catch {
+            valueOk = false;
+        }
+    }
+    let argsOk = false;
+    if (args) {
+        try {
+            argsOk = expect.args(args);
+        }
+        catch {
+            argsOk = false;
+        }
+    }
+    if (!args || !argsOk || !valueOk) {
+        const why = !args ? `is not a ${expect.fn} call` : !argsOk ? `is a ${expect.fn} call with other arguments than this one` : 'carries a value';
+        throw new ApiError(409, `${what}: the transaction the backend built ${why}. Only the escrow call you asked for is signed. Nothing was sent.`, undefined, 'TX_MISMATCH');
+    }
+    return { to: ethers.getAddress(expect.escrow.toLowerCase()), data };
+}
+/** `id` as a uint256 task id, or undefined when it is not a whole number. */
+export function taskIdOf(id) {
+    if (typeof id === 'bigint')
+        return id;
+    if (typeof id === 'number' && Number.isSafeInteger(id) && id >= 0)
+        return BigInt(id);
+    if (typeof id === 'string' && /^\d+$/.test(id))
+        return BigInt(id);
+    return undefined;
+}

package/dist/executor/WorkerRuntime.d.ts

@@ -28,6 +28,17 @@ export interface WorkerRuntimeConfig {
     existingAddress?: string;
     /** @deprecated Ignored — the public key is derived from `existingPrivateKey`. */
     existingPublicKey?: string;
+    /**
+     * The least a task must pay for this runtime to take it: a whole number of
+     * the pricing token's smallest unit (USDC, 6 decimals: '1000000' is 1 USDC).
+     * Registered with the executor, and applied where tasks are picked: browse
+     * claims only listings whose recorded reward (`meta.reward`) is in USDC and
+     * at least this much. A listing with no recorded reward, or one in another
+     * unit, is skipped. Unset (or '0') takes every task, as before. In restore
+     * mode (`existingPrivateKey`) the registered floor applies when this is
+     * unset. A floor of 10^12 or more is read as the old 18-decimal units, as
+     * the backend reads it.
+     */
     minReward?: string;
     preferredCapabilities?: AgentCapability[];
     browseIntervalMs?: number;
@@ -154,6 +165,8 @@ export declare class WorkerRuntime {
     private retries;
     private retryTimers;
     private listeners;
+    /** Set once the runtime has said it skips listings with no recorded reward. */
+    private warnedNoReward;
     constructor(config: WorkerRuntimeConfig);
     get isRunning(): boolean;
     get isPaused(): boolean;
@@ -209,6 +222,13 @@ export declare class WorkerRuntime {
     resume(): void;
     private startBrowseLoop;
     private browse;
+    /**
+     * The floor browse applies: `minReward`, else (restore mode) the floor the
+     * executor is registered with. Undefined: no floor.
+     */
+    private get minRewardFloor();
+    /** Whether a listing clears the floor (always, without one). */
+    private meetsFloor;
     /** Executions holding a concurrency slot. A task waiting for a wrap or backing off holds none. */
     private inFlight;
     /**

package/dist/executor/WorkerRuntime.js

@@ -62,6 +62,43 @@ class AcceptAbandoned extends Error {
     }
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * The unit minReward is written in: the pricing token's smallest unit, USDC
+ * with 6 decimals (CreateAgentParams.minReward), the backend's pricing unit on
+ * every chain it settles on. A reward in any other unit cannot be compared.
+ */
+const MIN_REWARD_UNIT = { symbol: 'USDC', decimals: 6 };
+/**
+ * 10^12 base units is 1,000,000 USDC, no plausible floor: the backend reads a
+ * floor at or above it as the old 18-decimal units and stores it divided by
+ * 10^12, rounded up (normalizeSettlementAmount in
+ * backend/src/services/settlementUnits.ts). The runtime applies the floor the
+ * backend holds the executor to.
+ */
+const LEGACY_SCALE = 10n ** 12n;
+/** A minReward as the backend holds it, in USDC base units; undefined for no floor (unset, empty, malformed or zero). */
+function rewardFloor(raw) {
+    if (typeof raw !== 'string' || !/^\d+$/.test(raw))
+        return undefined;
+    const value = BigInt(raw);
+    const floor = value >= LEGACY_SCALE ? (value + LEGACY_SCALE - 1n) / LEGACY_SCALE : value;
+    return floor === 0n ? undefined : floor;
+}
+/**
+ * Whether a listing's recorded reward clears `floor`. A missing reward, a
+ * malformed one, or one in another unit never does: comparing a floor with
+ * something it cannot price would let a 1-base-unit task through.
+ */
+function clearsRewardFloor(meta, floor) {
+    const reward = meta?.reward;
+    if (!reward || typeof reward !== 'object')
+        return false;
+    if (reward.unit?.symbol !== MIN_REWARD_UNIT.symbol || reward.unit?.decimals !== MIN_REWARD_UNIT.decimals)
+        return false;
+    if (typeof reward.amount !== 'string' || !/^\d+$/.test(reward.amount))
+        return false;
+    return BigInt(reward.amount) >= floor;
+}
 /** base, 2·base, 4·base … capped. `n` is 1 for the first failure. */
 function backoff(base, n, cap) {
     return Math.min(base * 2 ** Math.max(0, n - 1), cap);
@@ -79,6 +116,8 @@ export class WorkerRuntime {
     retries = new Map();
     retryTimers = new Set();
     listeners = new Set();
+    /** Set once the runtime has said it skips listings with no recorded reward. */
+    warnedNoReward = false;
     constructor(config) {
         this.config = { ...DEFAULTS, ...config };
         this.bb = new BlindMarket({ apiKey: config.apiKey, apiBase: config.apiBase });
@@ -132,6 +171,10 @@ export class WorkerRuntime {
                 "owner's registered public key and strand every task it accepted. To only look at tasks, call " +
                 'BlindMarket.browseA2ATasks() directly.');
         }
+        const minReward = this.config.minReward;
+        if (minReward !== undefined && minReward !== '' && !/^\d+$/.test(minReward)) {
+            throw new Error(`[WorkerRuntime] minReward must be a whole number of the pricing token's smallest unit (USDC has 6 decimals: '1000000' is 1 USDC), not ${JSON.stringify(minReward)}.`);
+        }
         if (this.declaredChains.length === 0) {
             throw new Error('[WorkerRuntime] no RPC configured. Set `rpcUrls.arc` (where production posts new tasks), `rpcUrls.base` and/or `rpcUrl` (0G) to the network the backend at ' +
                 '`apiBase` settles on. There is no default: submitEvidence is signed on this RPC after the task is already ' +
@@ -317,6 +360,12 @@ export class WorkerRuntime {
                 // no chain) is what keeps such tasks out.
                 if (entry.meta?.chain && !this.declaredChains.includes(entry.meta.chain))
                     continue;
+                // Nor a task below this runtime's minReward: the handler run and the
+                // submitEvidence gas are the operator's, and a poster can escrow 1
+                // base unit. Newer backends also refuse such an /accept (403
+                // BELOW_MIN_REWARD); older ones apply the floor only when ranking offers.
+                if (!this.meetsFloor(entry.meta))
+                    continue;
                 this.claim(taskId, state, entry.meta);
             }
             // Tasks that may still be held for this executor are not in the open
@@ -334,6 +383,28 @@ export class WorkerRuntime {
             this.emit({ type: 'error', error: `Browse failed: ${err}` });
         }
     }
+    /**
+     * The floor browse applies: `minReward`, else (restore mode) the floor the
+     * executor is registered with. Undefined: no floor.
+     */
+    get minRewardFloor() {
+        const configured = this.config.minReward;
+        return rewardFloor(configured !== undefined && configured !== '' ? configured : this.profile?.minReward);
+    }
+    /** Whether a listing clears the floor (always, without one). */
+    meetsFloor(meta) {
+        const floor = this.minRewardFloor;
+        if (floor === undefined)
+            return true;
+        if (clearsRewardFloor(meta, floor))
+            return true;
+        if (meta?.reward === undefined && !this.warnedNoReward) {
+            this.warnedNoReward = true;
+            console.warn(`[WorkerRuntime] minReward is set (${floor} USDC base units), so tasks listed without a recorded reward are skipped. ` +
+                'A backend older than the reward field lists none: unset minReward to take them.');
+        }
+        return false;
+    }
     /** Executions holding a concurrency slot. A task waiting for a wrap or backing off holds none. */
     inFlight() {
         let n = 0;

package/dist/index.d.ts

@@ -208,6 +208,14 @@ export interface RefundResult {
     chainId: number;
     /** Whether the backend took the task off the market. False leaves it listed until its deadline; the refund stands either way. */
     listingClosed: boolean;
+    /**
+     * What the transaction did, when the backend says: 'refund' returned the
+     * escrow to the poster; 'escalate' (reclaimAfterTimeout on work delivered
+     * before the deadline and never judged) sent the task for review and
+     * refunded nothing. An admin rules on it, and with no ruling within 14 days
+     * the worker is paid.
+     */
+    outcome?: 'refund' | 'escalate';
 }
 export interface RefundOptions {
     /** Signs on the task's chain instead of the configured executor. */
@@ -297,7 +305,11 @@ export declare class BlindMarket {
     health(): Promise<HealthStatus>;
     /** Live platform counts. */
     stats(): Promise<PlatformStats>;
-    /** List open tasks (human-readable). */
+    /**
+     * List open tasks from the legacy 0G TaskRegistry (numeric ids on the 0G
+     * escrow). Tasks escrowed on Base or Arc are not in it: browseA2ATasks()
+     * lists the work agents can take.
+     */
     listTasks(limit?: number): Promise<OpenTask[]>;
     /** Get full task details (on-chain + A2A state). */
     getTask(id: string): Promise<TaskDetail>;
@@ -327,11 +339,16 @@ export declare class BlindMarket {
     /**
      * Build an unsigned `claimTimeout` transaction (the refund of a task whose
      * deadline passed). reclaimAfterTimeout() builds, signs and sends it for you.
+     * `outcome` says what it will do: on work delivered before the deadline and
+     * never judged, the escrow sends the task for review ('escalate') instead
+     * of refunding it, and `message` explains.
      */
     claimTimeout(taskId: string, chain?: string): Promise<{
         unsignedTx: object;
         chain?: string;
         chainId?: number;
+        outcome?: 'refund' | 'escalate';
+        message?: string;
     }>;
     /**
      * Build an unsigned `submitEvidence` transaction.
@@ -350,6 +367,12 @@ export declare class BlindMarket {
         postingChain: string | null;
         chains: SettlementChainInfo[];
     }>;
+    /**
+     * `chain`'s entry in /health/settlement, with its escrow: every transaction
+     * the backend builds for this client to sign must target that escrow.
+     * Throws 409 CHAIN_UNKNOWN when the backend lists no escrow for it.
+     */
+    private settlementEntry;
     /**
      * Post a task end to end, from the API key's own wallet: encrypt the brief
      * (unless public) and wrap its key to the posting chain's executors, upload
@@ -359,8 +382,10 @@ export declare class BlindMarket {
      * The wallet signs locally, on the backend's posting chain (Arc on
      * production, where gas is paid in USDC). Before anything is sent it checks
      * the signer is the API key's owner, that its RPC is on the posting chain,
-     * that the wallet holds the amount, and that the backend built the tx for
-     * the escrow it advertises. The funding hash goes to `onFunded` as soon as
+     * that the wallet holds the amount, and that the backend built exactly this
+     * createTask (task hash, token, amount, zone, duration) for the escrow it
+     * advertises, with no other value: 409 ESCROW_MISMATCH / TX_MISMATCH
+     * otherwise. Only the tx's to and data are signed. The funding hash goes to `onFunded` as soon as
      * it is sent; an error after that carries it as `err.txHash`, and
      * indexTask() lists the funded task without paying again.
      *
@@ -391,16 +416,33 @@ export declare class BlindMarket {
      * then takes the task off the market (`POST /tasks/:id/confirm-tx`).
      * `taskId` is the on-chain id (PostedTask.taskId); pass `chain`
      * (PostedTask.chain) too, since ids repeat across chains.
+     *
+     * Only a zero-value `cancelTask(taskId)` on the escrow /health/settlement
+     * lists for the chain is signed (to and data only), and only on the chain
+     * you named: 409 ESCROW_MISMATCH, TX_MISMATCH, CHAIN_MISMATCH or
+     * CHAIN_UNKNOWN otherwise, with nothing sent. reclaimAfterTimeout() does
+     * the same for `claimTimeout(taskId)`.
      */
     cancelAndRefund(taskId: string, opts?: RefundOptions): Promise<RefundResult>;
-    /** Reclaim the escrow of a task whose deadline passed undelivered (claimTimeout), signed and sent. */
+    /**
+     * Reclaim the escrow of a task whose deadline passed undelivered
+     * (claimTimeout), signed and sent. On work delivered before the deadline
+     * and never judged, the escrow sends the task for review instead and
+     * refunds nothing: the result's outcome is then 'escalate'.
+     */
     reclaimAfterTimeout(taskId: string, opts?: RefundOptions): Promise<RefundResult>;
+    /**
+     * Sign the refund the backend built, once it is checked to be exactly
+     * `fn(taskId)` on the escrow of the chain it names (the one the caller
+     * named, when it named one), with no value. Only its to and data are signed.
+     */
     private sendRefund;
     /**
      * Tell the backend a refund landed (`POST /api/v1/tasks/:id/confirm-tx`),
      * which checks the receipt and takes the task off the market. Without it a
      * refunded task keeps listing as open until its deadline. Best effort: the
-     * money has already moved, so a failure here only reports false.
+     * money has already moved, so a failure here only reports it not closed.
+     * A claim that sent the task for review closes nothing (escalated).
      */
     private confirmRefund;
     /** What deploying an agent costs on this backend, and how to pay it. */
@@ -642,6 +684,13 @@ export declare class BlindMarket {
      * unsigned `submitEvidence` on the chain the backend names → `finalize()`.
      * Safe to re-call on a task stranded in 'submitted': INVALID_STATE at submit
      * and NOT_SUBMITTED_ON_CHAIN at finalize both heal through `rebroadcast()`.
+     *
+     * The executor key signs only a zero-value `submitEvidence(onChainTaskId,
+     * evidenceHash)` on the escrow /health/settlement lists for that chain,
+     * where (from /submit) evidenceHash is keccak256 of `JSON.stringify(resultData)`,
+     * over an RPC checked to serve that chain, and only its to and data.
+     * Anything else throws 409 ESCROW_MISMATCH, TX_MISMATCH, CHAIN_MISMATCH or
+     * CHAIN_UNKNOWN (or WRONG_CHAIN for the RPC) with nothing sent.
      */
     deliverResult(taskId: string, resultData: Record<string, unknown>, signerOverride?: DeliverSigner): Promise<Awaited<ReturnType<BlindMarket['finalize']>> & {
         submitTxHash?: string;

package/dist/index.js

@@ -2,6 +2,7 @@ import { ethers } from 'ethers';
 import { ApiError } from './apiError.js';
 import { sendAndWait, assertSignerChain, ensureAllowance, tokenBalance, UnconfirmedTransactionError, DEFAULT_CONFIRM_TIMEOUT_MS, } from './onchain.js';
 import { generateAesKey, aesEncrypt, eciesEncrypt, sha256, bytesToHex } from './crypto/index.js';
+import { checkEscrowCall, evidenceHashOf, taskIdOf } from './escrowCalls.js';
 /** A whole number of base units from a string or bigint; throws 400 INVALID_AMOUNT otherwise. */
 function wholeNumber(value, name) {
     if (typeof value === 'bigint')
@@ -99,7 +100,11 @@ export class BlindMarket {
         return this.req('GET', '/api/v1/stats');
     }
     // ── Task lifecycle ──────────────────────────────────────────────────────
-    /** List open tasks (human-readable). */
+    /**
+     * List open tasks from the legacy 0G TaskRegistry (numeric ids on the 0G
+     * escrow). Tasks escrowed on Base or Arc are not in it: browseA2ATasks()
+     * lists the work agents can take.
+     */
     async listTasks(limit = 20) {
         const { tasks } = await this.req('GET', `/api/v1/tasks?limit=${limit}`);
         return tasks;
@@ -135,6 +140,9 @@ export class BlindMarket {
     /**
      * Build an unsigned `claimTimeout` transaction (the refund of a task whose
      * deadline passed). reclaimAfterTimeout() builds, signs and sends it for you.
+     * `outcome` says what it will do: on work delivered before the deadline and
+     * never judged, the escrow sends the task for review ('escalate') instead
+     * of refunding it, and `message` explains.
      */
     async claimTimeout(taskId, chain) {
         return this.req('POST', `/api/v1/tasks/${taskId}/timeout`, chain ? { chain } : undefined);
@@ -153,6 +161,19 @@ export class BlindMarket {
     async getSettlement() {
         return this.req('GET', '/health/settlement');
     }
+    /**
+     * `chain`'s entry in /health/settlement, with its escrow: every transaction
+     * the backend builds for this client to sign must target that escrow.
+     * Throws 409 CHAIN_UNKNOWN when the backend lists no escrow for it.
+     */
+    async settlementEntry(chain, what, settlement) {
+        const { chains } = settlement ?? await this.getSettlement();
+        const entry = chains.find((c) => c.chain === chain);
+        if (!entry?.escrowAddress || !Number.isInteger(entry.chainId)) {
+            throw new ApiError(409, `${what}: the backend lists no escrow for ${chain} (GET /health/settlement), so a transaction built for it cannot be checked before signing. Nothing was sent.`, undefined, 'CHAIN_UNKNOWN');
+        }
+        return entry;
+    }
     /**
      * Post a task end to end, from the API key's own wallet: encrypt the brief
      * (unless public) and wrap its key to the posting chain's executors, upload
@@ -162,8 +183,10 @@ export class BlindMarket {
      * The wallet signs locally, on the backend's posting chain (Arc on
      * production, where gas is paid in USDC). Before anything is sent it checks
      * the signer is the API key's owner, that its RPC is on the posting chain,
-     * that the wallet holds the amount, and that the backend built the tx for
-     * the escrow it advertises. The funding hash goes to `onFunded` as soon as
+     * that the wallet holds the amount, and that the backend built exactly this
+     * createTask (task hash, token, amount, zone, duration) for the escrow it
+     * advertises, with no other value: 409 ESCROW_MISMATCH / TX_MISMATCH
+     * otherwise. Only the tx's to and data are signed. The funding hash goes to `onFunded` as soon as
      * it is sent; an error after that carries it as `err.txHash`, and
      * indexTask() lists the funded task without paying again.
      *
@@ -185,6 +208,7 @@ export class BlindMarket {
             throw new ApiError(400, 'durationSeconds must be a whole number from 3600 (1 hour) to 7776000 (90 days): the escrow refuses anything else. Nothing was sent.', undefined, 'INVALID_DURATION');
         }
         const privacy = params.privacy ?? 'private';
+        const locationZone = params.locationZone ?? 'global';
         const verificationMode = params.verificationMode ?? 'auto';
         const verificationCriteria = params.verificationCriteria
             ?? (verificationMode === 'auto' ? { min_length: 10, pass_threshold: 60 } : undefined);
@@ -251,7 +275,7 @@ export class BlindMarket {
             taskHash: taskHash,
             token: token,
             amount: amount.toString(),
-            locationZone: params.locationZone ?? 'global',
+            locationZone,
             duration: String(duration),
             targetExecutorType: 'agent',
             verificationMode,
@@ -266,9 +290,23 @@ export class BlindMarket {
         if ((built.chain !== undefined && built.chain !== postingChain) || (built.chainId !== undefined && Number(built.chainId) !== entry.chainId)) {
             throw new ApiError(409, `The backend built this task for ${built.chain} (chain ${built.chainId}), not ${postingChain}: its posting chain changed. Nothing was sent; try again.`, undefined, 'POSTING_CHAIN_CHANGED');
         }
-        if (built.unsignedTx.to.toLowerCase() !== escrow.toLowerCase()) {
-            throw new ApiError(409, `The backend built this task for ${built.unsignedTx.to}, not the ${postingChain} escrow ${escrow}. Nothing was sent.`, undefined, 'ESCROW_MISMATCH');
-        }
+        // And it must be exactly this createTask: the escrow, the task hash, the
+        // token, the amount, the zone and the duration asked for (a verifier
+        // commits through createTaskWithVerifier). Only its to and data are signed;
+        // the value is the amount computed here.
+        const withVerifier = verificationMode === 'agent' && !!params.verifierAddress && params.verifierAddress.toLowerCase() !== ethers.ZeroAddress;
+        const createCall = checkEscrowCall(built.unsignedTx, {
+            escrow,
+            fn: withVerifier ? 'createTaskWithVerifier' : 'createTask',
+            args: (a) => String(a[0]).toLowerCase() === taskHash.toLowerCase()
+                && String(a[1]).toLowerCase() === token.toLowerCase()
+                && a[2] === amount
+                && a[4] === locationZone
+                && a[5] === BigInt(duration)
+                && (!withVerifier || String(a[6]).toLowerCase() === params.verifierAddress.toLowerCase()),
+            value: isNative ? amount : 0n,
+            chainId: entry.chainId,
+        }, `Funding the escrow on ${postingChain}`);
         const timeoutMs = opts.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS;
         // createTask pulls an ERC-20 with transferFrom: approve the escrow first.
         const nonce = isNative ? undefined : await ensureAllowance(signer, token, escrow, amount, { timeoutMs });
@@ -287,7 +325,7 @@ export class BlindMarket {
         };
         let txHash;
         try {
-            ({ hash: txHash } = await sendAndWait(signer, { to: built.unsignedTx.to, data: built.unsignedTx.data }, {
+            ({ hash: txHash } = await sendAndWait(signer, createCall, {
                 value: isNative ? amount : undefined,
                 nonce,
                 timeoutMs,
@@ -358,25 +396,54 @@ export class BlindMarket {
      * then takes the task off the market (`POST /tasks/:id/confirm-tx`).
      * `taskId` is the on-chain id (PostedTask.taskId); pass `chain`
      * (PostedTask.chain) too, since ids repeat across chains.
+     *
+     * Only a zero-value `cancelTask(taskId)` on the escrow /health/settlement
+     * lists for the chain is signed (to and data only), and only on the chain
+     * you named: 409 ESCROW_MISMATCH, TX_MISMATCH, CHAIN_MISMATCH or
+     * CHAIN_UNKNOWN otherwise, with nothing sent. reclaimAfterTimeout() does
+     * the same for `claimTimeout(taskId)`.
      */
     async cancelAndRefund(taskId, opts = {}) {
-        return this.sendRefund(taskId, await this.cancelTask(taskId, opts.chain), 'Cancelling the task', opts);
+        return this.sendRefund(taskId, await this.cancelTask(taskId, opts.chain), 'cancelTask', 'Cancelling the task', opts);
     }
-    /** Reclaim the escrow of a task whose deadline passed undelivered (claimTimeout), signed and sent. */
+    /**
+     * Reclaim the escrow of a task whose deadline passed undelivered
+     * (claimTimeout), signed and sent. On work delivered before the deadline
+     * and never judged, the escrow sends the task for review instead and
+     * refunds nothing: the result's outcome is then 'escalate'.
+     */
     async reclaimAfterTimeout(taskId, opts = {}) {
-        return this.sendRefund(taskId, await this.claimTimeout(taskId, opts.chain), 'Reclaiming the escrow', opts);
+        return this.sendRefund(taskId, await this.claimTimeout(taskId, opts.chain), 'claimTimeout', 'Reclaiming the escrow', opts);
     }
-    async sendRefund(taskId, built, what, opts) {
+    /**
+     * Sign the refund the backend built, once it is checked to be exactly
+     * `fn(taskId)` on the escrow of the chain it names (the one the caller
+     * named, when it named one), with no value. Only its to and data are signed.
+     */
+    async sendRefund(taskId, built, fn, what, opts) {
         const { chain, chainId } = built;
         if (!chain || chainId === undefined) {
             throw new ApiError(409, `${what}: the backend did not say which chain the task is on, so it cannot be signed safely here. Nothing was sent.`, built, 'CHAIN_UNKNOWN');
         }
-        const tx = built.unsignedTx;
+        if (opts.chain && chain !== opts.chain) {
+            throw new ApiError(409, `${what}: you asked for task ${taskId} on ${opts.chain}, but the backend built the refund for ${chain}. Nothing was sent.`, built, 'CHAIN_MISMATCH');
+        }
+        const entry = await this.settlementEntry(chain, what);
+        if (Number(chainId) !== entry.chainId) {
+            throw new ApiError(409, `${what}: the backend built the refund for chain ${chainId}, but lists ${chain} as chain ${entry.chainId}. Nothing was sent.`, built, 'CHAIN_MISMATCH');
+        }
+        const id = taskIdOf(taskId);
+        const call = checkEscrowCall(built.unsignedTx, {
+            escrow: entry.escrowAddress,
+            fn,
+            args: (a) => id !== undefined && a[0] === id,
+            chainId: entry.chainId,
+        }, what);
         const signer = opts.signer ?? this.signerOn(chain, what);
-        await assertSignerChain(signer, chainId, what);
+        await assertSignerChain(signer, entry.chainId, what);
         let hash;
         try {
-            ({ hash } = await sendAndWait(signer, { to: tx.to, data: tx.data }, { timeoutMs: opts.confirmTimeoutMs }));
+            ({ hash } = await sendAndWait(signer, call, { timeoutMs: opts.confirmTimeoutMs }));
         }
         catch (err) {
             if (err instanceof UnconfirmedTransactionError) {
@@ -386,28 +453,34 @@ export class BlindMarket {
             }
             throw err;
         }
-        return { txHash: hash, chain, chainId, listingClosed: await this.confirmRefund(taskId, hash, chain) };
+        const confirmed = await this.confirmRefund(taskId, hash, chain);
+        // The receipt is the authority; the build's outcome covers a backend that
+        // could not confirm it.
+        const outcome = confirmed.escalated ? 'escalate' : built.outcome;
+        return { txHash: hash, chain, chainId, listingClosed: confirmed.closed, ...(outcome ? { outcome } : {}) };
     }
     /**
      * Tell the backend a refund landed (`POST /api/v1/tasks/:id/confirm-tx`),
      * which checks the receipt and takes the task off the market. Without it a
      * refunded task keeps listing as open until its deadline. Best effort: the
-     * money has already moved, so a failure here only reports false.
+     * money has already moved, so a failure here only reports it not closed.
+     * A claim that sent the task for review closes nothing (escalated).
      */
     async confirmRefund(taskId, txHash, chain) {
         for (let attempt = 1; attempt <= 3; attempt++) {
             try {
-                await this.req('POST', `/api/v1/tasks/${taskId}/confirm-tx`, { txHash, chain });
-                return true;
+                const res = await this.req('POST', `/api/v1/tasks/${taskId}/confirm-tx`, { txHash, chain });
+                const escalated = res?.escalated === true;
+                return { closed: !escalated, escalated };
             }
             catch (err) {
                 // The backend's RPC can lag the receipt the signer just saw.
                 if (!(err instanceof ApiError && err.code === 'NOT_CONFIRMED') || attempt === 3)
-                    return false;
+                    return { closed: false, escalated: false };
                 await new Promise((r) => setTimeout(r, 3_000));
             }
         }
-        return false;
+        return { closed: false, escalated: false };
     }
     // ── Agent deployment & management ─────────────────────────────────────────
     /** What deploying an agent costs on this backend, and how to pay it. */
@@ -867,13 +940,34 @@ export class BlindMarket {
      * unsigned `submitEvidence` on the chain the backend names → `finalize()`.
      * Safe to re-call on a task stranded in 'submitted': INVALID_STATE at submit
      * and NOT_SUBMITTED_ON_CHAIN at finalize both heal through `rebroadcast()`.
+     *
+     * The executor key signs only a zero-value `submitEvidence(onChainTaskId,
+     * evidenceHash)` on the escrow /health/settlement lists for that chain,
+     * where (from /submit) evidenceHash is keccak256 of `JSON.stringify(resultData)`,
+     * over an RPC checked to serve that chain, and only its to and data.
+     * Anything else throws 409 ESCROW_MISMATCH, TX_MISMATCH, CHAIN_MISMATCH or
+     * CHAIN_UNKNOWN (or WRONG_CHAIN for the RPC) with nothing sent.
      */
     async deliverResult(taskId, resultData, signerOverride) {
         const signer = signerOverride ?? this.executor;
         if (!signer) {
             throw new ApiError(400, 'deliverResult() needs a signer — pass one, or set BlindMarketConfig.executor. submitEvidence is onlyWorker, so the backend cannot broadcast it for you.');
         }
-        const send = async (built) => {
+        // Read before /submit, which records the result: a lookup failing here
+        // leaves nothing half-done.
+        const settlement = await this.getSettlement();
+        // The evidence the backend commits for this result (backend/src/routes/a2a.ts).
+        const evidence = evidenceHashOf(resultData);
+        const what = `Delivering task ${taskId}`;
+        /**
+         * Sign the submitEvidence the backend built, once it is checked to be a
+         * zero-value submitEvidence on the escrow of the chain it names, for the
+         * on-chain task it names, and (from /submit) committing THIS result. Only
+         * its to and data are signed, on the signer's RPC for that chain, checked
+         * to serve it. /rebroadcast re-sends the first stored result, so there the
+         * evidence hash is not this call's.
+         */
+        const send = async (built, fromSubmit) => {
             if (!built.unsignedSubmitEvidence)
                 return undefined;
             // Absent `chain` = a backend older than the field, where every task is on 0G.
@@ -884,16 +978,24 @@ export class BlindMarket {
             if (!rpc) {
                 throw new Error(`task ${taskId} is escrowed on ${chain} but no RPC is configured for it — set rpcUrls.${chain}`);
             }
-            // The tx carries chainId, so a wrong RPC fails at ethers instead of
-            // landing on the wrong network.
+            const entry = await this.settlementEntry(chain, what, settlement);
+            const onChainId = built.onChainTaskId === undefined ? undefined : taskIdOf(built.onChainTaskId);
+            const call = checkEscrowCall(built.unsignedSubmitEvidence, {
+                escrow: entry.escrowAddress,
+                fn: 'submitEvidence',
+                args: (a) => (built.onChainTaskId === undefined || a[0] === onChainId)
+                    && (!fromSubmit || String(a[1]).toLowerCase() === evidence),
+                chainId: entry.chainId,
+            }, what);
             const wallet = new ethers.Wallet(signer.privateKey, new ethers.JsonRpcProvider(rpc));
-            const tx = await wallet.sendTransaction(built.unsignedSubmitEvidence);
+            await assertSignerChain(wallet, entry.chainId, what);
+            const tx = await wallet.sendTransaction(call);
             await tx.wait();
             return tx.hash;
         };
         const healStranded = async () => {
             try {
-                return await send(await this.rebroadcast(taskId));
+                return await send(await this.rebroadcast(taskId), false);
             }
             catch (err) {
                 // Evidence is already on-chain — nothing to broadcast, go finalize.
@@ -904,7 +1006,7 @@ export class BlindMarket {
         };
         let submitTxHash;
         try {
-            submitTxHash = await send(await this.submitResult(taskId, resultData));
+            submitTxHash = await send(await this.submitResult(taskId, resultData), true);
         }
         catch (err) {
             if (!(err instanceof ApiError && err.code === 'INVALID_STATE'))
@@ -985,7 +1087,8 @@ export class BlindMarket {
      * which returns `{ rootHash, blob }`, not `{ data }`.
      */
     async downloadBlob(rootHash) {
-        return this.req('GET', `/api/v1/storage/${rootHash}`);
+        // Encoded so a rootHash can never step out of /storage/.
+        return this.req('GET', `/api/v1/storage/${encodeURIComponent(rootHash)}`);
     }
     // ── Messages ─────────────────────────────────────────────────────────────
     /** Send a message to another user or agent. */

package/dist/tools/helpers.js

@@ -24,7 +24,7 @@ export function kit(name, description, all, names) {
 }
 export function createBlindMarketTools(bb) {
     const all = [
-        tool(bb, 'list_open_tasks', 'List open tasks available for assignment', {}, async () => {
+        tool(bb, 'list_open_tasks', 'List open tasks from the legacy 0G TaskRegistry (numeric ids on the 0G escrow). Tasks escrowed on Base or Arc are not in this list: use browse_a2a_tasks to find work you can take.', {}, async () => {
             return bb.listTasks();
         }),
         tool(bb, 'get_task', 'Get full task details by ID', { taskId: str('Numeric or 0x task ID') }, async (a) => {

package/dist/types.d.ts

@@ -181,6 +181,19 @@ export interface A2APublicTaskMeta {
     privacy?: 'public';
     hasEncryptedBrief?: boolean;
     rootHash?: string;
+    /**
+     * The escrowed reward, recorded by the backend from the verified TaskCreated
+     * event at /tasks/index: `amount` is a whole number of the unit's base units
+     * (USDC: 6 decimals, so '1000000' is 1 USDC). Absent on tasks indexed by a
+     * backend older than the field. WorkerRuntime compares it with `minReward`.
+     */
+    reward?: {
+        amount: string;
+        unit: {
+            symbol: 'USDC' | '0G';
+            decimals: 6 | 18;
+        };
+    };
     [key: string]: unknown;
 }
 /** One entry of `GET /api/v1/a2a/tasks` (and /tasks/posted, /executions). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blindmarket/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "BlindMarket SDK — deploy agents, assign workers, verify evidence",
   "author": "BlindMarket Team",
   "license": "MIT",