@mikeargento/bitgraph-audit 0.7.0 → 0.9.0

package/src/ceilings.ts

@@ -9,10 +9,27 @@
  *
  * The writer address is a trust input, like a measurement allowlist: the
  * default is the address BitGraph publishes, and a reader can pass another.
+ *
+ * A ceiling file may carry its SETTLEMENT on Ethereum (bitgraph-settlement/1,
+ * the `settlement` field): the batcher transaction whose blobs hold the Base
+ * block. Two layers, both offline, reported as separate lines: the POINTER
+ * (verifySettlementPointer, against the Base mainnet pins or ones the reader
+ * passes) and the BLOBS (blob bytes kept in the bundle next to the ceiling
+ * file or under a `blobs/` folder, verified against the listed KZG
+ * commitments and decoded down to the ceiling transaction). Blob bytes
+ * absent from the bundle are reported, never a failure; a pointer or blob
+ * that is present and wrong fails the ceiling like any other bad evidence.
+ * The settlement is checked whether or not the ceiling's proof is in the
+ * bundle: it is evidence about the ceiling file itself.
  */
 
-import { verifyCeiling, checkCeilingOnline, type CeilingSidecar } from "@mikeargento/bitgraph-verify";
-import type { CeilingAnalysis, CeilingCheck, IngestResult } from "./types.js";
+import {
+  verifyCeiling, checkCeilingOnline, verifySettlementPointer, BASE_MAINNET_SETTLEMENT_PINS, decodeHeader, evmHexToBytes,
+  type CeilingSidecar, type SettlementPointer, type SettlementPins,
+} from "@mikeargento/bitgraph-verify";
+import { streamArtifactsByHash } from "./ingest.js";
+import { verifySettlementBlobs } from "./settlement-blobs.js";
+import type { CeilingAnalysis, CeilingCheck, CeilingSettlementCheck, IngestResult } from "./types.js";
 
 /** BitGraph's published ceiling writer on Base mainnet (bitgraph.ing/ceilings). */
 export const BITGRAPH_CEILING_WRITER = "0xf3972408D853c975F86351C311f4310220bbF2a3";
