@blindmarket/sdk 0.7.0 → 0.9.0

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,10 @@ 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;
+    /** The chain id each configured RPC answered, by URL, kept once it matched the backend's. */
+    rpcChainIds = new Map();
     constructor(config) {
         this.config = { ...DEFAULTS, ...config };
         this.bb = new BlindMarket({ apiKey: config.apiKey, apiBase: config.apiBase });
@@ -132,6 +173,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 +362,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 +385,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;
@@ -371,6 +444,40 @@ export class WorkerRuntime {
         return retry;
     }
     // ── Accept ──────────────────────────────────────────────────────────────
+    /**
+     * Why a task on `chain` must not be accepted, or null: this runtime's RPC
+     * for the chain answers another chain id than the one the backend settles
+     * it on (GET /health/settlement). A chain keeps its key when the backend
+     * moves it to another network (Arc Testnet 5042002, Arc mainnet 5042), and
+     * submitEvidence can only be signed where the task is. Nothing is held back
+     * when either side cannot be read or the backend does not list the chain:
+     * deliverResult() checks the chain again before it signs.
+     */
+    async wrongNetwork(chain) {
+        const known = SETTLEMENT_CHAINS.find((c) => c === chain);
+        const rpc = known ? rpcFor(this.config, known) : undefined;
+        if (!rpc)
+            return null;
+        try {
+            const { chains } = await this.bb.getSettlement();
+            const listed = chains.find((c) => c.chain === chain)?.chainId;
+            if (listed === undefined || !Number.isInteger(listed))
+                return null;
+            // A match is kept: a URL's network does not change under it. Anything
+            // else is asked again next time, so one wrong answer is not kept.
+            if (this.rpcChainIds.get(rpc) === BigInt(listed))
+                return null;
+            const served = (await new ethers.JsonRpcProvider(rpc).getNetwork()).chainId;
+            if (served === BigInt(listed)) {
+                this.rpcChainIds.set(rpc, served);
+                return null;
+            }
+            return `the RPC for ${chain} serves chain ${served}, but the backend settles ${chain} on chain ${listed}, where this runtime could not sign its submitEvidence. Point it at chain ${listed}.`;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * POST /accept, re-trying while the backend says the claim is still ours:
      * 503 ASSIGNMENT_PENDING means the assign tx is broadcast but unconfirmed
@@ -516,6 +623,19 @@ export class WorkerRuntime {
         if (!exec)
             return;
         try {
+            // An accept assigns on-chain for good, so not on a network this
+            // runtime's RPC is not on. The task is looked at again after a back-off
+            // that grows while the answer stays wrong.
+            const wrong = await this.wrongNetwork(meta?.chain);
+            if (wrong) {
+                this.executions.delete(taskId);
+                const retry = this.retryState(taskId);
+                retry.reaccept = undefined;
+                retry.failures++;
+                retry.notBefore = Date.now() + backoff(RELEASED_BACKOFF_MS, retry.failures, MAX_BACKOFF_MS);
+                this.emit({ type: 'task_failed', taskId, error: `not accepted: ${wrong}` });
+                return;
+            }
             // Accept task — get the rootHash + this executor's ECIES-wrapped AES
             // key. wrappedKey is a single hex string (this caller's slice), not a
             // Record — see acceptTask()'s doc comment in ../index.ts.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ethers } from 'ethers';
 import { ApiError } from './apiError.js';
+import { type SettlementPin } from './settlementPins.js';
 import type { Address, Hex, RootHash, HealthStatus, PlatformStats, OpenTask, TaskDetail, CreateTaskTx, ExecutorProfile, RegisterExecutorInput, DeployedAgentInfo, AgentWalletInfo, ReputationInfo, LeaderboardEntry, StorageUploadResult, Message, AgentSearchResult, TaskTemplate, VerifyTaskInput, A2ATaskEntry, AgentCapability, CreateAgentParams, CreateAgentResult, CreateTaskRequest } from './types.js';
 export interface BlindMarketConfig {
     /** Backend API base URL (default: https://api.blindmarket.xyz) */
@@ -13,6 +14,14 @@ export interface BlindMarketConfig {
      * never take a key as an argument. Stays in-process; never sent to the backend.
      */
     executor?: DeliverSigner;
+    /**
+     * Escrows postTask() and postTasks() may fund besides the known
+     * deployments (SETTLEMENT_PINS: Arc mainnet and Arc Testnet), for a custom
+     * or local deployment. Each names its chain id, escrow and settlement
+     * token; the backend's /health/settlement must name exactly one of them, or
+     * nothing is approved or funded (ESCROW_NOT_PINNED).
+     */
+    trustedEscrows?: SettlementPin[];
 }
 export interface DeployAgentParams {
     name: string;
@@ -141,6 +150,12 @@ export interface PostTaskParams {
     targetExecutor?: Address;
     /** Default 'global'. */
     locationZone?: string;
+    /**
+     * A public one-liner shown on the task board, at most 500 characters. A
+     * private task's brief is sealed, so this is what the board says it is
+     * about: keep secrets out of it.
+     */
+    routingSummary?: string;
 }
 export interface PostTaskOptions {
     /**
@@ -162,6 +177,8 @@ export interface PostTaskOptions {
      */
     onFunded?: (funding: {
         txHash: string;
+        nonce: number;
+        raw?: string;
         taskHash: string;
         indexParams: IndexTaskParams;
     }) => void | Promise<void>;
@@ -200,6 +217,168 @@ export interface IndexTaskParams {
     verifierAddress?: Address;
     requiredCapabilities?: AgentCapability[];
     targetExecutor?: Address;
+    routingSummary?: string;
+}
+export interface PostTasksOptions {
+    /** As postTask(): signs on the posting chain instead of the configured executor, and must be the API key's own wallet. */
+    signer?: ethers.Signer;
+    /**
+     * The most postTasks() will lock in escrow across every row, in the
+     * token's smallest unit. Refused with AMOUNT_ABOVE_MAX before anything is sent.
+     */
+    maxTotalRaw?: bigint | string;
+    /**
+     * Tasks per transaction on an escrow that has createTasks (SettlementChainInfo.batchCreate).
+     * Default 20, at most the chain's maxBatch and 50. On an escrow without
+     * it every task is its own transaction and this is ignored.
+     */
+    chunkSize?: number;
+    /** Called as each row settles: posted, unlisted, failed or skipped. A throwing callback does not stop the run. */
+    onProgress?: (progress: {
+        done: number;
+        total: number;
+        result: PostTasksRowResult;
+    }) => void | Promise<void>;
+    /**
+     * Called the moment a funding transaction is broadcast, once for every row
+     * it funds. Persist `indexParams`: if this process dies before the row is
+     * listed, indexTask(indexParams) lists it without funding it again, or
+     * indexTasks() for rows whose `batch` is true, which share one transaction
+     * (the single index route refuses a receipt that funded several tasks).
+     */
+    onFunded?: (funding: {
+        index: number;
+        txHash: string;
+        nonce: number;
+        raw?: string;
+        taskHash: string;
+        batch: boolean;
+        indexParams: IndexTaskParams;
+    }) => void | Promise<void>;
+    /** How long to wait for each transaction to confirm. Default 180000 ms. */
+    confirmTimeoutMs?: number;
+    /**
+     * Stops the run before the next row, or the next transaction of rows; a
+     * transaction already sent is always seen through to its listing. Rows not
+     * started come back 'skipped'.
+     */
+    signal?: AbortSignal;
+    /**
+     * Backoff for a rate limit (429), a 5xx or a network error on a read, an
+     * upload, a build or a listing: `attempts` tries in all (default 5), the
+     * wait doubling from `baseDelayMs` (default 2000). A funding transaction is
+     * never sent twice.
+     */
+    retry?: {
+        attempts?: number;
+        baseDelayMs?: number;
+    };
+}
+/** A row that cannot be posted as it is, from postTasks()' checks before anything is sent (ApiError INVALID_ROWS, `body.errors`). */
+export interface PostTasksRowError {
+    /** The row's position in the array passed to postTasks(). */
+    index: number;
+    code: string;
+    message: string;
+}
+/** What happened to one row of postTasks(), by its position in the input. */
+export type PostTasksRowResult = 
+/** Funded and listed. */
+{
+    index: number;
+    status: 'posted';
+    task: PostedTask;
+}
+/**
+ * Funded (or sent and maybe funded, with code UNCONFIRMED) but not listed.
+ * Do not post it again: list it with indexTask(indexParams), or with
+ * indexTasks() when `batch` is true, or cancel it for a refund.
+ */
+ | {
+    index: number;
+    status: 'unlisted';
+    taskHash: string;
+    txHash: string;
+    batch: boolean;
+    indexParams: IndexTaskParams;
+    aesKey?: string;
+    error: {
+        code?: string;
+        message: string;
+    };
+}
+/** Nothing was funded for this row. */
+ | {
+    index: number;
+    status: 'failed';
+    error: {
+        code?: string;
+        message: string;
+    };
+}
+/** Not started: the run was aborted, or stopped at an earlier row. */
+ | {
+    index: number;
+    status: 'skipped';
+    reason: string;
+};
+export interface PostTasksResult {
+    chain: string;
+    chainId: number;
+    /** 'batch': createTasks, several tasks per transaction. 'single': one createTask per task. */
+    mode: 'batch' | 'single';
+    /** One per input row, in input order. */
+    results: PostTasksRowResult[];
+    posted: number;
+    unlisted: number;
+    failed: number;
+    skipped: number;
+    /**
+     * Why the run stopped before the last row, when it did: an on-chain or
+     * listing failure (so no further escrow is funded behind it), a backend
+     * that built the wrong transaction, one that stayed unreachable, or the abort signal.
+     */
+    stopped?: {
+        index: number;
+        code?: string;
+        message: string;
+    };
+}
+/** POST /api/v1/tasks/batch: several posts built into one createTasks transaction. */
+export interface CreateTasksRequest {
+    token: Address;
+    tasks: Array<Omit<CreateTaskRequest, 'token'>>;
+}
+export interface CreateTasksTx {
+    unsignedTx: {
+        to: Address;
+        data: Hex;
+        value?: string;
+        from?: Address;
+    };
+    chain?: string;
+    chainId?: number;
+    /** The task hashes the transaction escrows, in order. */
+    taskHashes?: string[];
+}
+/** POST /api/v1/a2a/tasks/index-batch: list the tasks one transaction funded. */
+export interface IndexTasksParams {
+    txHash: string;
+    isUserOp?: boolean;
+    tasks: Array<Omit<IndexTaskParams, 'txHash'>>;
+}
+export interface IndexTasksResult {
+    results: Array<{
+        taskHash: string;
+        onChainTaskId?: string;
+        indexed: true;
+    } | {
+        taskHash: string;
+        error: {
+            code?: string;
+            message: string;
+        };
+    }>;
 }
 /** A refund the client signed and sent: cancelAndRefund() or reclaimAfterTimeout(). */
 export interface RefundResult {
@@ -208,6 +387,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. */
@@ -231,6 +418,15 @@ export interface SettlementChainInfo {
     relayChain?: string | null;
     gasSymbol?: string;
     postable?: boolean;
+    /**
+     * Whether this chain's escrow has createTasks (several tasks in one
+     * transaction), and how many one call takes. Absent from older backends,
+     * which is the same as unsupported.
+     */
+    batchCreate?: {
+        supported: boolean;
+        maxBatch: number;
+    };
 }
 /** Per-chain RPC URLs for signing `submitEvidence` — a task is escrowed on exactly one chain. */
 export interface DeliverSigner {
@@ -263,6 +459,7 @@ export declare class BlindMarket {
     private apiBase;
     private apiKey;
     private executor?;
+    private trustedEscrows;
     constructor(config: BlindMarketConfig);
     /** True when an executor signer was configured (see BlindMarketConfig.executor). */
     get canSign(): boolean;
@@ -292,12 +489,22 @@ export declare class BlindMarket {
      * generateText({ model, tools: tools(bb).vercel });
      * ```
      */
+    /**
+     * `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.
+     */
     private req;
     /** Backend liveness check. */
     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 +534,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 +562,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 +577,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.
      *
@@ -371,6 +591,109 @@ export declare class BlindMarket {
      * );
      */
     postTask(params: PostTaskParams, opts?: PostTaskOptions): Promise<PostedTask>;
+    /**
+     * 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}`),
+     * });
+     */
+    postTasks(rows: PostTaskParams[], opts?: PostTasksOptions): Promise<PostTasksResult>;
+    /**
+     * 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.
+     */
+    createTasks(params: CreateTasksRequest): Promise<CreateTasksTx>;
+    /**
+     * 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.
+     */
+    indexTasks(params: IndexTasksParams): Promise<IndexTasksResult>;
+    /**
+     * 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.
+     */
+    uploadBlobs(data: string[]): Promise<Array<{
+        rootHash: string;
+        txHash?: string;
+    }>>;
+    /** The posting chain, its escrow and token, and a signer checked to be the API key's own wallet on that chain. */
+    private postingContext;
+    /** Throws 402 INSUFFICIENT_BALANCE, with nothing sent, when the wallet holds less than `amount` of an ERC-20 settlement token. */
+    private assertCovers;
+    /** The executors on the posting chain a private brief can be wrapped to. */
+    private postingExecutors;
+    /**
+     * 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.
+     */
+    private checkedCreateCall;
+    /** The backend's createTasks, checked to be exactly these posts, in this order, for this token, escrow and chain. */
+    private checkedCreateTasksCall;
+    private postedTask;
+    /**
+     * 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).
+     */
+    private approveRemaining;
+    /** Every row a transaction funds, told its hash (again with a replacement's hash if the wallet re-priced it). */
+    private notifyFunded;
+    /** One row as its own createTask, the way postTask() posts it. */
+    private postRow;
+    /** Several rows in one createTasks transaction, listed with one call. */
+    private postChunk;
+    /**
+     * 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.
+     */
+    private uploadBriefs;
+    /** One /storage/upload-batch request, checked to answer one root hash per brief. */
+    private uploadBatchRequest;
+    /** One /storage/upload request, as postTask() stores a brief. */
+    private uploadOneRequest;
+    /**
+     * `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.
+     */
+    private retrying;
     /**
      * 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
@@ -391,16 +714,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 +982,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;
@@ -818,6 +1165,8 @@ export declare class BlindMarket {
 }
 export { ethers };
 export { ApiError };
+export { SETTLEMENT_PINS, isPinnedSettlement } from './settlementPins.js';
+export type { SettlementPin } from './settlementPins.js';
 export { tools, createBlindMarketTools, createTaskTools, createAgentManagementTools, createA2ATools, toLangChainTools, toVercelTools, toOpenAITools, toClaudeTools, } from './tools/index.js';
 export type { Tool, ToolKit, ToolDefinition } from './tools/types.js';
 export type { BlindMarketTools } from './tools/index.js';