brainchain-verify 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,7 +22,7 @@ brainchain-verify <mainnet|testnet|chainId> --task <taskId> [--set <TaskBoard>]
22
22
  | `mainnet`, `testnet` or a chain id | `mainnet` is chain 274663 at `https://rpc.usebrainchain.com`; `testnet` is chain 274630 at `https://rpc.testnet.usebrainchain.com`. |
23
23
  | `<decisionId>` | The decision's number in its `DecisionLog`, from 1. |
24
24
  | `--task <id>` | Check every decision about one task, oldest first. |
25
- | `--set <TaskBoard>` | A retired contract set, by its TaskBoard address or by the key a decision page uses (`?set=v3-1`). Without it, the active set. Each set numbers its tasks and decisions from 1. |
25
+ | `--set <TaskBoard>` | A retired contract set, by its TaskBoard address, by the key a decision page uses (`?set=v3-1`) or by release (`3.1.0`). Without it, the active set. Each set numbers its tasks and decisions from 1. |
26
26
  | `--rpc <url>` | Another RPC for the same chain. |
27
27
  | `--json` | One JSON object on stdout. |
28
28
 
@@ -52,7 +52,7 @@ Verdict: match. The published record is exactly what the chain recorded, and the
52
52
  Not checked: that Jev produced the answer. See https://docs.usebrainchain.com/trust-model