@@ -27,51 +44,64 @@ export interface CeilingAuditOptions {
    * network call (its zero-network guarantee), so the CLI never sets this.
    */
   getBlockHash?: (blockNumber: number) => Promise<string | null>;
+  /** The batch inbox and batcher a settlement pointer must name. Base mainnet's by default. */
+  settlementPins?: SettlementPins;
 }
 
 export async function verifyCeilings(ingest: IngestResult, options: CeilingAuditOptions = {}): Promise<CeilingAnalysis> {
   const writer = options.writer ?? BITGRAPH_CEILING_WRITER;
   const chainId = options.chainId ?? BASE_MAINNET_CHAIN_ID;
+  const pins = options.settlementPins ?? BASE_MAINNET_SETTLEMENT_PINS;
   const byHash = new Map(ingest.proofs.map((p) => [p.proofHash, p]));
   const checks: CeilingCheck[] = [];
   for (const f of ingest.ceilings ?? []) {
     const side = f.json as unknown as CeilingSidecar;
     const proofHash = typeof side.proofHash === "string" ? side.proofHash : null;
     const observed = proofHash ? byHash.get(proofHash) : undefined;
+    let check: CeilingCheck;
     if (!observed) {
-      checks.push({ path: f.path, proofHash, status: "unmatched", reason: "no proof in this bundle has this ceiling's proofHash", onChain: null });
-      continue;
-    }
-    const r = await verifyCeiling(observed.proof, side, { writerAddress: writer, chainId });
-    if (!r.ok) {
-      const pending = r.status === "pending";
-      checks.push({ path: f.path, proofHash, status: pending ? "pending" : "failed", ...(r.reason ? { reason: r.reason } : {}), onChain: null });
-      continue;
+      check = { path: f.path, proofHash, status: "unmatched", reason: "no proof in this bundle has this ceiling's proofHash", onChain: null };
+    } else {
+      const r = await verifyCeiling(observed.proof, side, { writerAddress: writer, chainId });
+      if (!r.ok) {
+        const pending = r.status === "pending";
+        check = { path: f.path, proofHash, status: pending ? "pending" : "failed", ...(r.reason ? { reason: r.reason } : {}), onChain: null };
+      } else {
+        const w = r.window!;
+        check = {
+          path: f.path,
+          proofHash,
+          status: "verified",
+          ...(r.label ? { label: r.label } : {}),
+          window: {
+            floorBlock: w.floor.blockNumber || null,
+            floorTime: w.floor.blockTimestamp,
+            ceilingChainId: w.ceiling.chainId,
+            ceilingBlock: w.ceiling.blockNumber,
+            ceilingTime: w.ceiling.blockTimestamp,
+            widthSeconds: w.widthSeconds,
+          },
+          onChain: null,
+          onChainDetail: "header not checked against chain",
+        };
+        if (options.getBlockHash) {
+          const online = await checkCeilingOnline(side, options.getBlockHash);
+          check.onChain = online.onChain;
+          check.onChainDetail = online.detail;
+          if (online.onChain === false) {
+            check.status = "failed";
+            check.reason = `chain: ${online.detail}`;
+          }
+        }
+      }
     }
-    const w = r.window!;
-    const check: CeilingCheck = {
-      path: f.path,
-      proofHash,
-      status: "verified",
-      ...(r.label ? { label: r.label } : {}),
-      window: {
-        floorBlock: w.floor.blockNumber || null,
-        floorTime: w.floor.blockTimestamp,
-        ceilingChainId: w.ceiling.chainId,
-        ceilingBlock: w.ceiling.blockNumber,
-        ceilingTime: w.ceiling.blockTimestamp,
-        widthSeconds: w.widthSeconds,
-      },
-      onChain: null,
-      onChainDetail: "header not checked against chain",
-    };
-    if (options.getBlockHash) {
-      const online = await checkCeilingOnline(side, options.getBlockHash);
-      check.onChain = online.onChain;
-      check.onChainDetail = online.detail;
-      if (online.onChain === false) {
+    const carried = f.json["settlement"];
+    if (carried !== null && carried !== undefined) {
+      const settlement = await auditSettlement(f.path, side, carried, ingest, pins);
+      check.settlement = settlement;
+      if (settlement.status === "failed" && check.status !== "failed") {
         check.status = "failed";
-        check.reason = `chain: ${online.detail}`;
+        check.reason = settlement.lines.find((l) => l.includes("FAILED")) ?? "settlement: failed";
       }
     }
     checks.push(check);
@@ -83,3 +113,107 @@ export async function verifyCeilings(ingest: IngestResult, options: CeilingAudit
   }));
   return { writer, chainId, checks, statuses };
 }
+
+// ── settlement ─────────────────────────────────────────────────────────────
+
+function whenUtc(unix: number): string {
+  const iso = new Date(unix * 1000).toISOString();
+  return `${iso.slice(0, 10)} ${iso.slice(11, 19)} UTC`;
+}
+
+/** The bundle paths a blob file named `file` may sit at, next to the ceiling file first. */
+function blobCandidatePaths(ceilingPath: string, file: string): string[] {
+  const slash = ceilingPath.lastIndexOf("/");
+  const dir = slash < 0 ? "" : ceilingPath.slice(0, slash + 1);
+  return [`${dir}${file}`, `${dir}blobs/${file}`, `blobs/${file}`, file];
+}
+
+async function auditSettlement(
+  path: string,
+  side: CeilingSidecar,
+  carried: unknown,
+  ingest: IngestResult,
+  pins: SettlementPins,
+): Promise<CeilingSettlementCheck> {
+  const lines: string[] = [];
+  const failed = (pointer: CeilingSettlementCheck["pointer"], blobs: CeilingSettlementCheck["blobs"]): CeilingSettlementCheck =>
+    ({ status: "failed", pointer, blobs, lines });
+  const noBlobs = (detail: string, listed: number): CeilingSettlementCheck["blobs"] => ({ status: "absent", detail, listed, supplied: 0 });
+
+  // 1. The pointer: header, inclusion, batcher, blob commitments.
+  const pointer = carried as SettlementPointer;
+  const p = verifySettlementPointer(pointer, pins);
+  const listed = Array.isArray(pointer?.blobs) ? pointer.blobs.length : 0;
+  if (!p.ok) {
+    lines.push(`settlement: pointer FAILED (${p.reason ?? "invalid"})`);
+    return failed({ ok: false, reason: p.reason ?? "invalid" }, noBlobs("not checked: the pointer failed", listed));
+  }
+  const existedBy = p.existedBy!;
+  // The pointer must be about THIS ceiling's Base block and transaction.
+  const anchor = side.anchor;
+  let mismatch: string | null = null;
+  if (!anchor) mismatch = "the ceiling has no Base transaction yet";
+  else if (pointer.baseBlockNumber !== anchor.blockNumber || pointer.baseBlockHash.toLowerCase() !== anchor.blockHash.toLowerCase()) {
+    mismatch = `the pointer names Base block ${pointer.baseBlockNumber} (${pointer.baseBlockHash.slice(0, 10)}…), this ceiling is in block ${anchor.blockNumber} (${anchor.blockHash.slice(0, 10)}…)`;
+  } else if (pointer.located && pointer.located.txHash.toLowerCase() !== anchor.txHash.toLowerCase()) {
+    mismatch = `the pointer locates transaction ${pointer.located.txHash.slice(0, 10)}…, this ceiling's is ${anchor.txHash.slice(0, 10)}…`;
+  }
+  if (mismatch) {
+    lines.push(`settlement: pointer FAILED (${mismatch})`);
+    return failed({ ok: false, reason: mismatch, existedBy }, noBlobs("not checked: the pointer is for another block", listed));
+  }
+  lines.push(`settlement: pointer ok, Ethereum block ${existedBy.blockNumber} at ${whenUtc(existedBy.blockTimestamp)}`);
+  const pointerOk: CeilingSettlementCheck["pointer"] = { ok: true, existedBy };
+
+  // 2. The blobs, when the bundle holds their bytes.
+  const wanted = new Map<string, string>(); // sha256 hex -> versioned hash
+  const byPath = new Map<string, string>(); // bundle path -> sha256 hex
+  for (const a of ingest.artifacts) for (const ap of a.paths) byPath.set(ap, a.sha256Hex);
+  const byBasename = new Map<string, string>();
+  for (const a of ingest.artifacts) for (const ap of a.paths) byBasename.set(ap.slice(ap.lastIndexOf("/") + 1), a.sha256Hex);
+  for (const b of pointer.blobs) {
+    const file = typeof b.file === "string" ? b.file : `${b.versionedHash.toLowerCase()}.bin`;
+    if (file.includes("/") || file.includes("\\") || file.includes("..")) continue;
+    const hex = blobCandidatePaths(path, file).map((c) => byPath.get(c)).find((h) => h !== undefined) ?? byBasename.get(file);
+    if (hex) wanted.set(hex, b.versionedHash.toLowerCase());
+  }
+  if (wanted.size === 0) {
+    lines.push("settlement: blobs not in bundle");
+    return { status: "pointer-only", pointer: pointerOk, blobs: noBlobs("blobs not in bundle", listed), lines };
+  }
+  const bytesByHash = new Map<string, Uint8Array>();
+  for await (const m of streamArtifactsByHash(ingest, wanted.keys())) bytesByHash.set(wanted.get(m.sha256Hex)!, m.bytes);
+  let expectParent: string | undefined;
+  try {
+    expectParent = anchor ? decodeHeader(evmHexToBytes(anchor.blockHeader)).parentHash : undefined;
+  } catch {
+    expectParent = undefined;
+  }
+  const r = await verifySettlementBlobs(pointer, bytesByHash, {
+    expect: {
+      txHash: anchor!.txHash,
+      rawTx: anchor!.rawTx,
+      ...(expectParent ? { baseParentHash: expectParent } : {}),
+    },
+  });
+  if (!r.ok) {
+    lines.push(`settlement: blobs FAILED (${r.reason ?? "invalid"})`);
+    return failed(pointerOk, { status: "failed", detail: r.reason ?? "invalid", listed, supplied: bytesByHash.size });
+  }
+  const c = r.channel!;
+  const frames = c.complete ? `all ${c.framesDecoded} frames` : `frames 0..${c.framesDecoded - 1}${c.framesTotal ? ` of ${c.framesTotal}` : ""}`;
+  const loc = r.located!;
+  lines.push(`settlement: blobs decoded (${frames}), ceiling tx located in Base block ${loc.baseBlockNumber}${loc.batchComplete ? "" : " (batch cut at the last frame supplied)"}`);
+  return {
+    status: "verified",
+    pointer: pointerOk,
+    blobs: {
+      status: "verified",
+      detail: `${bytesByHash.size} of ${listed} blobs supplied; ${frames} decoded; ${r.checks.map((k) => k.detail ?? k.name).join("; ")}`,
+      listed,
+      supplied: bytesByHash.size,
+      located: { baseBlockNumber: loc.baseBlockNumber, baseTxIndex: loc.baseTxIndex, txHash: loc.txHash, batchComplete: loc.batchComplete, framesDecoded: c.framesDecoded, framesTotal: c.framesTotal },
+    },
+    lines,
+  };
+}

package/src/cli.ts

@@ -25,6 +25,7 @@ import { parseCarrier, verifyCarrier } from "@mikeargento/bitgraph-verify";
 import type { VerificationPolicy } from "@mikeargento/bitgraph-verify";
 import { auditToolVersion, computeExitFlags, runAudit } from "./audit.js";
 import { attestationTimestampMs } from "./attestation.js";
+import { exportRunClaims } from "./exports.js";
 import { buildJsonReport } from "./report-json.js";
 import { buildMarkdownReport } from "./report-md.js";
 import type { ExitFlags } from "./types.js";
@@ -67,6 +68,14 @@ function helpText(): string {
     "printed first.",
     "archive. The audit runs entirely offline: no RPC, no HTTP, no DNS.",
     "",
+    "Exports (bitgraph-export/1) anywhere in the bundle are found by their",
+    "format field. Each is checked with verifyExport once per file in the",
+    "bundle it covers (by SHA-256: a member's committed bytes or original;",
+    "for the owner's export, any leaf's), or once without a file when none",
+    "is there, and its proof joins the proof analysis. Every claim, the",
+    "covered files and the three time claims (floor; ceiling on Base,",
+    "provisional; ceiling on Ethereum) are reported, never merged.",
+    "",
     "Options:",
     "  --out <dir>            Directory to write the report files into",
     "                         (default: current directory; created if missing).",
@@ -98,7 +107,12 @@ function helpText(): string {
     "      are absent from the bundle is NOT a failure by itself: its",
     "      bytes-free checks decide, unless a supplied trust policy makes",
     "      them fail (for example requireSlot), in which case it counts",
-    "      here.",
+    "      here. Also: an export (bitgraph-export/1) with any FALSE claim,",
+    "      its attestation claims included (an export is checked as one",
+    "      self-contained object, as a carrier is), or an export-shaped",
+    "      file that is malformed, of an unsupported format, or too large",
+    "      to read. A claim the export does not carry (NOT_CARRIED: a",
+    "      pending ceiling, the covered file absent) is never a failure.",
     "  2   Chain or authority anomalies, divergences between valid proofs,",
     "      or anchor witness verification failures: unexplained counter",
     "      positions, chain breaks, collisions, cross-kind position reuse,",
@@ -122,7 +136,8 @@ function helpText(): string {
     "change the exit code on their own: an invalid attestation document on",
     "an otherwise verified proof is reported without affecting the exit",
     "code, and counts under exit bit 1 only when a supplied trust policy",
-    "made verification itself fail.",
+    "made verification itself fail. The exception is an export's own",
+    "attestation claims, which are part of the export's verdict (exit 1).",
   ].join("\n");
 }
 
@@ -234,7 +249,7 @@ function loadTrustPolicy(path: string): VerificationPolicy {
 function exitMeaning(flags: ExitFlags): string {
   if (flags.code === 0) return "clean: no verification failures, no chain anomalies, no divergences";
   const parts: string[] = [];
-  if (flags.verificationFailures) parts.push("verification failures");
+  if (flags.verificationFailures) parts.push("verification failures (a proof, or an export with a FALSE claim)");
   if (flags.chainAnomaliesOrDivergences) {
     parts.push("chain anomalies, divergences, or anchor witness verification failures (or a failed ceiling in time)");
   }
@@ -375,8 +390,29 @@ async function main(): Promise<number> {
     process.stdout.write(c.status === "verified"
       ? `ceiling VERIFIED ${c.path}: ${c.label ?? ""}${width}; ${c.onChainDetail ?? ""}\n`
       : `ceiling ${c.status.toUpperCase()} ${c.path}: ${c.reason ?? ""}\n`);
+    for (const line of c.settlement?.lines ?? []) process.stdout.write(`  ${line}\n`);
   }
   for (const s of result.ceilings?.statuses ?? []) process.stdout.write(`ceiling ${s.status} ${s.path}: ${s.note}\n`);
+  for (const e of result.exports?.checks ?? []) {
+    if (e.status !== "checked") {
+      process.stdout.write(`export NOT CHECKED ${e.path}: ${e.reason ?? e.status}\n`);
+      continue;
+    }
+    const withFile = e.runs.filter((r) => r.file !== null).length;
+    const files = e.files.length === 0 ? "no covered file in the bundle" : `${withFile} of ${e.files.length} covered file${e.files.length === 1 ? "" : "s"} checked`;
+    process.stdout.write(`export ${e.verdict} ${e.path}: ${e.kind ?? "export"}, ${files}${e.failedClaims.length > 0 ? `; FALSE: ${e.failedClaims.join(", ")}` : ""}\n`);
+    // The three time claims, one line each, never merged.
+    const t = e.times;
+    const when = (unix: number) => new Date(unix * 1000).toISOString();
+    const firstClaims = e.runs[0] !== undefined ? exportRunClaims(e, e.runs[0]) : e.claims;
+    const why = (id: string) => {
+      const c = firstClaims.find((x) => x.id === id);
+      return c ? `not established (${c.result}: ${c.detail})` : "not established";
+    };
+    process.stdout.write(`  floor: ${t.floor ? `committed bytes finished after Ethereum block ${t.floor.blockNumber} (mined ${when(t.floor.blockTimestamp)})` : why("floor.header")}\n`);
+    process.stdout.write(`  ceiling on Base: ${t.ceilingBase ? `existed by Base block ${t.ceilingBase.blockNumber} (${when(t.ceilingBase.blockTimestamp)})${t.ceilingBase.provisional ? ", provisional until checked against Base" : ""}` : why("ceiling.base")}\n`);
+    process.stdout.write(`  ceiling on Ethereum: ${t.ceilingEthereum ? `existed by Ethereum block ${t.ceilingEthereum.blockNumber} (${when(t.ceilingEthereum.blockTimestamp)})` : why("ceiling.ethereum")}\n`);
+  }
   process.stdout.write(
     `bitgraph-audit ${auditToolVersion()}: wrote ${written.join(", ")}\n` +
       `exit ${flags.code}: ${exitMeaning(flags)}\n`