@taifoon/jev 0.2.16 → 0.2.18

package/README.md

@@ -14,7 +14,8 @@ npx @taifoon/jev run --demo
 
 ![npx @taifoon/jev run --demo: a BitAgent job on Base, graded by Jev, checked against the chain](https://raw.githubusercontent.com/taifoon-io/jev/main/docs/demo.gif)
 
-Then grade your own with your TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai). Installing it also
+Then grade your own: with no key, on your free grades on the Taifoon coordination layer (3 a day per caller), or with
+your TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai). Installing it also
 installs Taifoon's other packages (@taifoon/jev-wilson, @taifoon/n8n-nodes-typesafe). No key inside, and it signs nothing. Recording a grade on chain is optional.
 
 ## Quick start
@@ -55,7 +56,7 @@ claims the evidence cannot support. Grade one with your key:
 ```
 TYPESAFE_KEY=… npx @taifoon/jev run --job-file examples/jobs/invoice-extraction.json
 npx @taifoon/jev run --demo      # offline, no key: replays the Base job below and checks it against the chain
-npx @taifoon/jev run             # a live Base job from the coordination layer's queue (needs TYPESAFE_KEY)
+npx @taifoon/jev run             # a live Base job from the coordination layer's queue (your TYPESAFE_KEY, else the free grades)
 ```
 
 ## A Base job, graded
@@ -121,8 +122,9 @@ Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or
 | `--seller-record <k>/<n>` | read from the layer | Price the premium here from the seller's record (k delivered of n graded) with [`@taifoon/jev-wilson`](https://www.npmjs.com/package/@taifoon/jev-wilson): the layer's numbers, no request |
 | `--yes` / `--json` | ask per step / text | Run every step without asking / print the whole trace as JSON |
 
-Environment: `TYPESAFE_KEY` (your key; without it a job that needs Jev stops and says where to get one, while a job the
-code checks reject is still graded). Exit codes: `0` done, `1` a step failed, `2` a flag was refused.
+Environment: `TYPESAFE_KEY` (your key; without it a job that needs Jev is graded on your free grades on the layer, and
+past them it stops and says how to pay one grade; a job the code checks reject is graded either way; `--no-layer`, `--demo` and `--job-file` ask
+no one). `TAIFOON_RELAYER_KEY` pays layer grades past the free ones from that key's balance. Exit codes: `0` done, `1` a step failed, `2` a flag was refused.
 
 ## What you must know
 
@@ -132,8 +134,12 @@ code checks reject is still graded). Exit codes: `0` done, `1` a step failed, `2
 - **Code composes the verdict** under THRESHOLDS_v1: complete, reject or needs_review. needs_review ends nothing and
   leaves room for an appeal. Above 50 USDC a complete is held for review.
 - **Nothing is signed.** `record()` and `evaluatorCall()` return unsigned calls. Whoever holds the seat signs.
-- **Your key.** Jev is called with your own TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai),
-  directly at TypeSafe. The key is not stored and never appears in a receipt.
+- **Your key, or the free grades.** With your own TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai),
+  Jev is called directly at TypeSafe; the key is not stored and never appears in a receipt. Without one, `grade()`
+  claims one of your free grades on the coordination layer (`POST https://coord.taifoon.dev/v1/judge/compose`, 3 a day
+  per caller): the layer asks Jev the same four questions and this package composes the verdict from the answers, so the
+  receipt is the same shape (`via.connection: "trial"`, with the grades left). Past them the layer answers 402 with the
+  price of one grade (x402), or pass `layerKey` (a Taifoon key) to pay from its balance. `layer: false` turns this off.
 - **What the result is.** *Graded against a published rubric by a pinned decision model, with an appeal.* It is not
   "independently verified". An on-chain record is an attestation by whoever sent it, not a proof the answer is right.
 
@@ -146,7 +152,7 @@ code checks reject is still graded). Exit codes: `0` done, `1` a step failed, `2
 | `facts({ delivered, checks, priceUsdc? })` | Runs the checks your protocol supplies |
 | `record(receipt, { network, send? })` | Returns the unsigned `JevAnswerLog.record` and `JevDecisionLog.record` calls |
 | `evaluatorCall(protocol, jobId, verdict, digest)` | Returns the one unsigned call that ends the job; `null` for needs_review |
-| `verify(receiptOrDigest)` | Recomputes every digest and finds the records on chain |
+| `verify(receiptOrDigest, { network? })` | Recomputes every digest and finds the records on chain (the devnet unless you name a chain; see Chains) |
 
 `verifyDecision(record, { answers? })` does the same for a decision as the coordination layer serves it at
 `/v1/judge/decisions/{id}`: the input fingerprint, the decision digest, the answers digest and the verdict RUBRIC_v1
@@ -173,8 +179,42 @@ npx @taifoon/jev verify <decision id> --network base   # recompute the served re
 npx @taifoon/jev workflows export ./jev-workflows
 ```
 
+## Chains
+
+`verify` reads the Jev logs on every chain they are deployed to: the Taifoon devnet (36927), Base (8453), Arbitrum One
+(42161), Arc (5042) and Monad (143). Robinhood Chain (4663), Taifoon mainnet (3692781) and Ethereum (1) are known
+chains with no Jev log yet; `verify` says so instead of reading them.
+
+| Flag | What it does |
+|---|---|
+| `--chain <id or name>` | Read one chain: `devnet`, `base`, `arbitrum`, `arc`, `monad`, `robinhood`, `taifoon`, or a chain id |
+| `--network devnet\|base\|any` | The earlier flag; still works. `any` is the same as naming no chain |
+| `--rpc <url[,url]>` | Read through these endpoints instead of the rotation below |
+
+With no chain named, a decision id is read on the chain its record names (its anchor); a bare digest is looked up on
+the devnet first, then Base, then the other chains, and the first chain that holds it answers. Nothing reads a mainnet
+unless the record or you name one: the tests and examples use the devnet.
+
+Every chain read goes through the warmbed rotation (`https://warmbed.taifoon.dev`), which lists the endpoints it
+measured to serve log windows for that chain. A rate limit, a server error or a timeout moves the read to the next
+endpoint, two passes over the list; a revert does not. When warmbed does not answer, the package uses the static list
+it ships (`src/rpc-fallback.ts`, generated from the RPC registry).
+
+`onChain.status` in the output tells the outcomes apart:
+
+| `status` | Meaning |
+|---|---|
+| `recorded` | The answer row is on chain (and the decision row, when there is one: `checks.decisionOnChain`) |
+| `not_recorded` | The chain answered and holds no row for this digest |
+| `rpc_unavailable` | No endpoint answered; the row may exist. Try again later, or pass `--rpc` |
+| `not_deployed` | No Jev log on that chain |
+| `skipped` | `verify(x, { chain: false })`: digests recomputed, no chain read |
+
+In code: `verify(digest, { network: 'arbitrum' })` (a name or a chain id), `{ rpc: 'https://…' }`, and `JevChainError`
+(`code`: `rpc_unavailable`, `not_deployed`, `reverted`, `bad_input`) from the lower-level calls.
+
 ## Licence
 
 Independent project. Jev and TypeSafe are products of TypeSafe AI, Inc., which does not endorse this package.
 
