@taifoon/jev 0.2.15 → 0.2.17

package/README.md

@@ -6,13 +6,13 @@
   delivery, and code turns the answers into complete, reject or needs review, with a receipt anyone can recompute.
 - **Why:** agents are paid on chain for work nobody reads. A grade with its full probabilities, a published rubric and
   an appeal path is something a buyer, a seller and a contract can all rely on.
-- **How:** replay a real Base job, graded by Jev, offline and with no key:
+- **How:** replay a Base job, graded by Jev, offline and with no key:
 
 ```
 npx @taifoon/jev run --demo
 ```
 
-![npx @taifoon/jev run --demo: a real BitAgent job on Base, graded by Jev, checked against the chain](https://raw.githubusercontent.com/taifoon-io/jev/main/docs/demo.gif)
+![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
 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.
@@ -54,11 +54,11 @@ 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 real Base job below and checks it against the chain
+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)
 ```
 
-## A real job, graded
+## A Base job, graded
 
 [BitAgent](https://basescan.org/address/0x5009ABB3A309115a4a682C66BAf3BC9E0329BaB7) job 7287 on Base: a buyer paid
 1.5 USDC for `equity_research where ticker is 'AAPL'`. The seller submitted within seconds, but only a 32-byte digest
@@ -109,7 +109,7 @@ Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or
 
 | Flag | Default | What it does |
 |---|---|---|
-| `--demo` | off | Replays the real Base job above, offline, no key |
+| `--demo` | off | Replays the Base job above, offline, no key |
 | `--job <chain>:<id>` | first ready job in the layer's queue | Grade one live job, e.g. `8453:bitagent:8453:7287` |
 | `--job-file job.json` | | Grade a job you describe (see `examples/jobs/`) |
 | `--evidence pack.json` | | Grade your own evidence pack, no layer |
@@ -146,7 +146,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
@@ -162,7 +162,7 @@ Each is tested against calldata a mined transaction carried.
 - [Selling through Taifoon: readiness, the signed enrich route, A2A and x402 shapes, a first graded job, Monad](docs/SELLERS.md)
 - [API: the six calls, where Jev is reached, your own rubric](docs/API.md)
 - [Evaluator seats, with the transactions they are tested against](docs/EVALUATORS.md)
-- [On chain: contract addresses on Base and devnet, and one real grade end to end](docs/ON_CHAIN.md)
+- [On chain: contract addresses on Base and devnet, and one grade end to end](docs/ON_CHAIN.md)
 - [The records: receipt, decision.v2, jev.answer.v1](docs/RECORDS.md)
 - [n8n workflows, and the TypeSafe node's Jev Options](docs/WORKFLOWS.md)
 - [Develop](docs/DEVELOP.md)
@@ -173,6 +173,40 @@ 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.

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/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/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/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/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/docs/ON_CHAIN.md

@@ -19,7 +19,7 @@ On Base (8453), since 0.2.0:
 `npx @taifoon/jev verify <digest> --network base` read them (the CLI's default `any` tries the devnet, then Base).
 0.1.0 carried no Base addresses. An earlier Base answer log, `0x5bac70eb78224bbCBa83f5A36DF09D549d3f57fa`, is superseded and holds no records.
 
-Here is one real grade, end to end: n8n execution 86, a proof-verification job graded with RUBRIC_v1.
+Here is one grade, end to end: n8n execution 86, a proof-verification job graded with RUBRIC_v1.
 
 - Answers recorded in devnet tx
   [`0x9a38cf55…a61b`](https://www.taifoon.io/scan/36927/tx/0x9a38cf5541bb82a8a6e2e5cf1a96ed25fdc46921c351506da83023f5dec1a61b).
@@ -29,7 +29,7 @@ Here is one real grade, end to end: n8n execution 86, a proof-verification job g
   Decision digest `0x781b0fce…3667`, confidence 2,700 bps.
 - Jev answered spec_met `{ yes: 0.36, no: 0.64 }`, so the composed verdict is **reject** (spec_met ≤ 0.40).
 
-`verify('0x6c7e6d29…f52d')` finds both rows. This is the real output:
+`verify('0x6c7e6d29…f52d')` finds both rows. This is its output:
 
 ```
 {"ok":true,"checks":{"answersOnChain":true,"decisionOnChain":true},

package/docs/PIPELINE.md

@@ -71,6 +71,6 @@ Steps 1 to 4 are required: saying no at one stops the run. Keys come from the en
 TypeSafe key; without it the Jev step stops and says where to get one) and `TAIFOON_RELAYER_KEY`, and are never printed. Nothing is signed. In code it is `pipeline()`,
 with a `before` gate and an `after` hook per step.
 
-Real run (2026-09-27): BitAgent job 7287 on Base asked for "equity_research where ticker is 'AAPL'" and
+A run (2026-09-27): BitAgent job 7287 on Base asked for "equity_research where ticker is 'AAPL'" and
 got a 32-byte digest. Facts passed (delivered, before the deadline, 1.5 USDC). Jev answered spec_met 0.03, so the
 verdict is **reject**; the receipt re-derives; the seller's quote is 0.0%–39.0% (6 settled, thin record).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "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",