Sealed packs and working papers

Sealing a period

Fingerprints protect entries one at a time. A sealed pack protects a whole period at once.

When you seal a period, ByteBook takes its entries, its figures, the fingerprint of the whole ledger, and the fingerprint of the pack before it, and hashes them together into one value. That value is the pack's fingerprint. Verifying a pack recomputes it from the ledger as it stands now.

The consequence is sharp and easy to demonstrate:

• Backdate an entry into a sealed period and the pack's fingerprint changes. Verification fails, and it fails because of the change, not because something is missing.
• Void an entry inside a sealed period and the same thing happens — correctly, because the period's totals moved, and moving them after the fact is precisely what a sealed pack is designed to detect.

Linking each pack to the one before it means the periods form a chain of their own, one level up from the entries.

Timeline: what a pack protects

1. Work the period. Invoice, code the bank, file GST.
2. Check it. Run the assurance procedures; deal with what they found.
3. Seal it. Open Audit trail → Sealed packs, choose the period and press Seal this period. ByteBook records the pack and its fingerprint.
4. Later, verify it. Reopen the pack and check it. The fingerprint is recomputed from the entries as they are now. Match or no match, with no discretion in between.
5. If it fails, find out why. In a training exercise the cause is usually a backdated entry, and finding it is the exercise.

Working papers

Every procedure offers a working paper as a CSV. That is the format an auditor actually wants: a table you can open, check, and attach to a file, with the columns named and the figures traceable.

Two things make a working paper useful, and both are about the reader rather than the writer:

• It says what was done. Not "bank checked", but the balance in the ledger, the balance on the statement, the difference, and the date.
• It says what it found. Four exceptions, listed, so that a second person can re-perform the check and get the same answer.

This is ISA 230.8 applied to a small business: documentation sufficient for an experienced auditor with no previous connection to the engagement to understand what was done, what the results were, and what was concluded.

Assembling the file

There is a finishing step, and it has a deadline. The auditor assembles the documentation into an audit file and completes the administrative process of assembling the final audit file on a timely basis after the date of the auditor's report ISA (NZ) 230.14. Where there is a legal or regulatory deadline to complete the assembly, the standard's own period applies.

In ByteBook the equivalent is short: run the procedures, download the working papers (the CSV button on each procedure), seal the period, record a checkpoint (Audit trail → Checkpoints → Check the record now), take a backup, and put the pack's fingerprint in the file. The fingerprint is one line, and it is what lets a reader verify the period years later without re-reading everything.

Handing the record to somebody outside

An external auditor is usually given a PDF and a set of CSVs, and then has to take the numbers on trust. Audit trail → Hand it over produces the alternative: one folder, or one zip, containing the record itself and a small checker that tests it. In the training exercises, the same checks are on the Audit trail and The chain pages; running verify.py is the receiving auditor's job, not the learner's.

In the bundle	What it is
entries.csv	one row per entry, with the fingerprint it carries
lines.csv	one row per journal line, which is what the fingerprint covers
packs.json	every sealed period, with the figures it sealed
checkpoints.json	what the record looked like each time it was witnessed
receipts/	one receipt per checkpoint, to keep or pass on
manifest.json	what is inside, and a fingerprint of every file
verify.py	the script that checks all of the above
README.txt	what the folder is, in words

The auditor unpacks the folder and runs one small checker, verify.py (a reader who wants to repeat the checks inside ByteBook can use The chain → Check the record instead):

python3 verify.py

Python is a free program; if it is installed, that is all the checker needs. No ByteBook, no internet, no account. The script recomputes every entry fingerprint from the recorded fields, walks the chain, rebuilds the Merkle root, reproduces each sealed pack, checks the chain of checkpoints, and reads the receipts back against the entries. Then it prints PASS or FAIL, with the reason for anything it could not reproduce.

Three things about it are deliberate.

It reports, it does not judge. If the chain is broken, the bundle still exports and says so on its first page. An export that hid a broken chain would be the one failure that matters.

It is checkable years later. The bundle does not need this program, or this version of it, to be understood. The script is a page of plain Python that a reader can read before running.

A pass is narrower than it sounds. It means the files are exactly as exported and the record they describe holds together. It does not mean the entries are correct, that money moved, or that a price was agreed.

A read-only key, for an internal auditor

An external auditor usually wants a file. An internal auditor, or the organisation's own scripts, may want to pull the figures repeatedly and test them with their own tools. That is what an audit key is for: a named, revocable, read-only credential for the audit API.

The whole surface is twelve GET endpoints, all of which show what the pages show:

curl -H "Authorization: Bearer bbk_…" http://127.0.0.1:8321/api/audit/verify

• /verify — is the chain intact, and the Merkle root
• /entries, /lines — the rows, as JSON or CSV
• /proof/{id} — one entry, proved against the whole ledger
• /packs, /checkpoints — what was sealed and what was witnessed
• /procedures, /working-paper/{code} — the programme and its papers
• /bundle — the whole folder, as a zip
• /tokens, /access-log — which keys exist, and who read what, including the attempts that were refused
• /help — the list itself, for a tool that wants to discover it

Four properties make this something an organisation can actually hand out.

1. A key cannot write. It cannot post, edit, void, seal, or change a setting. It is refused in the language it asked in — JSON, with a reason — rather than being quietly redirected.
2. A key is shown once. Only its SHA-256 is kept, so a copy of the database does not hand anybody a working key, and a lost key is replaced rather than recovered.
3. A key can be taken away. Revoking it stops the next request, and the attempt is recorded.
4. Using a key leaves a trace. Every read is written to the access log with the key's name, the path, and how many rows were handed over. An auditor reading the books leaves a trace in the same record they came to read, which is the arrangement they would ask for if they designed it.

A checkpoint, and why a receipt matters

A checkpoint is one line of evidence. Every time somebody checks the record — or seals a period, which does the same thing by itself — ByteBook writes down how many entries there were, the fingerprint of the last one, and the Merkle root of the whole ledger. Each checkpoint includes the fingerprint of the checkpoint before it, so the log of checks is a chain of its own.

On its own that is still just another table in the same file. It becomes evidence when a copy leaves the file, and that copy is a receipt: two dozen lines with the business name, the date, the entry count, the last fingerprint, the Merkle root and the checkpoint's own fingerprint.

Keep a receipt the way you would keep a bank statement. Email it to your accountant at every month end, print it, drop it in the audit file. It costs nothing. What it buys is this: a record rewritten as a whole can rebuild every entry fingerprint, but it cannot reach the copy in somebody else's inbox.

To check one, paste it into Audit trail → Checkpoints → Check a receipt. The printed version and the JSON version both work. ByteBook says whether the books still contain everything the receipt witnessed, and how much work has happened since — because more work after a checkpoint is normal, and a record shorter than one is not.

What stays outside the program

ByteBook can prove that a period has not changed, that the two sides of every entry are equal, that the bank agrees, and that the figures on the reports can be reproduced from the rows. Those are arithmetic and record-integrity claims, and a computer is good at them.

It cannot judge whether a debt will be collected, whether a provision is adequate, whether a related party transaction was on arm's length terms, or whether a business is a going concern. Those are judgements, and they come with a person's name attached.

Knowing which side of that line you are standing on is most of what makes an auditor useful.