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 behindtoken savings, thegain dashboard and the community metrics — and, with one command, it becomes a tamper-evident, cryptographically signed receiptyou 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 onlyaggregate 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

The ledger's net-tokens figure is the same net_tokens_saved thatlean-ctx gain --json reports — savings reconciled against the provider bill, net of LeanCTX'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 persistentEd25519 key (the same per-machine identity used foragent 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:

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