53
53
  ```
54
54
 
55
- Each line is one check. `ok` passed and `FAIL` means the record and the chain disagree. `skip` is a check that could not run, with the reason on the line. `ERROR` means the record host did not answer after three tries, so the checks that need the record did not run.
55
+ Each line is one check. `ok` passed and `FAIL` means the record and the chain disagree. `skip` is a check that could not run, with the reason on the line. `ERROR` means the record could not be fetched, so the checks that need it did not run: the host did not answer after three tries, or it no longer has the record.
56
56
 
57
57
  ## What it checks
58
58
 
@@ -79,6 +79,7 @@ Some checks skip by design:
79
79
 
80
80
  - A record for work Jev did not accept is served without the work, so `record-hash` and `input-hash` cannot match it. The answer, confidence and threshold are still checked.
81
81
  - A decision the board never applied, because a later decision or a closed window settled the task, skips `threshold`.
82
+ - A grade of work delivered outside BrainChain has no task on the board, so it skips `threshold`. Its subject, levels and confidence are still checked.
82
83
  - A grade recorded before the chain gated on the paid levels skips `confidence-recomputed`: its confidence is Jev's score confidence, which the probabilities alone do not give.
83
84
 
84
85
  ## What it cannot check
package/dist/cli.js CHANGED
@@ -12,8 +12,8 @@ fetches the published record, recomputes its hashes and confidence, and applies
12
12
  the task's thresholds as the contracts do. Needs no keys.
13
13
 
14
14
  --task <id> check every decision about one task
15
- --set <board> a retired contract set, by TaskBoard address or by its key on
16
- the site (v3-1); without it, the active set
15
+ --set <board> a retired contract set, by TaskBoard address, by its key on
16
+ the site (v3-1) or by release (3.1.0); without it, the active set
17
17
  --rpc <url> another RPC for the same chain
18
18
  --json one JSON object on stdout
19
19
 
@@ -64,7 +64,7 @@ if (!foundNetwork)
64
64
  const network = foundNetwork;
65
65
  const foundSet = setArg === undefined
66
66
  ? network.sets[0]
67
- : network.sets.find((s) => (isAddress(setArg) ? s.board.toLowerCase() === setArg.toLowerCase() : s.key === setArg));
67
+ : network.sets.find((s) => (isAddress(setArg) ? s.board.toLowerCase() === setArg.toLowerCase() : s.key === setArg || s.release === setArg));
68
68
  if (!foundSet) {
69
69
  const sets = network.sets.map((s, i) => `${s.key} (TaskBoard ${s.board}${i === 0 ? ", active" : ""})`);
70
70
  usage(`No contract set ${setArg} on ${network.name}. Sets: ${sets.join(", ")}`);
@@ -90,7 +90,7 @@ function verdict(failed, errors, skipped, many) {
90
90
  if (failed > 0)
91
91
  return `Verdict: MISMATCH. ${failed} check${failed === 1 ? "" : "s"} failed; see the FAIL lines.`;
92
92
  if (errors > 0)
93
- return "Verdict: UNVERIFIED. A record could not be fetched, so its checks did not run; see the ERROR lines and try again.";
93
+ return "Verdict: UNVERIFIED. A record could not be fetched, so its checks did not run; see the ERROR lines.";
94
94
  if (skipped > 0)
95
95
  return "Verdict: match. Every check that could run passed; the skip lines say what could not be checked.";
96
96
  return many
@@ -52,7 +52,7 @@ export const NETWORKS = {
52
52
  "executor": "0xA3a40A2D46D54dc6e88c08a9d98Ec47785CB2366"
53
53
  },
54
54
  {
55
- "key": "v3-4",
55
+ "key": "v3-4-1",
56
56
  "release": "3.4.1",
57
57
  "fromBlock": 2141,
58
58
  "board": "0x67e0C5F884E1df61AC585B6d158c6E8175956AD1",
package/dist/verify.d.ts CHANGED
@@ -12,6 +12,8 @@ export interface DecisionReport {
12
12
  id: number;
13
13
  kind?: string;
14
14
  task?: number;
15
+ /** A grade of work delivered outside BrainChain, so no task here. */
16
+ outside?: boolean;
15
17
  block?: number;
16
18
  recordedAt?: string;
17
19
  confidenceBps?: number;
package/dist/verify.js CHANGED
@@ -1,4 +1,4 @@
1
- import { BaseError, decodeFunctionData, encodeAbiParameters, keccak256, pad, toBytes, } from "viem";
1
+ import { BaseError, decodeFunctionData, encodeAbiParameters, keccak256, pad, toBytes, toHex, } from "viem";
2
2
  import { decisionExecutorAbi, decisionLogAbi, modelRegistryAbi, taskBoardAbi } from "./abi.js";
3
3
  import { canonicalStringify } from "./canonical.js";
4
4
  const Kind = { Hire: 1, Grade: 2, Ruling: 3, Change: 4 };
@@ -42,6 +42,20 @@ function decodeText(bytes) {
42
42
  return undefined;
43
43
  }
44
44
  }
45
+ /** Base and Base Sepolia, where ACP evaluations come from. */
46
+ const ACP_CHAINS = [8453n, 84532n];
47
+ /** Whether a grade's subject is the one the service derives for work delivered elsewhere: a paid grade by its id, or an ACP evaluation by its job. */
48
+ function outsideGrade(recorded, subject) {
49
+ if (!/^\d+$/.test(recorded))
50
+ return false;
51
+ const id = BigInt(recorded);
52
+ if (id >> 256n !== 0n)
53
+ return false;
54
+ const paid = keccak256(encodeAbiParameters([{ type: "string" }, { type: "bytes32" }], ["x402-grade", toHex(id, { size: 32 })]));
55
+ if (paid === subject)
56
+ return true;
57
+ return ACP_CHAINS.some((chain) => keccak256(encodeAbiParameters([{ type: "string" }, { type: "uint256" }, { type: "uint256" }], ["acp-evaluation", chain, id])) === subject);
58
+ }
45
59
  /** TaskBoard.subjectOf(id): the task on this board on this chain. */
46
60
  function taskSubject(chainId, board, task) {
47
61
  return keccak256(encodeAbiParameters([{ type: "uint256" }, { type: "address" }, { type: "uint256" }], [BigInt(chainId), board, task]));
@@ -126,6 +140,8 @@ async function fetchBytes(uri) {
126
140
  if (url.protocol !== "https:" && url.protocol !== "http:")
127
141
  throw new Error(`${url.protocol} URIs are not supported`);
128
142
  const response = await get(url);
143
+ if (response.status === 404)
144
+ throw new Error(`${display(uri)} answered with status 404: the host no longer has this record, so trying again will not help`);
129
145
  if (!response.ok)
130
146
  throw new Error(`${display(uri)} answered with status ${response.status}`);
131
147
  return {
@@ -231,12 +247,18 @@ export async function verifyDecision(ctx, id) {
231
247
  c.check("input-hash", input === decision.inputHash, `request hash matches inputHash ${short(input)}`, `request hash ${short(input)} differs from inputHash ${short(decision.inputHash)}`);
232
248
  }
233
249
  c.check("kind", record.kind === kind, `kind: ${record.kind}`, `the record is a ${record.kind}; the chain recorded a ${kind}`);
234
- const task = decision.kind !== Kind.Change && /^\d+$/.test(record.subject) ? BigInt(record.subject) : undefined;
250
+ const outside = decision.kind === Kind.Grade && outsideGrade(record.subject, decision.subject);
251
+ const task = !outside && decision.kind !== Kind.Change && /^\d+$/.test(record.subject) ? BigInt(record.subject) : undefined;
235
252
  if (task !== undefined)
236
253
  report.task = Number(task);
254
+ if (outside)
255
+ report.outside = true;
237
256
  if (decision.kind === Kind.Change) {
238
257
  c.check("subject", record.subject.toLowerCase() === decision.subject, `subject: ${short(decision.subject)}, the exact call this change names`, "the record's subject differs from the one on chain");
239
258
  }
259
+ else if (outside) {
260
+ c.add("subject", "ok", "subject: a grade of work delivered outside BrainChain, so no task on this board");
261
+ }
240
262
  else {
241
263
  c.check("subject", task !== undefined && taskSubject(network.chainId, set.board, task) === decision.subject, `subject: task ${record.subject} on board ${short(set.board)}, chain ${network.chainId}`, `the record names task ${record.subject}, which is not the subject recorded on chain`);
242
264
  }
@@ -278,6 +300,10 @@ export async function verifyDecision(ctx, id) {
278
300
  await checkBrief(ctx, c, task, decision, record, state);
279
301
  await checkTaskThreshold(ctx, c, id, task, decision, record);
280
302
  }
303
+ if (outside) {
304
+ checkOutsideGrade(c, record);
305
+ c.add("threshold", "skip", "threshold: no task on this chain, so no board applied this grade; the caller received the verdict");
306
+ }
281
307
  if (decision.kind === Kind.Change)
282
308
  await checkChange(ctx, c, id, decision, record, state);
283
309
  return report;
@@ -311,7 +337,18 @@ async function checkBrief(ctx, c, task, decision, record, state) {
311
337
  c.add("confidence-recomputed", "skip", "grade confidence: this grade predates the rule that gates on the paid levels, so its confidence is Jev's score confidence, which the probabilities alone do not give");
312
338
  return;
313
339
  }
314
- const paidKeys = ascending.map((_, i) => String(i)).slice(ascending.length - 1 - brief.passIndex);
340
+ checkGradeConfidence(c, record, ascending.map((_, i) => String(i)).slice(ascending.length - 1 - brief.passIndex));
341
+ }
342
+ // No brief on chain to compare with: the levels and the pass level are in the record, which inputHash commits to.
343
+ function checkOutsideGrade(c, record) {
344
+ const levels = record.request.questions.decision.criteria;
345
+ if (!Array.isArray(levels) || record.passFrom === undefined) {
346
+ c.add("confidence-recomputed", "skip", "grade confidence: the record does not name its pass level");
347
+ return;
348
+ }
349
+ checkGradeConfidence(c, record, levels.map((_, i) => String(i)).slice(record.passFrom));
350
+ }
351
+ function checkGradeConfidence(c, record, paidKeys) {
315
352
  const parts = paidKeys.map((key) => record.probabilities[key] ?? 0);
316
353
  const jev = share(parts);
317
354
  const how = `paid levels ${paidKeys.join(", ")} hold ${parts.join(" + ")} = ${jev.toFixed(4)}`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brainchain-verify",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Check a BrainChain decision against the chain: the published record, its hashes, its confidence and the thresholds the contracts applied.",
5
5
  "license": "MIT",
6
6
  "author": "BrainChain",