Audit a bundle

You have been handed a bundle: an archive of BitGraph proof files, and perhaps the files they commit to, Ethereum anchor witnesses (for earlier proofs) and a manifest. This is the recipient’s walkthrough. The audit runs on your machine, offline, and reports exactly what the supplied evidence supports, nothing more.

What a bundle is

A bundle is a .tar.gz, .tar or plain directory containing BitGraph proof JSON files. It may also hold the bytes each proof commits to, Ethereum anchor witness files for earlier proofs and a manifest.json. Proofs are found by their schema shape, not by filename, and files are matched by their fingerprint (SHA-256 digest), so the layout inside the archive does not matter. A Frame file (<name>.bitgraph-fuse.json, the carrier of a fused file) is read as a proof file: the proof inside it is the member, and the fused copy it describes is matched by digest like any other file.

A bundle can come from anyone who collected proofs: an export from the proof viewer (a README.md that says how to read it, proof.json, the committed bytes under committed/, the original under original/ when the committed file was made from one, the Ethereum anchors with their witnesses for earlier proofs, and the Base ceiling; packages made before October 2026 keep the committed file under new-file/ beside a top-level original, and read the same), an operator who assembled a set of proofs, or a colleague who handed you an archive. How you received it does not matter; the contents carry their own evidence.

The producer and consumer specification, with the deterministic contents hash and its test vectors, is Bundle Format in the repository. It is precise enough to reimplement either role from the document alone. The Frame carrier is not yet in the document; the audit source shows how it is unwrapped.

What you need

• Node.jsThe audit is a published npm package; npx fetches it once. Or build it from source, below.
• The bundleThe archive or directory as you received it. Nothing in it is uploaded, and nothing is fetched to check it.
• A trust policyOptional. A JSON file in the VerificationPolicy shape, passed with --trust-policy and applied at both verification tiers. Use it to pin the enclave measurements you accept; the verification page lists the fields.

Two hashes, two meanings

Before running anything, you can check the archive you received. Two different hashes exist, and they pin different things.

• The archive file’s SHA-256 (shasum -a 256 bundle.tar.gz) identifies the exact archive you received. If the producer made a BitGraph of the archive itself, compare your computed hash against the digest that proof names. This step is optional and only meaningful when such a proof exists.
• The manifest’s contentsHashB64 is a deterministic hash over the bundle’s entries, defined in the Bundle Format specification. You do not check it by hand: the audit tool recomputes it and reports manifest-contents-hash-mismatch if the declared value does not match.

Run it

With Node.js installed, run the published CLI against your bundle:

npx @mikeargento/bitgraph-audit ./bundle.tar.gz --out ./audit

Or build from source if you prefer:

git clone https://github.com/mikeargento/bitgraph
cd bitgraph
npm install
npm run build
node packages/audit/dist/cli.js /path/to/bundle.tar.gz --out ./audit

Both write audit-report.json (machine-readable, complete) and audit-report.md (human-readable) into the output directory. No network access occurs in either mode: no RPC, no HTTP, no DNS.

Ceilings in time

A package from a proof page carries base-ceiling/ceiling.json beside proof.json when the record has a ceiling in time. The audit checks it offline against its proof: the record’s hash under the Merkle root, the root in a Base transaction signed by BitGraph’s published writer, the transaction inside the block, and the block’s time from its header. A package without one carries ceiling-status.json saying why.

The audit never goes online, so it reports whether that block is Base’s own as unchecked. One command answers it, or any Base explorer:

npx -p @mikeargento/bitgraph-sdk bitgraph ceiling verify proof.json base-ceiling/ceiling.json --rpc https://mainnet.base.org

Read the report

Open audit-report.md. The executive summary at the top is written for a reader with no cryptography background: how many proofs were observed, how many fully verified, how many lacked their file bytes (their binding to a specific file was not independently checked), whether the observed chain is intact, what anomalies and divergences exist, and what externally verifiable time evidence the bundle carries. Every anomaly is explained by consequence, and absence of evidence is stated as exactly that: a counter position missing from the bundle means the supplied evidence cannot reconstruct it, not that the authority failed to create it. The engineer-level sections and the JSON report carry the full records.

The status of each proof

• verifiedThe full check passed with the file’s bytes present in the bundle.
• failedA check failed, at either tier. The verifier’s exact reason is recorded.
• artifact-unavailableThe bytes-free checks passed, but no bytes for this proof were in the bundle, so the digest match was not independently checked. Never reported as verified.

Exit codes

The CLI exit code is a bit-flag summary of the report:

A proof whose bytes are absent from the bundle is not a failure by itself; it is reported as artifact-unavailable and its bytes-free checks decide, unless a supplied trust policy makes them fail (for example requireSlot). Attestation results are reported in full but never change the exit code on their own; an invalid attestation document on an otherwise verified proof counts under exit code 1 only when a supplied trust policy made verification itself fail.

What the report cannot conclude

A bundle is evidence, not a verdict. The report is careful about the following, and so should you be when you pass it on.

• AbsenceAn incomplete bundle yields an incomplete reconstruction. Missing proofs show up as unexplained counter positions and broken predecessor links. That means the supplied evidence cannot reconstruct those positions. It does not show that the authority never made them, nor that anyone withheld them.
• Missing bytesartifact-unavailable is not a failure. It says the digest match was not checked, not that it would have failed.
• The manifestIt is unsigned. Every field in it, including generatedAt, is advisory. The contents hash detects transport corruption; it authenticates nothing unless the hash value itself reached you through a channel you trust.
• TimeUnsigned metadata times inside proofs, manifest times, file modification times and archive entry times carry no weight. Wall-clock bounds come only from verified block evidence (for earlier proofs, the anchor witnesses; the Base ceiling files), and they bound segments of the chain; no individual proof’s exact time is ever established.
• CompletenessThe bundle proves what it contains, not what the operator holds. A clean audit shows the supplied proofs are consistent and valid. It does not show that these are all the proofs that exist, or that no conflicting proof exists outside the bundle.
• FailuresA failure belongs to an object, not to the bundle. A bundle containing an invalid proof is not an invalid bundle; the report names the object’s failure and moves on.

If you do not trust this tool

You do not have to. The audit package and the verifier it delegates to (@mikeargento/bitgraph-verify) are MIT-licensed source you can read: packages/audit/ and packages/verify/ in the repository. The bundle format is specified precisely so a stranger can reimplement both the producer and the consumer from the document and check the same evidence independently.

Where next

• VerificationWhat one proof’s checks are, in order, and what each result means.
• PlayerEvaluate ordering rules over the proofs in a bundle and get a reproducible verdict.
• Bundle FormatThe wire format, the contents hash and the witness procedure, in the repository.