@blindmarket/sdk 0.6.4 → 0.8.0

package/dist/index.js

@@ -1,18 +1,15 @@
 import { ethers } from 'ethers';
-// ── Helpers ─────────────────────────────────────────────────────────────────
-class ApiError extends Error {
-    status;
-    body;
-    code;
-    constructor(status, message, body, 
-    /** Backend error code (e.g. 'NEEDS_WRAP', 'NOT_SUBMITTED_ON_CHAIN'), when the envelope carried one. */
-    code) {
-        super(message);
-        this.status = status;
-        this.body = body;
-        this.code = code;
-        this.name = 'ApiError';
-    }
+import { ApiError } from './apiError.js';
+import { sendAndWait, assertSignerChain, ensureAllowance, tokenBalance, UnconfirmedTransactionError, DEFAULT_CONFIRM_TIMEOUT_MS, } from './onchain.js';
+import { generateAesKey, aesEncrypt, eciesEncrypt, sha256, bytesToHex } from './crypto/index.js';
+import { checkEscrowCall, evidenceHashOf, taskIdOf } from './escrowCalls.js';
+/** A whole number of base units from a string or bigint; throws 400 INVALID_AMOUNT otherwise. */
+function wholeNumber(value, name) {
+    if (typeof value === 'bigint')
+        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');
 }
 // ── Main client ─────────────────────────────────────────────────────────────
 /**
@@ -86,7 +83,10 @@ export class BlindMarket {
         });
         const json = await res.json();
         if (!json.success) {
-            throw new ApiError(res.status, json.error?.message ?? `HTTP ${res.status}`, json, json.error?.code);
+            const err = new ApiError(res.status, json.error?.message ?? `HTTP ${res.status}`, json, json.error?.code);
+            if (typeof json.error?.reason === 'string')
+                err.reason = json.error.reason;
+            throw err;
         }
         return json.data;
     }
@@ -100,7 +100,11 @@ export class BlindMarket {
         return this.req('GET', '/api/v1/stats');
     }
     // ── Task lifecycle ──────────────────────────────────────────────────────
-    /** List open tasks (human-readable). */
+    /**
+     * List open tasks from the legacy 0G TaskRegistry (numeric ids on the 0G
+     * escrow). Tasks escrowed on Base or Arc are not in it: browseA2ATasks()
+     * lists the work agents can take.
+     */
     async listTasks(limit = 20) {
         const { tasks } = await this.req('GET', `/api/v1/tasks?limit=${limit}`);
         return tasks;
@@ -125,16 +129,23 @@ export class BlindMarket {
         return this.req('POST', `/api/v1/tasks/${taskId}/assign`, { worker });
     }
     /**
-     * Build an unsigned `cancelTask` transaction.
+     * Build an unsigned `cancelTask` transaction (the refund of a task no one
+     * has taken). `chain`/`chainId` name where to send it. cancelAndRefund()
+     * builds, signs and sends it for you.
      */
-    async cancelTask(taskId) {
-        return this.req('POST', `/api/v1/tasks/${taskId}/cancel`);
+    async cancelTask(taskId, chain) {
+        // Task ids collide across chains: naming the chain builds for that one.
+        return this.req('POST', `/api/v1/tasks/${taskId}/cancel`, chain ? { chain } : undefined);
     }
     /**
-     * Build an unsigned `claimTimeout` transaction.
+     * 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) {
-        return this.req('POST', `/api/v1/tasks/${taskId}/timeout`);
+    async claimTimeout(taskId, chain) {
+        return this.req('POST', `/api/v1/tasks/${taskId}/timeout`, chain ? { chain } : undefined);
     }
     /**
      * Build an unsigned `submitEvidence` transaction.
@@ -142,10 +153,373 @@ export class BlindMarket {
     async submitEvidence(params) {
         return this.req('POST', '/api/v1/submissions/submit', params);
     }
+    // ── Posting a task end to end ─────────────────────────────────────────────
+    /**
+     * Where new tasks are posted and what each chain settles in
+     * (`GET /health/settlement`): no auth, no RPC reads on the backend.
+     */
+    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
+     * it, build createTask, approve the escrow for the amount when the token is
+     * an ERC-20, fund the escrow, and list the task (`POST /a2a/tasks/index`).
+     *
+     * 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 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.
+     *
+     * @example
+     * const task = await bb.postTask(
+     *   { instructions: 'Summarise this paper in 5 bullets: …', amountRaw: '2000000' }, // 2 USDC
+     *   { onFunded: ({ txHash }) => saveSomewhere(txHash) },
+     * );
+     */
+    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 locationZone = params.locationZone ?? 'global';
+        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');
+            }
+        }
+        // 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,
+            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');
+        }
+        // And it must be exactly this createTask: the escrow, the task hash, the
+        // token, the amount, the zone and the duration asked for (a verifier
+        // commits through createTaskWithVerifier). Only its to and data are signed;
+        // the value is the amount computed here.
+        const withVerifier = verificationMode === 'agent' && !!params.verifierAddress && params.verifierAddress.toLowerCase() !== ethers.ZeroAddress;
+        const createCall = checkEscrowCall(built.unsignedTx, {
+            escrow,
+            fn: withVerifier ? 'createTaskWithVerifier' : 'createTask',
+            args: (a) => String(a[0]).toLowerCase() === taskHash.toLowerCase()
+                && String(a[1]).toLowerCase() === token.toLowerCase()
+                && a[2] === amount
+                && a[4] === locationZone
+                && a[5] === BigInt(duration)
+                && (!withVerifier || String(a[6]).toLowerCase() === params.verifierAddress.toLowerCase()),
+            value: isNative ? amount : 0n,
+            chainId: entry.chainId,
+        }, `Funding the escrow on ${postingChain}`);
+        const timeoutMs = opts.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS;
+        // createTask pulls an ERC-20 with transferFrom: approve the escrow first.
+        const nonce = isNative ? undefined : await ensureAllowance(signer, token, escrow, amount, { timeoutMs });
+        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 } : {}),
+        };
+        let txHash;
+        try {
+            ({ hash: txHash } = await sendAndWait(signer, createCall, {
+                value: isNative ? amount : undefined,
+                nonce,
+                timeoutMs,
+                onSent: (hash) => opts.onFunded?.({ txHash: hash, taskHash, indexParams: { ...indexParams, txHash: hash } }),
+                unconfirmedHint: (hash) => `If it confirms, call indexTask() with txHash '${hash}' to list the task; do not fund it again.`,
+            }));
+        }
+        catch (err) {
+            if (err instanceof UnconfirmedTransactionError) {
+                const out = new ApiError(0, err.message, { indexParams: { ...indexParams, txHash: err.hash } }, 'UNCONFIRMED');
+                out.txHash = err.hash;
+                throw out;
+            }
+            throw err;
+        }
+        indexParams.txHash = txHash;
+        let indexed;
+        try {
+            indexed = await this.indexTaskPatiently(indexParams);
+        }
+        catch (err) {
+            const e = err;
+            const out = new ApiError(e.status ?? 0, `${e.message} — the escrow is funded (transaction ${txHash}) but the task is not listed yet. Call indexTask() with err.body.indexParams to list it, or cancelAndRefund() it; do not post it again.`, { indexParams }, e.code);
+            out.txHash = txHash;
+            throw out;
+        }
+        return {
+            taskHash,
+            ...(indexed.onChainTaskId !== undefined ? { taskId: String(indexed.onChainTaskId) } : {}),
+            txHash,
+            chain: postingChain,
+            chainId: entry.chainId,
+            rootHash,
+            privacy,
+            wrappedTo: wrappedKeys ? Object.keys(wrappedKeys).length : 0,
+            ...(aesKey ? { aesKey } : {}),
+        };
+    }
+    /**
+     * 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
+     * backend merges a repeat from the same poster. postTask() calls it; call
+     * it yourself to finish a post whose funding confirmed but whose listing
+     * failed (the error's `body.indexParams` holds the fields).
+     */
+    async indexTask(params) {
+        return this.req('POST', '/api/v1/a2a/tasks/index', params);
+    }
+    /** indexTask(), asking again while the backend's RPC has not seen the receipt or the backend is briefly down. */
+    async indexTaskPatiently(params) {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await this.indexTask(params);
+            }
+            catch (err) {
+                const transient = err instanceof ApiError
+                    ? err.code === 'RECEIPT_NOT_FOUND' || err.status >= 500
+                    : err instanceof TypeError; // fetch failed: the network, not the request
+                if (!transient || attempt >= 4)
+                    throw err;
+                await new Promise((r) => setTimeout(r, 3_000));
+            }
+        }
+    }
+    /**
+     * Cancel a task no one has taken and get its escrow back: builds
+     * cancelTask, checks the signer is on the task's chain, signs and sends it,
+     * 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), 'cancelTask', 'Cancelling the task', opts);
+    }
+    /**
+     * 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), 'claimTimeout', 'Reclaiming the escrow', 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');
+        }
+        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, entry.chainId, what);
+        let hash;
+        try {
+            ({ hash } = await sendAndWait(signer, call, { timeoutMs: opts.confirmTimeoutMs }));
+        }
+        catch (err) {
+            if (err instanceof UnconfirmedTransactionError) {
+                const out = new ApiError(0, `${err.message} Check it before sending another.`, { txHash: err.hash }, 'UNCONFIRMED');
+                out.txHash = err.hash;
+                throw out;
+            }
+            throw err;
+        }
+        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 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 {
+                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 { closed: false, escalated: false };
+                await new Promise((r) => setTimeout(r, 3_000));
+            }
+        }
+        return { closed: false, escalated: false };
+    }
     // ── Agent deployment & management ─────────────────────────────────────────
+    /** What deploying an agent costs on this backend, and how to pay it. */
+    async getDeployFee() {
+        return this.req('GET', '/api/v1/agents/deploy-fee');
+    }
+    /**
+     * Run every check POST /deploy makes before it takes a fee, with nothing
+     * paid or saved. Throws the same ApiError the deploy would (400 with field
+     * errors, 404 SKILL_NOT_FOUND, 400 INVALID_OWNER_PUBLIC_KEY). Returns false
+     * when the backend predates the check and nothing could be checked.
+     */
+    async validateDeploy(params) {
+        const { ownerAddress: _ignored, ...body } = params;
+        try {
+            await this.req('POST', '/api/v1/agents/deploy/validate', body);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof SyntaxError || (err instanceof ApiError && err.status === 404 && err.code !== 'SKILL_NOT_FOUND'))
+                return false;
+            throw err;
+        }
+    }
     /**
-     * Deploy a new agent. The backend generates a wallet, mints an INFT,
-     * and returns the agent descriptor.
+     * Deploy a new hosted agent. The backend generates its wallet, mints an
+     * INFT, starts it, and returns the agent descriptor.
+     *
+     * Deploying costs a fee (1 USDC on Arc on production; getDeployFee() says).
+     * An unspent AgentFactory credit pays first. Otherwise deployAgent() pays
+     * only with `{ payFee: true }`, from the configured executor wallet (set
+     * `rpcUrls.arc`) or `payer`, which must be the API key's owner. Before it
+     * pays it checks the payer's chain, the fee against `maxFeeRaw`, and the
+     * request itself, so nothing is paid for a deploy that would be refused.
+     *
+     * The fee's hash goes to `onFeePaid` as soon as it is sent, and onto any
+     * error after that (`err.feeTxHash`): retry with `params.feeTxHash` set to
+     * it and nothing is paid twice. A retry whose payment already created one
+     * of your agents returns that agent, with `alreadyDeployed: true`.
      *
      * @example
      * const agent = await bb.deployAgent({
@@ -154,13 +528,178 @@ export class BlindMarket {
      *   provider: 'anthropic',
      *   model: 'claude-sonnet-4-5',
      *   apiKey: process.env.ANTHROPIC_API_KEY!,
-     *   ownerAddress: wallet.address,
      *   // Uncompressed, no 0x (`wallet` is an ethers Wallet; its `publicKey` is compressed).
      *   ownerPublicKey: wallet.signingKey.publicKey.slice(2),
-     * });
+     * }, { payFee: true, onFeePaid: (hash) => saveSomewhere(hash) });
      */
