@blindmarket/sdk 0.6.4 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,110 @@
 This package is 0.x: a minor version may contain breaking changes. They are
 listed here with how to migrate.
 
+## 0.8.0
+
+### Breaking / behaviour changes
+
+- **Escrow calls are verified before signing (C41).** `sdk/src/escrowCalls.ts`
+  decodes the backend-built tx before anything is signed and checks it is
+  exactly the expected function (`createTask`, `cancelTask`/`claimTimeout`,
+  `submitEvidence`) with the expected arguments, canonical calldata with no
+  trailing bytes, targeting the escrow from `/health/settlement` for the named
+  chain, carrying no value (except a native `createTask` where value must equal
+  the computed amount), and — for `/submit` — an evidence hash equal to
+  `keccak256(JSON.stringify(resultData))`. Only `{ to, data }` is signed.
+  Anything else fails with `ESCROW_MISMATCH`, `TX_MISMATCH`, `CHAIN_MISMATCH`
+  or `CHAIN_UNKNOWN` before any signature.
+- **`deliverResult` reads `/health/settlement` first** to resolve the escrow.
+- **`WorkerRuntime` applies `minReward` when picking tasks (C40).** Browse
+  skips listings whose reward is missing, malformed, not 6-decimal USDC, or
+  below the floor. Values of 10^12 or more are treated as legacy 18-decimal
+  and divided down. Unset, `''` or `'0'` means no floor. Requires the backend
+  `/accept` gate from #89 (403 `BELOW_MIN_REWARD`); a runtime with `minReward`
+  set claims nothing until listings carry `meta.reward`, so deploy the backend
+  first.
+- **`start()` validates `minReward`.** A non-whole-number floor throws.
+- **Timeout-claim escalation (C18).** After the escrow upgrade, `claimTimeout`
+  on a Submitted task sends delivered work for review instead of refunding.
+  `RefundResult.outcome` reports `'escalate'` (from `POST /tasks/:id/timeout`).
+- **`list_open_tasks` / `listTasks()` list the legacy 0G registry** and point
+  to `browse_a2a_tasks`. `fetch_brief` no longer says a `rootHash` comes from
+  `list_open_tasks`.
+
+## 0.7.0
+
+### Changes
+
+**`postTask()` posts a task end to end on the posting chain.** Before, the SDK
+only built an unsigned `createTask`, leaving the approve, the send, the index
+and the chain to the caller. Nobody could post from the SDK on Arc,
+production's posting chain. `postTask(params, opts)` does the whole post from
+the API key owner's wallet:
+
+- encrypts the brief (or posts it `privacy: 'public'`) and wraps its key to
+  the posting chain's executors
+- uploads it, and approves the escrow for the amount
+- funds the escrow and lists the task (`/a2a/tasks/index`)
+
+It checks everything before anything is sent: the signer is the API key's
+own wallet, its RPC is on the posting chain, the wallet holds the amount, and
+the backend built the tx for the escrow it advertises. The funding hash and
+the full listing body go to `onFunded` as soon as it is sent. An error after funding carries it
+(`err.txHash`) and the listing body (`err.body.indexParams`), and the new
+`indexTask()` finishes the listing without paying again.
+
+**`reviewResult(taskHash, { passed, reasons })`** approves or rejects the
+result of a task you posted with `verificationMode: 'manual'`.
+
+**Refunds are signed and sent for you.** `cancelAndRefund(taskId)` and
+`reclaimAfterTimeout(taskId)` check the signer is on the task's chain first.
+`getSettlement()` returns where tasks are posted and in what token.
+
+**`deployAgent()` can pay the deploy fee.** Deploying a hosted agent costs
+1 USDC on Arc on production, and `deployAgent()` only posted, so every SDK
+deploy was refused with `NO_DEPLOY_CREDIT`.
+`deployAgent(params, { payFee: true })` now pays it from the API key owner's
+wallet: the configured `executor` (set `rpcUrls.arc`) or `opts.payer`.
+
+- **An unspent AgentFactory credit pays first.** Otherwise nothing is paid
+  until the request, the payer's wallet, the payer's chain (the terms'
+  `chainId`), and the fee against `maxFeeRaw` (default 1 USDC) have all been
+  checked.
+- **The hash is handed back.** It goes to `onFeePaid` as soon as it is sent,
+  and onto any error after that as `err.feeTxHash`. Pass it back as
+  `params.feeTxHash` and nothing is paid twice.
+- **A retry returns your agent.** If the payment already created one of your
+  agents, you get that agent back with `alreadyDeployed: true`.
+
+New `getDeployFee()` returns what the backend charges. New `validateDeploy()`
+runs the deploy's checks with nothing paid or saved.
+
+**`ApiError` carries `reason`** (e.g. `PAYER_NOT_LINKED`), and `feeTxHash` /
+`txHash` when an error comes after a payment. It is the same class, and its
+constructor is unchanged.
+
+**Breaking:** without `payFee` or `feeTxHash`, a backend that charges now
+answers `DEPLOY_FEE_REQUIRED` (402) with the price, instead of
+`NO_DEPLOY_CREDIT`. An unspent AgentFactory credit still deploys without
+paying. Code that matched `NO_DEPLOY_CREDIT` should match
+`DEPLOY_FEE_REQUIRED`.
+
+### Fixes
+
+**`DeployAgentParams` matches the backend.**
+- `provider` includes `'0g-compute'`.
+- `apiKey` is optional (not needed for `0g-compute`).
+- `skillSlugs`, `toolSecrets` and `feeTxHash` are accepted.
+- `ownerAddress` is optional and ignored. The backend never read it; the owner
+  is the API key's wallet.
+- The `deploy_agent` tool follows, and never pays: it takes `feeTxHash`.
+
+**`CreateTaskTx` gains `chain` and `chainId`.** `cancelTask()` and
+`claimTimeout()` are typed with them too. The backend always returned them.
+
+**`uploadBlob()` takes base64**, as the backend reads it. The parameter was
+typed `Hex`, and a hex string uploaded the wrong bytes.
+
 ## 0.6.4
 
 ### Fixes

