@taifoon/jev 0.2.18 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ npx @taifoon/jev run --demo
 
 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.
+installs Taifoon's other packages (@taifoon/jev-wilson, @taifoon/n8n-nodes-typesafe). No key inside, and it signs nothing. Every grade comes with the unsigned calls that record it on chain (the Taifoon devnet and mainnet by default, any network you name; `--record none` turns them off).
 
 ## Quick start
 
@@ -106,7 +106,7 @@ the output says how to retry. Set `record` to `none` to grade without writing on
 
 ## `jev run` flags
 
-Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or sent. A typo is refused, never guessed.
+Safe by default: nothing is signed or sent. The calls that record and stamp the grade come back unsigned (`--record none` turns them off). A typo is refused, never guessed.
 
 | Flag | Default | What it does |
 |---|---|---|
@@ -115,7 +115,7 @@ Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or
 | `--job-file job.json` | | Grade a job you describe (see `examples/jobs/`) |
 | `--evidence pack.json` | | Grade your own evidence pack, no layer |
 | `--answers answers.json` | | Answers you already have (e.g. from the n8n node); Jev is not asked |
-| `--record none\|devnet\|base\|both` | `none` | Opt in to the unsigned calls that record the grade on chain |
+| `--record none\|devnet\|base\|both` | Taifoon devnet + mainnet | Where the unsigned calls that record and stamp the grade point; `none` turns them off |
 | `--layer <https url>` / `--no-layer` | `https://coord.taifoon.dev` | Where jobs and quotes are read |
 | `--protocol <name>` | from the job id | Evaluator seat: `virtuals-erc8183`, `virtuals-memo-acp`, `bitagent-erc8183`, `assurance-hook`, `judge-adapter` |
 | `--price-usdc <n>` | the job's budget | Price for the premium quote |

package/bin/run.mjs

@@ -6,7 +6,8 @@
 //   jev run --demo                       offline, no key: replays a REAL graded job (BitAgent 7287 on Base) with Jev's
 //                                        recorded answers, and checks the result against the decision on chain
 //   jev run --answers answers.json       answers you already have (the n8n TypeSafe node's output): Jev is not asked
-//   --record none|devnet|base|both       opt-in: where the grade is recorded (default none: the receipt and digests only);
+//   --record none|devnet|base|both       where the grade is recorded (default: unsigned calls for the Taifoon devnet and
+//                                        mainnet; none = the receipt and digests only);
 //                                        --network is the same flag
 //   --layer <url> | --no-layer           the coordination layer (default https://coord.taifoon.dev)
 //   --yes                                run every step without asking;  --json  print the whole trace as JSON at the end
