Savings Ledger

Every time LeanCTX compresses a read, a search or a shell result, it records the saving in a local savings ledger. The ledger is the source of truth behind token savings, the gain dashboard and the community metrics — and, with one command, it becomes a tamper-evident, cryptographically signed receipt you can hand to a manager, a client or a finance team to prove exactly how much you saved.

Nothing leaves your machine unless you choose to share it, and even then only aggregate numbers travel — never your code, file paths or prompts.

An append-only hash chain

The ledger lives at ~/.lean-ctx/savings/ and is an append-only SHA-256 hash chain: every event commits the hash of the previous one, so editing, reordering, inserting or deleting any past entry breaks the chain. This is the same tamper-evident pattern LeanCTX uses for its audit trail — applied to your savings.

Because the chain is self-checking, verify can tell you in milliseconds whether the local history is intact, and the chain head (the latest hash) acts as a fingerprint for your entire savings history.

The savings commands

Command	What it does	Leaves your machine?
lean-ctx savings summary	Verified totals: net tokens, $ saved, by-model and by-tool breakdown (default)	No
lean-ctx savings verify	Checks the local SHA-256 chain is intact (no tampering)	No
lean-ctx savings export	Dumps every raw event as JSON (for your own analysis)	No
lean-ctx savings sign	Builds + Ed25519-signs a portable aggregate artifact	Only the file you choose to share
lean-ctx savings verify-batch <file>	Verifies a signed artifact offline — integrity + origin, no ledger needed	No (runs on any machine)

Signing: a portable, tamper-evident receipt

lean-ctx savings sign reads your local ledger, snapshots the aggregate totals plus the chain head, and signs the whole thing with your machine's persistent Ed25519 key (the same per-machine identity used for agent handoffs). The result is a small JSON file that is self-verifying — it carries its own public key and signature.

$ lean-ctx savings sign
Signed savings batch written to ~/.lean-ctx/savings/signed-batch-v1_20260602T184500Z.json
  Net saved:  12.8M tokens (~$32.41) over 1,240 event(s)
  Chain head: 9f2c4b…e1a7   (SHA-256 tip of your whole history)
  Chain:      intact (SHA-256)
  Signer key: 7b1e90…c4d2   (your Ed25519 public key)

Verify anywhere (no ledger needed):  lean-ctx savings verify-batch ~/.lean-ctx/savings/signed-batch-v1_20260602T184500Z.json

Write it somewhere specific with --out:

$ lean-ctx savings sign --out ./q2-savings-attestation.json

Verifying anywhere — offline

Anyone who receives the artifact can check it with verify-batch. No LeanCTX install history, no network, no access to your ledger or code is required — the signature alone proves both that the file is unaltered and that it was produced by the holder of that public key.

$ lean-ctx savings verify-batch ./q2-savings-attestation.json
Signed savings batch: VALID
  Signed by:  7b1e90…c4d2
  Agent:      local
  Created:    2026-06-02T18:45:00Z
  lean-ctx:   3.7.0
  Net saved:  12.8M tokens (~$32.41) over 1,240 event(s)
  Chain head: 9f2c4b…e1a7

Change a single byte — bump the token count, swap the public key, rewrite the chain head — and verification fails loudly:

$ lean-ctx savings verify-batch ./tampered.json
Signed savings batch: INVALID — signature does not match payload (tampered or wrong key)

What's inside the artifact — and what never is

The signed batch (schema lean-ctx.savings-batch, v1) contains only aggregates an auditor needs, plus the cryptographic commitments:

Field	Meaning
totals	Net tokens saved, $ saved, event count, and the top by-model / by-tool rows
last_entry_hash	The SHA-256 chain head — binds the totals to the exact history that produced them
chain_valid	Whether the local chain verified intact at signing time
created_at / lean_ctx_version	When it was signed and with which version
signer_public_key / signature	Ed25519 public key and signature (hex) — make the file self-verifying

Never included: raw events, file names or paths, source code, prompts, command contents, or per-event timestamps. Signing is an aggregate-only operation by construction — the payload is a dedicated struct, so a private field cannot accidentally be serialized.

The trust model

A verified artifact answers two independent questions at once:

• Integrity — the numbers have not been altered by a single byte since signing. The Ed25519 signature covers the entire canonical payload.
• Origin — the artifact was produced by the holder of a specific keypair. Pair the public key with your name once (in an email, a README, a signed commit) and every future artifact from that key is attributable to you.

The embedded last_entry_hash ties the aggregate totals to a concrete append-only chain: you cannot sign totals that don't correspond to a real, intact history. Together that makes the artifact a verifiable receipt rather than a screenshot anyone could fake.

A user journey: prove your savings in three commands

You've been using LeanCTX for a sprint and want to show your lead the real payoff — without sending them your repository or a screenshot they'd have to trust.

1. Check the receipt is intact. lean-ctx savings verify confirms the local chain has not been tampered with.
2. Sign it. lean-ctx savings sign --out ./sprint-savings.json produces a portable, aggregate-only attestation.
3. Share & let them verify. Send the JSON. They run lean-ctx savings verify-batch ./sprint-savings.json on their own machine and see VALID with your net tokens and dollars — provably yours, provably unaltered, and not a line of code in sight.

Want the full command-by-command walkthrough? See the Proof & Audit journey.

When to reach for it

• Justify the tool to a lead or finance. A signed dollar figure beats an unverifiable claim when you're defending a line item or a renewal.
• Bill or report savings to a client. Attach an attestation to an invoice or status report; they can verify it themselves, offline.
• Procurement & compliance. A tamper-evident artifact with a version stamp and chain commitment fits an evidence trail far better than a spreadsheet.
• Personal record. Snapshot your savings at the end of each quarter and keep a verifiable history.

Related: Token Savings · Observatory · Security & Integrity