-    async deployAgent(params) {
-        return this.req('POST', '/api/v1/agents/deploy', params);
+    async deployAgent(params, opts = {}) {
+        const { ownerAddress: _ignored, feeTxHash: given, ...rest } = params;
+        const body = rest;
+        const pollMs = opts.pollIntervalMs ?? 5_000;
+        // A named payment: the backend may still be waiting for its receipt.
+        if (given)
+            return this.deployWithFee(body, given, pollMs);
+        let terms;
+        try {
+            terms = await this.getDeployFee();
+        }
+        catch (err) {
+            // A backend from before the fee route: deploy as the SDK always did.
+            if (err instanceof SyntaxError || (err instanceof ApiError && err.status === 404))
+                return this.postDeploy(body, [], 1, pollMs);
+            throw err;
+        }
+        if (!terms.required)
+            return this.postDeploy(body, [], 1, pollMs);
+        // An unspent AgentFactory credit pays before anything new is spent. This
+        // POST also runs every check the deploy makes: a request it would refuse
+        // fails here, before a payment.
+        try {
+            return await this.postDeploy(body, [], 1, pollMs);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError && err.code === 'NO_DEPLOY_CREDIT'))
+                throw err;
+            if (!opts.payFee) {
+                const cost = terms.method === 'transfer'
+                    ? `${ethers.formatUnits(BigInt(terms.amountRaw), terms.decimals).replace(/\.0$/, '')} USDC on ${terms.chain}`
+                    : `a fee through AgentFactory on ${terms.chain}`;
+                throw new ApiError(402, `Deploying an agent costs ${cost}. Call deployAgent(params, { payFee: true }) to pay it from your wallet, or pay it yourself and pass params.feeTxHash.`, { terms }, 'DEPLOY_FEE_REQUIRED');
+            }
+        }
+        // Everything checkable is checked before anything is paid.
+        if (body.provider !== '0g-compute' && !body.apiKey) {
+            throw new ApiError(400, `A ${body.provider} agent needs params.apiKey to call its model. Nothing was paid.`, undefined, 'API_KEY_REQUIRED');
+        }
+        if (terms.chainId === undefined) {
+            throw new ApiError(409, 'This backend does not say which chain its deploy fee is paid on, so it cannot be paid safely from here. Nothing was paid.', { terms }, 'DEPLOY_FEE_CHAIN_UNKNOWN');
+        }
+        const maxFee = BigInt(opts.maxFeeRaw ?? 1000000n);
+        const payer = opts.payer ?? this.signerOn(terms.chain, 'Paying the deploy fee');
+        const payerAddress = await payer.getAddress();
+        await this.assertFeePayer(payerAddress);
+        await assertSignerChain(payer, terms.chainId, 'The deploy fee');
+        const timeoutMs = opts.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS;
+        if (terms.method === 'transfer') {
+            const fee = BigInt(terms.amountRaw);
+            this.assertFeeCeiling(fee, maxFee, terms.decimals);
+            const data = new ethers.Interface(['function transfer(address to, uint256 amount) returns (bool)'])
+                .encodeFunctionData('transfer', [terms.recipient, fee]);
+            let hash;
+            try {
+                ({ hash } = await sendAndWait(payer, { to: terms.token, data }, {
+                    onSent: opts.onFeePaid,
+                    timeoutMs,
+                    unconfirmedHint: (h) => `If it confirms, retry with params.feeTxHash = '${h}' so the fee is not paid twice.`,
+                }));
+            }
+            catch (err) {
+                if (err instanceof UnconfirmedTransactionError)
+                    throw this.withFee(err, err.hash, 'UNCONFIRMED');
+                throw err;
+            }
+            return this.deployWithFee(body, hash, pollMs);
+        }
+        if (!terms.factory)
+            throw new ApiError(503, 'This backend charges through AgentFactory but names no factory address.', { terms }, 'DEPLOY_FEE_UNAVAILABLE');
+        const factory = new ethers.Interface(['function deployAgent(uint256 usdcAmount)', 'function deployFeeUsdc() view returns (uint256)', 'function usdc() view returns (address)']);
+        const reader = payer.provider;
+        const [fee] = factory.decodeFunctionResult('deployFeeUsdc', await reader.call({ to: terms.factory, data: factory.encodeFunctionData('deployFeeUsdc') }));
+        const [token] = factory.decodeFunctionResult('usdc', await reader.call({ to: terms.factory, data: factory.encodeFunctionData('usdc') }));
+        this.assertFeeCeiling(fee, maxFee, 6);
+        const nonce = await ensureAllowance(payer, token, terms.factory, fee, { timeoutMs });
+        let factoryTx;
+        try {
+            ({ hash: factoryTx } = await sendAndWait(payer, { to: terms.factory, data: factory.encodeFunctionData('deployAgent', [0]) }, { nonce, timeoutMs }));
+        }
+        catch (err) {
+            if (err instanceof UnconfirmedTransactionError) {
+                throw new ApiError(0, `${err.message} If it confirms, its credit pays for the next deployAgent() call; do not pay again.`, { factoryTxHash: err.hash }, 'UNCONFIRMED');
+            }
+            throw err;
+        }
+        // The backend indexes the factory every 15s: the credit lags the payment.
+        try {
+            return { ...(await this.postDeploy(body, ['NO_DEPLOY_CREDIT'], 20, pollMs)), feeTxHash: factoryTx };
+        }
+        catch (err) {
+            const e = err;
+            throw new ApiError(e.status ?? 500, `${e.message} The fee was paid through AgentFactory (transaction ${factoryTx}): its credit stays with your wallet and pays for the next deployAgent() call, so do not pay again.`, err instanceof ApiError ? err.body : undefined, e.code);
+        }
+    }
+    /** Deploy with a fee transaction already paid: wait for the backend to see it, and make a retry safe. */
+    async deployWithFee(body, feeTxHash, pollMs) {
+        try {
+            const agent = await this.postDeploy({ ...body, feeTxHash }, ['DEPLOY_FEE_NOT_FOUND', 'DEPLOY_FEE_IN_USE', 'DEPLOY_FEE_CHECK_FAILED'], 4, pollMs);
+            return { ...agent, feeTxHash };
+        }
+        catch (err) {
+            // This payment already created an agent: a retry after a lost response.
+            // Return it when it is the caller's.
+            if (err instanceof ApiError && err.code === 'DEPLOY_FEE_ALREADY_USED') {
+                const agentId = err.body?.error?.agentId;
+                const existing = agentId ? await this.ownAgent(agentId).catch(() => null) : null;
+                if (existing)
+                    return { ...existing, feeTxHash, alreadyDeployed: true };
+            }
+            throw this.withFee(err, feeTxHash);
+        }
+    }
+    /** `agentId` as a DeployedAgent, when the API key's owner owns it; else null. */
+    async ownAgent(agentId) {
+        const [agent, who] = await Promise.all([this.getAgent(agentId), this.whoami()]);
+        const mine = new Set([who.address, ...(who.addresses ?? [])].map((a) => String(a).toLowerCase()));
+        if (!agent?.ownerAddress || !mine.has(agent.ownerAddress.toLowerCase()))
+            return null;
+        const { id, name, walletAddress, publicKey, inftTokenId, status } = agent;
+        return { id, name, walletAddress, publicKey, status, ...(inftTokenId !== undefined ? { inftTokenId } : {}) };
+    }
+    /**
+     * An error after the fee was paid, carrying the payment: `feeTxHash` on the
+     * error and in its body, and the message says how to reuse it. The
+     * backend's code, status and envelope are kept.
+     */
+    withFee(err, feeTxHash, fallbackCode) {
+        const e = err;
+        const spent = err instanceof ApiError && ['DEPLOY_FEE_ALREADY_USED', 'DEPLOY_FEE_NOT_PAID', 'DEPLOY_FEE_REVERTED'].includes(err.code ?? '');
+        const message = spent || e.message.includes(feeTxHash)
+            ? e.message
+            : `${e.message} — the deploy fee is paid (transaction ${feeTxHash}); retry with params.feeTxHash = '${feeTxHash}' so it is not paid twice.`;
+        const body = e.body && typeof e.body === 'object' ? { ...e.body, feeTxHash } : { feeTxHash };
+        const out = new ApiError(e.status ?? 0, message, body, e.code ?? fallbackCode);
+        if (err instanceof ApiError && err.reason)
+            out.reason = err.reason;
+        out.feeTxHash = feeTxHash;
+        return out;
+    }
+    assertFeeCeiling(fee, maxFee, decimals) {
+        if (fee <= maxFee)
+            return;
+        const fmt = (v) => ethers.formatUnits(v, decimals).replace(/\.0$/, '');
+        throw new ApiError(402, `The deploy fee is ${fmt(fee)} USDC, above your limit of ${fmt(maxFee)}. Nothing was paid. Raise opts.maxFeeRaw to pay it.`, { feeRaw: fee.toString(), maxFeeRaw: maxFee.toString() }, 'DEPLOY_FEE_ABOVE_MAX');
+    }
+    /** POST /agents/deploy, asking again while the backend answers one of `retryCodes`. */
+    async postDeploy(body, retryCodes, attempts, pollMs) {
+        for (let i = 1;; i++) {
+            try {
+                return await this.req('POST', '/api/v1/agents/deploy', body);
+            }
+            catch (err) {
+                if (!(err instanceof ApiError) || !retryCodes.includes(err.code ?? '') || i >= attempts)
+                    throw err;
+                await new Promise((r) => setTimeout(r, pollMs));
+            }
+        }
+    }
+    /** The configured executor as a signer on `chain`. */
+    signerOn(chain, what) {
+        if (!this.executor) {
+            throw new ApiError(400, `${what} needs a signer: set BlindMarketConfig.executor, or pass one in the options.`, undefined, 'NO_SIGNER');
+        }
+        const rpc = this.executor.rpcUrls[chain];
+        if (!rpc)
+            throw new ApiError(400, `${what} happens on ${chain}, but no RPC is configured for it — set rpcUrls.${chain}.`, undefined, 'NO_RPC');
+        return new ethers.Wallet(this.executor.privateKey, new ethers.JsonRpcProvider(rpc));
     }
     /**
      * One-shot executor registration in the A2A marketplace.
@@ -257,6 +796,30 @@ export class BlindMarket {
         }
         return true;
     }
+    /**
+     * Before a spend: throw 409 OWNER_MISMATCH unless `address` is a wallet the
+     * backend will credit the spend to. `exact` needs the API key's own address
+     * (a task is posted as that wallet); otherwise any wallet linked to it
+     * counts, as the deploy fee check does. Unlike assertOwnerKey this fails
+     * closed: money never moves on an unchecked wallet.
+     */
+    async assertSpender(address, what, exact) {
+        let who;
+        try {
+            who = await this.whoami();
+        }
+        catch (err) {
+            throw new ApiError(err instanceof ApiError ? err.status : 503, `${what}: could not check which wallet this API key belongs to (${err.message}). Nothing was sent.`, undefined, 'OWNER_UNCHECKED');
+        }
+        const allowed = new Set([who.address, ...(exact ? [] : who.addresses ?? [])].filter((a) => typeof a === 'string').map((a) => a.toLowerCase()));
+        if (!allowed.has(address.toLowerCase())) {
+            throw new ApiError(409, `This API key belongs to ${who.address} but the signer is ${address}. Nothing was sent. ` +
+                `${what} counts only from the API key's own wallet: sign with that wallet, or mint an API key signed in as this one.`, undefined, 'OWNER_MISMATCH');
+        }
+    }
+    assertFeePayer(address) {
+        return this.assertSpender(address, 'A deploy fee', false);
+    }
     /** List deployed agents, optionally filtered by owner address. */
     async listAgents(ownerAddress) {
         const qs = ownerAddress ? `?owner=${ownerAddress}` : '';
@@ -377,13 +940,34 @@ export class BlindMarket {
      * unsigned `submitEvidence` on the chain the backend names → `finalize()`.
      * Safe to re-call on a task stranded in 'submitted': INVALID_STATE at submit
      * and NOT_SUBMITTED_ON_CHAIN at finalize both heal through `rebroadcast()`.
+     *
+     * The executor key signs only a zero-value `submitEvidence(onChainTaskId,
+     * evidenceHash)` on the escrow /health/settlement lists for that chain,
+     * where (from /submit) evidenceHash is keccak256 of `JSON.stringify(resultData)`,
+     * over an RPC checked to serve that chain, and only its to and data.
+     * Anything else throws 409 ESCROW_MISMATCH, TX_MISMATCH, CHAIN_MISMATCH or
+     * CHAIN_UNKNOWN (or WRONG_CHAIN for the RPC) with nothing sent.
      */
     async deliverResult(taskId, resultData, signerOverride) {
         const signer = signerOverride ?? this.executor;
         if (!signer) {
             throw new ApiError(400, 'deliverResult() needs a signer — pass one, or set BlindMarketConfig.executor. submitEvidence is onlyWorker, so the backend cannot broadcast it for you.');
         }
-        const send = async (built) => {
+        // Read before /submit, which records the result: a lookup failing here
+        // leaves nothing half-done.
+        const settlement = await this.getSettlement();
+        // The evidence the backend commits for this result (backend/src/routes/a2a.ts).
+        const evidence = evidenceHashOf(resultData);
+        const what = `Delivering task ${taskId}`;
+        /**
+         * Sign the submitEvidence the backend built, once it is checked to be a
+         * zero-value submitEvidence on the escrow of the chain it names, for the
+         * on-chain task it names, and (from /submit) committing THIS result. Only
+         * its to and data are signed, on the signer's RPC for that chain, checked
+         * to serve it. /rebroadcast re-sends the first stored result, so there the
+         * evidence hash is not this call's.
+         */
+        const send = async (built, fromSubmit) => {
             if (!built.unsignedSubmitEvidence)
                 return undefined;
             // Absent `chain` = a backend older than the field, where every task is on 0G.
@@ -394,16 +978,24 @@ export class BlindMarket {
             if (!rpc) {
                 throw new Error(`task ${taskId} is escrowed on ${chain} but no RPC is configured for it — set rpcUrls.${chain}`);
             }
-            // The tx carries chainId, so a wrong RPC fails at ethers instead of
-            // landing on the wrong network.
+            const entry = await this.settlementEntry(chain, what, settlement);
+            const onChainId = built.onChainTaskId === undefined ? undefined : taskIdOf(built.onChainTaskId);
+            const call = checkEscrowCall(built.unsignedSubmitEvidence, {
+                escrow: entry.escrowAddress,
+                fn: 'submitEvidence',
+                args: (a) => (built.onChainTaskId === undefined || a[0] === onChainId)
+                    && (!fromSubmit || String(a[1]).toLowerCase() === evidence),
+                chainId: entry.chainId,
+            }, what);
             const wallet = new ethers.Wallet(signer.privateKey, new ethers.JsonRpcProvider(rpc));
-            const tx = await wallet.sendTransaction(built.unsignedSubmitEvidence);
+            await assertSignerChain(wallet, entry.chainId, what);
+            const tx = await wallet.sendTransaction(call);
             await tx.wait();
             return tx.hash;
         };
         const healStranded = async () => {
             try {
-                return await send(await this.rebroadcast(taskId));
+                return await send(await this.rebroadcast(taskId), false);
             }
             catch (err) {
                 // Evidence is already on-chain — nothing to broadcast, go finalize.
@@ -414,7 +1006,7 @@ export class BlindMarket {
         };
         let submitTxHash;
         try {
-            submitTxHash = await send(await this.submitResult(taskId, resultData));
+            submitTxHash = await send(await this.submitResult(taskId, resultData), true);
         }
         catch (err) {
             if (!(err instanceof ApiError && err.code === 'INVALID_STATE'))
@@ -431,6 +1023,16 @@ export class BlindMarket {
             return { ...(await this.finalize(taskId)), submitTxHash };
         }
     }
+    /**
+     * Approve or reject the delivered result of a task you posted with
+     * `verificationMode: 'manual'` (`POST /api/v1/a2a/tasks/:hash/verify`).
+     * Approving settles the escrow to the worker (90%); rejecting fails the
+     * round, and the worker may resubmit before the deadline. Only the poster
+     * can review, and only once the task is `submitted`.
+     */
+    async reviewResult(taskHash, review) {
+        return this.req('POST', `/api/v1/a2a/tasks/${encodeURIComponent(taskHash)}/verify`, review);
+    }
     /** Get tasks posted by the authenticated user. */
     async getPostedTasks() {
         return this.req('GET', '/api/v1/a2a/tasks/posted');
@@ -470,7 +1072,11 @@ export class BlindMarket {
         return this.req('GET', `/api/v1/reputation/leaderboard?limit=${limit}`);
     }
     // ── Storage ─────────────────────────────────────────────────────────────
-    /** Upload an encrypted blob to 0G Storage. */
+    /**
+     * Upload a blob to 0G Storage. `data` is the bytes as **base64**: the
+     * backend base64-decodes it. (The type once said Hex; a hex string sent
+     * here uploads the wrong bytes.)
+     */
     async uploadBlob(data) {
         return this.req('POST', '/api/v1/storage/upload', { data });
     }
@@ -481,7 +1087,8 @@ export class BlindMarket {
      * which returns `{ rootHash, blob }`, not `{ data }`.
      */
     async downloadBlob(rootHash) {
-        return this.req('GET', `/api/v1/storage/${rootHash}`);
+        // Encoded so a rootHash can never step out of /storage/.
+        return this.req('GET', `/api/v1/storage/${encodeURIComponent(rootHash)}`);
     }
     // ── Messages ─────────────────────────────────────────────────────────────
     /** Send a message to another user or agent. */