Transparency Log
What it is
Each CMDash deployment keeps one append-only transparency log of the proof receipts it issues. It is a Merkle tree (RFC 9162 hashing). The log proves a receipt was published and where it sits in the order of publication. It does not know who issued a receipt or what it says: an entry is a salted digest of the receipt, so a log entry reveals nothing without the receipt.
The log signs a checkpoint (the number of entries and one hash covering all of them) roughly every ten minutes. Log version 1 adds two things on top of the first version:
- Consistency proofs. A proof that the tree at an older checkpoint is a prefix of the tree at a newer one: nothing the log signed earlier was changed or removed. Anyone who kept an older checkpoint can ask whether today's log still extends it.
- Checkpoint history. The list of every signed checkpoint, newest first, with each signed note verbatim, so a reader can check them.
All of it is public and needs no account. The routes are served from your deployment under
/api/.well-known/cmdash-proof-log/: the log key document, the latest checkpoint, a checkpoint
of a given size, an inclusion proof for a receipt digest, a consistency proof between two sizes,
and the checkpoint history.
When to use it
When you receive a receipt and want to know it was really published, or when you want to check that a log has not rewritten its history or shown different readers different histories.
Before you start
- Tier: none. The log is part of every deployment that issues receipts.
- Role: none to read. Receipts are issued by your own workspace; see Proof receipts.
- What you need: a receipt for the inclusion check; a checkpoint you saved yourself on an earlier day (or took from a receipt) for the strongest consistency check.
How to
See where a receipt sits in the log
Open the receipt at /proof/<receiptId>: it shows where the log placed it. The
public verifier checks the placement against a signed checkpoint
once you confirm the deployment and let it fetch the checkpoint. If the log never signed a
checkpoint of the receipt's size (a very recent receipt), the verifier checks the receipt without
its log section and says so; it does not call it invalid.
Check the history
The checkpoint history page (/verify/log on the CMDash website, on every deployment's own
verifier route for self-hosted) does the following in your browser:
- Fetches the log key document and the newest checkpoints from the deployment and checks each checkpoint's signature.
- When you ask, fetches the consistency proof between each checkpoint and the one before it and checks that each newer tree extends the older one, using the notes it already holds, never the answer's own copies.
- Checks a checkpoint you paste in, one you saved on another day, against the newest. This is the check that can catch a log showing different people different histories, because the older checkpoint did not come from this page.
Each step reports CONSISTENT, INCONSISTENT or UNVERIFIABLE. A checkpoint no trusted key signed makes the question unanswerable (UNVERIFIABLE), never INCONSISTENT, because anyone can write an unsigned note. If the log served a proof that fails, treat its history as forked and keep both notes.
The same check is in the command-line verifier as the library's checkpoint-consistency function
(@cmdash/proof-verify, 0.2.0 and later).
What it proves and what it does not
- Proves: a receipt is in the log at the stated position, and (with consistency checks) that a later signed tree extends an earlier signed tree.
- Does not prove: that the log key is the right key. The key document comes from the same deployment as the checkpoints, so a signature check shows the checkpoints are that key holder's, not that the key is the one you meant to trust. Independent witness cosignatures are not built. The strongest protection is a checkpoint you saved from a source other than the log.
The history page is reachable but not promoted. The page is on the website, not linked from its navigation, and says so at the top: until the log is announced as a product capability, treat it as a working tool and not as a published commitment.
Common questions
Does the log reveal my receipts? No. An entry is a salted digest; an inclusion proof is served only for a digest the caller already holds.
Is my data in it? No tenant data is read to serve it. The log tables hold signed tree heads, public keys and hashes, and carry no tenant column.
What happens to the log when I leave? Your export carries an inclusion proof for each of your logged receipts. See Exit guarantee.
Related
- Verifying a proof receipt
- Proof receipts
- Exit guarantee
- The specification:
docs/specs/proof-receipt-v0.md, sections 7.1 to 7.9