-Built by Taifoon. MIT. Its runtime dependencies are Taifoon's own packages, @taifoon/jev-wilson (the pricing) and @taifoon/n8n-nodes-typesafe; nothing third-party. It contains no key. It calls Jev only with your own TypeSafe key.
+Built by Taifoon. MIT. Its runtime dependencies are Taifoon's own packages, @taifoon/jev-wilson (the pricing) and @taifoon/n8n-nodes-typesafe; nothing third-party. It contains no key. It calls Jev with your own TypeSafe key, or without one through your free grades on the Taifoon coordination layer.

package/bin/jev.mjs

@@ -3,7 +3,10 @@
 //   jev workflows list [--version X]          the bundled n8n workflows (and which nodes and credentials each needs)
 //   jev workflows export <dir> [--version X]  write them, their schemas, manifest and README into <dir>
 //   jev run [--job 8453:81100] [--evidence pack.json] [--network …] [--yes] [--json]   one job through the pipeline, step by step
-//   jev verify <answers-digest | decision id> [--network devnet|base|any]  (a decision id: recompute its record offline, then) find the digest's JevAnswered / Decided rows (default any: devnet, then Base 8453)
+//   jev verify <answers-digest | decision id> [--chain <id|name>] [--rpc url[,url]]  (a decision id: recompute its record offline, then) find the digest's
+//     JevAnswered / Decided rows: on --chain, else the chain the decision record names, else every chain with Jev logs (devnet,
+//     Base, then the rest). Chain reads go through warmbed's rotation, then the registry's static list; --rpc overrides both.
+//     --network devnet|base|any still works (any = no chain named).
 import { cpSync, existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -16,6 +19,9 @@ const flag = (n) => { const i = args.indexOf(n); return i >= 0 ? args.splice(i,
 const BUNDLES = readdirSync(join(ROOT, 'workflows')).filter((d) => /^\d+\.\d+\.\d+$/.test(d)).sort((x, y) => x.localeCompare(y, undefined, { numeric: true }));
 const version = flag('--version') ?? BUNDLES.at(-1) ?? PKG.version;
 const network = flag('--network') ?? 'any';
+// --rpc <url[,url…]>: read through these endpoints instead of warmbed's rotation (the named or anchored chain; else Base)
+const rpcFlag = flag('--rpc');
+const chainFlag = flag('--chain');
 const bundle = join(ROOT, 'workflows', version);
 const die = (m) => { console.error(m); process.exit(1); };
 const [cmd, sub, target] = args;
@@ -34,9 +40,12 @@ if (cmd === 'workflows') {
 } else if (cmd === 'run') {
   await import('./run.mjs').then((m) => m.run(process.argv.slice(3)));
 } else if (cmd === 'verify' && sub) {
-  const { verify, verifyDecision, LAYER } = await import('../dist/index.js');
-  if (!['devnet', 'base', 'any'].includes(network)) die('--network is devnet, base or any');
-  let digest = sub; let offline = null;
+  const { verify, verifyDecision, LAYER, chainIdOf, JEV_CHAINS } = await import('../dist/index.js');
+  // which chain(s) to read: --chain <id|name> (or --network devnet|base|<chain>) names one; otherwise the chain the decision
+  // record names (its anchor); otherwise every chain with Jev logs in turn (devnet, Base, then the rest) until one holds it
+  let named = null;
+  try { named = chainFlag ? chainIdOf(chainFlag) : network !== 'any' ? chainIdOf(network) : null; } catch (e) { die(e.message); }
+  let digest = sub; let offline = null; let anchor = null;
   // a decision id (or its /v1/judge/decisions URL): read the served record and its answers, recompute both here, then
   // find the answers digest on chain like any other
   const m = /(decision-\d+-[0-9a-f]{10})/.exec(sub);
@@ -48,11 +57,20 @@ if (cmd === 'workflows') {
     offline = verifyDecision(rec, ans?.record ? { answers: ans.record } : {});
     if (!ad) { console.log(JSON.stringify({ offline }, null, 1)); process.exit(offline.ok ? 0 : 2); }
     digest = ad;
+    const a = rec?.decision?.anchor;
+    if (a && a.status === 'ok' && Number.isInteger(Number(a.chain))) anchor = { chain: Number(a.chain), block: Number(a.block) || undefined };
+  }
+  const chains = named ? [named] : anchor ? [anchor.chain] : JEV_CHAINS;
+  // --rpc reads one chain: the named or anchored one, else Base (the endpoints a reader passes are almost always Base's)
+  const rpcFor = (c) => (rpcFlag && (chains.length === 1 || c === 8453) ? { rpc: rpcFlag } : {});
+  let v = null;
+  for (const c of chains) {
+    const r = await verify(digest, { network: c, ...rpcFor(c), ...(anchor && anchor.chain === c && anchor.block ? { decisionBlock: anchor.block } : {}) });
+    if (!v || r.checks.answersOnChain || (c === 8453 && !v.ok)) v = r;
+    if (r.checks.answersOnChain) break;
   }
-  let v = await verify(digest, { network: network === 'base' ? 'base' : 'devnet' });
-  if (network === 'any' && !v.checks.answersOnChain) { const b = await verify(sub, { network: 'base' }); if (b.checks.answersOnChain || !v.ok) v = b; }
   console.log(JSON.stringify(offline ? { offline, ...v, ok: v.ok && offline.ok } : v, null, 1));
   process.exit(v.ok && (!offline || offline.ok) ? 0 : 2);
 } else {
-  console.log(`jev ${PKG.version}\n  jev workflows list [--version X]\n  jev workflows export <dir> [--version X]\n  jev run [--job <chain>:<id>] [--evidence pack.json] [--network none|devnet|base|both] [--yes] [--json]\n  jev verify <answers-digest | decision id> [--network devnet|base|any]`);
+  console.log(`jev ${PKG.version}\n  jev workflows list [--version X]\n  jev workflows export <dir> [--version X]\n  jev run [--job <chain>:<id>] [--evidence pack.json] [--network none|devnet|base|both] [--yes] [--json]\n  jev verify <answers-digest | decision id> [--chain <id|name>] [--rpc url[,url]]`);
 }

package/bin/run.mjs

@@ -1,5 +1,5 @@
 // jev run — one job through the pipeline, one step at a time.
-//   jev run                              the first ready job on the coordination layer's queue (needs TYPESAFE_KEY)
+//   jev run                              the first ready job on the coordination layer's queue (your TYPESAFE_KEY, else the free grades)
 //   jev run --job 8453:81100             a job you name (chain:id; ids like bitagent:8453:7287 work too)
 //   jev run --evidence pack.json         your own pack, no layer at all: { subject, state, delivered?, checks?, priceUsdc? }
 //   jev run --job-file job.json          one agent job: { id, task, criteria[], delivered, source?, checks[] } (see examples/jobs/)
@@ -71,7 +71,7 @@ export async function run(argv) {
 
   const t = createTerm({ quiet: json });
   const rl = yes ? null : createInterface({ input: process.stdin, output: process.stdout });
-  t.info(`jev run · ${noLayer ? 'offline' : `layer ${layer ?? 'https://coord.taifoon.dev'}`} · grade on ${demo ? `Jev's recorded answers for ${rec.job.ref} (${rec.job.task})` : ansFile ? 'supplied answers' : process.env.TYPESAFE_KEY ? 'your TypeSafe key' : 'no key: set TYPESAFE_KEY, or try --demo'} · record → ${network === 'none' ? 'none (opt in with --record devnet|base|both)' : network}${process.env.TAIFOON_RELAYER_KEY ? ' + the layer' : ''}`);
+  t.info(`jev run · ${noLayer ? 'offline' : `layer ${layer ?? 'https://coord.taifoon.dev'}`} · grade on ${demo ? `Jev's recorded answers for ${rec.job.ref} (${rec.job.task})` : ansFile ? 'supplied answers' : process.env.TYPESAFE_KEY ? 'your TypeSafe key' : noLayer ? 'no key: set TYPESAFE_KEY, or try --demo' : 'your free grades on the layer (no TypeSafe key)'} · record → ${network === 'none' ? 'none (opt in with --record devnet|base|both)' : network}${process.env.TAIFOON_RELAYER_KEY ? ' + the layer' : ''}`);
 
   const trace = await pipeline({
     layer, job, network, protocol, priceUsdc: price ? Number(price) : undefined, sellerRecord: recM ? { k: Number(recM[1]), n: Number(recM[2]) } : undefined,

package/dist/addresses.d.ts

@@ -60,3 +60,14 @@ export declare const REGISTRY_ADDRESSES: {
         readonly block: 48395723;
     };
 };
+/** The Jev logs on every chain the registry deploys them to (JevAnswerLog + JevDecisionLog, from their deploy block). */
+export declare const JEV_LOGS: Readonly<Record<number, {
+    answerLog: {
+        address: string;
+        fromBlock: number;
+    };
+    decisionLog: {
+        address: string;
+        fromBlock: number;
+    };
+}>>;

package/dist/addresses.js

@@ -22,3 +22,11 @@ export const REGISTRY_ADDRESSES = {
     /** standards-erc8183 · BitAgent ERC-8183 escrow (live) */
     bitagentErc8183: { chainId: 8453, address: '0x5009ABB3A309115a4a682C66BAf3BC9E0329BaB7', block: 48395723 },
 };
+/** The Jev logs on every chain the registry deploys them to (JevAnswerLog + JevDecisionLog, from their deploy block). */
+export const JEV_LOGS = {
+    143: { answerLog: { address: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', fromBlock: 110216088 }, decisionLog: { address: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', fromBlock: 110216093 } },
+    5042: { answerLog: { address: '0x45214361A8cADb8aEe6302cd5653E119E5a89839', fromBlock: 24071071 }, decisionLog: { address: '0x863db7dAc69CC614a98822082cbe884F1f3b55cA', fromBlock: 24071074 } },
+    8453: { answerLog: { address: '0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d', fromBlock: 51863008 }, decisionLog: { address: '0x209490d6A0FFC5368A42b0c2208BDCda853f6a92', fromBlock: 51856200 } },
+    36927: { answerLog: { address: '0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3', fromBlock: 1106754 }, decisionLog: { address: '0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05', fromBlock: 981099 } },
+    42161: { answerLog: { address: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', fromBlock: 511340178 }, decisionLog: { address: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', fromBlock: 511340188 } },
+};

package/dist/ask.d.ts

@@ -6,9 +6,16 @@ export type Asked = {
     answers: Record<string, Answer>;
     model: string | null;
     latency_ms: number | null;
-    connection: 'key';
-    trial: null;
+    connection: 'key' | 'trial';
+    trial: {
+        calls: number;
+        left: number;
+    } | null;
 };
+/** the coordination layer, where a caller without a TypeSafe key claims its free grades */
+export declare const LAYER_URL = "https://coord.taifoon.dev";
+/** the questions the layer's free grade answers (RUBRIC_v1 asks exactly these); another rubric needs the caller's own key */
+export declare const LAYER_QUESTIONS: readonly string[];
 export declare class JevError extends Error {
     readonly status: number;
     readonly next?: string | undefined;
@@ -22,3 +29,12 @@ export declare function askJev(a: {
     model?: string;
     fetch?: typeof fetch;
 }): Promise<Asked>;
+/** A free grade on the coordination layer (or one paid from a Taifoon key's balance, with `apiKey`): the layer asks Jev the
+ *  four RUBRIC questions on `text` and returns the answers; this package composes the verdict from them as with a key. */
+export declare function askLayer(a: {
+    text: string;
+    questions: readonly Question[];
+    layer?: string;
+    apiKey?: string | null;
+    fetch?: typeof fetch;
+}): Promise<Asked>;

package/dist/ask.js

@@ -1,6 +1,10 @@
 export const TYPESAFE_URL = 'https://api.typesafe.ai';
 /** The model every key-path call asks for. Pinned, not `jev-latest`: a record says which model answered, and an alias can move. */
 export const JEV_MODEL = 'jev-1.13.0';
+/** the coordination layer, where a caller without a TypeSafe key claims its free grades */
+export const LAYER_URL = 'https://coord.taifoon.dev';
+/** the questions the layer's free grade answers (RUBRIC_v1 asks exactly these); another rubric needs the caller's own key */
+export const LAYER_QUESTIONS = Object.freeze(['spec_met', 'unsupported_claim', 'ending', 'cheat_shaped']);
 export class JevError extends Error {
     status;
     next;
@@ -33,3 +37,29 @@ export async function askJev(a) {
     }
     return { answers, model: j.model ?? null, latency_ms: Date.now() - started, connection: 'key', trial: null };
 }
+/** A free grade on the coordination layer (or one paid from a Taifoon key's balance, with `apiKey`): the layer asks Jev the
+ *  four RUBRIC questions on `text` and returns the answers; this package composes the verdict from them as with a key. */
+export async function askLayer(a) {
+    const f = a.fetch ?? fetch;
+    const started = Date.now();
+    const other = a.questions.map((q) => q.id).filter((id) => !LAYER_QUESTIONS.includes(id));
+    if (other.length)
+        throw new JevError(`the layer's free grade answers ${LAYER_QUESTIONS.join(', ')}; this rubric also asks ${other.join(', ')}: pass { key } (your TypeSafe key)`, 400, 'grade({ key: process.env.TYPESAFE_KEY })');
+    const base = (a.layer ?? LAYER_URL).replace(/\/$/, '');
+    if (!/^https:\/\//.test(base) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(base))
+        throw new JevError('the layer is only called over https', 400);
+    const r = await f(`${base}/v1/judge/compose`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-taifoon-client': '@taifoon/jev', ...(a.apiKey ? { 'x-api-key': a.apiKey } : {}) }, body: JSON.stringify({ state: a.text }), signal: AbortSignal.timeout(65_000) });
+    const j = (await r.json().catch(() => ({})));
+    if (r.status === 402)
+        throw new JevError('no free grade left for this caller today: pass { key } (your TypeSafe key), a Taifoon key (layerKey), or pay one grade with x402 at POST ' + `${base}/v1/judge/compose`, 402, `${base}/v1/judge/compose`);
+    if (!r.ok)
+        throw new JevError(`the layer answered ${r.status}${j.error ? `: ${String(j.error).slice(0, 200)}` : ''}`, r.status);
+    const answers = {};
+    for (const q of a.questions) {
+        const x = j.receipt?.answers?.[q.id];
+        if (x)
+            answers[q.id] = norm(q.id, x);
+    }
+    const g = j.quota?.grades;
+    return { answers, model: j.model ?? null, latency_ms: Date.now() - started, connection: 'trial', trial: g && typeof g.free === 'number' && typeof g.left === 'number' ? { calls: g.free, left: g.left } : null };
+}

package/dist/chains.d.ts

@@ -0,0 +1,18 @@
+export declare const DEVNET = 36927;
+export declare const CHAIN_NAMES: Readonly<Record<number, string>>;
+export declare const chainName: (id: number) => string;
+/** A chain id from an id ("8453"), a name ("base", "Arbitrum One") or a number. Throws JevChainError bad_input. */
+export declare function chainIdOf(x: string | number): number;
+/** The Jev logs of a chain, or null when none is deployed there. */
+export declare const jevLogsOn: (chainId: number) => {
+    answerLog: {
+        address: string;
+        fromBlock: number;
+    };
+    decisionLog: {
+        address: string;
+        fromBlock: number;
+    };
+} | null;
+/** Every chain that carries Jev logs, the devnet first, then Base, then the rest by id. */
+export declare const JEV_CHAINS: readonly number[];

package/dist/chains.js

@@ -0,0 +1,31 @@
+// The chains verify() knows: every chain the coordination layer reads, by id or name, and the Jev logs on each
+// (vendored from the address registry: src/addresses.ts JEV_LOGS). A chain without Jev logs is known but has nothing to verify.
+import { JEV_LOGS } from './addresses.js';
+import { JevChainError } from './errors.js';
+export const DEVNET = 36927;
+export const CHAIN_NAMES = {
+    36927: 'Taifoon devnet', 8453: 'Base', 42161: 'Arbitrum One', 5042: 'Arc', 4663: 'Robinhood Chain', 143: 'Monad',
+    3692781: 'Taifoon mainnet', 1: 'Ethereum',
+};
+const ALIASES = {
+    devnet: 36927, 'taifoon-devnet': 36927, base: 8453, arbitrum: 42161, 'arbitrum-one': 42161, arb: 42161, arc: 5042,
+    robinhood: 4663, 'robinhood-chain': 4663, monad: 143, taifoon: 3692781, 'taifoon-mainnet': 3692781, ethereum: 1, eth: 1,
+};
+export const chainName = (id) => `${CHAIN_NAMES[id] ?? 'chain'} (${id})`;
+/** A chain id from an id ("8453"), a name ("base", "Arbitrum One") or a number. Throws JevChainError bad_input. */
+export function chainIdOf(x) {
+    if (typeof x === 'number' && Number.isInteger(x) && x > 0)
+        return x;
+    const s = String(x).trim().toLowerCase().replace(/\s+/g, '-');
+    if (/^\d+$/.test(s))
+        return Number(s);
+    const id = ALIASES[s];
+    if (!id)
+        throw new JevChainError('bad_input', `unknown chain "${x}"; use an id or one of: ${Object.keys(ALIASES).join(', ')}`);
+    return id;
+}
+/** The Jev logs of a chain, or null when none is deployed there. */
+export const jevLogsOn = (chainId) => JEV_LOGS[chainId] ?? null;
+/** Every chain that carries Jev logs, the devnet first, then Base, then the rest by id. */
+export const JEV_CHAINS = Object.keys(JEV_LOGS).map(Number)
+    .sort((a, b) => (a === DEVNET ? -1 : b === DEVNET ? 1 : a === 8453 ? -1 : b === 8453 ? 1 : a - b));

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Why a chain read did not give an answer. `rpc_unavailable`: every endpoint failed (rate limit, 5xx, timeout); the record
+ * may well exist, try again or pass --rpc. `not_deployed`: no Jev log on that chain. `reverted`: the call reverted.
+ * `bad_input`: an argument verify() cannot use. "Not recorded" is not an error: verify() reports it in onChain.status.
+ */
+export type JevChainErrorCode = 'rpc_unavailable' | 'not_deployed' | 'reverted' | 'bad_input';
+export declare class JevChainError extends Error {
+    readonly code: JevChainErrorCode;
+    readonly chainId?: number;
+    constructor(code: JevChainErrorCode, message: string, chainId?: number);
+}

package/dist/errors.js

@@ -0,0 +1,5 @@
+export class JevChainError extends Error {
+    code;
+    chainId;
+    constructor(code, message, chainId) { super(message); this.name = 'JevChainError'; this.code = code; this.chainId = chainId; }
+}

package/dist/grade.d.ts

@@ -20,6 +20,11 @@ export type GradeInput = {
     caller?: string;
     /** base URL for `key` (default https://api.typesafe.ai) */
     endpoint?: string;
+    /** with no `key` and no `answers`: the coordination layer whose free grades are claimed (default https://coord.taifoon.dev);
+     *  false never calls it (then a key or answers are required) */
+    layer?: string | false;
+    /** a Taifoon key (tfr_…): a grade past the free ones is paid from its balance on the layer */
+    layerKey?: string | null;
     fetch?: typeof fetch;
     /** ms since epoch for the answer record; default now */
     at?: number;

package/dist/grade.js

@@ -1,5 +1,5 @@
 // grade(): evidence → deterministic facts → Jev's atomic questions → composed verdict → receipt.
-import { askJev, JevError } from './ask.js';
+import { askJev, askLayer, JevError } from './ask.js';
 import { answersOf, buildReceipt, DEFAULT_FACTS, inputFor, packOf, rubricOf } from './receipt.js';
 export async function grade(g) {
     const rubric = rubricOf(g.rubric);
@@ -17,9 +17,12 @@ export async function grade(g) {
             connection = 'supplied';
         }
         else {
-            if (!g.key)
+            if (!g.key && g.layer === false)
                 throw new JevError('pass { key } (your TypeSafe key, from console.typesafe.ai) or { answers } you already have', 400);
-            asked = await askJev({ text: jevState, questions: rubric.asked, key: g.key, endpoint: g.endpoint, fetch: g.fetch });
+            // _FREE_GRADES_v1_: no key of your own → the caller's free grades on the coordination layer (then x402 or a Taifoon key)
+            asked = g.key
+                ? await askJev({ text: jevState, questions: rubric.asked, key: g.key, endpoint: g.endpoint, fetch: g.fetch })
+                : await askLayer({ text: jevState, questions: rubric.asked, layer: g.layer || undefined, apiKey: g.layerKey, fetch: g.fetch });
             const missing = rubric.asked.filter((q) => !asked.answers[q.id]).map((q) => q.id);
             if (missing.length)
                 throw new JevError(`Jev returned no valid answer for: ${missing.join(', ')}`, 502);

package/dist/index.d.ts

@@ -20,6 +20,9 @@ export { prepareJob, runCheck } from './job.js';
 export { record } from './record.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
+export { JevChainError, type JevChainErrorCode } from './errors.js';
+export { CHAIN_NAMES, JEV_CHAINS, chainIdOf, chainName, jevLogsOn } from './chains.js';
+export { rpcRotation, WARMBED } from './rpc.js';
 export { verifyDecision } from './decision.js';
 export { pipeline, STEPS, LAYER, factsFromEvidence, protocolFor, parseJob, localQuote } from './pipeline.js';
 export { RUBRIC_v1 } from './rubric.js';
@@ -28,7 +31,7 @@ export type { GradeInput, Receipt } from './grade.js';
 export type { FactsInput, Check } from './facts.js';
 export type { JobSpec, JobCheck, PreparedJob } from './job.js';
 export type { Recorded, UnsignedCall, Network } from './record.js';
-export type { Verification, AnswerEvent, DecisionEvent } from './verify.js';
+export type { Verification, AnswerEvent, DecisionEvent, ChainStatus, VerifyOptions, VerifyNetwork } from './verify.js';
 export type { DecisionRecord, DecisionCheck } from './decision.js';
 export type { Protocol, Adapter, AdapterOpts, EvaluatorCall } from './evaluator/index.js';
 export type { JevError } from './ask.js';

package/dist/index.js

@@ -20,6 +20,9 @@ export { prepareJob, runCheck } from './job.js';
 export { record } from './record.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
+export { JevChainError } from './errors.js';
+export { CHAIN_NAMES, JEV_CHAINS, chainIdOf, chainName, jevLogsOn } from './chains.js';
+export { rpcRotation, WARMBED } from './rpc.js';
 export { verifyDecision } from './decision.js';
 export { pipeline, STEPS, LAYER, factsFromEvidence, protocolFor, parseJob, localQuote } from './pipeline.js';
 export { RUBRIC_v1 } from './rubric.js';

package/dist/pipeline.js

@@ -1,7 +1,7 @@
 // pipeline(): one job through the coordination layer's steps, each step a function with a typed output.
 //   pick → evidence → facts → grade → record → evaluator → premium → verify
 // Every step works without the layer too: pass `evidence` (your own pack) and the layer is never read; `grade` then
-// runs on your own TypeSafe key (or answers you already have), `record` returns unsigned calls, `premium` is priced from a `sellerRecord` you pass (or skipped). With the layer
+// runs on your own TypeSafe key (or answers you already have, or without either on the caller's free grades on the layer), `record` returns unsigned calls, `premium` is priced from a `sellerRecord` you pass (or skipped). With the layer
 // (https://coord.taifoon.dev by default) the job comes from /v1/judge/queue, the pack from /v1/judge/evidence, the
 // seller's terms from /v1/pools/quote, and — only with a relayer key — the answers are recorded on the layer through
 // /v1/judge/answers/record. Nothing here signs a transaction.
@@ -156,12 +156,17 @@ export async function pipeline(o = {}) {
         }
         else if (o.key)
             g.key = o.key;
+        // _FREE_GRADES_v1_: no key → the caller's free grades on this layer (paid from relayerKey's balance past them); offline: none
+        else {
+            g.layer = layer ?? false;
+            g.layerKey = o.relayerKey ?? null;
+        }
         // no key: a job the code checks reject is still graded (Jev is not asked); only asking Jev needs the key
         try {
             t.receipt = await grade(g);
         }
         catch (e) {
-            if (!o.key && !o.answers && /TypeSafe key/.test(e.message))
+            if (!o.key && !o.answers && !layer && /TypeSafe key/.test(e.message))
                 throw new Error('Jev needs your TypeSafe key: set TYPESAFE_KEY (console.typesafe.ai), or pass answers you already have');
             throw e;
         }

package/dist/rpc-fallback.d.ts

@@ -0,0 +1,4 @@
+export declare const RPC_FALLBACK: Readonly<Record<number, {
+    logs: readonly string[];
+    call: readonly string[];
+}>>;

package/dist/rpc-fallback.js

@@ -0,0 +1,36 @@
+// GENERATED by scripts/vendor-rpc.mjs from packages/rpc/fallback.json (measured 2026-10-08). Do not edit.
+// The fallback only: verify() asks warmbed's rotation first and uses these when warmbed does not answer.
+export const RPC_FALLBACK = {
+    36927: {
+        logs: ["https://rpc.taifoon.dev"],
+        call: ["https://rpc.taifoon.dev"],
+    },
+    8453: {
+        logs: ["https://base.rpc.blxrbdn.com", "https://base.public.blockpi.network/v1/rpc/public", "https://base-rpc.publicnode.com", "https://gateway.tenderly.co/public/base", "https://base.gateway.tenderly.co"],
+        call: ["https://base.rpc.blxrbdn.com", "https://base.public.blockpi.network/v1/rpc/public", "https://gateway.tenderly.co/public/base", "https://base.gateway.tenderly.co", "https://base-rpc.publicnode.com", "https://developer-access-mainnet.base.org", "https://mainnet.base.org", "https://base.drpc.org", "https://base-mainnet.public.blastapi.io", "https://api.zan.top/base-mainnet", "https://base.meowrpc.com", "https://base-public.nodies.app"],
+    },
+    42161: {
+        logs: ["https://arb1.arbitrum.io/rpc", "https://gateway.tenderly.co/public/arbitrum", "https://arbitrum.gateway.tenderly.co"],
+        call: ["https://arb1.arbitrum.io/rpc", "https://gateway.tenderly.co/public/arbitrum", "https://arbitrum.gateway.tenderly.co", "https://arbitrum.drpc.org", "https://arbitrum-one-rpc.publicnode.com", "https://arbitrum-one.public.blastapi.io"],
+    },
+    5042: {
+        logs: ["https://rpc.mainnet.arc.io", "https://rpc.quicknode.mainnet.arc.io", "https://rpc.blockdaemon.mainnet.arc.io", "https://arc.gateway.tenderly.co"],
+        call: ["https://rpc.mainnet.arc.io", "https://rpc.quicknode.mainnet.arc.io", "https://rpc.blockdaemon.mainnet.arc.io", "https://arc.gateway.tenderly.co", "https://rpc.drpc.mainnet.arc.io", "https://arc.drpc.org", "https://arc-rpc.publicnode.com"],
+    },
+    4663: {
+        logs: ["https://rpc.mainnet.chain.robinhood.com", "https://rpc.ordofi.network"],
+        call: ["https://rpc.mainnet.chain.robinhood.com", "https://rpc.ordofi.network", "https://robinhood.drpc.org", "https://robinhood-rpc.publicnode.com"],
+    },
+    143: {
+        logs: ["https://rpc1.monad.xyz", "https://infra.originstake.com/monad/evm"],
+        call: ["https://rpc1.monad.xyz", "https://infra.originstake.com/monad/evm", "https://rpc.monad.xyz", "https://rpc3.monad.xyz", "https://rpc-mainnet.monadinfra.com", "https://monad.gateway.tenderly.co", "https://rpc.ankr.com/monad_mainnet", "https://rpc4.monad.xyz"],
+    },
+    3692781: {
+        logs: ["https://mainnet.taifoon.dev"],
+        call: ["https://mainnet.taifoon.dev"],
+    },
+    1: {
+        logs: ["https://gateway.tenderly.co/public/mainnet", "https://rpc.mevblocker.io", "https://mainnet.gateway.tenderly.co", "https://ethereum.publicnode.com", "https://rpc.flashbots.net"],
+        call: ["https://gateway.tenderly.co/public/mainnet", "https://mainnet.gateway.tenderly.co", "https://rpc.mevblocker.io", "https://ethereum-rpc.publicnode.com", "https://ethereum.publicnode.com", "https://rpc.flashbots.net", "https://eth.drpc.org"],
+    },
+};

package/dist/rpc.d.ts

@@ -0,0 +1,17 @@
+export declare const WARMBED = "https://warmbed.taifoon.dev";
+export declare const RPC_TIMEOUT_MS = 30000;
+/** Forget the cached rotations (tests; a long-running process never needs it: entries expire after 60 s). */
+export declare function clearRpcCache(): void;
+/** warmbed's rotation of a chain for `need`, then the static fallback (deduplicated). Never throws. */
+export declare function rpcRotation(chainId: number, f?: typeof fetch, need?: 'logs' | 'call'): Promise<string[]>;
+/** The cap an endpoint names when it refuses a range ("eth_getLogs is limited to a 500 range"), or null. */
+export declare function rangeCapOf(message: string): number | null;
+/**
+ * One JSON-RPC call over a list of endpoints (or one URL): each endpoint in turn, two passes with a short pause, each
+ * attempt bounded by RPC_TIMEOUT_MS. Throws JevChainError reverted / rpc_unavailable, or the range refusal as is.
+ */
+export declare function rpcCall<T>(rpc: string | readonly string[], f: typeof fetch, method: string, params: unknown[], o?: {
+    chainId?: number;
+    passes?: number;
+    timeoutMs?: number;
+}): Promise<T>;

package/dist/rpc.js

@@ -0,0 +1,87 @@
+// The RPCs the package reads through: warmbed's rotation (https://warmbed.taifoon.dev, endpoints it measured to serve
+// eth_getLogs windows), then the static list vendored from the RPC registry (src/rpc-fallback.ts). A rate limit, a 5xx,
+// a timeout or a refusal moves a call to the next endpoint; a revert is thrown at once (JevChainError reverted), and so is a
+// range refusal that names its cap (the caller narrows the window). When every endpoint failed: JevChainError rpc_unavailable.
+import { JevChainError } from './errors.js';
+import { RPC_FALLBACK } from './rpc-fallback.js';
+export const WARMBED = 'https://warmbed.taifoon.dev';
+export const RPC_TIMEOUT_MS = 30_000;
+const WARMBED_TIMEOUT_MS = 2_500;
+const TTL_MS = 60_000;
+const cache = new Map();
+/** Forget the cached rotations (tests; a long-running process never needs it: entries expire after 60 s). */
+export function clearRpcCache() { cache.clear(); }
+/** warmbed's rotation of a chain for `need`, then the static fallback (deduplicated). Never throws. */
+export async function rpcRotation(chainId, f = fetch, need = 'logs') {
+    const k = `${chainId}:${need}`;
+    const hit = cache.get(k);
+    if (hit && Date.now() - hit.at < TTL_MS)
+        return hit.urls;
+    let warm = [];
+    try {
+        const r = await f(`${WARMBED}/warmbed/chain/${chainId}/rotation?need=${need}${need === 'logs' ? '&min_span=500' : ''}&n=8`, { signal: AbortSignal.timeout(WARMBED_TIMEOUT_MS) });
+        const body = r && r.ok ? (await r.json()) : null;
+        if (Array.isArray(body))
+            warm = body.map((e) => (e && typeof e === 'object' ? String(e.url ?? '') : '')).filter((u) => /^https:\/\//.test(u));
+    }
+    catch {
+        warm = [];
+    }
+    const urls = [...new Set([...warm, ...(RPC_FALLBACK[chainId]?.[need] ?? []), ...(RPC_FALLBACK[chainId]?.call ?? [])])];
+    if (warm.length)
+        cache.set(k, { at: Date.now(), urls });
+    return urls;
+}
+const REVERT = /revert|invalid opcode|out of gas/i;
+/** The cap an endpoint names when it refuses a range ("eth_getLogs is limited to a 500 range"), or null. */
+export function rangeCapOf(message) {
+    const m = /limited to (?:a )?(\d+)(?: block)? range/i.exec(message) ?? /range (?:is )?(?:limited|capped) (?:to|at) (\d+)/i.exec(message);
+    return m ? Number(m[1]) : null;
+}
+/**
+ * One JSON-RPC call over a list of endpoints (or one URL): each endpoint in turn, two passes with a short pause, each
+ * attempt bounded by RPC_TIMEOUT_MS. Throws JevChainError reverted / rpc_unavailable, or the range refusal as is.
+ */
+export async function rpcCall(rpc, f, method, params, o = {}) {
+    const urls = typeof rpc === 'string' ? [rpc] : rpc;
+    if (!urls.length)
+        throw new JevChainError('rpc_unavailable', `${method}: no RPC endpoint`, o.chainId);
+    const passes = o.passes ?? 2;
+    let last = '';
+    for (let p = 0; p < passes; p++) {
+        for (const u of urls) {
+            try {
+                const r = await f(u, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }), signal: AbortSignal.timeout(o.timeoutMs ?? RPC_TIMEOUT_MS) });
+                if (typeof r.status === 'number' && r.status >= 400) {
+                    last = `${hostOf(u)}: http ${r.status}`;
+                    continue;
+                }
+                const j = (await r.json());
+                if (j.error) {
+                    const msg = String(j.error.message ?? j.error.code);
+                    if (j.error.code === 3 || REVERT.test(msg))
+                        throw new JevChainError('reverted', `${method}: ${msg}`, o.chainId);
+                    if (rangeCapOf(msg))
+                        throw Object.assign(new Error(`${method}: ${msg}`), { final: true });
+                    last = `${hostOf(u)}: ${msg.slice(0, 160)}`;
+                    continue;
+                }
+                return j.result;
+            }
+            catch (e) {
+                if (e instanceof JevChainError || e.final)
+                    throw e;
+                last = `${hostOf(u)}: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        if (p + 1 < passes)
+            await new Promise((r) => setTimeout(r, 400 * (p + 1)));
+    }
+    throw new JevChainError('rpc_unavailable', `${method}: every RPC endpoint failed (last: ${last})`, o.chainId);
+}
+function hostOf(u) { try {
+    return new URL(u).host;
+}
+catch {
+    return u;
+} }

package/dist/verify.d.ts

@@ -1,3 +1,4 @@
+import { rangeCapOf } from './rpc.js';
 import { type Hex } from './hash.js';
 import type { Receipt } from './receipt.js';
 import { type Rubric, type RubricInput } from './rubric.js';
@@ -25,36 +26,48 @@ export type DecisionEvent = {
 export type Verification = {
     ok: boolean;
     checks: Record<string, boolean>;
+    /** status: recorded (the answer row is on chain) · not_recorded (the chain answered, no row) · rpc_unavailable (no endpoint
+     *  answered: the row may exist) · not_deployed (no Jev log on that chain) · skipped (chain: false) */
     onChain: {
         chainId: number;
         answers: AnswerEvent[];
         decisions: DecisionEvent[];
+        status?: ChainStatus;
     };
     problems: string[];
 };
+export type ChainStatus = 'recorded' | 'not_recorded' | 'rpc_unavailable' | 'not_deployed' | 'skipped';
 export type Log = {
     transactionHash: string;
     blockNumber: string;
     topics: string[];
     data: Hex;
 };
-/** The block cap an endpoint names when it refuses a range ("eth_getLogs is limited to a 500 range"), or null. */
-export declare function rangeCapOf(message: string): number | null;
+type Rpc = string | readonly string[];
+export { rangeCapOf };
 /**
  * eth_getLogs over [from, to], nearest to `center` first, in windows of at most `step` blocks (public Base endpoints
  * refuse wide ranges: mainnet.base.org caps a call at 500 blocks). A refusal that names a smaller cap shrinks the
  * window and retries. Stops at the first window where `hit` matches, so a record next to its answer costs one call.
  */
-export declare function logsAround(rpc: string, f: typeof fetch, address: string, topics: Array<string | null>, center: number, from: number, to: number, hit: (l: Log) => boolean, step?: number): Promise<Log[]>;
-/**
- * `network`: 'devnet' (default, chain 36927) or 'base' (8453). On Base the answer row is found through
- * JevAnswerLog.recordedAt (trusted records only) and the decision row in a window around it, because public Base
- * endpoints refuse wide log ranges.
- */
-export declare function verify(x: Receipt | string, opts?: {
-    rpc?: string;
+export declare function logsAround(rpc: Rpc, f: typeof fetch, address: string, topics: Array<string | null>, center: number, from: number, to: number, hit: (l: Log) => boolean, step?: number, chainId?: number): Promise<Log[]>;
+/** Which chain verify() reads: 'devnet' (default, 36927), 'base', a chain id or a chain name ("arbitrum", "arc", "monad" …). */
+export type VerifyNetwork = 'devnet' | 'base' | number | string;
+export type VerifyOptions = {
+    /** one URL, a comma list or a list: read through these instead of warmbed's rotation */
+    rpc?: string | readonly string[];
     fetch?: typeof fetch;
     rubric?: Rubric | RubricInput;
+    /** false: recompute the digests only, read no chain */
     chain?: boolean;
-    network?: 'devnet' | 'base';
-}): Promise<Verification>;
+    network?: VerifyNetwork;
+    /** a block near the decision row (a decision record's anchor.block): its window is read first */
+    decisionBlock?: number;
+};
+/**
+ * Recompute a receipt (or take a bare answers digest), then find its rows on one chain. Every chain but the devnet is
+ * read through JevAnswerLog.recordedAt (trusted records only) and the decision row in windows around it, because public
+ * endpoints refuse wide log ranges; the devnet is read in one range. The chain is read through warmbed's rotation, then
+ * the registry's static list; `rpc` overrides both.
+ */
+export declare function verify(x: Receipt | string, opts?: VerifyOptions): Promise<Verification>;

package/dist/verify.js

@@ -1,7 +1,9 @@
 // verify(): recompute every digest a receipt carries, re-compose its verdict from its own answers, then find the chain
 // events that hold those digests. Given a bare answers digest, it finds the JevAnswered log for it.
 import { decode } from './abi.js';
-import { CONTRACTS } from './contracts.js';
+import { chainIdOf, chainName, DEVNET, jevLogsOn } from './chains.js';
+import { JevChainError } from './errors.js';
+import { rangeCapOf, rpcCall, rpcRotation } from './rpc.js';
 import { keccakHex, sha256Hex } from './hash.js';
 import { answersDigestOf, confidenceBpsOf, decisionAnswersOf, decisionDigest, subjectIdOf } from './records.js';
 import { defineRubric, receiptBody, receiptHashOf, RUBRIC_v1 } from './rubric.js';
@@ -10,34 +12,23 @@ const TOPIC_DECIDED = keccakHex('Decided(bytes32,bytes32,address,uint256,bytes32
 const ANSWERED_DATA = ['address', 'bytes32', 'bytes32', 'string', 'string', 'uint256', 'bool'];
 const DECIDED_DATA = ['uint256', 'bytes32', 'uint16', 'string', 'string'];
 const hexN = (n) => '0x' + n.toString(16);
-async function rpcCall(rpc, f, method, params) {
-    const r = await f(rpc, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }), signal: AbortSignal.timeout(30_000) });
-    const j = (await r.json());
-    if (j.error)
-        throw new Error(`${method}: ${j.error.message}`);
-    return j.result;
-}
-async function logs(rpc, f, address, topics, fromBlock, toBlock) {
-    return (await rpcCall(rpc, f, 'eth_getLogs', [{ address, topics, fromBlock: hexN(fromBlock), toBlock: toBlock == null ? 'latest' : hexN(toBlock) }])) ?? [];
+async function logs(rpc, f, address, topics, fromBlock, toBlock, chainId) {
+    return (await rpcCall(rpc, f, 'eth_getLogs', [{ address, topics, fromBlock: hexN(fromBlock), toBlock: toBlock == null ? 'latest' : hexN(toBlock) }], { chainId })) ?? [];
 }
 const SEL_RECORDED_AT = keccakHex('recordedAt(bytes32)').slice(0, 10);
 /** JevAnswerLog.recordedAt(digest): the block of the first trusted record, 0 when none. */
-async function recordedAt(rpc, f, address, digest) {
-    const out = await rpcCall(rpc, f, 'eth_call', [{ to: address, data: SEL_RECORDED_AT + digest.slice(2) }, 'latest']);
+async function recordedAt(rpc, f, address, digest, chainId) {
+    const out = await rpcCall(rpc, f, 'eth_call', [{ to: address, data: SEL_RECORDED_AT + digest.slice(2) }, 'latest'], { chainId });
     return out && out !== '0x' ? Number(BigInt(out)) : 0;
 }
-/** The block cap an endpoint names when it refuses a range ("eth_getLogs is limited to a 500 range"), or null. */
-export function rangeCapOf(message) {
-    const m = /limited to (?:a )?(\d+)(?: block)? range/i.exec(message) ?? /range (?:is )?(?:limited|capped) (?:to|at) (\d+)/i.exec(message);
-    return m ? Number(m[1]) : null;
-}
+export { rangeCapOf };
 /**
  * eth_getLogs over [from, to], nearest to `center` first, in windows of at most `step` blocks (public Base endpoints
  * refuse wide ranges: mainnet.base.org caps a call at 500 blocks). A refusal that names a smaller cap shrinks the
  * window and retries. Stops at the first window where `hit` matches, so a record next to its answer costs one call.
  */
-export async function logsAround(rpc, f, address, topics, center, from, to, hit, step = 500) {
-    const head = Number(BigInt(await rpcCall(rpc, f, 'eth_blockNumber', [])));
+export async function logsAround(rpc, f, address, topics, center, from, to, hit, step = 500, chainId) {
+    const head = Number(BigInt(await rpcCall(rpc, f, 'eth_blockNumber', [], { chainId })));
     to = Math.min(to, head); // endpoints refuse a range past the head
     center = Math.min(Math.max(center, from), to);
     const out = [];
@@ -46,7 +37,7 @@ export async function logsAround(rpc, f, address, topics, center, from, to, hit,
             try {
                 const got = [];
                 for (let x = a; x <= b; x += step)
-                    got.push(...(await logs(rpc, f, address, topics, x, Math.min(b, x + step - 1))));
+                    got.push(...(await logs(rpc, f, address, topics, x, Math.min(b, x + step - 1), chainId)));
                 return got;
             }
             catch (e) {
@@ -79,20 +70,18 @@ export async function logsAround(rpc, f, address, topics, center, from, to, hit,
 const answerEvent = (l) => { const [recorder, inputDigest, decisionDigest, model, uri, , trusted] = decode(ANSWERED_DATA, l.data); return { tx: l.transactionHash, block: parseInt(l.blockNumber, 16), recorder: String(recorder), trusted: Boolean(trusted), subject: l.topics[2], inputDigest: inputDigest, decisionDigest: decisionDigest, model: String(model), uri: String(uri) }; };
 const decisionEvent = (l) => { const [index, digest, bps, model, uri] = decode(DECIDED_DATA, l.data); return { tx: l.transactionHash, block: parseInt(l.blockNumber, 16), recorder: `0x${String(l.topics[3]).slice(26)}`, index: Number(index), digest: digest, confidenceBps: Number(bps), model: String(model), uri: String(uri) }; };
 /**
- * `network`: 'devnet' (default, chain 36927) or 'base' (8453). On Base the answer row is found through
- * JevAnswerLog.recordedAt (trusted records only) and the decision row in a window around it, because public Base
- * endpoints refuse wide log ranges.
+ * Recompute a receipt (or take a bare answers digest), then find its rows on one chain. Every chain but the devnet is
+ * read through JevAnswerLog.recordedAt (trusted records only) and the decision row in windows around it, because public
+ * endpoints refuse wide log ranges; the devnet is read in one range. The chain is read through warmbed's rotation, then
+ * the registry's static list; `rpc` overrides both.
  */
 export async function verify(x, opts = {}) {
-    const network = opts.network ?? 'devnet';
+    const chainId = chainIdOf(opts.network ?? 'devnet');
     const f = opts.fetch ?? fetch;
-    const rpc = opts.rpc ?? CONTRACTS[network].rpc;
-    const dev = network === 'base'
-        ? { chainId: CONTRACTS.base.chainId, answerLog: CONTRACTS.base.answerLog, decisionLog: CONTRACTS.base.decisionLog }
-        : { chainId: CONTRACTS.devnet.chainId, answerLog: CONTRACTS.devnet.answerLog, decisionLog: CONTRACTS.devnet.decisionLog };
+    const dev = { chainId, ...(jevLogsOn(chainId) ?? { answerLog: null, decisionLog: null }) };
     const checks = {};
     const problems = [];
-    const onChain = { chainId: dev.chainId, answers: [], decisions: [] };
+    const onChain = { chainId: dev.chainId, answers: [], decisions: [], status: 'skipped' };
     let answersDigest;
     let subjectId = null;
     let decision = null;
@@ -125,32 +114,46 @@ export async function verify(x, opts = {}) {
         decision = x.decision?.digest ?? null;
     }
     if (opts.chain !== false && answersDigest) {
-        try {
-            if (!dev.answerLog || !dev.decisionLog)
-                throw new Error(`this package version carries no ${network} address for the logs`);
-            if (network === 'base') {
-                const at = await recordedAt(rpc, f, dev.answerLog.address, answersDigest);
-                if (at > 0)
-                    onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], at, at)).map(answerEvent);
-            }
-            else
-                onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], dev.answerLog.fromBlock)).map(answerEvent);
-            // a bare digest: the answer row names its subject and decision, so the decision row can be found too
-            const first = onChain.answers[0];
-            if (!subjectId && first && !/^0x0{64}$/.test(first.decisionDigest)) {
-                subjectId = first.subject;
-                decision = first.decisionDigest;
+        const where = chainName(chainId);
+        if (!dev.answerLog || !dev.decisionLog) {
+            onChain.status = 'not_deployed';
+            problems.push(`no Jev log is deployed on ${where}`);
+        }
+        else {
+            try {
+                // an explicit rpc (one URL, a comma list or a list) wins; otherwise warmbed's rotation, then the static fallback
+                const given = typeof opts.rpc === 'string' ? opts.rpc.split(',').map((u) => u.trim()).filter(Boolean) : opts.rpc;
+                const rpc = given?.length ? given : await rpcRotation(chainId, f);
+                if (chainId !== DEVNET) {
+                    const at = await recordedAt(rpc, f, dev.answerLog.address, answersDigest, chainId);
+                    if (at > 0)
+                        onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], at, at, chainId)).map(answerEvent);
+                }
+                else
+                    onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], dev.answerLog.fromBlock, undefined, chainId)).map(answerEvent);
+                // a bare digest: the answer row names its subject and decision, so the decision row can be found too
+                const first = onChain.answers[0];
+                if (!subjectId && first && !/^0x0{64}$/.test(first.decisionDigest)) {
+                    subjectId = first.subject;
+                    decision = first.decisionDigest;
+                }
+                if (subjectId && decision) {
+                    const center = opts.decisionBlock ?? first?.block;
+                    const found = chainId !== DEVNET && center
+                        ? await logsAround(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], center, Math.max(dev.decisionLog.fromBlock, center - 4000), center + 4000, (l) => decisionEvent(l).digest.toLowerCase() === decision.toLowerCase(), 500, chainId)
+                        : await logs(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], dev.decisionLog.fromBlock, undefined, chainId);
+                    onChain.decisions = found.map(decisionEvent).filter((d) => d.digest.toLowerCase() === decision.toLowerCase());
+                }
+                onChain.status = onChain.answers.length ? 'recorded' : 'not_recorded';
+                if (!onChain.answers.length)
+                    problems.push(`not recorded on ${where}`);
             }
-            if (subjectId && decision) {
-                const found = network === 'base' && first
-                    ? await logsAround(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], first.block, Math.max(dev.decisionLog.fromBlock, first.block - 4000), first.block + 4000, (l) => decisionEvent(l).digest.toLowerCase() === decision.toLowerCase())
-                    : await logs(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], dev.decisionLog.fromBlock);
-                onChain.decisions = found.map(decisionEvent).filter((d) => d.digest.toLowerCase() === decision.toLowerCase());
+            catch (e) {
+                const unavailable = !(e instanceof JevChainError) || e.code === 'rpc_unavailable';
+                onChain.status = unavailable ? 'rpc_unavailable' : onChain.answers.length ? 'recorded' : 'not_recorded';
+                problems.push(`${unavailable ? `RPC unavailable on ${where}` : `chain read failed on ${where}`}: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
-        catch (e) {
-            problems.push(`chain read failed: ${e instanceof Error ? e.message : String(e)}`);
-        }
         checks.answersOnChain = onChain.answers.length > 0;
         if (decision)
             checks.decisionOnChain = onChain.decisions.length > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "Grade AI agent jobs with TypeSafe's Jev and record the verdict on chain: code checks the facts, Jev answers a published rubric, and you get a receipt, the on-chain record and the evaluator call for ERC-8183 and Virtuals ACP. No runtime dependencies, no key inside.",
   "keywords": [
     "jev",