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 in the data dir at $XDG_DATA_HOME/lean-ctx/savings/ (legacy single-dir installs: ~/.local/share/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)

The ledger's net-tokens figure is the same net_tokens_saved that lean-ctx gain --json reports — savings reconciled against the provider bill, net of lean-ctx's own injected overhead (per-turn tax × turns). It can go negative on short sessions, and says so, so the receipt never overstates the win.

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 $XDG_DATA_HOME/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 $XDG_DATA_HOME/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.8.6
  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 Prove It 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