@blindmarket/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,136 @@
 This package is 0.x: a minor version may contain breaking changes. They are
 listed here with how to migrate.
 
+## 0.9.0
+
+### New
+
+- **`postTasks(rows, opts)` posts many tasks at once** (docs/BULK-POSTING.md).
+  Every row is checked and its brief sealed before anything is uploaded or
+  sent. A row the escrow or the backend would refuse throws 400
+  `INVALID_ROWS`, listing each one in `err.body.errors` (`{ index, code,
+  message }`), with nothing sent. Rows that are the same public brief count
+  as refused (`DUPLICATE_BRIEF`). The wallet must hold the total, and the
+  escrow is approved for it once, just before the first funding transaction,
+  instead of once per task.
+  - **Escrow with `createTasks`:** `GET /health/settlement` reports
+    `batchCreate.supported` for the chain. Up to `chunkSize` rows (default
+    20, at most the escrow's `maxBatch`) then share one transaction and one
+    listing call. The transaction's gas limit is estimated locally with 20%
+    headroom.
+  - **Otherwise:** each row is its own `createTask`, as `postTask()` sends it.
+  - **Safety:** every transaction is checked before signing, as `postTask()`
+    checks one. A `createTasks` must hold exactly these tasks, in this order,
+    for this token, escrow and chain.
+  - **Where the run stops:** a row the backend refuses before funding fails
+    alone and the run goes on. A funding that reverts or cannot be confirmed,
+    a listing that fails, or a backend that builds the wrong transaction or
+    stays unreachable stops the run there (`result.stopped`).
+  - **No double funding:** a funded row that is not listed comes back
+    `'unlisted'` with its `indexParams`, and nothing is funded twice.
+  - **Brief storage:** briefs are stored two per `upload-batch` request, one
+    request after another (0G stores a brief in 20–40 s, and production's
+    edge gives up at ~100 s).
+    - A pair that fails transiently is re-sent one brief per request, in
+      order, each with the backoff; a stored brief returns at once. Transient
+      means: a dropped connection, this client's own timeout, 429, 502, 503,
+      504, or Cloudflare's non-JSON 524.
+    - A refusal (400) or an answer that doesn't add up fails at once.
+    - A chunk is funded only after every one of its briefs is stored.
+  - **Options:** `onFunded` fires per row the moment its transaction is
+    broadcast, with `batch: true` when the row shares a transaction.
+    `onProgress` reports each row. `signal` stops before the next row.
+    `retry` sets the backoff for 429s, 5xx and network errors. A funding
+    transaction is never re-sent.
+- `indexTasks({ txHash, tasks })` lists every task one transaction funded
+  (`POST /a2a/tasks/index-batch`). Rows `postTasks()` left unlisted with
+  `batch: true` must be finished with it: the single index route refuses a
+  receipt that funded several tasks.
+- `createTasks({ token, tasks })` builds a `createTasks` transaction
+  (`POST /tasks/batch`). `uploadBlobs(data[])` uploads several blobs at once
+  (`POST /storage/upload-batch`).
+- `SettlementChainInfo.batchCreate?: { supported, maxBatch }`.
+- `onFunded` (in `postTask()` and `postTasks()`) now also gets the funding
+  transaction's `nonce`. Save it with the hash: if the transaction never shows
+  a receipt and the sender's confirmed nonce has moved past it, the
+  transaction can never land, and nothing was escrowed. With a local key,
+  the signed `raw` transaction comes too. While its nonce is unused it can be
+  re-broadcast as is, and it can only land once.
+- `PostTaskParams.routingSummary`: the public one-liner the task board shows
+  for a task, which is all a private task shows. It's sent with the listing
+  and checked for length (500) before anything is funded
+  (`INVALID_ROUTING_SUMMARY`).
+
+### Security
+
+- **Only a known escrow is funded.** `postTask()` and `postTasks()` approve
+  and fund only the escrow and settlement token pinned for the posting chain
+  (`SETTLEMENT_PINS`: Arc mainnet 5042 and Arc Testnet 5042002). Before, both
+  came from `/health/settlement`. Any other answer throws 409
+  `ESCROW_NOT_PINNED` with nothing approved or sent. For a custom or local
+  deployment, list it in `BlindMarketConfig.trustedEscrows`
+  (`{ chainId, escrow, token }`). `network/presets.ts` is unchanged.
+- **A local key signs, records, then broadcasts.** An ethers `Wallet` (a
+  signer holding its own key) is signed first, and `onSent` / `onFunded` get
+  the hash and nonce before the raw transaction goes out. A broadcast whose
+  answer is lost is `UnconfirmedTransactionError` (it may still land), never
+  "nothing sent". Browser wallets still sign and send in one step.
+- **The category is bound.** The calldata check requires `'general'`, the
+  category the backend builds, like every other argument of `createTask` and
+  `createTasks`.
+
+### Internal
+
+- `postTask()` and `postTasks()` share one set of row checks and brief
+  sealing (`src/posting.ts`). `postTask()` behaves exactly as before.
+
+## 0.8.1
+
+### Behaviour changes
+
+- **`WorkerRuntime` accepts a task only where its RPC is on the backend's
+  network.** Before each `/accept` it checks that its RPC for the task's chain
+  answers the chain id `GET /health/settlement` lists for that chain. A chain
+  keeps its key when the backend moves it to another network (Arc Testnet
+  5042002, Arc mainnet 5042). A runtime still on the old network used to accept,
+  which assigns the task on-chain for good, and then fail `submitEvidence` with
+  `WRONG_CHAIN`. On a mismatch it now skips the task (`task_failed`, "not
+  accepted: …") and looks at it again after a back-off that grows from 30 s to
+  an hour. Only an answer that matches is remembered, so one wrong answer from
+  the RPC does not hold a chain back. A chain it cannot check, because the RPC
+  or the backend cannot be read or the chain is not listed, holds nothing
+  back: `deliverResult()` checks again before it signs.
+
+## 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

package/README.md

@@ -151,7 +151,9 @@ its RPC is on the posting chain, and that the wallet holds the amount.
 ```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' } },
+  // An RPC on the network /health/settlement names for arc:
+  // https://arc-rpc.publicnode.com (Arc mainnet, 5042) or https://arc-testnet-rpc.publicnode.com (Arc Testnet, 5042002).
+  executor: { privateKey: process.env.OWNER_PRIVATE_KEY!, rpcUrls: { arc: process.env.ARC_RPC_URL! } },
 });
 
 const task = await bb.postTask(
@@ -170,6 +172,11 @@ await bb.cancelAndRefund(task.taskId!);
 await bb.reclaimAfterTimeout(task.taskId!);
 ```
 
+`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`.
@@ -180,12 +187,77 @@ The lower-level builders are unchanged: `createTask()`, `cancelTask()` and
 `claimTimeout()` return unsigned transactions, now with the `chain` and
 `chainId` to send them on.
 
+**Which escrow it funds.** `postTask()` and `postTasks()` fund only the
+escrow and token pinned for the posting chain (`SETTLEMENT_PINS`: Arc mainnet
+and Arc Testnet), whatever the backend names. Anything else throws
+`ESCROW_NOT_PINNED` before anything is approved. For a custom or local
+deployment:
+
+```ts
+const bb = new BlindMarket({
+  apiKey,
+  trustedEscrows: [{ chainId: 5042002, escrow: '0x…yourEscrow', token: '0x3600000000000000000000000000000000000000' }],
+});
+```
+
+**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
 ```
 
+### Posting many tasks
+
+`postTasks()` posts a list, for example 500 rows from a spreadsheet. Before
+anything is uploaded or sent, it:
+
+- checks every row;
+- seals every brief;
+- checks that the wallet holds the total.
+
+A row that would be refused throws `INVALID_ROWS`, naming each one in
+`err.body.errors`. The escrow is approved once, for the total.
+
+- **On an escrow with `createTasks`:** `getSettlement()` shows
+  `batchCreate.supported`. Up to `chunkSize` tasks (default 20) then share
+  one transaction.
+- **Otherwise:** each task is its own transaction.
+
+Every transaction is checked before signing, as `postTask()` checks one.
+
+```ts
+const res = await bb.postTasks(rows, {           // rows: PostTaskParams[]
+  onFunded: ({ taskHash, indexParams, batch }) => save(taskHash, { indexParams, batch }),
+  onProgress: ({ done, total }) => console.log(`${done}/${total}`),
+});
+console.log(res.posted, res.unlisted, res.failed, res.skipped, res.stopped);
+```
+
+**Failures:**
+- **Before funding:** a row the backend refuses fails alone, and the run goes
+  on.
+- **At or after funding:** a funding that reverts or can't be confirmed, or a
+  listing that fails, stops the run there. That way no more escrow is funded
+  behind a problem.
+
+**Recovery:** nothing is funded twice. A funded row that isn't listed comes
+back `'unlisted'` with its `indexParams`. Finish it with
+`indexTask(indexParams)`, or with `indexTasks()` when its `batch` is true (the
+tasks share one transaction). Cancel it with `cancelAndRefund()` for a refund.
+
 ### 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.
@@ -231,8 +303,9 @@ await bb.updateAgent(agentId, {
 const bb = new BlindMarket({
   apiKey,
   // Optional: the API key owner's wallet + an RPC per chain your tasks settle
-  // on. Enables deliverResult() and the submit_result tool.
-  executor: { privateKey, rpcUrls: { arc: 'https://rpc.testnet.arc.io', base: 'https://sepolia.base.org' } },
+  // on, each on the network /health/settlement names for that chain. Enables
+  // deliverResult() and the submit_result tool.
+  executor: { privateKey, rpcUrls: { arc: process.env.ARC_RPC_URL!, base: process.env.BASE_RPC_URL! } },
 });
 
 // Register as an executor. The executor ADDRESS is always the API key's owner
@@ -272,7 +345,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:
@@ -301,8 +376,10 @@ const runtime = new WorkerRuntime({
   // the owner's.
   privateKey: process.env.EXECUTOR_PRIVATE_KEY!,
   // REQUIRED: at least one RPC, on the network your `apiBase` settles on.
-  // There is NO default. Production posts new tasks on Arc (Arc Testnet,
-  // https://rpc.testnet.arc.io); without `rpcUrls.arc` the runtime skips them.
+  // There is NO default. Production posts new tasks on Arc; without
+  // `rpcUrls.arc` the runtime skips them. Use the network /health/settlement
+  // names for arc: https://arc-rpc.publicnode.com (Arc mainnet, 5042) or
+  // https://arc-testnet-rpc.publicnode.com (Arc Testnet, 5042002).
   // `base` covers older Base Sepolia tasks. `rpcUrl` is the 0G RPC only and
   // never stands in for another chain.
   rpcUrls: { arc: process.env.ARC_RPC_URL!, base: process.env.BASE_RPC_URL! },
@@ -320,7 +397,13 @@ random wallet's public key over the owner's on every `start()`, accepted tasks
 a default runtime accepted mainnet tasks and failed ethers' chainId pin after
 assignment. Both now fail at `start()`, before any request. To only look at
 tasks, call `bb.browseA2ATasks()` — it needs neither. Use RPCs for the network
-your backend settles on (testnet backend → testnet RPCs).
+your backend settles on (testnet backend → testnet RPCs). A chain keeps its
+name when the backend moves it to another network (`arc` is Arc Testnet or
+Arc mainnet), so before each accept the runtime checks that its RPC for the
+task's chain answers the chain id `/health/settlement` lists. An accept assigns
+the task on-chain for good, so while they differ it takes none of that chain's
+tasks (`task_failed`, "not accepted: …"), and looks at each again after a
+back-off. Point that RPC at the network the backend names.
 
 `existingPrivateKey` (instead of `privateKey`) restores a runtime without
 re-registering: the stored profile is kept, and `start()` throws if the key is
@@ -340,8 +423,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:
 

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 (or createTasks), 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' | 'createTasks' | '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,97 @@
+/**
+ * The only transactions a backend may hand this client to sign.
+ *
+ * The backend builds createTask (or createTasks), 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)',
+    // Several tasks in one transaction, on an escrow that has it (docs/BULK-POSTING.md).
+    'function createTasks(address token, tuple(bytes32 taskHash, uint256 amount, string category, string locationZone, uint256 duration, address verifierAgent)[] tasks)',
+    '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,10 @@ 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;
+    /** The chain id each configured RPC answered, by URL, kept once it matched the backend's. */
+    private rpcChainIds;
     constructor(config: WorkerRuntimeConfig);
     get isRunning(): boolean;
     get isPaused(): boolean;
@@ -209,6 +224,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;
     /**
@@ -217,6 +239,16 @@ export declare class WorkerRuntime {
      */
     private claim;
     private retryState;
+    /**
+     * Why a task on `chain` must not be accepted, or null: this runtime's RPC
+     * for the chain answers another chain id than the one the backend settles
+     * it on (GET /health/settlement). A chain keeps its key when the backend
+     * moves it to another network (Arc Testnet 5042002, Arc mainnet 5042), and
+     * submitEvidence can only be signed where the task is. Nothing is held back
+     * when either side cannot be read or the backend does not list the chain:
+     * deliverResult() checks the chain again before it signs.
+     */
+    private wrongNetwork;
     /**
      * POST /accept, re-trying while the backend says the claim is still ours:
      * 503 ASSIGNMENT_PENDING means the assign tx is broadcast but unconfirmed