@blindmarket/sdk 0.6.1 → 0.6.2

package/dist/index.d.ts

@@ -1,10 +1,17 @@
 import { ethers } from 'ethers';
-import type { Address, Hex, RootHash, HealthStatus, PlatformStats, OpenTask, TaskDetail, CreateTaskTx, ExecutorProfile, RegisterExecutorInput, DeployedAgentInfo, AgentWalletInfo, ReputationInfo, LeaderboardEntry, StorageUploadResult, Message, AgentSearchResult, TaskTemplate, VerifyTaskInput, A2ATaskState, CreateAgentParams, CreateAgentResult } from './types.js';
+import type { Address, Hex, RootHash, HealthStatus, PlatformStats, OpenTask, TaskDetail, CreateTaskTx, ExecutorProfile, RegisterExecutorInput, DeployedAgentInfo, AgentWalletInfo, ReputationInfo, LeaderboardEntry, StorageUploadResult, Message, AgentSearchResult, TaskTemplate, VerifyTaskInput, A2ATaskEntry, CreateAgentParams, CreateAgentResult, CreateTaskRequest } from './types.js';
 export interface BlindMarketConfig {
     /** Backend API base URL (default: https://api.blindmarket.xyz) */
     apiBase?: string;
     /** API key — shared AGENT_API_KEY or device-flow token */
     apiKey: string;
+    /**
+     * Executor signer: the private key of the wallet that owns `apiKey`, plus
+     * the RPC(s) to broadcast `submitEvidence` on. Default for `createAgent()`
+     * and `deliverResult()`, and what enables the `submit_result` tool — tools
+     * never take a key as an argument. Stays in-process; never sent to the backend.
+     */
+    executor?: DeliverSigner;
 }
 export interface DeployAgentParams {
     name: string;
@@ -28,7 +35,18 @@ export interface DeployedAgent {
 declare class ApiError extends Error {
     status: number;
     body?: unknown | undefined;
-    constructor(status: number, message: string, body?: unknown | undefined);
+    /** Backend error code (e.g. 'NEEDS_WRAP', 'NOT_SUBMITTED_ON_CHAIN'), when the envelope carried one. */
+    code?: string | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined, 
+    /** Backend error code (e.g. 'NEEDS_WRAP', 'NOT_SUBMITTED_ON_CHAIN'), when the envelope carried one. */
+    code?: string | undefined);
+}
+/** Per-chain RPC URLs for signing `submitEvidence` — a task is escrowed on exactly one chain. */
+export interface DeliverSigner {
+    /** Private key of the executor wallet (the API key's owner) — `submitEvidence` is `onlyWorker`. */
+    privateKey: string;
+    /** RPC per chain. No default: a missing entry refuses the task's chain rather than guessing a network. */
+    rpcUrls: Partial<Record<string, string | undefined>>;
 }
 /**
  * BlindMarket REST API client.
@@ -53,7 +71,10 @@ declare class ApiError extends Error {
 export declare class BlindMarket {
     private apiBase;
     private apiKey;
+    private executor?;
     constructor(config: BlindMarketConfig);
+    /** True when an executor signer was configured (see BlindMarketConfig.executor). */
+    get canSign(): boolean;
     /**
      * Tool definitions for AI agent frameworks. Access framework-specific formats
      * via property — no need to remember adapter function names.
@@ -91,16 +112,11 @@ export declare class BlindMarket {
     getTask(id: string): Promise<TaskDetail>;
     /**
      * Build an unsigned `createTask` transaction.
-     * You must sign and broadcast it with your wallet.
+     * You must sign and broadcast it with your wallet (the API key's owner is
+     * the poster), then index it via `POST /api/v1/a2a/tasks/index` for A2A.
+     * The deadline is set on-chain as now + `duration` seconds.
      */
-    createTask(params: {
-        agent: Address;
-        amount: string;
-        token: Address;
-        category: string;
-        locationZone: string;
-        deadline: number;
-    }): Promise<CreateTaskTx>;
+    createTask(params: CreateTaskRequest): Promise<CreateTaskTx>;
     /**
      * Build an unsigned `assignWorker` transaction.
      */
@@ -146,22 +162,48 @@ export declare class BlindMarket {
      */
     deployAgent(params: DeployAgentParams): Promise<DeployedAgent>;
     /**
-     * One-shot agent creation: generates a secp256k1 wallet, then registers the
-     * agent as an executor in the A2A marketplace with the generated wallet
-     * address and public key. Replaces the manual two-step flow of generating a
-     * wallet, then calling registerExecutor().
+     * One-shot executor registration in the A2A marketplace.
      *
-     * The private key is returned **once** in the response — store it securely.
+     * The registered executor is ALWAYS the wallet that owns the API key — the
+     * backend takes the address from auth, never from the request. Briefs are
+     * wrapped to the public key registered here, and `submitEvidence` is built
+     * for the owner address. So pass `privateKey` (or set
+     * `BlindMarketConfig.executor`) — the OWNER wallet's key: its uncompressed
+     * public key is registered, the key never leaves this process, and this
+     * throws 409 OWNER_MISMATCH — BEFORE registering anything — when the key is
+     * not the API key's owner (checked through `whoami()`).
+     *
+     * Without a key a random secp256k1 wallet is generated and its private key
+     * returned **once** (store it securely). That wallet can decrypt briefs, but
+     * it is not the registered executor address, so it cannot sign
+     * `submitEvidence` for tasks the owner accepts — use it only when delivery
+     * goes through another signer (e.g. the backend relay).
      *
      * @example
      * const { executor, wallet } = await bb.createAgent({
+     *   privateKey: process.env.EXECUTOR_PRIVATE_KEY!, // the API key owner's wallet (or set BlindMarketConfig.executor)
      *   displayName: 'DataBot',
      *   capabilities: [AgentCap.DATA_PROCESSING, AgentCap.WEB_RESEARCH],
      *   minReward: '1000000', // 1 USDC (the payment token's smallest unit; USDC has 6 decimals)
      * });
-     * console.log(`Agent ${wallet.address} registered as ${executor.address}`);
+     * console.log(`Registered executor ${executor.address}`);
      */
     createAgent(params: CreateAgentParams): Promise<CreateAgentResult>;
+    /**
+     * The wallet this API key authenticates as (`GET /api/v1/api-keys/whoami`).
+     * /a2a/register and /accept act for `address`. A legacy shared
+     * AGENT_API_KEY resolves to the non-wallet principal `"agent"`.
+     */
+    whoami(): Promise<{
+        address: string;
+        addresses?: string[];
+    }>;
+    /**
+     * Throws 409 OWNER_MISMATCH, without side effects, when `address` is not
+     * the API key's owner. Returns false only when the backend has no whoami
+     * route (404 / a non-JSON 404 page) and nothing could be checked.
+     */
+    private assertOwnerKey;
     /** List deployed agents, optionally filtered by owner address. */
     listAgents(ownerAddress?: string): Promise<DeployedAgentInfo[]>;
     /** Get a single deployed agent by ID. */
@@ -187,7 +229,12 @@ export declare class BlindMarket {
         tools: object[];
         minReward: string;
     }>): Promise<DeployedAgentInfo>;
-    /** Register as an A2A agent executor (worker-side). */
+    /**
+     * Register as an A2A agent executor (worker-side). The executor address is
+     * the API key's owner wallet (any `address` sent is ignored). `publicKey`
+     * must be uncompressed secp256k1 hex, 130 chars, leading `04`, no 0x —
+     * `new ethers.Wallet(pk).signingKey.publicKey.slice(2)`, NOT `wallet.publicKey`.
+     */
     registerExecutor(params: RegisterExecutorInput): Promise<{
         agent: ExecutorProfile;
     }>;
@@ -199,12 +246,17 @@ export declare class BlindMarket {
     getExecutorProfile(): Promise<{
         agent: ExecutorProfile;
     }>;
-    /** Browse A2A tasks available for execution. */
+    /**
+     * Browse A2A tasks available for execution. Each entry is `{ meta, state }`
+     * — the id and status live on `state` (`entry.state.taskId`), the chain and
+     * deadline on `meta`.
+     */
     browseA2ATasks(params?: {
         capabilities?: string[];
         minReputation?: number;
     }): Promise<{
-        tasks: A2ATaskState[];
+        tasks: A2ATaskEntry[];
+        total?: number;
     }>;
     /** Register intent to accept a task (bid). */
     bidOnTask(taskId: string): Promise<void>;
@@ -266,13 +318,40 @@ export declare class BlindMarket {
         };
         reconciled?: boolean;
     }>;
+    /**
+     * Rebuild the unsigned `submitEvidence` for a task stranded in 'submitted'
+     * — `/submit` flips the state when the tx is BUILT, so a crash before the
+     * broadcast leaves `finalize()` failing with NOT_SUBMITTED_ON_CHAIN and
+     * `submitResult()` refusing with INVALID_STATE. Sign + broadcast the
+     * returned tx on `chain`, then call `finalize()`. 409 ALREADY_SUBMITTED
+     * means the evidence did land — just call `finalize()`.
+     */
+    rebroadcast(taskId: string): Promise<{
+        taskId: string;
+        onChainTaskId?: string;
+        /** A string, not a union — see submitResult(). */
+        chain?: string;
+        evidenceHash?: Hex;
+        unsignedSubmitEvidence?: Record<string, unknown> | null;
+    }>;
+    /**
+     * Deliver a result end to end: `submitResult()` → sign + broadcast the
+     * 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()`.
+     */
+    deliverResult(taskId: string, resultData: Record<string, unknown>, signerOverride?: DeliverSigner): Promise<Awaited<ReturnType<BlindMarket['finalize']>> & {
+        submitTxHash?: string;
+    }>;
     /** Get tasks posted by the authenticated user. */
     getPostedTasks(): Promise<{
-        tasks: A2ATaskState[];
+        tasks: A2ATaskEntry[];
+        total?: number;
     }>;
     /** Get tasks executed by the authenticated user. */
     getExecutions(address?: string): Promise<{
-        tasks: A2ATaskState[];
+        executions: A2ATaskEntry[];
+        total: number;
     }>;
     /**
      * Trigger TEE / AI verification for a task.

package/dist/index.js

@@ -3,10 +3,14 @@ import { ethers } from 'ethers';
 class ApiError extends Error {
     status;
     body;
-    constructor(status, message, 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';
     }
 }
@@ -34,9 +38,15 @@ class ApiError extends Error {
 export class BlindMarket {
     apiBase;
     apiKey;
+    executor;
     constructor(config) {
         this.apiBase = config.apiBase ?? 'https://api.blindmarket.xyz';
         this.apiKey = config.apiKey;
+        this.executor = config.executor;
+    }
+    /** True when an executor signer was configured (see BlindMarketConfig.executor). */
+    get canSign() {
+        return !!this.executor;
     }
     // ── Tools ─────────────────────────────────────────────────────────────────
     /**
@@ -76,7 +86,7 @@ export class BlindMarket {
         });
         const json = await res.json();
         if (!json.success) {
-            throw new ApiError(res.status, json.error?.message ?? `HTTP ${res.status}`, json);
+            throw new ApiError(res.status, json.error?.message ?? `HTTP ${res.status}`, json, json.error?.code);
         }
         return json.data;
     }
@@ -101,7 +111,9 @@ export class BlindMarket {
     }
     /**
      * Build an unsigned `createTask` transaction.
-     * You must sign and broadcast it with your wallet.
+     * You must sign and broadcast it with your wallet (the API key's owner is
+     * the poster), then index it via `POST /api/v1/a2a/tasks/index` for A2A.
+     * The deadline is set on-chain as now + `duration` seconds.
      */
     async createTask(params) {
         return this.req('POST', '/api/v1/tasks', params);
@@ -151,28 +163,42 @@ export class BlindMarket {
         return this.req('POST', '/api/v1/agents/deploy', params);
     }
     /**
-     * One-shot agent creation: generates a secp256k1 wallet, then registers the
-     * agent as an executor in the A2A marketplace with the generated wallet
-     * address and public key. Replaces the manual two-step flow of generating a
-     * wallet, then calling registerExecutor().
+     * One-shot executor registration in the A2A marketplace.
+     *
+     * The registered executor is ALWAYS the wallet that owns the API key — the
+     * backend takes the address from auth, never from the request. Briefs are
+     * wrapped to the public key registered here, and `submitEvidence` is built
+     * for the owner address. So pass `privateKey` (or set
+     * `BlindMarketConfig.executor`) — the OWNER wallet's key: its uncompressed
+     * public key is registered, the key never leaves this process, and this
+     * throws 409 OWNER_MISMATCH — BEFORE registering anything — when the key is
+     * not the API key's owner (checked through `whoami()`).
      *
-     * The private key is returned **once** in the response — store it securely.
+     * Without a key a random secp256k1 wallet is generated and its private key
+     * returned **once** (store it securely). That wallet can decrypt briefs, but
+     * it is not the registered executor address, so it cannot sign
+     * `submitEvidence` for tasks the owner accepts — use it only when delivery
+     * goes through another signer (e.g. the backend relay).
      *
      * @example
      * const { executor, wallet } = await bb.createAgent({
+     *   privateKey: process.env.EXECUTOR_PRIVATE_KEY!, // the API key owner's wallet (or set BlindMarketConfig.executor)
      *   displayName: 'DataBot',
      *   capabilities: [AgentCap.DATA_PROCESSING, AgentCap.WEB_RESEARCH],
      *   minReward: '1000000', // 1 USDC (the payment token's smallest unit; USDC has 6 decimals)
      * });
-     * console.log(`Agent ${wallet.address} registered as ${executor.address}`);
+     * console.log(`Registered executor ${executor.address}`);
      */
     async createAgent(params) {
-        const wallet = ethers.Wallet.createRandom();
+        // With a key (params.privateKey, or BlindMarketConfig.executor) the agent
+        // IS the API key owner's wallet, the only one that can settle. Without one
+        // a random wallet is generated, as before — see the JSDoc for its limits.
+        const privateKey = params.privateKey ?? this.executor?.privateKey;
+        const wallet = privateKey ? new ethers.Wallet(privateKey) : ethers.Wallet.createRandom();
         // The uncompressed key (0x04…): /register requires it, and posters wrap
         // brief keys to it. `wallet.publicKey` is the compressed form in ethers v6.
         const publicKey = wallet.signingKey.publicKey;
         const executor = {
-            address: wallet.address,
             displayName: params.displayName,
             capabilities: params.capabilities,
             publicKey: publicKey.slice(2), // strip 0x prefix — backend expects raw hex
@@ -182,7 +208,17 @@ export class BlindMarket {
             preferredCapabilities: params.preferredCapabilities,
             supportedChains: params.supportedChains,
         };
+        // Only when the caller supplied the key: they are claiming to be the owner.
+        // Checked BEFORE /register, which upserts `publicKey` over the owner's
+        // record — a mismatch found afterwards has already redirected every new
+        // brief to a key whose wallet cannot sign submitEvidence.
+        const ownerChecked = privateKey ? await this.assertOwnerKey(wallet.address) : false;
         const result = await this.registerExecutor(executor);
+        // Backends without /api-keys/whoami could not be checked up front.
+        if (privateKey && !ownerChecked && result.agent.address.toLowerCase() !== wallet.address.toLowerCase()) {
+            throw new ApiError(409, `Registered executor is ${result.agent.address} (the API key's owner) but privateKey belongs to ${wallet.address}. ` +
+                'This backend has no /api-keys/whoami, so the mismatch could only be seen after registering: briefs are now wrapped to a key whose wallet cannot sign submitEvidence — re-run with the owner wallet\'s key, or mint an API key signed in as this wallet.', undefined, 'OWNER_MISMATCH');
+        }
         return {
             executor: result.agent,
             wallet: {
@@ -192,6 +228,35 @@ export class BlindMarket {
             },
         };
     }
+    /**
+     * The wallet this API key authenticates as (`GET /api/v1/api-keys/whoami`).
+     * /a2a/register and /accept act for `address`. A legacy shared
+     * AGENT_API_KEY resolves to the non-wallet principal `"agent"`.
+     */
+    async whoami() {
+        return this.req('GET', '/api/v1/api-keys/whoami');
+    }
+    /**
+     * Throws 409 OWNER_MISMATCH, without side effects, when `address` is not
+     * the API key's owner. Returns false only when the backend has no whoami
+     * route (404 / a non-JSON 404 page) and nothing could be checked.
+     */
+    async assertOwnerKey(address) {
+        let owner;
+        try {
+            owner = (await this.whoami()).address;
+        }
+        catch (err) {
+            if (err instanceof SyntaxError || (err instanceof ApiError && err.status === 404))
+                return false;
+            throw err;
+        }
+        if (typeof owner !== 'string' || owner.toLowerCase() !== address.toLowerCase()) {
+            throw new ApiError(409, `This API key belongs to ${owner} but privateKey belongs to ${address}. Nothing was registered. ` +
+                "The executor is always the API key's owner, and only that wallet can sign submitEvidence — use the owner wallet's key, or mint an API key signed in as this wallet.", undefined, 'OWNER_MISMATCH');
+        }
+        return true;
+    }
     /** List deployed agents, optionally filtered by owner address. */
     async listAgents(ownerAddress) {
         const qs = ownerAddress ? `?owner=${ownerAddress}` : '';
@@ -229,7 +294,12 @@ export class BlindMarket {
         return this.req('PATCH', `/api/v1/agents/${id}`, patch);
     }
     // ── A2A executor registration ───────────────────────────────────────────
-    /** Register as an A2A agent executor (worker-side). */
+    /**
+     * Register as an A2A agent executor (worker-side). The executor address is
+     * the API key's owner wallet (any `address` sent is ignored). `publicKey`
+     * must be uncompressed secp256k1 hex, 130 chars, leading `04`, no 0x —
+     * `new ethers.Wallet(pk).signingKey.publicKey.slice(2)`, NOT `wallet.publicKey`.
+     */
     async registerExecutor(params) {
         return this.req('POST', '/api/v1/a2a/register', params);
     }
@@ -243,10 +313,14 @@ export class BlindMarket {
         return this.req('GET', '/api/v1/a2a/profile');
     }
     // ── A2A task lifecycle ───────────────────────────────────────────────────
-    /** Browse A2A tasks available for execution. */
+    /**
+     * Browse A2A tasks available for execution. Each entry is `{ meta, state }`
+     * — the id and status live on `state` (`entry.state.taskId`), the chain and
+     * deadline on `meta`.
+     */
     async browseA2ATasks(params) {
         const qs = new URLSearchParams();
-        if (params?.capabilities)
+        if (params?.capabilities?.length)
             qs.set('capabilities', params.capabilities.join(','));
         if (params?.minReputation != null)
             qs.set('minReputation', String(params.minReputation));
@@ -287,6 +361,76 @@ export class BlindMarket {
     async finalize(taskId) {
         return this.req('POST', `/api/v1/a2a/tasks/${taskId}/finalize`);
     }
+    /**
+     * Rebuild the unsigned `submitEvidence` for a task stranded in 'submitted'
+     * — `/submit` flips the state when the tx is BUILT, so a crash before the
+     * broadcast leaves `finalize()` failing with NOT_SUBMITTED_ON_CHAIN and
+     * `submitResult()` refusing with INVALID_STATE. Sign + broadcast the
+     * returned tx on `chain`, then call `finalize()`. 409 ALREADY_SUBMITTED
+     * means the evidence did land — just call `finalize()`.
+     */
+    async rebroadcast(taskId) {
+        return this.req('POST', `/api/v1/a2a/tasks/${taskId}/rebroadcast`);
+    }
+    /**
+     * Deliver a result end to end: `submitResult()` → sign + broadcast the
+     * 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()`.
+     */
+    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) => {
+            if (!built.unsignedSubmitEvidence)
+                return undefined;
+            // Absent `chain` = a backend older than the field, where every task is on 0G.
+            // Any other name must have its own RPC entry: signing an unknown chain's
+            // tx on the 0G RPC would target the wrong escrow.
+            const chain = built.chain ?? '0g';
+            const rpc = signer.rpcUrls[chain];
+            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 wallet = new ethers.Wallet(signer.privateKey, new ethers.JsonRpcProvider(rpc));
+            const tx = await wallet.sendTransaction(built.unsignedSubmitEvidence);
+            await tx.wait();
+            return tx.hash;
+        };
+        const healStranded = async () => {
+            try {
+                return await send(await this.rebroadcast(taskId));
+            }
+            catch (err) {
+                // Evidence is already on-chain — nothing to broadcast, go finalize.
+                if (err instanceof ApiError && err.code === 'ALREADY_SUBMITTED')
+                    return undefined;
+                throw err;
+            }
+        };
+        let submitTxHash;
+        try {
+            submitTxHash = await send(await this.submitResult(taskId, resultData));
+        }
+        catch (err) {
+            if (!(err instanceof ApiError && err.code === 'INVALID_STATE'))
+                throw err;
+            submitTxHash = await healStranded();
+        }
+        try {
+            return { ...(await this.finalize(taskId)), submitTxHash };
+        }
+        catch (err) {
+            if (!(err instanceof ApiError && err.code === 'NOT_SUBMITTED_ON_CHAIN'))
+                throw err;
+            submitTxHash = (await healStranded()) ?? submitTxHash;
+            return { ...(await this.finalize(taskId)), submitTxHash };
+        }
+    }
     /** Get tasks posted by the authenticated user. */
     async getPostedTasks() {
         return this.req('GET', '/api/v1/a2a/tasks/posted');

package/dist/tools/helpers.js

@@ -23,7 +23,7 @@ export function kit(name, description, all, names) {
     return { name, description, tools: all.filter((t) => namesSet.has(t.definition.function.name)) };
 }
 export function createBlindMarketTools(bb) {
-    return [
+    const all = [
         tool(bb, 'list_open_tasks', 'List open tasks available for assignment', {}, async () => {
             return bb.listTasks();
         }),
@@ -36,7 +36,7 @@ export function createBlindMarketTools(bb) {
         }, async (a) => {
             return bb.searchAgents(a);
         }),
-        tool(bb, 'create_agent', 'One-shot agent creation: generates wallet + registers as A2A executor', {
+        tool(bb, 'create_agent', "Register the API key's owner wallet as an A2A executor, using the executor key configured on the client (BlindMarketConfig.executor). With no key configured, a random wallet is generated and its private key returned once — that wallet can decrypt briefs but cannot sign submitEvidence for the owner.", {
             displayName: str('Display name for the agent'),
             capabilities: arr('List of capabilities', str('Capability', CAP_ENUM)),
             minReward: str("Minimum reward per task, as an integer in the payment token's smallest unit (USDC: 6 decimals) (optional)"),
@@ -44,21 +44,27 @@ export function createBlindMarketTools(bb) {
             agentCardUrl: str('Agent card URL for marketplace display (optional)'),
             mcpEndpointUrl: str('MCP endpoint URL (optional)'),
         }, async (a) => {
-            return bb.createAgent(a);
+            // A configured key comes from the client config, never from tool
+            // arguments, and is never echoed back into the model's context. A
+            // generated one has to be returned: this is the only place it exists.
+            const { executor, wallet } = await bb.createAgent(a);
+            if (!bb.canSign)
+                return { executor, wallet };
+            return { executor, wallet: { address: wallet.address, publicKey: wallet.publicKey } };
         }, ['displayName', 'capabilities']),
         tool(bb, 'register_as_executor', 'Register as an A2A executor to receive task offers', {
-            address: str('Your wallet address (0x...)'),
+            address: str("Ignored — the executor is always the API key's owner wallet (optional)"),
             displayName: str('Human-readable display name'),
             capabilities: arr('List of capabilities', str('Capability', CAP_ENUM)),
-            publicKey: str('Your uncompressed secp256k1 public key'),
+            publicKey: str('Your uncompressed secp256k1 public key: 130 hex chars, leading 04, no 0x prefix'),
             minReward: str("Minimum reward, as an integer in the payment token's smallest unit (USDC: 6 decimals) (optional)"),
             preferredCapabilities: arr('Preferred subset of capabilities (optional)', str('Capability', CAP_ENUM)),
             // No enum: the backend validates the list, and a newer backend may accept
             // a chain this SDK version doesn't know.
-            supportedChains: arr("Settlement chains you can sign submitEvidence on, e.g. ['0g', 'base']. You are only offered tasks escrowed on these (optional; omitted means 0g and base)", str('Chain slug')),
+            supportedChains: arr("Settlement chains you can sign submitEvidence on, e.g. ['0g', 'base']. Stored on your executor record as a declaration; the backend does not filter offers by it, so check a task's chain before accepting (optional)", str('Chain slug')),
         }, async (a) => {
             return bb.registerExecutor(a);
-        }, ['address', 'displayName', 'capabilities', 'publicKey']),
+        }, ['displayName', 'capabilities', 'publicKey']),
         tool(bb, 'browse_a2a_tasks', 'Browse tasks available for A2A execution', {
             capabilities: arr('Required capabilities filter'),
             minReputation: num('Minimum reputation filter'),
@@ -71,16 +77,19 @@ export function createBlindMarketTools(bb) {
             await bb.bidOnTask(a.taskId);
             return { success: true };
         }, ['taskId']),
-        tool(bb, 'accept_task', 'Accept a task and get the wrapped AES key', {
+        tool(bb, 'accept_task', 'Claim an open task (assigns you on-chain) and get the rootHash + wrapped AES key. On NEEDS_WRAP, call bid_on_task and retry once the poster has wrapped the key to you.', {
             taskId: str('Task ID'),
         }, async (a) => {
             return bb.acceptTask(a.taskId);
         }, ['taskId']),
-        tool(bb, 'submit_result', 'Submit execution result for an accepted task', {
-            taskId: str('Task ID'),
+        // Completes the WHOLE delivery: /submit only builds an unsigned
+        // submitEvidence and flips state to 'submitted', so a tool that stopped
+        // there stranded the task. Needs BlindMarketConfig.executor to sign.
+        tool(bb, 'submit_result', "Deliver the result for an accepted task: submits it, signs + broadcasts submitEvidence from the executor wallet, then finalizes so verification can release the escrow. Safe to re-call — a task stranded in 'submitted' is healed via rebroadcast.", {
+            taskId: str('Task ID (0x task hash)'),
             output: str('Result output text'),
         }, async (a) => {
-            return bb.submitResult(a.taskId, { output: a.output });
+            return bb.deliverResult(a.taskId, { output: a.output });
         }, ['taskId', 'output']),
         tool(bb, 'deploy_agent', 'Deploy a new AI agent on BlindMarket', {
             name: str('Agent name'),
@@ -162,7 +171,20 @@ export function createBlindMarketTools(bb) {
             return bb.getUnreadCount();
         }),
     ];
+    // submit_result signs a transaction; without a configured signer it could
+    // only strand tasks, so it is not offered at all.
+    if (bb.canSign)
+        return all;
+    // Said once per process: up to 0.5.x the tool was always present, and a
+    // model that is simply never offered it fails quietly.
+    if (!warnedNoSubmitResult) {
+        warnedNoSubmitResult = true;
+        console.warn('[@blindmarket/sdk] the submit_result tool is not offered: the client has no executor signer. ' +
+            'Pass `executor: { privateKey, rpcUrls }` to new BlindMarket() to enable it (see CHANGELOG 0.6.0).');
+    }
+    return all.filter((t) => t.definition.function.name !== 'submit_result');
 }
+let warnedNoSubmitResult = false;
 export function createTaskTools(bb) {
     return kit('tasks', 'Browse and manage tasks', createBlindMarketTools(bb), [
         'list_open_tasks', 'get_task', 'bid_on_task', 'accept_task', 'submit_result',