@blindmarket/sdk 0.7.0 → 0.9.0

package/dist/index.js

@@ -1,15 +1,125 @@
 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';
-/** A whole number of base units from a string or bigint; throws 400 INVALID_AMOUNT otherwise. */
-function wholeNumber(value, name) {
-    if (typeof value === 'bigint')
-        return value;
-    if (typeof value === 'string' && /^\d+$/.test(value))
-        return BigInt(value);
-    throw new ApiError(400, `${name} must be a whole number of the token's smallest unit (USDC has 6 decimals: '2500000' is 2.5 USDC), not ${JSON.stringify(value)}. Nothing was sent.`, undefined, 'INVALID_AMOUNT');
+import { checkEscrowCall, evidenceHashOf, taskIdOf } from './escrowCalls.js';
+import { isPinnedSettlement, SETTLEMENT_PINS } from './settlementPins.js';
+import { normalizePost, checkRowFields, sealBrief, createTaskBody, indexParamsFor, commitsVerifier, } from './posting.js';
+// ── Posting many tasks: internals ───────────────────────────────────────────
+/** Rows per postTasks() call: past this, split the list (each row is sealed in memory first). */
+const MAX_POST_TASKS_ROWS = 1000;
+/** Rows per createTasks transaction unless chunkSize says otherwise. */
+const DEFAULT_CHUNK_SIZE = 20;
+/** POST /storage/upload-batch and /a2a/tasks/index-batch take at most this many items. */
+const MAX_BATCH_REQUEST = 50;
+const MAX_RETRY_DELAY_MS = 30_000;
+/** The category the backend builds every task with (backend/src/routes/tasks.ts): bound in the calldata check like the rest. */
+const TASK_CATEGORY = 'general';
+/** A createTasks gas limit is its estimate plus a fifth. */
+const BATCH_GAS_HEADROOM_PCT = 120n;
+/**
+ * Briefs per /storage/upload-batch request. The backend stores briefs on 0G
+ * one at a time (20–40 s each) and answers within ~85 s, and production sits
+ * behind a ~100 s edge timeout (Cloudflare's 524), so a request carries two
+ * at most. The web app does the same (frontend/src/lib/postTaskFlow.ts).
+ */
+const UPLOAD_GROUP = 2;
+/** How long one upload request may take before it counts as timed out. */
+const UPLOAD_TIMEOUT_MS = 95_000;
+function retryPolicy(retry) {
+    const attempts = retry?.attempts ?? 5;
+    const baseDelayMs = retry?.baseDelayMs ?? 2_000;
+    return {
+        attempts: Number.isInteger(attempts) && attempts >= 1 ? attempts : 5,
+        baseDelayMs: Number.isFinite(baseDelayMs) && baseDelayMs >= 0 ? baseDelayMs : 2_000,
+    };
+}
+/** A rate limit, a server error, a network failure, or a body that was not JSON (a proxy's error page): worth asking again. */
+function isTransient(err) {
+    if (err instanceof ApiError)
+        return err.status === 429 || err.status >= 500 || err.code === 'RATE_LIMIT' || err.code === 'TIMEOUT';
+    return err instanceof TypeError || err instanceof SyntaxError;
+}
+/**
+ * Storage busy or unreachable, as opposed to a brief the backend refused or
+ * an answer that does not add up: a dropped connection (fetch's TypeError),
+ * this client's own timeout, or a gateway giving up (502, 503, 504,
+ * Cloudflare's 524): the web app's isTransientUploadError. A rate limit
+ * (429) counts too: it asks to come back later, which the backoff does.
+ */
+function isTransientUpload(err) {
+    if (err instanceof TypeError)
+        return true;
+    if (!(err instanceof ApiError))
+        return false;
+    return err.code === 'TIMEOUT' || err.code === 'RATE_LIMIT' || [429, 502, 503, 504, 524].includes(err.status);
+}
+/**
+ * Failures before a row is funded that stop the whole run rather than that
+ * row: a backend that built the wrong transaction or moved chain, an auth
+ * failure, or one that stayed unreachable through every retry. Anything else
+ * (a brief the backend refuses, say) fails the row alone.
+ */
+const HALTING_CODES = new Set([
+    'ESCROW_MISMATCH', 'TX_MISMATCH', 'CHAIN_MISMATCH', 'POSTING_CHAIN_CHANGED', 'CHAIN_UNKNOWN',
+    'SETTLEMENT_NOT_POSTABLE', 'WRONG_CHAIN', 'OWNER_MISMATCH', 'UPLOAD_MISMATCH',
+]);
+function haltsBeforeFunding(err) {
+    if (err instanceof ApiError && (HALTING_CODES.has(err.code ?? '') || err.status === 401 || err.status === 403))
+        return true;
+    // The escrow approve reverted or never confirmed: no row can be funded.
+    if (!(err instanceof ApiError))
+        return true;
+    return isTransient(err);
+}
+function errorInfo(err) {
+    const e = err;
+    const code = err instanceof ApiError || err instanceof UnconfirmedTransactionError
+        ? err.code
+        : typeof e?.code === 'string' ? e.code : undefined;
+    return { ...(code ? { code } : {}), message: typeof e?.message === 'string' ? e.message : String(err) };
 }
+function haltAt(index, err, code) {
+    const info = errorInfo(err);
+    const c = code ?? info.code;
+    return { index, ...(c ? { code: c } : {}), message: info.message };
+}
+function rowError(index, err) {
+    const info = errorInfo(err);
+    return { index, code: info.code ?? 'INVALID_ROW', message: info.message };
+}
+function invalidRows(errors, total) {
+    errors.sort((a, b) => a.index - b.index);
+    const shown = errors.slice(0, 3).map((e) => `rows[${e.index}]: ${e.message.replace(/\s*Nothing was sent\.?$/, '')}`).join('; ');
+    return new ApiError(400, `${errors.length} of ${total} rows cannot be posted as they are (${shown}${errors.length > 3 ? '; …' : ''}). Nothing was sent: fix them, or leave them out, and post again.`, { errors }, 'INVALID_ROWS');
+}
+function failedRow(index, err) {
+    return { index, status: 'failed', error: errorInfo(err) };
+}
+function unlistedRow(index, txHash, batch, indexParams, aesKey, error) {
+    return {
+        index, status: 'unlisted', taskHash: indexParams.taskHash, txHash, batch,
+        indexParams: { ...indexParams, txHash }, ...(aesKey ? { aesKey } : {}), error,
+    };
+}
+/**
+ * The rows an all-or-nothing POST /tasks/batch refused, by position in the
+ * request, when its 400 names them ({ errors: [{ index, code, message }] });
+ * null when it does not, so the whole call fails as it came back.
+ */
+function refusedRows(err, count) {
+    if (!(err instanceof ApiError) || err.status !== 400)
+        return null;
+    const body = err.body;
+    const list = body?.error?.errors ?? body?.errors ?? body?.error?.details?.errors;
+    if (!Array.isArray(list))
+        return null;
+    const rows = list
+        .filter((e) => !!e && typeof e === 'object' && Number.isInteger(e.index)
+        && e.index >= 0 && e.index < count)
+        .map((e) => ({ index: e.index, code: typeof e.code === 'string' ? e.code : 'INVALID_ROW', message: typeof e.message === 'string' ? e.message : 'refused by the backend' }));
+    return rows.length > 0 ? rows : null;
+}
+const capsKey = (caps) => [...caps].sort().join(',');
 // ── Main client ─────────────────────────────────────────────────────────────
 /**
  * BlindMarket REST API client.
@@ -35,10 +145,12 @@ export class BlindMarket {
     apiBase;
     apiKey;
     executor;
+    trustedEscrows;
     constructor(config) {
         this.apiBase = config.apiBase ?? 'https://api.blindmarket.xyz';
         this.apiKey = config.apiKey;
         this.executor = config.executor;
+        this.trustedEscrows = config.trustedEscrows ?? [];
     }
     /** True when an executor signer was configured (see BlindMarketConfig.executor). */
     get canSign() {
@@ -71,16 +183,40 @@ export class BlindMarket {
      * generateText({ model, tools: tools(bb).vercel });
      * ```
      */
-    async req(method, path, body) {
-        const res = await fetch(`${this.apiBase}${path}`, {
-            method,
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${this.apiKey}`,
-            },
-            body: body ? JSON.stringify(body) : undefined,
-        });
-        const json = await res.json();
+    /**
+     * `timeoutMs` gives up on a request that has not answered (ApiError
+     * TIMEOUT). `strictBody` turns a reply that is not JSON (a gateway's error
+     * page, such as Cloudflare's 524) into an ApiError carrying its HTTP status,
+     * instead of the parser's SyntaxError.
+     */
+    async req(method, path, body, opts = {}) {
+        let res;
+        try {
+            res = await fetch(`${this.apiBase}${path}`, {
+                method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                ...(opts.timeoutMs ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),
+            });
+        }
+        catch (err) {
+            if (opts.timeoutMs && err?.name === 'TimeoutError') {
+                throw new ApiError(0, `${path} did not answer within ${Math.round(opts.timeoutMs / 1000)} s.`, undefined, 'TIMEOUT');
+            }
+            throw err;
+        }
+        let json;
+        try {
+            json = await res.json();
+        }
+        catch (err) {
+            if (opts.strictBody)
+                throw new ApiError(res.status, `${path} answered HTTP ${res.status} with a body that is not JSON.`, undefined, `HTTP_${res.status}`);
+            throw err;
+        }
         if (!json.success) {
             const err = new ApiError(res.status, json.error?.message ?? `HTTP ${res.status}`, json, json.error?.code);
             if (typeof json.error?.reason === 'string')
@@ -99,7 +235,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 +275,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 +296,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 +318,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.
      *
@@ -174,124 +332,27 @@ export class BlindMarket {
      * );
      */
     async postTask(params, opts = {}) {
-        const amount = wholeNumber(params.amountRaw, 'amountRaw');
-        if (amount <= 0n)
-            throw new ApiError(400, 'amountRaw must be above 0. Nothing was sent.', undefined, 'INVALID_AMOUNT');
-        if (opts.maxAmountRaw !== undefined && amount > BigInt(opts.maxAmountRaw)) {
-            throw new ApiError(402, `The escrow of ${amount} is above your limit of ${opts.maxAmountRaw}. Nothing was sent.`, undefined, 'AMOUNT_ABOVE_MAX');
-        }
-        const duration = params.durationSeconds ?? 86_400;
-        if (!Number.isInteger(duration) || duration < 3_600 || duration > 90 * 86_400) {
-            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 verificationMode = params.verificationMode ?? 'auto';
-        const verificationCriteria = params.verificationCriteria
-            ?? (verificationMode === 'auto' ? { min_length: 10, pass_threshold: 60 } : undefined);
-        const requiredCapabilities = params.requiredCapabilities ?? [];
-        // Where the escrow is funded, and in what.
-        const { postingChain, chains } = await this.getSettlement();
-        const entry = chains.find((c) => c.chain === postingChain);
-        if (!postingChain || !entry || !entry.escrowAddress || !entry.token.address) {
-            throw new ApiError(503, `The backend has no chain to post new tasks on right now (posting chain: ${postingChain ?? 'none'}). Nothing was sent.`, { postingChain, chains }, 'SETTLEMENT_NOT_POSTABLE');
-        }
-        const escrow = entry.escrowAddress;
-        const token = entry.token.address;
-        const isNative = entry.token.kind === 'native';
-        const signer = opts.signer ?? this.signerOn(postingChain, 'Funding the escrow');
-        const poster = await signer.getAddress();
-        await this.assertSpender(poster, 'A task', true);
-        await assertSignerChain(signer, entry.chainId, `Funding the escrow on ${postingChain}`);
-        if (!isNative) {
-            const balance = await tokenBalance(signer, token, poster);
-            if (balance < amount) {
-                const fmt = (v) => ethers.formatUnits(v, entry.token.decimals);
-                throw new ApiError(402, `${poster} holds ${fmt(balance)} ${entry.token.symbol} on ${postingChain}; the escrow needs ${fmt(amount)}. Nothing was sent.`, undefined, 'INSUFFICIENT_BALANCE');
-            }
-        }
+        const post = normalizePost(params, opts.maxAmountRaw);
+        const ctx = await this.postingContext(opts.signer);
+        await this.assertCovers(ctx, post.amount);
         // The brief: plaintext, or encrypted to the executors that can take it.
-        const plaintext = new TextEncoder().encode(params.instructions);
-        let blob;
-        let wrappedKeys;
-        let aesKey;
-        if (privacy === 'public') {
-            blob = plaintext;
-        }
-        else {
-            const qs = new URLSearchParams({ capabilities: requiredCapabilities.join(','), chain: postingChain });
-            const { executors } = await this.req('GET', `/api/v1/a2a/executors?${qs}`);
-            let targets = executors.filter((e) => typeof e.publicKey === 'string' && e.publicKey.length > 0);
-            if (params.targetExecutor) {
-                const want = params.targetExecutor.toLowerCase();
-                targets = targets.filter((e) => e.address.toLowerCase() === want);
-                if (targets.length === 0) {
-                    throw new ApiError(404, `${params.targetExecutor} is not a registered executor on ${postingChain} with a public key, so it could not read the brief. Nothing was sent.`, undefined, 'EXECUTOR_NOT_FOUND');
-                }
-            }
-            if (targets.length > 200) {
-                throw new ApiError(409, `${targets.length} executors match, more than the 200 a brief can be wrapped to. Narrow requiredCapabilities, name a targetExecutor, or post with privacy 'public'. Nothing was sent.`, undefined, 'TOO_MANY_EXECUTORS');
-            }
-            const key = await generateAesKey();
-            blob = await aesEncrypt(plaintext, key);
-            wrappedKeys = {};
-            for (const e of targets) {
-                try {
-                    wrappedKeys[e.address.toLowerCase()] = bytesToHex(await eciesEncrypt(key, e.publicKey));
-                }
-                catch { /* a malformed public key: that executor can't be wrapped to */ }
-            }
-            if (Object.keys(wrappedKeys).length === 0) {
-                throw new ApiError(409, `No executor on ${postingChain} can decrypt an encrypted brief right now, so no one could take the task. Post with privacy 'public', or wait for executors to register. Nothing was sent.`, undefined, 'NO_EXECUTORS');
-            }
-            aesKey = bytesToHex(key);
-        }
-        const taskHash = `0x${bytesToHex(await sha256(blob))}`;
-        const { rootHash } = await this.uploadBlob(ethers.encodeBase64(blob));
-        const built = await this.createTask({
-            taskHash: taskHash,
-            token: token,
-            amount: amount.toString(),
-            locationZone: params.locationZone ?? 'global',
-            duration: String(duration),
-            targetExecutorType: 'agent',
-            verificationMode,
-            ...(verificationCriteria ? { verificationCriteria } : {}),
-            ...(params.verifierAddress ? { verifierAddress: params.verifierAddress } : {}),
-            requiredCapabilities,
-            rootHash,
-            ...(wrappedKeys ? { wrappedKeys } : {}),
-        });
-        // The tx must go to the escrow and chain checked above: a backend whose
-        // posting chain moved in between would otherwise have it signed blind.
-        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');
-        }
+        const executors = post.privacy === 'public' ? [] : await this.postingExecutors(ctx.postingChain, post.requiredCapabilities);
+        const sealed = await sealBrief(post, executors, ctx.postingChain);
+        const { taskHash } = sealed;
+        const { rootHash } = await this.uploadBlob(ethers.encodeBase64(sealed.blob));
+        const built = await this.createTask(createTaskBody(post, sealed, ctx.token, rootHash));
+        const createCall = this.checkedCreateCall(ctx, built, post, taskHash);
         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 });
-        const indexParams = {
-            txHash: '',
-            taskHash,
-            rootHash,
-            ...(wrappedKeys ? { wrappedKeys } : {}),
-            privacy,
-            ...(privacy === 'public' ? { publicBrief: params.instructions.slice(0, 4000) } : {}),
-            verificationMode,
-            ...(verificationCriteria ? { verificationCriteria } : {}),
-            ...(params.verifierAddress ? { verifierAddress: params.verifierAddress } : {}),
-            requiredCapabilities,
-            ...(params.targetExecutor ? { targetExecutor: params.targetExecutor } : {}),
-        };
+        const nonce = ctx.isNative ? undefined : await ensureAllowance(ctx.signer, ctx.token, ctx.escrow, post.amount, { timeoutMs });
+        const indexParams = indexParamsFor(post, sealed, rootHash);
         let txHash;
         try {
-            ({ hash: txHash } = await sendAndWait(signer, { to: built.unsignedTx.to, data: built.unsignedTx.data }, {
-                value: isNative ? amount : undefined,
+            ({ hash: txHash } = await sendAndWait(ctx.signer, createCall, {
+                value: ctx.isNative ? post.amount : undefined,
                 nonce,
                 timeoutMs,
-                onSent: (hash) => opts.onFunded?.({ txHash: hash, taskHash, indexParams: { ...indexParams, txHash: hash } }),
+                onSent: (hash, sentNonce, raw) => opts.onFunded?.({ txHash: hash, nonce: sentNonce, ...(raw ? { raw } : {}), taskHash, indexParams: { ...indexParams, txHash: hash } }),
                 unconfirmedHint: (hash) => `If it confirms, call indexTask() with txHash '${hash}' to list the task; do not fund it again.`,
             }));
         }
@@ -314,18 +375,553 @@ export class BlindMarket {
             out.txHash = txHash;
             throw out;
         }
+        return this.postedTask(ctx, post, sealed, rootHash, txHash, indexed.onChainTaskId);
+    }
+    /**
+     * Post many tasks, from the API key's own wallet: postTask() for a list, in
+     * as few transactions as the posting chain's escrow allows.
+     *
+     * Every row is checked and its brief sealed before anything is uploaded or
+     * sent: a row the escrow or the backend would refuse throws 400
+     * INVALID_ROWS listing every such row (`err.body.errors`), with nothing
+     * sent. The wallet must hold the total, and the escrow is approved for it
+     * once, just before the first funding transaction.
+     *
+     * On an escrow with createTasks (SettlementChainInfo.batchCreate) up to
+     * `chunkSize` rows share one transaction and one listing call; otherwise
+     * each row is its own createTask, as postTask() sends it. The same checks
+     * guard every transaction: the backend's build must be exactly these tasks,
+     * for this escrow and chain, before a key signs it.
+     *
+     * A row the backend refuses before funding fails alone and the run goes on.
+     * A funding transaction that reverts or cannot be confirmed, a listing that
+     * fails, or a backend that builds the wrong transaction or stays
+     * unreachable stops the run there (`result.stopped`), so no further escrow
+     * is funded behind a problem. Nothing is ever funded twice: a funded row
+     * that is not listed comes back 'unlisted' with its `indexParams`.
+     *
+     * @example
+     * const res = await bb.postTasks(rows, {
+     *   onFunded: ({ taskHash, indexParams }) => save(taskHash, indexParams),
+     *   onProgress: ({ done, total }) => console.log(`${done}/${total}`),
+     * });
+     */
+    async postTasks(rows, opts = {}) {
+        if (!Array.isArray(rows) || rows.length === 0) {
+            throw new ApiError(400, 'postTasks() needs at least one row. Nothing was sent.', undefined, 'NO_ROWS');
+        }
+        if (rows.length > MAX_POST_TASKS_ROWS) {
+            throw new ApiError(400, `postTasks() takes at most ${MAX_POST_TASKS_ROWS} rows per call, not ${rows.length}: split the list. Nothing was sent.`, undefined, 'TOO_MANY_ROWS');
+        }
+        if (opts.chunkSize !== undefined && (!Number.isInteger(opts.chunkSize) || opts.chunkSize < 1)) {
+            throw new ApiError(400, `chunkSize must be a whole number of rows from 1, not ${opts.chunkSize}. Nothing was sent.`, undefined, 'INVALID_CHUNK_SIZE');
+        }
+        // 1. Each row's own fields, before any lookup.
+        const errors = [];
+        const checked = rows.map((row, index) => {
+            try {
+                checkRowFields(row);
+                return normalizePost(row);
+            }
+            catch (err) {
+                errors.push(rowError(index, err));
+                return undefined;
+            }
+        });
+        if (errors.length > 0)
+            throw invalidRows(errors, rows.length);
+        const posts = checked;
+        const total = posts.reduce((sum, p) => sum + p.amount, 0n);
+        if (opts.maxTotalRaw !== undefined && total > BigInt(opts.maxTotalRaw)) {
+            throw new ApiError(402, `The ${rows.length} escrows total ${total}, above your limit of ${opts.maxTotalRaw}. Nothing was sent.`, undefined, 'AMOUNT_ABOVE_MAX');
+        }
+        // 2. Where, and from which wallet: postTask()'s checks, for the total.
+        const retry = retryPolicy(opts.retry);
+        const ctx = await this.postingContext(opts.signer);
+        await this.assertCovers(ctx, total);
+        // 3. Every brief sealed, still before anything is sent. Executors are
+        //    asked for once per capability list.
+        const executors = new Map();
+        for (const post of posts) {
+            if (post.privacy !== 'private')
+                continue;
+            const key = capsKey(post.requiredCapabilities);
+            if (!executors.has(key))
+                executors.set(key, await this.retrying(() => this.postingExecutors(ctx.postingChain, post.requiredCapabilities), retry));
+        }
+        const sealed = [];
+        for (let i = 0; i < posts.length; i++) {
+            try {
+                const post = posts[i];
+                sealed[i] = await sealBrief(post, post.privacy === 'private' ? executors.get(capsKey(post.requiredCapabilities)) : [], ctx.postingChain);
+            }
+            catch (err) {
+                errors.push(rowError(i, err));
+            }
+        }
+        // A public brief's task hash is the brief's hash, and the market lists a hash once.
+        const firstWithHash = new Map();
+        sealed.forEach((s, i) => {
+            if (!s)
+                return;
+            const hash = s.taskHash.toLowerCase();
+            const first = firstWithHash.get(hash);
+            if (first === undefined)
+                firstWithHash.set(hash, i);
+            else
+                errors.push({ index: i, code: 'DUPLICATE_BRIEF', message: `rows[${i}] is the same public brief as rows[${first}], and the market lists a brief once. Nothing was sent.` });
+        });
+        if (errors.length > 0)
+            throw invalidRows(errors, rows.length);
+        // 4. Fund and list, in as few transactions as the escrow allows.
+        const batch = ctx.entry.batchCreate;
+        const batchable = !ctx.isNative && batch?.supported === true && Number.isInteger(batch.maxBatch) && batch.maxBatch > 1;
+        const size = batchable ? Math.max(1, Math.min(opts.chunkSize ?? DEFAULT_CHUNK_SIZE, batch.maxBatch, MAX_BATCH_REQUEST)) : 1;
+        let mode = size > 1 ? 'batch' : 'single';
+        let units = [];
+        for (let i = 0; i < posts.length; i += size)
+            units.push(posts.slice(i, i + size).map((_, j) => i + j));
+        const results = new Array(rows.length);
+        const run = {
+            ctx, posts, sealed, opts, retry,
+            timeoutMs: opts.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS,
+            pending: new Set(posts.map((_, i) => i)),
+            approved: ctx.isNative,
+            settle: async (result) => {
+                results[result.index] = result;
+                run.pending.delete(result.index);
+                try {
+                    await opts.onProgress?.({ done: rows.length - run.pending.size, total: rows.length, result });
+                }
+                catch { /* a progress callback never stops a run that is moving money */ }
+            },
+        };
+        let stopped;
+        for (let u = 0; u < units.length; u++) {
+            const unit = units[u];
+            if (!stopped && opts.signal?.aborted) {
+                stopped = { index: unit[0], code: 'ABORTED', message: 'The run was aborted before this row started.' };
+            }
+            if (stopped) {
+                const reason = stopped.code === 'ABORTED' ? 'aborted' : `stopped at rows[${stopped.index}]: ${stopped.message}`;
+                for (const i of unit)
+                    await run.settle({ index: i, status: 'skipped', reason });
+                continue;
+            }
+            const outcome = unit.length === 1 ? await this.postRow(run, unit[0]) : await this.postChunk(run, unit);
+            if (outcome.fallback && outcome.fallback.length > 0) {
+                // The escrow refused createTasks after all: the rest go one by one.
+                mode = 'single';
+                units = [...units.slice(0, u + 1), ...outcome.fallback.map((i) => [i]), ...units.slice(u + 1).flat().map((i) => [i])];
+            }
+            if (outcome.halt)
+                stopped = outcome.halt;
+        }
+        const count = (status) => results.filter((r) => r.status === status).length;
+        return {
+            chain: ctx.postingChain,
+            chainId: ctx.entry.chainId,
+            mode,
+            results,
+            posted: count('posted'),
+            unlisted: count('unlisted'),
+            failed: count('failed'),
+            skipped: count('skipped'),
+            ...(stopped ? { stopped } : {}),
+        };
+    }
+    /**
+     * Build and list several posts at once (POST /api/v1/tasks/batch): one
+     * unsigned createTasks transaction for the posting chain's escrow. Only an
+     * escrow with createTasks builds it (409 BATCH_UNSUPPORTED otherwise);
+     * postTasks() calls it, and checks the transaction before signing.
+     */
+    async createTasks(params) {
+        return this.req('POST', '/api/v1/tasks/batch', params);
+    }
+    /**
+     * List every task one funding transaction created
+     * (POST /api/v1/a2a/tasks/index-batch). It works for a transaction that
+     * funded one task too. Each task comes back listed, or with its own error;
+     * a task the receipt does not hold is NOT_IN_RECEIPT. postTasks() calls it;
+     * call it yourself to finish rows it returned 'unlisted' with `batch` true.
+     */
+    async indexTasks(params) {
+        return this.req('POST', '/api/v1/a2a/tasks/index-batch', params);
+    }
+    /**
+     * Upload several blobs to 0G Storage in one call
+     * (POST /api/v1/storage/upload-batch). Each is base64, as uploadBlob()
+     * takes it; the results come back in the same order. All or nothing.
+     */
+    async uploadBlobs(data) {
+        const { results } = await this.req('POST', '/api/v1/storage/upload-batch', { items: data.map((d) => ({ data: d })) });
+        return results;
+    }
+    /** The posting chain, its escrow and token, and a signer checked to be the API key's own wallet on that chain. */
+    async postingContext(signerOption) {
+        const { postingChain, chains } = await this.getSettlement();
+        const entry = chains.find((c) => c.chain === postingChain);
+        if (!postingChain || !entry || !entry.escrowAddress || !entry.token.address) {
+            throw new ApiError(503, `The backend has no chain to post new tasks on right now (posting chain: ${postingChain ?? 'none'}). Nothing was sent.`, { postingChain, chains }, 'SETTLEMENT_NOT_POSTABLE');
+        }
+        // The escrow approved and funded, and its token, must be a known
+        // deployment (or one the caller trusts), not whatever the backend names.
+        if (!isPinnedSettlement(entry.chainId, entry.escrowAddress, entry.token.address, this.trustedEscrows)) {
+            const known = [...SETTLEMENT_PINS, ...this.trustedEscrows].filter((p) => p.chainId === entry.chainId);
+            throw new ApiError(409, `The backend names escrow ${entry.escrowAddress} and token ${entry.token.address} on ${postingChain} (chain ${entry.chainId}), which ${known.length ? `is not the known deployment (escrow ${known.map((p) => p.escrow).join(' or ')})` : 'has no known deployment'}. Nothing was approved or sent. For a custom or local deployment, list it in BlindMarketConfig.trustedEscrows.`, undefined, 'ESCROW_NOT_PINNED');
+        }
+        const signer = signerOption ?? this.signerOn(postingChain, 'Funding the escrow');
+        const poster = await signer.getAddress();
+        await this.assertSpender(poster, 'A task', true);
+        await assertSignerChain(signer, entry.chainId, `Funding the escrow on ${postingChain}`);
+        return {
+            postingChain,
+            entry: entry,
+            escrow: entry.escrowAddress,
+            token: entry.token.address,
+            isNative: entry.token.kind === 'native',
+            signer,
+            poster,
+        };
+    }
+    /** Throws 402 INSUFFICIENT_BALANCE, with nothing sent, when the wallet holds less than `amount` of an ERC-20 settlement token. */
+    async assertCovers(ctx, amount) {
+        if (ctx.isNative)
+            return;
+        const balance = await tokenBalance(ctx.signer, ctx.token, ctx.poster);
+        if (balance < amount) {
+            const fmt = (v) => ethers.formatUnits(v, ctx.entry.token.decimals);
+            throw new ApiError(402, `${ctx.poster} holds ${fmt(balance)} ${ctx.entry.token.symbol} on ${ctx.postingChain}; the escrow needs ${fmt(amount)}. Nothing was sent.`, undefined, 'INSUFFICIENT_BALANCE');
+        }
+    }
+    /** The executors on the posting chain a private brief can be wrapped to. */
+    async postingExecutors(postingChain, capabilities) {
+        const qs = new URLSearchParams({ capabilities: capabilities.join(','), chain: postingChain });
+        const { executors } = await this.req('GET', `/api/v1/a2a/executors?${qs}`);
+        return executors;
+    }
+    /**
+     * The backend's createTask, checked to be exactly this post before a key
+     * signs it: the chain and escrow checked above, the task hash, the token,
+     * the amount, the zone and the duration (a verifier commits through
+     * createTaskWithVerifier). Only its to and data are signed; the value is
+     * the amount computed here.
+     */
+    checkedCreateCall(ctx, built, post, taskHash) {
+        // A backend whose posting chain moved in between would otherwise have it signed blind.
+        if ((built.chain !== undefined && built.chain !== ctx.postingChain) || (built.chainId !== undefined && Number(built.chainId) !== ctx.entry.chainId)) {
+            throw new ApiError(409, `The backend built this task for ${built.chain} (chain ${built.chainId}), not ${ctx.postingChain}: its posting chain changed. Nothing was sent; try again.`, undefined, 'POSTING_CHAIN_CHANGED');
+        }
+        const withVerifier = commitsVerifier(post);
+        return checkEscrowCall(built.unsignedTx, {
+            escrow: ctx.escrow,
+            fn: withVerifier ? 'createTaskWithVerifier' : 'createTask',
+            args: (a) => String(a[0]).toLowerCase() === taskHash.toLowerCase()
+                && String(a[1]).toLowerCase() === ctx.token.toLowerCase()
+                && a[2] === post.amount
+                && a[3] === TASK_CATEGORY
+                && a[4] === post.locationZone
+                && a[5] === BigInt(post.duration)
+                && (!withVerifier || String(a[6]).toLowerCase() === post.verifierAddress.toLowerCase()),
+            value: ctx.isNative ? post.amount : 0n,
+            chainId: ctx.entry.chainId,
+        }, `Funding the escrow on ${ctx.postingChain}`);
+    }
+    /** The backend's createTasks, checked to be exactly these posts, in this order, for this token, escrow and chain. */
+    checkedCreateTasksCall(ctx, built, rows) {
+        if ((built.chain !== undefined && built.chain !== ctx.postingChain) || (built.chainId !== undefined && Number(built.chainId) !== ctx.entry.chainId)) {
+            throw new ApiError(409, `The backend built these tasks for ${built.chain} (chain ${built.chainId}), not ${ctx.postingChain}: its posting chain changed. Nothing was sent; try again.`, undefined, 'POSTING_CHAIN_CHANGED');
+        }
+        return checkEscrowCall(built.unsignedTx, {
+            escrow: ctx.escrow,
+            fn: 'createTasks',
+            args: (a) => {
+                if (String(a[0]).toLowerCase() !== ctx.token.toLowerCase())
+                    return false;
+                const tasks = a[1];
+                if (tasks.length !== rows.length)
+                    return false;
+                return rows.every(({ post, taskHash }, j) => {
+                    const t = tasks[j];
+                    const verifier = commitsVerifier(post) ? post.verifierAddress.toLowerCase() : ethers.ZeroAddress;
+                    return String(t[0]).toLowerCase() === taskHash.toLowerCase()
+                        && t[1] === post.amount
+                        && t[2] === TASK_CATEGORY
+                        && t[3] === post.locationZone
+                        && t[4] === BigInt(post.duration)
+                        && String(t[5]).toLowerCase() === verifier;
+                });
+            },
+            value: 0n,
+            chainId: ctx.entry.chainId,
+        }, `Funding ${rows.length} escrows on ${ctx.postingChain}`);
+    }
+    postedTask(ctx, post, sealed, rootHash, txHash, onChainTaskId) {
         return {
-            taskHash,
-            ...(indexed.onChainTaskId !== undefined ? { taskId: String(indexed.onChainTaskId) } : {}),
+            taskHash: sealed.taskHash,
+            ...(onChainTaskId !== undefined ? { taskId: String(onChainTaskId) } : {}),
             txHash,
-            chain: postingChain,
-            chainId: entry.chainId,
+            chain: ctx.postingChain,
+            chainId: ctx.entry.chainId,
             rootHash,
-            privacy,
-            wrappedTo: wrappedKeys ? Object.keys(wrappedKeys).length : 0,
-            ...(aesKey ? { aesKey } : {}),
+            privacy: post.privacy,
+            wrappedTo: sealed.wrappedKeys ? Object.keys(sealed.wrappedKeys).length : 0,
+            ...(sealed.aesKey ? { aesKey: sealed.aesKey } : {}),
         };
     }
+    /**
+     * The escrow's ERC-20 allowance for every row still to fund, approved once,
+     * right before the first funding transaction (after that transaction's
+     * build has been checked, as postTask() approves).
+     */
+    async approveRemaining(run) {
+        if (run.approved)
+            return;
+        let remaining = 0n;
+        for (const i of run.pending)
+            remaining += run.posts[i].amount;
+        const nonce = await ensureAllowance(run.ctx.signer, run.ctx.token, run.ctx.escrow, remaining, { timeoutMs: run.timeoutMs });
+        run.approved = true;
+        if (nonce !== undefined)
+            run.nonce = nonce;
+    }
+    /** Every row a transaction funds, told its hash (again with a replacement's hash if the wallet re-priced it). */
+    async notifyFunded(run, rows, hash, nonce, batch, raw) {
+        for (const { index, indexParams } of rows) {
+            try {
+                await run.opts.onFunded?.({ index, txHash: hash, nonce, ...(raw ? { raw } : {}), taskHash: indexParams.taskHash, batch, indexParams: { ...indexParams, txHash: hash } });
+            }
+            catch { /* the transaction is out; one row's callback must not keep the others from hearing it */ }
+        }
+    }
+    /** One row as its own createTask, the way postTask() posts it. */
+    async postRow(run, i) {
+        const { ctx, retry } = run;
+        const post = run.posts[i];
+        const sealed = run.sealed[i];
+        let call;
+        let rootHash;
+        try {
+            [rootHash] = await this.uploadBriefs([ethers.encodeBase64(sealed.blob)], retry, false);
+            const built = await this.retrying(() => this.createTask(createTaskBody(post, sealed, ctx.token, rootHash)), retry);
+            call = this.checkedCreateCall(ctx, built, post, sealed.taskHash);
+            await this.approveRemaining(run);
+        }
+        catch (err) {
+            await run.settle(failedRow(i, err));
+            return haltsBeforeFunding(err) ? { halt: haltAt(i, err) } : {};
+        }
+        const indexParams = indexParamsFor(post, sealed, rootHash);
+        let txHash;
+        try {
+            const sent = await sendAndWait(ctx.signer, call, {
+                value: ctx.isNative ? post.amount : undefined,
+                nonce: run.nonce,
+                timeoutMs: run.timeoutMs,
+                onSent: (hash, nonce, raw) => this.notifyFunded(run, [{ index: i, indexParams }], hash, nonce, false, raw),
+                unconfirmedHint: (hash) => `If it confirms, call indexTask() with txHash '${hash}' to list the task; do not fund it again.`,
+            });
+            run.nonce = sent.nonce + 1;
+            txHash = sent.hash;
+        }
+        catch (err) {
+            run.nonce = undefined;
+            if (err instanceof UnconfirmedTransactionError) {
+                await run.settle(unlistedRow(i, err.hash, false, indexParams, sealed.aesKey, { code: 'UNCONFIRMED', message: err.message }));
+                return { halt: haltAt(i, err, 'UNCONFIRMED') };
+            }
+            await run.settle(failedRow(i, err));
+            return { halt: haltAt(i, err) };
+        }
+        indexParams.txHash = txHash;
+        try {
+            const indexed = await this.retrying(() => this.indexTask(indexParams), retry, { receiptLag: true });
+            await run.settle({ index: i, status: 'posted', task: this.postedTask(ctx, post, sealed, rootHash, txHash, indexed.onChainTaskId) });
+            return {};
+        }
+        catch (err) {
+            await run.settle(unlistedRow(i, txHash, false, indexParams, sealed.aesKey, errorInfo(err)));
+            return { halt: haltAt(i, err) };
+        }
+    }
+    /** Several rows in one createTasks transaction, listed with one call. */
+    async postChunk(run, unit) {
+        const { ctx, retry } = run;
+        let live = [...unit];
+        const rootHashes = new Map();
+        let call;
+        let gasLimit;
+        try {
+            // Every brief of the chunk is stored before anything of it is built or funded.
+            const roots = await this.uploadBriefs(live.map((i) => ethers.encodeBase64(run.sealed[i].blob)), retry, true);
+            live.forEach((i, j) => rootHashes.set(i, roots[j]));
+            const build = () => this.retrying(() => this.createTasks({
+                token: ctx.token,
+                tasks: live.map((i) => {
+                    const { token: _token, ...task } = createTaskBody(run.posts[i], run.sealed[i], ctx.token, rootHashes.get(i));
+                    return task;
+                }),
+            }), retry);
+            let built;
+            try {
+                built = await build();
+            }
+            catch (err) {
+                // All or nothing: the rows the backend refused fail, and the rest are built again, once.
+                const refused = refusedRows(err, live.length);
+                if (!refused)
+                    throw err;
+                const bad = new Set(refused.map((r) => r.index));
+                for (const r of refused)
+                    await run.settle({ index: live[r.index], status: 'failed', error: { code: r.code, message: r.message } });
+                live = live.filter((_, j) => !bad.has(j));
+                if (live.length === 0)
+                    return {};
+                built = await build();
+            }
+            call = this.checkedCreateTasksCall(ctx, built, live.map((i) => ({ post: run.posts[i], taskHash: run.sealed[i].taskHash })));
+            await this.approveRemaining(run);
+            // A createTasks costs about 200k gas per task. The limit is estimated
+            // here, after the approve it depends on, with headroom; a backend's gas
+            // field is never forwarded (security audit run 1, C41). An estimate that
+            // fails is a revert predicted before anything is sent.
+            const estimate = await ctx.signer.estimateGas({ to: call.to, data: call.data, ...(run.nonce !== undefined ? { nonce: run.nonce } : {}) });
+            gasLimit = (estimate * BATCH_GAS_HEADROOM_PCT) / 100n;
+        }
+        catch (err) {
+            // An escrow that refuses createTasks after all: these rows go one by one.
+            if (err instanceof ApiError && err.code === 'BATCH_UNSUPPORTED')
+                return { fallback: live };
+            for (const i of live)
+                await run.settle(failedRow(i, err));
+            return haltsBeforeFunding(err) ? { halt: haltAt(live[0], err) } : {};
+        }
+        const indexParams = new Map(live.map((i) => [i, indexParamsFor(run.posts[i], run.sealed[i], rootHashes.get(i))]));
+        const funded = live.map((i) => ({ index: i, indexParams: indexParams.get(i) }));
+        let txHash;
+        try {
+            const sent = await sendAndWait(ctx.signer, call, {
+                nonce: run.nonce,
+                gasLimit,
+                timeoutMs: run.timeoutMs,
+                onSent: (hash, nonce, raw) => this.notifyFunded(run, funded, hash, nonce, true, raw),
+                unconfirmedHint: (hash) => `If it confirms, call indexTasks() with txHash '${hash}' to list these tasks; do not fund them again.`,
+            });
+            run.nonce = sent.nonce + 1;
+            txHash = sent.hash;
+        }
+        catch (err) {
+            run.nonce = undefined;
+            if (err instanceof UnconfirmedTransactionError) {
+                for (const i of live)
+                    await run.settle(unlistedRow(i, err.hash, true, indexParams.get(i), run.sealed[i].aesKey, { code: 'UNCONFIRMED', message: err.message }));
+                return { halt: haltAt(live[0], err, 'UNCONFIRMED') };
+            }
+            for (const i of live)
+                await run.settle(failedRow(i, err));
+            return { halt: haltAt(live[0], err) };
+        }
+        for (const params of indexParams.values())
+            params.txHash = txHash;
+        let listed;
+        try {
+            listed = await this.retrying(() => this.indexTasks({
+                txHash,
+                tasks: live.map((i) => {
+                    const { txHash: _tx, ...task } = indexParams.get(i);
+                    return task;
+                }),
+            }), retry, { receiptLag: true });
+        }
+        catch (err) {
+            for (const i of live)
+                await run.settle(unlistedRow(i, txHash, true, indexParams.get(i), run.sealed[i].aesKey, errorInfo(err)));
+            return { halt: haltAt(live[0], err) };
+        }
+        const byHash = new Map((Array.isArray(listed?.results) ? listed.results : []).map((r) => [String(r?.taskHash).toLowerCase(), r]));
+        let firstUnlisted;
+        for (const i of live) {
+            const sealed = run.sealed[i];
+            const r = byHash.get(sealed.taskHash.toLowerCase());
+            if (r && 'indexed' in r && r.indexed) {
+                await run.settle({ index: i, status: 'posted', task: this.postedTask(ctx, run.posts[i], sealed, rootHashes.get(i), txHash, r.onChainTaskId) });
+                continue;
+            }
+            const error = r && 'error' in r && r.error ? r.error : { code: 'NOT_LISTED', message: 'The backend did not say it listed this task.' };
+            await run.settle(unlistedRow(i, txHash, true, indexParams.get(i), sealed.aesKey, error));
+            firstUnlisted ??= { index: i, ...(error.code ? { code: error.code } : {}), message: `funded in ${txHash} but not listed: ${error.message}` };
+        }
+        return firstUnlisted ? { halt: firstUnlisted } : {};
+    }
+    /**
+     * Store briefs (base64) and return their root hashes, in order. Batched
+     * (upload-batch), they go UPLOAD_GROUP to a request, one request after the
+     * other; a group that fails transiently (isTransientUpload) is sent again
+     * one brief per request, each with the backoff, and a brief already stored
+     * comes back at once. Unbatched, each brief is one /storage/upload request
+     * with the backoff. A refusal (a 400) or an answer that does not add up
+     * fails at once.
+     */
+    async uploadBriefs(blobs, retry, batched) {
+        const one = (blob) => this.retrying(() => (batched ? this.uploadBatchRequest([blob]) : this.uploadOneRequest(blob)), retry, { retryable: isTransientUpload });
+        const roots = [];
+        for (let i = 0; i < blobs.length; i += batched ? UPLOAD_GROUP : 1) {
+            const group = blobs.slice(i, i + (batched ? UPLOAD_GROUP : 1));
+            if (group.length === 1) {
+                roots.push(...(await one(group[0])));
+                continue;
+            }
+            try {
+                roots.push(...(await this.uploadBatchRequest(group)));
+            }
+            catch (err) {
+                if (!isTransientUpload(err))
+                    throw err;
+                // A slow storage node pushed the pair past the deadline: one at a time.
+                for (const blob of group)
+                    roots.push(...(await one(blob)));
+            }
+        }
+        return roots;
+    }
+    /** One /storage/upload-batch request, checked to answer one root hash per brief. */
+    async uploadBatchRequest(blobs) {
+        const res = await this.req('POST', '/api/v1/storage/upload-batch', { items: blobs.map((data) => ({ data })) }, { timeoutMs: UPLOAD_TIMEOUT_MS, strictBody: true });
+        const results = Array.isArray(res?.results) ? res.results : [];
+        if (results.length !== blobs.length || results.some((r) => typeof r?.rootHash !== 'string' || !r.rootHash)) {
+            throw new ApiError(0, `The backend answered ${results.length} uploads for ${blobs.length} briefs. Nothing was sent.`, undefined, 'UPLOAD_MISMATCH');
+        }
+        return results.map((r) => r.rootHash);
+    }
+    /** One /storage/upload request, as postTask() stores a brief. */
+    async uploadOneRequest(blob) {
+        const res = await this.req('POST', '/api/v1/storage/upload', { data: blob }, { timeoutMs: UPLOAD_TIMEOUT_MS, strictBody: true });
+        if (typeof res?.rootHash !== 'string' || !res.rootHash) {
+            throw new ApiError(0, 'The backend stored the brief but answered no root hash. Nothing was sent.', undefined, 'UPLOAD_MISMATCH');
+        }
+        return [res.rootHash];
+    }
+    /**
+     * `fn`, asked again after a rate limit, a 5xx or a network error (and, for
+     * a listing, while the backend's RPC has not seen the receipt), or after
+     * what `retryable` says is worth another try.
+     */
+    async retrying(fn, policy, opts = {}) {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                const again = opts.retryable
+                    ? opts.retryable(err)
+                    : isTransient(err) || (!!opts.receiptLag && err instanceof ApiError && err.code === 'RECEIPT_NOT_FOUND');
+                if (!again || attempt >= policy.attempts)
+                    throw err;
+                await new Promise((r) => setTimeout(r, Math.min(policy.baseDelayMs * 2 ** (attempt - 1), MAX_RETRY_DELAY_MS)));
+            }
+        }
+    }
     /**
      * List a funded task on the market (`POST /api/v1/a2a/tasks/index`), from
      * its funding transaction. Safe to call again for the same task: the
@@ -358,25 +954,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 +1011,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 +1498,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 +1536,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 +1564,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 +1645,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. */
@@ -1159,6 +1820,7 @@ export class BlindMarket {
 }
 export { ethers };
 export { ApiError };
+export { SETTLEMENT_PINS, isPinnedSettlement } from './settlementPins.js';
 export { tools, createBlindMarketTools, createTaskTools, createAgentManagementTools, createA2ATools, toLangChainTools, toVercelTools, toOpenAITools, toClaudeTools, } from './tools/index.js';
 export * from './executor/index.js';
 export * from './types.js';