Every receipt heso signs is also added to a transparency log: an append-only history of what your agents did. Once a receipt lands in the log it cannot be quietly removed, edited, or reordered. If anyone tries, the proofs below stop adding up.

The log is built on a standard tamper-evident log, the same kind certificate transparency uses, so the proofs verify with off-the-shelf tools, not just ours. Anyone can ask for proof that a given receipt is in the log, and that today’s log is an honest extension of yesterday’s, then check it themselves.

What you can prove

There are two questions the log answers, and you can ask either one for free.

Inclusion

A specific receipt is in the log. You give heso an action_hash and get back proof that it sits at a fixed spot under a signed checkpoint.

Consistency

The log only grew. Given an earlier checkpoint and a later one, the proof shows the later log contains everything the earlier one did, in the same order, with nothing dropped or rewritten.

The signed checkpoint

Periodically heso publishes a checkpoint: a small note that says how big the log is and what its current state is, signed by heso’s log key. Every inclusion and consistency proof is checked against a checkpoint, so a proof is only as trustworthy as the signature on the note it points to.

The checkpoint and the log key are public. You do not need a heso account or an API key to read them.

# the most recent published checkpoint: size, state, and heso's signature
curl https://api.heso.ca/v1/transparency/checkpoint/latest

Pin the log key out of band

A proof tells you a receipt is committed under a checkpoint signed by some key. It is only meaningful if that key is heso’s. Fetch the log key once, keep your own copy, and check every checkpoint against the copy you trust, not the one served alongside the proof.

Prove a receipt is in the log

Ask for an inclusion proof by org and receipt hash. You get back proof material only, never receipt content, so the endpoint is safe to leave public.

Bash

# replace ORG_ID and ACTION_HASH with your org's uuid and the receipt's hash
curl https://api.heso.ca/v1/transparency/inclusion/ORG_ID/ACTION_HASH

Fetch the checkpoint and the proof
Pull the latest checkpoint and the inclusion proof for your action_hash.
Check the signature
Confirm the checkpoint note is signed by the log key you pinned. A bad or missing signature means stop.
Recompute and compare
Walk the proof from your receipt up to the checkpoint state. If it matches, the receipt is provably in the log. If it does not, something was tampered with.

A miss is honest, not an error

If a receipt is too new to be covered by a published checkpoint yet, the inclusion endpoint returns a plain not-found. That is the log being honest about what it has anchored so far, not a failure.

Prove the log only grew

A consistency proof compares two checkpoints and shows the later one is an append-only extension of the earlier one. No receipt was removed, and nothing was reordered behind your back. This is the check a witness or an auditor runs over time to keep heso honest.

Bash

# prove checkpoint 12 grew honestly into checkpoint 30
curl "https://api.heso.ca/v1/transparency/consistency?from=12&to=30"

Where this fits

Verifying a single receipt and verifying the log are two different jobs. Verify tells you one receipt is genuine and untampered. The transparency log tells you that receipt is part of a history heso cannot quietly rewrite. Use both: verify the receipt, then prove it is in the log.

Verify a receipt

Check that one receipt is genuine and untampered, offline, anywhere.

The chain

How receipts are kept in order, the ordering the log is built on.

Limits

The log proves the history is append-only and that a given receipt is part of it. It does not prove the action behind a receipt was correct or that your agent did the right thing. It proves nobody changed the record after the fact. And a receipt only shows up once it is covered by a published checkpoint, so the most recent activity may not be anchored yet.