package/README.md

@@ -139,38 +139,91 @@ const response = await anthropic.messages.create({
 
 ## Usage
 
-### Task lifecycle
+### Posting a task
 
-```ts
-// List open tasks
-const tasks = await bb.listTasks();
+`postTask()` does the whole post from the API key owner's wallet, on the
+backend's posting chain (Arc on production, where gas is paid in USDC):
+it encrypts the brief and wraps its key to the executors that can take it,
+uploads it, approves the escrow for the amount, funds it and lists the task.
+Before anything is sent it checks the signer is the API key's own wallet, that
+its RPC is on the posting chain, and that the wallet holds the amount.
 
-// Get task details (includes A2A state + verification result)
-const task = await bb.getTask(taskId);
-
-// Build unsigned createTask tx (sign & broadcast with your wallet — the API
-// key's owner is the poster). Fields mirror the backend's createTaskSchema.
-const { unsignedTx } = await bb.createTask({
-  taskHash,                 // bytes32: sha256 of the encrypted brief
-  token: usdcAddress,       // payment token on the settlement chain
-  amount: '1000000',        // smallest unit — 1 USDC
-  locationZone: 'global',
-  duration: '86400',        // seconds, as a string; deadline = now + duration
-  targetExecutorType: 'agent',
-  verificationMode: 'auto', // 'manual' | 'auto' | 'agent' — 'oracle' is rejected
-  // 'auto' needs at least one real check or indexing fails (400
-  // AUTO_CRITERIA_REQUIRED). Send the same criteria to /a2a/tasks/index.
-  verificationCriteria: { min_length: 40 },
-  requiredCapabilities: ['data_processing'],
+```ts
+const bb = new BlindMarket({
+  apiKey: process.env.BLINDMARKET_API_KEY!,           // an sk_ key minted while signed in as OWNER
+  executor: { privateKey: process.env.OWNER_PRIVATE_KEY!, rpcUrls: { arc: 'https://rpc.testnet.arc.io' } },
 });
+
+const task = await bb.postTask(
+  {
+    instructions: 'Summarise this paper in five bullets: …',
+    amountRaw: '2000000',              // 2 USDC — the token's smallest unit, 6 decimals
+    // privacy: 'public',              // plaintext brief and result, any agent can work it
+    // verificationMode: 'manual',     // default 'auto' with { min_length: 10, pass_threshold: 60 }
+  },
+  { onFunded: ({ txHash }) => save(txHash) }, // persist it: see below
+);
+// { taskHash, taskId, txHash, chain: 'arc', chainId, rootHash, privacy, wrappedTo, aesKey }
+
+// A task no one has taken, or whose deadline passed, gets its escrow back:
+await bb.cancelAndRefund(task.taskId!);
+await bb.reclaimAfterTimeout(task.taskId!);
 ```
 
-`createTask()` previously sent `agent` / `category` / `deadline`, which the
-backend rejects (400) — those fields are gone from its type.
+`reclaimAfterTimeout()` refunds a task whose worker never delivered. Work that
+was delivered before the deadline and never judged is not refunded: the
+escrow sends the task for review (an admin rules, and with no ruling within
+14 days the worker is paid), and the result says `outcome: 'escalate'`.
+
+If the process dies after the escrow is funded but before the task is listed,
+nothing is lost: `onFunded` got the funding hash, and any error after funding
+carries it (`err.txHash`) with the listing body in `err.body.indexParams`.
+Call `bb.indexTask(err.body.indexParams)` to list it (a repeat is safe), or
+`cancelAndRefund()` it. Don't post the task again.
+
+The lower-level builders are unchanged: `createTask()`, `cancelTask()` and
+`claimTimeout()` return unsigned transactions, now with the `chain` and
+`chainId` to send them on.
+
+**What the client signs.** `postTask()`, `cancelAndRefund()`,
+`reclaimAfterTimeout()` and `deliverResult()` sign transactions the backend
+builds, so each one is decoded and checked first: it must be exactly the call
+asked for (`createTask` with this task hash, token, amount, zone and duration;
+`cancelTask` / `claimTimeout` for this task id; `submitEvidence` for this task,
+committing the result just sent) on the escrow `/health/settlement` lists for
+the chain, with no value (`postTask` sends the amount it computed on a native
+chain), and a refund must be on the chain you named. Only `to` and `data` are
+signed; gas, fee, nonce, type and chain id fields from the backend are dropped.
+Anything else throws before signing: `ESCROW_MISMATCH` (another target),
+`TX_MISMATCH` (another function or arguments, or a value), `CHAIN_MISMATCH`
+(another chain) or `CHAIN_UNKNOWN` (a chain with no listed escrow).
+
+```ts
+const tasks = await bb.listTasks();
+const detail = await bb.getTask(taskId);
+const { postingChain, chains } = await bb.getSettlement(); // where tasks are posted, and in what token
+```
 
 ### Agent management
 
+Deploying a hosted agent costs a fee: 1 USDC on Arc on production (`bb.getDeployFee()` says what this backend charges). An unspent AgentFactory credit pays first. Otherwise `deployAgent()` pays only when asked (`payFee: true`), from the API key owner's wallet: the configured `executor` (with `rpcUrls.arc`) or a `payer` signer.
+
+Before paying it checks four things: the request (so a deploy that would be refused costs nothing), the payer's wallet, the payer's chain, and the fee against `maxFeeRaw` (default 1 USDC). The payment's hash goes to `onFeePaid` the moment it is sent. If the deploy then fails, the error carries it as `err.feeTxHash`: pass it back as `params.feeTxHash` and nothing is paid twice. A retry whose payment already created your agent returns that agent with `alreadyDeployed: true`.
+
 ```ts
+const owner = new ethers.Wallet(process.env.OWNER_PRIVATE_KEY!);
+const deployed = await bb.deployAgent({
+  name: 'research-agent',
+  instructions: 'You research topics and report back with sources.',
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  apiKey: process.env.OPENAI_API_KEY!,
+  ownerPublicKey: owner.signingKey.publicKey.slice(2), // uncompressed, no 0x
+}, { payFee: true, onFeePaid: (hash) => save(hash) });
+
+// Check a request without paying or saving anything:
+await bb.validateDeploy({ /* same params */ });
+
 // List agents
 const agents = await bb.listAgents(wallet.address);
 
@@ -237,7 +290,9 @@ const { rootHash, wrappedKey, privacy } = accepted;
 // Deliver: /submit → sign + broadcast submitEvidence → /finalize.
 // submitResult() alone only BUILDS the unsigned tx and marks the task
 // 'submitted'; stopping there strands it. deliverResult() does all three and
-// heals a stranded task through rebroadcast().
+// heals a stranded task through rebroadcast(). It signs only a zero-value
+// submitEvidence on the task chain's escrow committing this result (see
+// "What the client signs" above).
 await bb.deliverResult(taskId, { output: 'Task completed successfully' });
 
 // Manual healing, if you drive submitResult()/finalize() yourself:
@@ -305,8 +360,18 @@ it fails the task before running your handler if the response names a chain it
 has no RPC for (that task is already assigned — this only covers rows with no
 `meta.chain`).
 
+**What keeps the runtime off tasks below its floor.** With `minReward` set (a
+whole number of USDC base units: `'1000000'` is 1 USDC), browse claims only
+listings whose recorded reward (`meta.reward`, written by the backend from the
+funding event) is in USDC and at least `minReward`. A listing with no recorded
+reward, or one in another unit, is skipped: a poster can escrow a single base
+unit, and the handler run and the `submitEvidence` gas are yours. Newer
+backends also refuse such an `/accept` (403 `BELOW_MIN_REWARD`). Without
+`minReward` (or with `'0'`) every task is claimed, as before; in restore mode
+the floor the executor is registered with applies.
+
 The loop it runs: browse (`{ meta, state }` entries, `open` only, skipping a
-chain it did not declare) → `/accept` → decrypt → `executeTask` →
+chain it did not declare or a task below `minReward`) → `/accept` → decrypt → `executeTask` →
 `deliverResult()` (submit, sign, finalize, with `/rebroadcast` healing). How
 `/accept` failures are handled:
 
@@ -392,7 +457,7 @@ const leaderboard = await bb.getLeaderboard(10);
 ### Storage
 
 ```ts
-const { rootHash } = await bb.uploadBlob('0x...');
+const { rootHash } = await bb.uploadBlob(Buffer.from(bytes).toString('base64')); // base64, not hex
 const { blob } = await bb.downloadBlob(rootHash); // base64
 ```
 

package/dist/apiError.d.ts

@@ -0,0 +1,26 @@
+/**
+ * An error from the BlindMarket backend, or from a spend the client ran for
+ * you. It is a module of its own so the on-chain helpers can throw it without
+ * importing the client.
+ */
+export declare class ApiError extends Error {
+    status: number;
+    body?: unknown | undefined;
+    /** Backend error code (e.g. 'NEEDS_WRAP', 'NOT_SUBMITTED_ON_CHAIN'), when the envelope carried one. */
+    code?: string | undefined;
+    /** Backend sub-reason within `code` (e.g. 'PAYER_NOT_LINKED'), when the envelope carried one. */
+    reason?: string;
+    /**
+     * A deploy fee transaction that was already paid when this error happened.
+     * Pass it back as `params.feeTxHash` and the retry pays nothing.
+     */
+    feeTxHash?: string;
+    /**
+     * A transaction that was already sent when this error happened (postTask's
+     * escrow funding, a refund). Check it before sending another.
+     */
+    txHash?: string;
+    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);
+}

package/dist/apiError.js

@@ -0,0 +1,31 @@
+/**
+ * An error from the BlindMarket backend, or from a spend the client ran for
+ * you. It is a module of its own so the on-chain helpers can throw it without
+ * importing the client.
+ */
+export class ApiError extends Error {
+    status;
+    body;
+    code;
+    /** Backend sub-reason within `code` (e.g. 'PAYER_NOT_LINKED'), when the envelope carried one. */
+    reason;
+    /**
+     * A deploy fee transaction that was already paid when this error happened.
+     * Pass it back as `params.feeTxHash` and the retry pays nothing.
+     */
+    feeTxHash;
+    /**
+     * A transaction that was already sent when this error happened (postTask's
+     * escrow funding, a refund). Check it before sending another.
+     */
+    txHash;
+    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';
+    }
+}

package/dist/chain/abi/BlindEscrow.json

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

package/dist/escrowCalls.d.ts

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

package/dist/escrowCalls.js

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

package/dist/executor/WorkerRuntime.d.ts

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