@@ -27,7 +28,7 @@ function factOf(r) {
     case 'evidence': return `${o.facts} labelled facts · ${o.gaps?.length ?? 0} gaps · ${o.state_chars} characters for Jev to read`;
     case 'facts': return `delivered ${o.delivered ? 'yes' : 'no'} · checks ${o.checksOk === false ? 'failed' : o.checksOk ? 'ok' : 'none'}${o.priceUsdc != null ? ` · ${o.priceUsdc} USDC` : ''}`;
     case 'grade': return `${o.verdict} · ${o.reasons?.[0] ?? ''}${o.model ? ` · ${o.model}` : ''}`;
-    case 'record': return `${o.status === 'none' ? 'not recorded (opt in with --record)' : `${o.status} · ${(o.calls ?? []).join(', ')}`}${o.recording?.held ? ` · layer held it: ${o.recording.held}` : ''}${typeof o.layer === 'object' && o.layer ? ` · layer ${short(o.layer.digest)}` : ''}`;
+    case 'record': return `${o.status === 'none' ? 'not recorded (--record none)' : `${o.status} · ${(o.calls ?? []).join(', ')}`}${o.recording?.held ? ` · layer held it: ${o.recording.held}` : ''}${typeof o.layer === 'object' && o.layer ? ` · layer ${short(o.layer.digest)}` : ''}`;
     case 'evaluator': return `${o.fn} on ${o.protocol} · signed by ${o.signer}`;
     case 'premium': return `${o.guaranteed ? 'guaranteed' : 'not guaranteed'} · premium ${o.premium_label ?? o.premium_ratio}`;
     case 'verify': return o.ok ? `the receipt re-derives · ${Object.keys(o.checks ?? {}).length} checks` : `problems: ${(o.problems ?? []).join('; ')}`;
@@ -55,10 +56,10 @@ export async function run(argv) {
   const jobFile = file('--job-file');
   const ansFile = file('--answers');
   const rec = demo ? JSON.parse(readFileSync(new URL('../examples/jobs/base-bitagent-7287.recorded.json', import.meta.url), 'utf8')) : null;
-  const network = val('--record') ?? val('--network') ?? 'none'; const layer = noLayer ? false : val('--layer');
+  const network = val('--record') ?? val('--network') ?? undefined; const layer = noLayer ? false : val('--layer');
   const protocol = val('--protocol'); const price = val('--price-usdc'); const sellerRec = val('--seller-record');
   if (a.length) refuse(`unknown flag ${a[0]}`);
-  if (!['none', 'devnet', 'base', 'both'].includes(network)) refuse(`--record is none, devnet, base or both (got ${network})`);
+  if (network !== undefined && !['none', 'devnet', 'base', 'both'].includes(network)) refuse(`--record is none, devnet, base or both (got ${network})`);
   if (demo && (job || evFile || jobFile || ansFile)) refuse('--demo replays one recorded job: drop --job, --job-file, --evidence and --answers');
   if ([job, evFile, jobFile].filter(Boolean).length > 1) refuse('pick one source: --job, --job-file or --evidence');
   if (job && !/^\d+:.+$/.test(job) && !/^\S+$/.test(job)) refuse(`--job is <chain>:<id>, e.g. 8453:bitagent:8453:7287 (got ${job})`);
@@ -71,7 +72,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' : 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' : ''}`);
+  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 === undefined ? 'Taifoon devnet + mainnet (unsigned calls; --record none turns it off)' : 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/attest.d.ts

@@ -0,0 +1,129 @@
+/**
+ * attest: the attested mark, the on-chain attestation and the stamp of one step (a grade, an assurance settle, a resale
+ * step), as UNSIGNED calls aimed at a default network chosen by profile. _ATTEST_BY_DEFAULT_v1_
+ *
+ * ONE file with NO imports, pure and browser-safe, like assurance.ts: @taifoon/jev, @taifoon/assurance (and through its
+ * sync, taifoon-sdk and moonbeam-sdk) carry a byte-identical copy and pin its hash. The addresses come from the address
+ * registry (packages/addresses) through scripts/gen-attest.mjs; nothing below the generated block names an address.
+ *
+ *   mark          what is attested, offline: the step's kind, the subject ids (decision log + stamp registry) and the
+ *                 digest = keccak256 of the canonical JSON body (or the digest the caller already has, e.g. Jev's).
+ *   attestation   JevDecisionLog.record(subject, kind, digest, confidenceBps, model, uri) on every target network, after
+ *                 JevAnswerLog.record(...) when the step carries Jev's answers.
+ *   stamp         GradeStampRegistry.stamp(subject, digest, verdict, mode, model, uri) when the step has a verdict.
+ *
+ * Recording is ON by default (the owner's rule of 2026-10-14): profile taifoon → the Taifoon devnet 36927 and the Taifoon
+ * mainnet 3692781 (GRID); profile moonbeam → Base 8453. Any network can be named instead; `networks: 'none'` opts out
+ * (the mark is still returned). A contract the registry does not have on a target network is listed in `missing`, with
+ * no call: nothing is faked. Nothing here signs or sends; the caller signs the calls.
+ */
+/** The attestation contracts on every chain the address registry has one on (superseded deploys left out). */
+export declare const ATTEST_TARGETS: Readonly<Record<number, {
+    name: string;
+    decisionLog: string | null;
+    answerLog: string | null;
+    stampRegistry: string | null;
+}>>;
+/** The default networks per profile. Taifoon: its devnet and its mainnet (GRID). Moonbeam: Base only. */
+export declare const ATTEST_PROFILES: {
+    readonly taifoon: readonly [36927, 3692781];
+    readonly moonbeam: readonly [8453];
+};
+export type AttestProfile = keyof typeof ATTEST_PROFILES;
+export type AttestHex = `0x${string}`;
+export type AttestCall = {
+    chainId: number;
+    to: string;
+    data: AttestHex;
+    value: '0';
+    fn: 'JevDecisionLog.record' | 'JevAnswerLog.record' | 'GradeStampRegistry.stamp';
+};
+export type AttestMissing = {
+    chainId: number;
+    network: string;
+    contract: 'JevDecisionLog' | 'JevAnswerLog' | 'GradeStampRegistry';
+    why: string;
+};
+/** the REF verdict vocabulary of GradeStampRegistry: 1 delivered as specified · 2 with defects · 3 not delivered · 4 cannot determine */
+export type StampVerdict = 1 | 2 | 3 | 4;
+export type AttestInput = {
+    /** the step: 'grade', 'assurance.settle', 'resale.<hop>' … (the decision log's kind is keccak256 of it) */
+    kind: string;
+    /** the job the step is about, on its own chain and contract */
+    subject: {
+        chainId: number;
+        contract: string;
+        jobId: string | number | bigint;
+    };
+    /** the canonical body of the step; its keccak256 is the digest unless `digest` is given */
+    body?: unknown | undefined;
+    digest?: AttestHex | undefined;
+    /** 0..10000; default 10000 (a deterministic step) */
+    confidenceBps?: number | undefined;
+    /** ≤ 64 bytes, e.g. 'jev-1.13.0' or 'det:assurance-settle-v1' */
+    model: string;
+    /** ≤ 512 bytes; default urn:taifoon:<kind>:<digest> */
+    uri?: string | undefined;
+    /** a stamp is built when there is a verdict; mode 1 deterministic (default) · 2 calibrated */
+    verdict?: StampVerdict | null | undefined;
+    mode?: 1 | 2 | undefined;
+    /** Jev's answer record digests: adds JevAnswerLog.record */
+    answers?: {
+        useCase: string;
+        inputDigest: AttestHex;
+        answersDigest: AttestHex;
+        uri?: string | undefined;
+    } | undefined;
+};
+export type AttestOptions = {
+    /** picks the default networks; default 'taifoon' */
+    profile?: AttestProfile | undefined;
+    /** overrides the profile: chain ids, or 'none' to opt out of recording (the mark is still returned) */
+    networks?: readonly number[] | 'none' | undefined;
+    /** extra or replacement contracts per chain (e.g. a fork's deploy, or a network the registry does not list) */
+    targets?: Readonly<Record<number, Partial<{
+        name: string;
+        decisionLog: string | null;
+        answerLog: string | null;
+        stampRegistry: string | null;
+    }>>> | undefined;
+};
+export type Attested = {
+    mark: {
+        kind: string;
+        kindId: AttestHex;
+        subject: AttestHex;
+        stampSubject: AttestHex;
+        digest: AttestHex;
+        confidenceBps: number;
+        verdict: StampVerdict | null;
+        model: string;
+        uri: string;
+    };
+    /** false only when the caller opted out */
+    recorded: boolean;
+    networks: number[];
+    calls: AttestCall[];
+    missing: AttestMissing[];
+    /** ready: every target contract exists · partial: some are missing · missing: none exist · none: opted out */
+    status: 'ready' | 'partial' | 'missing' | 'none';
+};
+export declare function attestKeccak(input: Uint8Array | string): AttestHex;
+export declare const DECISION_LOG_RECORD_SIG = "record(bytes32,bytes32,bytes32,uint16,string,string)";
+export declare const ANSWER_LOG_RECORD_SIG = "record(bytes32,bytes32,bytes32,bytes32,bytes32,string,string)";
+export declare const STAMP_SIG = "stamp(bytes32,bytes32,uint8,uint8,string,string)";
+/** canonical JSON: sorted keys, bigint as a decimal string, no whitespace (the digest's preimage) */
+export declare function attestCanonical(v: unknown): string;
+/** JevDecisionLog.subjectOf(chainId, at, ref) = keccak256(abi.encode("taifoon.decision.subject.v1", chainId, at, ref)) */
+export declare const decisionSubjectOf: (chainId: number, at: string, ref: string | number | bigint) => AttestHex;
+/** GradeStampRegistry.subjectOf(chainId, jobContract, jobId) = keccak256(abi.encode("taifoon.stamp.subject.v1", …)) */
+export declare const stampSubjectOf: (chainId: number, jobContract: string, jobId: string | number | bigint) => AttestHex;
+/** the stamp verdict of a settled ending, from the seller-record verdict the machine writes (endingOf): correct → 1;
+ *  a Jev case (rejected or expired after delivery) → 4, it takes a grade to say more; incorrect → 3; excluded → no stamp */
+export declare function stampVerdictOfEnding(e: {
+    verdict: string;
+    jevCase: boolean;
+    excluded: string | null;
+}): StampVerdict | null;
+/** the mark, the attestation calls and the stamp call of one step, on the profile's networks (or the ones named) */
+export declare function attest(input: AttestInput, opts?: AttestOptions): Attested;

package/dist/attest.js

@@ -0,0 +1,223 @@
+/**
+ * attest: the attested mark, the on-chain attestation and the stamp of one step (a grade, an assurance settle, a resale
+ * step), as UNSIGNED calls aimed at a default network chosen by profile. _ATTEST_BY_DEFAULT_v1_
+ *
+ * ONE file with NO imports, pure and browser-safe, like assurance.ts: @taifoon/jev, @taifoon/assurance (and through its
+ * sync, taifoon-sdk and moonbeam-sdk) carry a byte-identical copy and pin its hash. The addresses come from the address
+ * registry (packages/addresses) through scripts/gen-attest.mjs; nothing below the generated block names an address.
+ *
+ *   mark          what is attested, offline: the step's kind, the subject ids (decision log + stamp registry) and the
+ *                 digest = keccak256 of the canonical JSON body (or the digest the caller already has, e.g. Jev's).
+ *   attestation   JevDecisionLog.record(subject, kind, digest, confidenceBps, model, uri) on every target network, after
+ *                 JevAnswerLog.record(...) when the step carries Jev's answers.
+ *   stamp         GradeStampRegistry.stamp(subject, digest, verdict, mode, model, uri) when the step has a verdict.
+ *
+ * Recording is ON by default (the owner's rule of 2026-10-14): profile taifoon → the Taifoon devnet 36927 and the Taifoon
+ * mainnet 3692781 (GRID); profile moonbeam → Base 8453. Any network can be named instead; `networks: 'none'` opts out
+ * (the mark is still returned). A contract the registry does not have on a target network is listed in `missing`, with
+ * no call: nothing is faked. Nothing here signs or sends; the caller signs the calls.
+ */
+// ── GENERATED from packages/addresses/addresses.json by scripts/gen-attest.mjs: do not edit ──
+/** The attestation contracts on every chain the address registry has one on (superseded deploys left out). */
+export const ATTEST_TARGETS = {
+    143: { name: 'Monad', decisionLog: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', answerLog: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', stampRegistry: null },
+    5042: { name: 'Arc', decisionLog: '0x863db7dAc69CC614a98822082cbe884F1f3b55cA', answerLog: '0x45214361A8cADb8aEe6302cd5653E119E5a89839', stampRegistry: null },
+    8453: { name: 'Base', decisionLog: '0x209490d6A0FFC5368A42b0c2208BDCda853f6a92', answerLog: '0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d', stampRegistry: null },
+    36927: { name: 'Taifoon devnet', decisionLog: '0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05', answerLog: '0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3', stampRegistry: '0xff5B4852AC7066D04FEd8de97bdA52401d03ad6E' },
+    42161: { name: 'Arbitrum One', decisionLog: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', answerLog: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', stampRegistry: null },
+    3692781: { name: 'Taifoon mainnet', decisionLog: null, answerLog: null, stampRegistry: null },
+};
+// ── END GENERATED ──
+/** The default networks per profile. Taifoon: its devnet and its mainnet (GRID). Moonbeam: Base only. */
+export const ATTEST_PROFILES = { taifoon: [36927, 3692781], moonbeam: [8453] };
+// ── keccak256 (the same code as packages/addresses/keccak.mjs; test/attest.test.ts checks known vectors) ──
+const KM = (1n << 64n) - 1n;
+const KRC = [
+    0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an, 0x8000000080008000n, 0x000000000000808bn, 0x0000000080000001n,
+    0x8000000080008081n, 0x8000000000008009n, 0x000000000000008an, 0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
+    0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n, 0x8000000000008002n, 0x8000000000000080n,
+    0x000000000000800an, 0x800000008000000an, 0x8000000080008081n, 0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n,
+];
+const KR = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14];
+const krot = (v, n) => (n === 0 ? v : ((v << BigInt(n)) | (v >> BigInt(64 - n))) & KM);
+function kf(A) {
+    const C = [0n, 0n, 0n, 0n, 0n];
+    const B = new Array(25).fill(0n);
+    const at = (a, i) => a[i];
+    for (let round = 0; round < 24; round++) {
+        for (let x = 0; x < 5; x++)
+            C[x] = at(A, x) ^ at(A, x + 5) ^ at(A, x + 10) ^ at(A, x + 15) ^ at(A, x + 20);
+        for (let x = 0; x < 5; x++) {
+            const d = at(C, (x + 4) % 5) ^ krot(at(C, (x + 1) % 5), 1);
+            for (let y = 0; y < 25; y += 5)
+                A[x + y] = at(A, x + y) ^ d;
+        }
+        for (let x = 0; x < 5; x++)
+            for (let y = 0; y < 5; y++)
+                B[y + 5 * ((2 * x + 3 * y) % 5)] = krot(at(A, x + 5 * y), KR[x + 5 * y]);
+        for (let x = 0; x < 5; x++)
+            for (let y = 0; y < 5; y++)
+                A[x + 5 * y] = at(B, x + 5 * y) ^ (~at(B, (x + 1) % 5 + 5 * y) & KM & at(B, (x + 2) % 5 + 5 * y));
+        A[0] = at(A, 0) ^ KRC[round];
+    }
+}
+/** UTF-8 bytes of a string (no TextEncoder: the file runs where no DOM or Node lib is typed) */
+function utf8(s) {
+    const out = [];
+    for (const ch of s) {
+        const c = ch.codePointAt(0);
+        if (c < 0x80)
+            out.push(c);
+        else if (c < 0x800)
+            out.push(0xc0 | (c >> 6), 0x80 | (c & 63));
+        else if (c < 0x10000)
+            out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+        else
+            out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 63), 0x80 | ((c >> 6) & 63), 0x80 | (c & 63));
+    }
+    return Uint8Array.from(out);
+}
+export function attestKeccak(input) {
+    const bytes = typeof input === 'string' ? utf8(input) : input;
+    const rate = 136;
+    const A = new Array(25).fill(0n);
+    const padded = new Uint8Array(Math.ceil((bytes.length + 1) / rate) * rate);
+    padded.set(bytes);
+    padded[bytes.length] = padded[bytes.length] ^ 0x01;
+    padded[padded.length - 1] = padded[padded.length - 1] ^ 0x80;
+    for (let off = 0; off < padded.length; off += rate) {
+        for (let i = 0; i < rate / 8; i++) {
+            let w = 0n;
+            for (let b = 7; b >= 0; b--)
+                w = (w << 8n) | BigInt(padded[off + i * 8 + b]);
+            A[i] = A[i] ^ w;
+        }
+        kf(A);
+    }
+    let out = '0x';
+    for (let i = 0; i < 4; i++)
+        for (let b = 0; b < 8; b++)
+            out += Number((A[i] >> BigInt(8 * b)) & 0xffn).toString(16).padStart(2, '0');
+    return out;
+}
+// ── ABI encoding (only the types these three calls use) ──
+const hexOf = (b) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+const bytesOf = (h) => { const s = h.replace(/^0x/, ''); const o = new Uint8Array(s.length / 2); for (let i = 0; i < o.length; i++)
+    o[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16); return o; };
+const word = (n) => { if (n < 0n || n >= 1n << 256n)
+    throw new Error(`attest: ${n} does not fit a uint256`); return n.toString(16).padStart(64, '0'); };
+const isHex32 = (v) => /^0x[0-9a-fA-F]{64}$/.test(v);
+const isAddr = (v) => /^0x[0-9a-fA-F]{40}$/.test(v);
+function encodeArgs(args) {
+    let head = '';
+    let tail = '';
+    const headLen = args.length * 32;
+    for (const a of args) {
+        if (a.t === 'string') {
+            const b = utf8(String(a.v));
+            head += word(BigInt(headLen + tail.length / 2));
+            tail += word(BigInt(b.length)) + hexOf(b).padEnd(Math.ceil(b.length / 32) * 64, '0');
+        }
+        else if (a.t === 'bytes32') {
+            if (!isHex32(String(a.v)))
+                throw new Error(`attest: ${a.v} is not a bytes32`);
+            head += String(a.v).slice(2).toLowerCase();
+        }
+        else if (a.t === 'address') {
+            if (!isAddr(String(a.v)))
+                throw new Error(`attest: ${a.v} is not an address`);
+            head += String(a.v).slice(2).toLowerCase().padStart(64, '0');
+        }
+        else
+            head += word(BigInt(a.v));
+    }
+    return head + tail;
+}
+const selector = (sig) => attestKeccak(sig).slice(2, 10);
+const call = (sig, args) => `0x${selector(sig)}${encodeArgs(args)}`;
+export const DECISION_LOG_RECORD_SIG = 'record(bytes32,bytes32,bytes32,uint16,string,string)';
+export const ANSWER_LOG_RECORD_SIG = 'record(bytes32,bytes32,bytes32,bytes32,bytes32,string,string)';
+export const STAMP_SIG = 'stamp(bytes32,bytes32,uint8,uint8,string,string)';
+/** canonical JSON: sorted keys, bigint as a decimal string, no whitespace (the digest's preimage) */
+export function attestCanonical(v) {
+    if (typeof v === 'bigint')
+        return JSON.stringify(v.toString());
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v ?? null);
+    if (Array.isArray(v))
+        return `[${v.map(attestCanonical).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o).filter((k) => o[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${attestCanonical(o[k])}`).join(',')}}`;
+}
+const jobRef = (id) => (typeof id === 'string' && isHex32(id) ? id : `0x${word(BigInt(id))}`);
+/** JevDecisionLog.subjectOf(chainId, at, ref) = keccak256(abi.encode("taifoon.decision.subject.v1", chainId, at, ref)) */
+export const decisionSubjectOf = (chainId, at, ref) => attestKeccak(bytesOf(encodeArgs([{ t: 'string', v: 'taifoon.decision.subject.v1' }, { t: 'uint', v: chainId }, { t: 'address', v: at }, { t: 'bytes32', v: jobRef(ref) }])));
+/** GradeStampRegistry.subjectOf(chainId, jobContract, jobId) = keccak256(abi.encode("taifoon.stamp.subject.v1", …)) */
+export const stampSubjectOf = (chainId, jobContract, jobId) => attestKeccak(bytesOf(encodeArgs([{ t: 'string', v: 'taifoon.stamp.subject.v1' }, { t: 'uint', v: chainId }, { t: 'address', v: jobContract }, { t: 'bytes32', v: jobRef(jobId) }])));
+/** the stamp verdict of a settled ending, from the seller-record verdict the machine writes (endingOf): correct → 1;
+ *  a Jev case (rejected or expired after delivery) → 4, it takes a grade to say more; incorrect → 3; excluded → no stamp */
+export function stampVerdictOfEnding(e) {
+    if (e.excluded)
+        return null;
+    if (e.verdict === 'correct')
+        return 1;
+    if (e.jevCase || e.verdict === 'undecided')
+        return 4;
+    if (e.verdict === 'incorrect')
+        return 3;
+    return null;
+}
+/** the mark, the attestation calls and the stamp call of one step, on the profile's networks (or the ones named) */
+export function attest(input, opts = {}) {
+    const { subject } = input;
+    if (!isAddr(subject.contract))
+        throw new Error(`attest: subject.contract ${subject.contract} is not an address`);
+    if (!input.kind)
+        throw new Error('attest: a kind names the step');
+    const digest = input.digest ?? attestKeccak(attestCanonical(input.body ?? null));
+    if (!isHex32(digest) || /^0x0{64}$/.test(digest))
+        throw new Error('attest: the digest must be a non-zero bytes32');
+    const confidenceBps = input.confidenceBps ?? 10_000;
+    if (!Number.isInteger(confidenceBps) || confidenceBps < 0 || confidenceBps > 10_000)
+        throw new Error(`attest: confidenceBps ${confidenceBps} is not 0..10000`);
+    const model = input.model;
+    if (!model || utf8(model).length > 64)
+        throw new Error('attest: model is 1..64 bytes');
+    const uri = input.uri ?? `urn:taifoon:${input.kind}:${digest}`;
+    if (utf8(uri).length > 512)
+        throw new Error('attest: uri is ≤ 512 bytes');
+    const verdict = input.verdict ?? null;
+    const mode = input.mode ?? 1;
+    if (verdict !== null && ![1, 2, 3, 4].includes(verdict))
+        throw new Error(`attest: verdict ${verdict} is not 1..4`);
+    const kindId = attestKeccak(input.kind);
+    const mark = { kind: input.kind, kindId, subject: decisionSubjectOf(subject.chainId, subject.contract, subject.jobId), stampSubject: stampSubjectOf(subject.chainId, subject.contract, subject.jobId), digest, confidenceBps, verdict, model, uri };
+    if (opts.networks === 'none')
+        return { mark, recorded: false, networks: [], calls: [], missing: [], status: 'none' };
+    const networks = [...(opts.networks ?? ATTEST_PROFILES[opts.profile ?? 'taifoon'])];
+    const calls = [];
+    const missing = [];
+    for (const chainId of networks) {
+        const t = { name: `chain ${chainId}`, decisionLog: null, answerLog: null, stampRegistry: null, ...ATTEST_TARGETS[chainId], ...opts.targets?.[chainId] };
+        const gap = (contract) => missing.push({ chainId, network: t.name, contract, why: `no ${contract} on ${t.name} (${chainId}) in the address registry` });
+        // the answers first, then the decision that cites them (the order the layer's recorder sends)
+        if (input.answers) {
+            if (t.answerLog)
+                calls.push({ chainId, to: t.answerLog, value: '0', fn: 'JevAnswerLog.record', data: call(ANSWER_LOG_RECORD_SIG, [{ t: 'bytes32', v: attestKeccak(input.answers.useCase) }, { t: 'bytes32', v: mark.subject }, { t: 'bytes32', v: input.answers.inputDigest }, { t: 'bytes32', v: input.answers.answersDigest }, { t: 'bytes32', v: digest }, { t: 'string', v: model }, { t: 'string', v: input.answers.uri ?? uri }]) });
+            else
+                gap('JevAnswerLog');
+        }
+        if (t.decisionLog)
+            calls.push({ chainId, to: t.decisionLog, value: '0', fn: 'JevDecisionLog.record', data: call(DECISION_LOG_RECORD_SIG, [{ t: 'bytes32', v: mark.subject }, { t: 'bytes32', v: kindId }, { t: 'bytes32', v: digest }, { t: 'uint', v: confidenceBps }, { t: 'string', v: model }, { t: 'string', v: uri }]) });
+        else
+            gap('JevDecisionLog');
+        if (verdict !== null) {
+            if (t.stampRegistry)
+                calls.push({ chainId, to: t.stampRegistry, value: '0', fn: 'GradeStampRegistry.stamp', data: call(STAMP_SIG, [{ t: 'bytes32', v: mark.stampSubject }, { t: 'bytes32', v: digest }, { t: 'uint', v: verdict }, { t: 'uint', v: mode }, { t: 'string', v: model }, { t: 'string', v: uri }]) });
+            else
+                gap('GradeStampRegistry');
+        }
+    }
+    const status = missing.length === 0 ? 'ready' : calls.length === 0 ? 'missing' : 'partial';
+    return { mark, recorded: true, networks, calls, missing, status };
+}

package/dist/index.d.ts

@@ -17,7 +17,8 @@
 export { grade } from './grade.js';
 export { facts } from './facts.js';
 export { prepareJob, runCheck } from './job.js';
-export { record } from './record.js';
+export { record, STAMP_VERDICT_OF } from './record.js';
+export { attest, ATTEST_PROFILES, ATTEST_TARGETS, decisionSubjectOf, stampSubjectOf } from './attest.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
 export { JevChainError, type JevChainErrorCode } from './errors.js';
@@ -31,6 +32,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 { Attested, AttestInput, AttestOptions, AttestProfile, AttestMissing, AttestCall, StampVerdict } from './attest.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';

package/dist/index.js

@@ -17,7 +17,8 @@
 export { grade } from './grade.js';
 export { facts } from './facts.js';
 export { prepareJob, runCheck } from './job.js';
-export { record } from './record.js';
+export { record, STAMP_VERDICT_OF } from './record.js';
+export { attest, ATTEST_PROFILES, ATTEST_TARGETS, decisionSubjectOf, stampSubjectOf } from './attest.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
 export { JevChainError } from './errors.js';

package/dist/pipeline.d.ts

@@ -108,10 +108,12 @@ export type PipelineOpts = {
     answers?: Record<string, Answer> | Answer[];
     /** the model that produced supplied `answers` (e.g. "jev-1.13.0"); it is part of the decision digest */
     model?: string | null;
-    /** where record() points the calls; default devnet */
-    /** recording is opt-in: where record() points the calls and what the layer may record. Default none: the receipt and
-     *  its digests only (recomputable offline), no transaction. */
+    /** where record() points the calls and what the layer may record. Recording is ON by default (_ATTEST_BY_DEFAULT_v1_):
+     *  unsigned calls for the Taifoon devnet 36927 and the Taifoon mainnet 3692781 (a log a network lacks is listed as
+     *  missing); `none` turns it off (the receipt and its digests only, recomputable offline). */
     network?: Network;
+    /** any chain ids instead of `network` (e.g. [8453] for Base) */
+    networks?: readonly number[];
     /** X-API-Key for POST /v1/judge/answers/record; omitted: nothing is written to the layer */
     relayerKey?: string | null;
     /** the job's protocol for the evaluator call; omitted: guessed from the job id */

package/dist/pipeline.js

@@ -178,11 +178,11 @@ export async function pipeline(o = {}) {
     await step('record', async () => {
         if (!receipt.decision)
             return { skip: `nothing to record: ${receipt.reasons[0] ?? receipt.verdict} (the facts decided; Jev was not asked)` };
-        t.recorded = await record(receipt, { network: o.network ?? 'none' });
+        t.recorded = await record(receipt, { network: o.network, networks: o.networks });
         if (layer && o.relayerKey && receipt.answersRecord)
-            t.layerRecord = await getJson(f, `${layer}/v1/judge/answers/record`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': o.relayerKey }, body: JSON.stringify({ ...receipt.answersRecord, record: o.network ?? 'none' }) });
+            t.layerRecord = await getJson(f, `${layer}/v1/judge/answers/record`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': o.relayerKey }, body: JSON.stringify({ ...receipt.answersRecord, record: o.network ?? (o.networks ? (o.networks.includes(8453) ? (o.networks.includes(36927) ? 'both' : 'base') : o.networks.includes(36927) ? 'devnet' : 'none') : 'devnet') }) });
         const rec = t.layerRecord?.recording;
-        return { status: t.recorded.status, recording: rec ? { used: rec.used ?? null, held: rec.held?.message ?? null } : null, calls: t.recorded.calls.map((c) => `${c.fn}@${c.chainId}${c.to ? '' : ' (no address)'}`), digests: t.recorded.digests, layer: t.layerRecord ?? (layer ? 'not written: pass a relayer key to record on the layer' : 'independent mode') };
+        return { status: t.recorded.status, recording: rec ? { used: rec.used ?? null, held: rec.held?.message ?? null } : null, calls: t.recorded.calls.map((c) => `${c.fn}@${c.chainId}`), missing: t.recorded.missing.map((m) => `${m.contract}@${m.chainId}`), digests: t.recorded.digests, layer: t.layerRecord ?? (layer ? 'not written: pass a relayer key to record on the layer' : 'independent mode') };
     });
     await step('evaluator', async () => {
         if (receipt.verdict === 'needs_review')

package/dist/record.d.ts

@@ -1,5 +1,7 @@
-import { type Hex } from './hash.js';
+import { type AttestMissing, type AttestProfile, type StampVerdict } from './attest.js';
+import type { Hex } from './hash.js';
 import type { Receipt } from './receipt.js';
+import type { Verdict } from './rubric.js';
 export type Network = 'none' | 'devnet' | 'base' | 'both';
 export type UnsignedCall = {
     chainId: number;
@@ -9,24 +11,35 @@ export type UnsignedCall = {
     fn: string;
 };
 export type Recorded = {
-    network: Network;
-    /** ready: every call has an address · partial: some have `to: null` · sent: `send` sent the addressed ones · none: nothing to send */
-    status: 'ready' | 'partial' | 'sent' | 'none';
+    network: Network | 'default' | 'chains';
+    /** the chains the calls aim at (empty when opted out) */
+    networks: number[];
+    /** ready: every contract exists · partial: some are missing · missing: none exist · sent: `send` sent the calls · none: opted out */
+    status: 'ready' | 'partial' | 'missing' | 'sent' | 'none';
     calls: UnsignedCall[];
+    /** a contract a target network does not have: said here, with no call */
+    missing: AttestMissing[];
     digests: {
         answers: Hex;
         decision: Hex;
         input: Hex;
         subject: Hex;
         receipt: Hex;
+        stampSubject: Hex;
     };
     notes: string[];
     sent?: string[];
 };
 export declare const ANSWER_LOG_RECORD = "record(bytes32,bytes32,bytes32,bytes32,bytes32,string,string)";
 export declare const DECISION_LOG_RECORD = "record(bytes32,bytes32,bytes32,uint16,string,string)";
+/** the composed verdict → the stamp's REF code. Jev is asked only when the facts found a delivery, so a reject is a
+ *  delivery with defects (2), not a missing one; needs_review cannot be determined yet (4). */
+export declare const STAMP_VERDICT_OF: Record<Verdict, StampVerdict>;
 export declare function record(r: Receipt, opts?: {
     network?: Network;
+    networks?: readonly number[];
+    profile?: AttestProfile;
     uri?: string;
+    stamp?: boolean;
     send?: (call: UnsignedCall) => Promise<string>;
 }): Promise<Recorded>;

package/dist/record.js

@@ -1,39 +1,47 @@
-// record(): the unsigned calls that put a receipt's digests on chain — JevAnswerLog.record (jev.answer.v1) and
-// JevDecisionLog.record (decision.v2). `network` is a flag: none | devnet | base | both. Nothing here signs: pass `send`
-// (your wallet, e.g. viem's walletClient.sendTransaction) to send the calls that have an address, or hand them on.
-import { encodeCall } from './abi.js';
-import { CONTRACTS } from './contracts.js';
-import { keccakHex } from './hash.js';
+// record(): the unsigned calls that put a receipt on chain — JevAnswerLog.record (jev.answer.v1), JevDecisionLog.record
+// (decision.v2) and GradeStampRegistry.stamp (the grade's verdict) — built by the shared attestation helper (attest.ts,
+// vendored byte for byte). Recording is ON by default (_ATTEST_BY_DEFAULT_v1_): the Taifoon devnet 36927 and the Taifoon
+// mainnet 3692781. `network` still takes none | devnet | base | both; `networks` takes any chain ids. A log or registry a
+// network does not have is listed in `missing`, never faked. Nothing here signs: pass `send` (your wallet, e.g. viem's
+// walletClient.sendTransaction) to send the calls, or hand them on.
+import { attest, ATTEST_PROFILES } from './attest.js';
+import { refBytes32, ZERO_ADDRESS } from './records.js';
 export const ANSWER_LOG_RECORD = 'record(bytes32,bytes32,bytes32,bytes32,bytes32,string,string)';
 export const DECISION_LOG_RECORD = 'record(bytes32,bytes32,bytes32,uint16,string,string)';
-const TARGETS = {
-    devnet: () => ({ chainId: CONTRACTS.devnet.chainId, answerLog: CONTRACTS.devnet.answerLog.address, decisionLog: CONTRACTS.devnet.decisionLog.address,
-        note: 'devnet 36927: any account may send (gas from https://faucet.taifoon.dev). A sender outside JevAnswerLog’s deploy-time recorders is logged with trusted = false.' }),
-    base: () => ({ chainId: CONTRACTS.base.chainId, answerLog: CONTRACTS.base.answerLog?.address ?? null, decisionLog: CONTRACTS.base.decisionLog?.address ?? null,
-        note: CONTRACTS.base.answerLog && CONTRACTS.base.decisionLog ? 'Base 8453: the logs at CONTRACTS.base.' : 'Base 8453: this package version carries no Base address for the logs, so these calls have to = null (the call data is final; set `to` to send them).' }),
-};
+/** the composed verdict → the stamp's REF code. Jev is asked only when the facts found a delivery, so a reject is a
+ *  delivery with defects (2), not a missing one; needs_review cannot be determined yet (4). */
+export const STAMP_VERDICT_OF = { complete: 1, reject: 2, needs_review: 4 };
+const NETWORKS = { devnet: [36927], base: [8453], both: [36927, 8453] };
 export async function record(r, opts = {}) {
     if (!r.decision || !r.answersRecord || !r.answersDigest)
         throw new Error(`nothing to record: Jev was not asked (${r.reasons[0] ?? r.verdict}) — a hard fail is decided by the facts alone`);
-    const network = opts.network ?? 'devnet';
-    const digests = { answers: r.answersDigest, decision: r.decision.digest, input: r.inputDigest, subject: r.subjectId, receipt: r.receiptHash };
-    if (network === 'none')
-        return { network, status: 'none', calls: [], digests, notes: ['network none: the receipt and its digests only'] };
+    const network = opts.network ?? (opts.networks ? 'chains' : 'default');
+    const chains = opts.network === 'none' ? 'none' : opts.network ? NETWORKS[opts.network] : opts.networks ?? ATTEST_PROFILES[opts.profile ?? 'taifoon'];
     const model = (r.answersRecord.upstream_model ?? r.answersRecord.model ?? 'jev').slice(0, 64);
     const uri = (kind, d) => (opts.uri ? `${opts.uri.replace(/\/$/, '')}/${d}` : `urn:jev:${kind}:${d}`).slice(0, 512);
-    const answerData = encodeCall(ANSWER_LOG_RECORD, [keccakHex(r.answersRecord.use_case), r.subjectId, r.inputDigest, r.answersDigest, r.decision.digest, model, uri('answers', r.answersDigest)]);
-    const decisionData = encodeCall(DECISION_LOG_RECORD, [r.subjectId, r.decision.kindId, r.decision.digest, r.decision.confidenceBps, model, uri('decision', r.decision.digest)]);
-    const targets = (network === 'both' ? ['devnet', 'base'] : [network]).map((n) => TARGETS[n]());
-    const calls = targets.flatMap((t) => [
-        { chainId: t.chainId, to: t.answerLog, value: '0', fn: 'JevAnswerLog.record', data: answerData },
-        { chainId: t.chainId, to: t.decisionLog, value: '0', fn: 'JevDecisionLog.record', data: decisionData },
-    ]);
-    const out = { network, status: calls.every((c) => c.to) ? 'ready' : 'partial', calls, digests, notes: targets.map((t) => t.note) };
+    const s = r.chainSubject;
+    const a = attest({
+        kind: r.decision.kind, subject: { chainId: s.chainId, contract: s.at ?? ZERO_ADDRESS, jobId: refBytes32(s.ref) },
+        digest: r.decision.digest, confidenceBps: r.decision.confidenceBps, model, uri: uri('decision', r.decision.digest),
+        answers: { useCase: r.answersRecord.use_case, inputDigest: r.inputDigest, answersDigest: r.answersDigest, uri: uri('answers', r.answersDigest) },
+        verdict: opts.stamp === false ? null : STAMP_VERDICT_OF[r.verdict], mode: 2,
+    }, { networks: chains });
+    if (a.mark.subject !== r.subjectId)
+        throw new Error('record: the attestation subject differs from the receipt\'s subject id');
+    const digests = { answers: r.answersDigest, decision: r.decision.digest, input: r.inputDigest, subject: r.subjectId, receipt: r.receiptHash, stampSubject: a.mark.stampSubject };
+    if (!a.recorded)
+        return { network, networks: [], status: 'none', calls: [], missing: [], digests, notes: ['recording turned off (network none): the receipt and its digests only'] };
+    const out = {
+        network, networks: a.networks, status: a.status === 'none' ? 'none' : a.status, calls: a.calls, missing: a.missing, digests,
+        notes: [
+            ...(a.networks.includes(36927) ? ['devnet 36927: any account may send (gas from https://faucet.taifoon.dev). A sender outside JevAnswerLog’s deploy-time recorders is logged with trusted = false.'] : []),
+            ...a.missing.map((m) => m.why),
+        ],
+    };
     if (opts.send) {
         out.sent = [];
-        for (const c of calls)
-            if (c.to)
-                out.sent.push(await opts.send(c));
+        for (const c of out.calls)
+            out.sent.push(await opts.send(c));
         if (out.sent.length)
             out.status = 'sent';
     }

package/dist/rpc-fallback.js

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-rpc.mjs from packages/rpc/fallback.json (measured 2026-10-08). Do not edit.
+// GENERATED by scripts/vendor-rpc.mjs from packages/rpc/fallback.json (measured 2026-10-10). 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: {

package/docs/API.md

@@ -6,7 +6,7 @@
 |---|---|---|
 | `grade({ subject, evidence, facts?, rubric?, key \| answers })` | Checks the facts first. If none fails, asks Jev the rubric, composes the verdict and returns the receipt. | Asks Jev once, or never on a hard fail |
 | `facts({ delivered, checks, priceUsdc? })` | Runs the checks your protocol supplies. A check is a value or an (async) function; one that throws counts as "could not be checked". | None |
-| `record(receipt, { network, send? })` | Returns the unsigned `JevAnswerLog.record` and `JevDecisionLog.record` calls. `network` is a flag: `none`, `devnet` (default), `base` or `both`. Pass `send` (your wallet) to send every call that has an address. | None unless you pass `send` |
+| `record(receipt, { network?, networks?, stamp?, send? })` | Returns the unsigned `JevAnswerLog.record`, `JevDecisionLog.record` and `GradeStampRegistry.stamp` calls. By default they aim at the Taifoon devnet 36927 and the Taifoon mainnet 3692781; `network` (`none`, `devnet`, `base`, `both`) or `networks` (any chain ids) choose others, `none` turns recording off. A contract a network does not have is listed in `missing`, with no call. Pass `send` (your wallet) to send the calls. | None unless you pass `send` |
 | `evaluatorCall(protocol, jobId, verdict, digest)` | Returns the one unsigned call that ends the job on that protocol. For `needs_review` it returns `null`. | None |
 | `prepareJob({ id, task, criteria, delivered, source?, checks? })` | Turns a job as the buyer laid it out into the evidence Jev reads and the checks code runs. | None |
 | `verify(receiptOrDigest)` | Recomputes every digest, re-composes the verdict and finds the `JevAnswered` and `Decided` events. | One devnet RPC read |

package/docs/PIPELINE.md

@@ -12,8 +12,8 @@ This package puts Jev inside a fixed judging procedure:
 - Code establishes the facts first. A failed check ends the job, and Jev is never asked.
 - Jev answers four **atomic** questions from a published rubric. It never gets a holistic "is the job good?".
 - Code composes the verdict from the facts and the answers under published thresholds.
-- Everything is hashed into a receipt and turned into the one call that ends the job. Recording it on chain is
-  optional: `record()` builds the calls only when you ask.
+- Everything is hashed into a receipt and turned into the one call that ends the job. `record()` builds the
+  unsigned calls that record and stamp it on chain, on the Taifoon devnet and mainnet by default (`network: 'none'` turns them off).
 
 How to describe the result: *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 that the answer is right.

package/package.json

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