The audit trail and the chain

The idea

A bookkeeping record is a claim about the past, and the claim is only useful if you can tell whether it has been altered since it was written.

ByteBook seals every entry with a SHA-256 fingerprint: a short string of characters computed from the entry's own contents — its date, its accounts, its amounts, its description. Change any of that and the fingerprint changes. There is no way to adjust an entry and keep the same fingerprint.

Then it does the second, more useful thing. Each entry's fingerprint is computed including the fingerprint of the entry before it. This is a chain, and it has a property that a list of separate fingerprints does not: altering an entry anywhere in the middle breaks every fingerprint after it. To alter an old entry and leave no trace, you would have to recompute every entry that follows, in order, in secret. The books are a file on a disk, so that is not impossible — but it is no longer a quiet edit.

What the Audit trail page shows

Open Audit trail. ByteBook recomputes the whole chain from the recorded entries, including the voided entries whose fingerprints do not change when they are voided, and reports:

• how many entries there are;
• how many verify;
• how many links are broken, if any;
• a fingerprint of the whole ledger.

If a link is broken, the page says so, and the meaning is specific: something wrote to the books outside ByteBook. That is not a bookkeeping error. It is a statement about the record itself, and it is worth more than a page of clean ticks.

The chain, drawn

The chain page shows the same thing at three scales, because one picture cannot answer both "is this intact?" and "what exactly is in this entry?".

The ribbon is the whole record on a time axis. Each mark is one day, and how tall it is tells you how many entries that day holds. Under the marks runs the chain itself — a line that is solid where the links hold and broken where they do not. Under that, each sealed period is drawn as a span across the days it covers, linked to the period before it. Everything the record has ever held is in that ribbon: it is not sampled and it is not paginated.

The chain below is the entries in order, each one a block and each fingerprint a line between two. The window starts at the most recent two dozen entries; click a day on the ribbon to open it, or press Everything to see the lot. Click a block to read the entry behind it, click a link to see the two hashes it joins. A correction is a block too: a voided entry stays in the picture, because it is part of the history.

The panel beside them takes one entry apart. It shows what was hashed — the date, the reference, the description, the type, the accounts and the amounts — and the fingerprint that came out, and which entry before it points at it. Then it offers the thing a chain cannot offer on its own: Fetch the proof. That returns the handful of sibling hashes that carry this one entry up to the Merkle root of the whole ledger, and whether they arrive there.

Two details are worth noticing, because they are the difference between a picture and evidence:

• The page draws only what ByteBook recomputed from the entries when you asked for it, and it does no arithmetic of its own. Even the proof is checked by ByteBook and reported on the page.
• The ribbon can be read in one glance, which matters when the answer is "no": a break is a break in the line, not a block you have to hunt for.

Proving one entry without the whole ledger

The chain and the tree answer two different questions, and it is worth keeping them apart.

The chain asks has anything moved? To answer it you have to read every entry from the beginning, because each one is built on the one before. That is the right question for the owner of the books and the wrong one for somebody checking a single invoice.

The Merkle tree asks was this entry in the ledger? The fingerprints of all the entries are folded together in pairs until one value is left, and that value is the Merkle root. To prove that one entry belongs, you need its fingerprint and one sibling hash per level: about ten hashes for a thousand entries, not a thousand.

That is what Fetch the proof gives you, and what chapter 14 puts in the file an external auditor can check on their own computer.

Where this fits in an audit

The chain is not a replacement for an auditor's procedures, and ByteBook does not claim it is. It answers one narrow question extremely well: has the record changed since it was written?

That question sits underneath several others. When an auditor relies on the books, they are relying on the information in them being relevant and reliable ISA (NZ) 500.7. A chain of fingerprints is evidence about reliability that is produced by the system itself, on every entry, rather than sampled.

Procedure A01 in chapter 13 reports it as part of the routine: entries verified, broken links, and the fingerprint of the whole ledger. Procedure A12 then asks the next question: does a period that was sealed still match the ledger as it stands now?

What catches what

Five things can happen to a record, and they are not caught by the same thing. Knowing which is which is most of what makes the rest of this part useful.

If somebody…	What catches it
changes a figure in an old entry	the entry's own fingerprint: the block turns red
deletes an entry from the middle	the link the next entry carries
posts into a period that was already sealed	procedure A09, and the pack itself
rewrites the whole record, end to end	a receipt held outside the file
enters a figure that is simply wrong	a person

The fourth line is the one people find surprising, and it is worth being exact about. Somebody with the file, the algorithm and the patience can recompute every fingerprint and leave a chain that verifies perfectly. Nothing inside the file can detect that, because there is nothing inside the file that disagrees. A copy of the fingerprints held somewhere else can, which is what a checkpoint receipt is for. See chapter 14.

What to do when a link breaks

1. Stop and find out what wrote to the file. Restore, tooling, a script, a copy edited by hand — a broken chain always has a cause, and the cause is the finding.
2. Do not re-seal anything. Recomputing fingerprints to make a broken chain look intact destroys the only evidence you have.
3. Record what you found. In a training exercise, that note is the answer.

What gets hashed, exactly

It is worth reading once, because it is where a chain either holds or leaks. The fingerprint of an entry is computed from this text and nothing else:

id | date | reference | description | type | fingerprint of the entry before
   | account:amount:amount | account:amount:amount | …

Voiding an entry afterwards does not change its fingerprint. That is deliberate: voiding is a legitimate correction, and a correction that broke the chain it sits in would make the chain useless. The reversal is posted beside the original, and both stay in the chain.

Two consequences follow, and both are worth knowing before somebody asks.

What the fingerprint covers: the money, and the words that identify the entry. A change to any of those is caught, on that entry and on every entry after it.

What it does not cover: the tax code on a line, the contact, and the line description. Those can change without breaking the chain. A chain that verifies is therefore proof that the amounts and the entry itself are as they were written, and not proof that the GST treatment is the one somebody typed.

That gap is why the tree exists. Its leaf for an entry is a fingerprint of every field the entry holds — the tax codes, the contacts and the line descriptions included — written as JSON with sorted keys so it cannot be rearranged into a different entry. The leaf is not stored and not chained: it is recomputed from the row whenever it is needed, which is what lets it afford to be that greedy.

So there are two fingerprints, and it is worth keeping them apart:

• the chain fingerprint covers the money, and holds the chain together;
• the print in the tree covers everything, and is what an entry is proved against and what a receipt witnesses.

Together they mean a change to a tax code leaves the chain intact and still cannot survive a receipt you kept.