@blindmarket/sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,106 @@
 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

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(
@@ -185,6 +187,19 @@ 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
@@ -204,6 +219,45 @@ 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.
@@ -249,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
@@ -321,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! },
@@ -340,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

package/dist/escrowCalls.d.ts

@@ -1,7 +1,7 @@
 /**
  * The only transactions a backend may hand this client to sign.
  *
- * The backend builds createTask, submitEvidence, cancelTask and claimTimeout
+ * 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
@@ -18,7 +18,7 @@
  */
 import { ethers } from 'ethers';
 export declare const ESCROW_CALLS: ethers.Interface;
-export type EscrowFunction = 'createTask' | 'createTaskWithVerifier' | 'submitEvidence' | 'cancelTask' | 'claimTimeout';
+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

package/dist/escrowCalls.js

@@ -1,7 +1,7 @@
 /**
  * The only transactions a backend may hand this client to sign.
  *
- * The backend builds createTask, submitEvidence, cancelTask and claimTimeout
+ * 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
@@ -21,6 +21,8 @@ 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)',

package/dist/executor/WorkerRuntime.d.ts

@@ -167,6 +167,8 @@ export declare class WorkerRuntime {
     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;
@@ -237,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

package/dist/executor/WorkerRuntime.js

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