{"id":51167033,"url":"https://github.com/thequantumfalcon/kry","last_synced_at":"2026-06-26T20:03:22.650Z","repository":{"id":365417504,"uuid":"1269600203","full_name":"thequantumfalcon/kry","owner":"thequantumfalcon","description":"Verifiable proof-of-efficiency compute credit for LLM spend — prove your inference savings instead of trusting a dashboard. Pure-Python stdlib, zero-dependency.","archived":false,"fork":false,"pushed_at":"2026-06-17T07:54:24.000Z","size":6432,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T09:25:17.610Z","etag":null,"topics":["attestation","cost-optimization","finops","inference-cost","llm","llm-cost-optimization","llm-routing","llmops","model-routing","proof-of-efficiency","python","tee","tlsnotary","verifiable-compute","zero-dependency"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thequantumfalcon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T23:04:13.000Z","updated_at":"2026-06-17T08:03:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thequantumfalcon/kry","commit_stats":null,"previous_names":["thequantumfalcon/kry"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/thequantumfalcon/kry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thequantumfalcon%2Fkry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thequantumfalcon%2Fkry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thequantumfalcon%2Fkry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thequantumfalcon%2Fkry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thequantumfalcon","download_url":"https://codeload.github.com/thequantumfalcon/kry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thequantumfalcon%2Fkry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34831250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["attestation","cost-optimization","finops","inference-cost","llm","llm-cost-optimization","llm-routing","llmops","model-routing","proof-of-efficiency","python","tee","tlsnotary","verifiable-compute","zero-dependency"],"created_at":"2026-06-26T20:03:21.795Z","updated_at":"2026-06-26T20:03:22.643Z","avatar_url":"https://github.com/thequantumfalcon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# kry\n\n[![CI](https://github.com/thequantumfalcon/kry/actions/workflows/ci.yml/badge.svg)](https://github.com/thequantumfalcon/kry/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/thequantumfalcon/kry/actions/workflows/codeql.yml/badge.svg)](https://github.com/thequantumfalcon/kry/actions/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/thequantumfalcon/kry/badge)](https://scorecard.dev/viewer/?uri=github.com/thequantumfalcon/kry)\n[![License](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue.svg)](LICENSE.md)\n[![Python](https://img.shields.io/badge/python-%E2%89%A53.11-blue.svg)](https://www.python.org/)\n\n### don't trust your LLM savings dashboard. verify it. 🧾\n\n**kry turns the usage logs you already have into a _stranger-verifiable_ proof that your caching \u0026 routing savings ledger is **intact and honestly priced** — cryptographically tamper-evident, recomputed against public pricing, with the trust you place in the operator made an explicit, machine-checked `veracity_floor`. It proves integrity, not that the savings happened (that's the floor's job). No prompts exposed, zero dependencies.**\n\n`zero-dependency` · `pure Python stdlib` · `Python ≥ 3.11` · `stdlib suite green` · `readiness: research_grade`\n\n![kry running live — earn → mint → attest → a stranger verifies → carbon, then a real routing log becomes a verifiable savings statement](media/kry-demo.gif)\n\n\u003csub\u003eThe package actually running, start to finish — the proof is the attestation plus verifier, not the animation. Prefer text? Full transcript right below. 👇\u003c/sub\u003e\n\n\u003csub\u003e💸😭 \u003cem\u003eyour inference bill is about to cry.\u003c/em\u003e\u003c/sub\u003e\n\n\u003c/div\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📜 Full demo output — readable text\u003c/b\u003e (a representative run, ANSI-stripped; produced by \u003ccode\u003ebash examples/demo.sh\u003c/code\u003e)\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```text\n  K R Y   —   Proof-of-Efficiency Compute Credit\n  earn by provably avoiding inference cost · prove it to a stranger · stdlib only\n\n━━━━━━ FULL LIFECYCLE  —  earn → mint → attest → STRANGER-verifies → carbon ━━━━━━\nThe whole loop, on real efficiency events, in one program:\n\n──────────────────────────────────────────────────────────────────────\n1. EARN — efficiency events become KRY (edge-weighted by what they avoided)\n──────────────────────────────────────────────────────────────────────\n  balance:            2,436.00 KRY\n  lifetime earned:    2,436.00 KRY\n  frontier basis: $25.0/M output tokens   (40,000 KRY / USD)\n\n──────────────────────────────────────────────────────────────────────\n2. RETAIN — the honest value TODAY (money kept, no counterparty needed)\n──────────────────────────────────────────────────────────────────────\n  retained_usd:                 $0.0609\n  value_type:                   retained_dollars (money kept) — NOT a tradeable token\n  external_counterparty_exists: False  (honest label)\n\n──────────────────────────────────────────────────────────────────────\n3. MINT — every earn is a SHA-256 hash-chain receipt (tamper-evident)\n──────────────────────────────────────────────────────────────────────\n  receipts:    3\n  chain_tip:   eae1b80e8baedc1e...\n  chain_valid: True\n  veracity_floor: 0.3924  (fraction externally anchored vs operator self-report)\n\n──────────────────────────────────────────────────────────────────────\n4. ATTEST — a public, content-sealed proof of the balance\n──────────────────────────────────────────────────────────────────────\n  wrote 3 links, total 2,436.00 KRY -\u003e \u003ctmpdir\u003e/attestation.json\n  (contains only hashes + aggregates — no prompts, responses, or model\n   names beyond the event type; safe to hand to a third party)\n\n──────────────────────────────────────────────────────────────────────\n5. VERIFY — a STRANGER checks it with stdlib only (the differentiator)\n──────────────────────────────────────────────────────────────────────\nKRY external verification — attestation\n  receipts:        3 (recomputed from links)\n  total_kry:       2436.0 (recomputed from links, not the declared field)\n  veracity_floor:  0.3924 (fraction externally anchored; rest rests on operator self-report)\n                   ↳ anchored tiers are chain-bound LABELS — run kry_tee_verify /\n                     kry_tlsn_verify to independently check the underlying evidence doc\n  price basis:     $25.0/M frontier, as of 2026-06-03 (magnitude recomputed from the public price table)\n  anchor check:    NONE — ⚠ the externally-anchored fraction is OPERATOR-ASSERTED\n                   here: a genesis re-mint with upgraded tiers passes this check.\n                   Re-run with --anchor \u003coperator's pre-published chain head\u003e to make\n                   a retroactive re-mint detectable.\n  VERDICT: VALID — integrity + conservation + magnitude (where checkable) hold; trust surface honest (read veracity_floor for what is operator-asserted).\n\n──────────────────────────────────────────────────────────────────────\n6. CARBON — second denomination: avoided inference -\u003e CO2 (ESTIMATE)\n──────────────────────────────────────────────────────────────────────\n  kry_avoided:        2,436.00\n  energy_kwh_avoided: 0.001353 kWh\n  co2_grams_avoided:  0.5413 g\n  status:             ESTIMATE — not a certified carbon credit (grid region unknowable: inference_geo redacted)\n\n══════════════════════════════════════════════════════════════════════\nDone. The balance was minted from real efficiency events, anchored in a\ntamper-evident chain, and verified by a program that trusts nothing in\nthis package. That is what 'proof-of-efficiency' means in practice.\n(temp data dir \u003ctmpdir\u003e — safe to delete)\n══════════════════════════════════════════════════════════════════════\n\n━━━━━━ OPERATOR VIEW  —  a real routing log → a verifiable savings statement ━━━━━━\nSAVED vs SPEND + veracity_floor; --mint anchors it, --attest emits the public proof.\n  \n    minted savings into the chain; attestation -\u003e \u003ctmp\u003e/att.json\n  KRY savings report\n    records analysed:     48  {'cache_hit': 10, 'holdout': 35, 'displacement': 1, 'paid_call': 2, 'free_call': 0}\n    SAVED (retained):         3,080.50 KRY   = $0.0770\n    SPEND (real):            17,017.60 KRY   = $0.4254\n    efficiency_ratio:     15.33%  (saved / (saved+spend))\n    veracity_floor:       70.78%  (holdout-validated + provider-metered share of savings)\n      self_reported:            900.00 KRY\n      holdout_validated:      1,798.10 KRY\n      provider_metered:         382.40 KRY\n    holdout measurement:  1 class(es) measured; cost 15,000.00 KRY ($0.3750) — the price of veracity\n    by request-class:\n      code                                 treated=0     holdout=0    p̂=—                saved=    382.40 KRY [provider_metered]\n      greet                                treated=2     holdout=0    p̂=—                saved=      0.00 KRY [self_reported]\n      summarize                            treated=5     holdout=35   p̂=86% (CI≥71%)     saved=  1,798.10 KRY [holdout_validated]\n      translate                            treated=3     holdout=0    p̂=—                saved=    900.00 KRY [self_reported]\n\n━━━━━━ STRANGER CHECK  —  verify that statement with stdlib only (imports nothing from KRY) ━━━━━━\n  KRY external verification — attestation\n    receipts:        11 (recomputed from links)\n    total_kry:       3080.4984 (recomputed from links, not the declared field)\n    veracity_floor:  0.7078 (fraction externally anchored; rest rests on operator self-report)\n                     ↳ anchored tiers are chain-bound LABELS — run kry_tee_verify /\n                       kry_tlsn_verify to independently check the underlying evidence doc\n    price basis:     $25.0/M frontier, as of 2026-06-03 (magnitude recomputed from the public price table)\n    anchor check:    NONE — ⚠ the externally-anchored fraction is OPERATOR-ASSERTED\n                     here: a genesis re-mint with upgraded tiers passes this check.\n                     Re-run with --anchor \u003coperator's pre-published chain head\u003e to make\n                     a retroactive re-mint detectable.\n    VERDICT: VALID — integrity + conservation + magnitude (where checkable) hold; trust surface honest (read veracity_floor for what is operator-asserted).\n  ↑ confirmed by code that does NOT trust the producer — the whole point.\n\n━━━━━━ T2  —  the same trust model, anchored to a REAL provider's TLS response ━━━━━━\nTLSNotary proves what openrouter.ai returned, verifiable by a stranger with real CA roots.\nMechanism proven (2026-06-04) — NOT yet trustless: self-hosted notary != neutral party (§5).\n  docs/KRY_T2_FINDINGS_REPORT.md  ·  tlsnotary/\n\n  earn → mint → attest → verify → (T1 reconcile / T2 notarize).  That is proof-of-efficiency.\n```\n\n\u003c/details\u003e\n\n---\n\nKRY is earned by avoiding inference cost (a cache hit, a compression, a cheaper-model\ndisplacement) and spent on routing permission. The interesting part is not the ledger —\nit's that the whole system is built around a single uncomfortable question:\n\n\u003e **A hash chain can prove a balance is *intact*. It cannot prove the savings *happened*.**\n\u003e So how much do you have to trust the operator — and can that number be made explicit,\n\u003e machine-checkable, and driven toward zero?\n\nThat question — **integrity ≠ veracity** — is the spine of this project. Everything\nbelow is organized so the answer is *computed and labeled*, never asserted.\n\n\u003e [!IMPORTANT]\n\u003e **Value today = retained dollars** (money kept, provable against real provider\n\u003e pricing). KRY is **not** a tradeable instrument: `external_counterparty_exists = False`\n\u003e until a counterparty accepts it. No token sale, no exchange, no speculation. See\n\u003e [Legal posture](#legal-posture).\n\n---\n\n## Contents\n\n- [The idea in 60 seconds](#the-idea-in-60-seconds)\n- [Quickstart](#quickstart)\n- [How it works](#how-it-works)\n- [Veracity: the trust ladder](#veracity-the-trust-ladder)\n- [Magnitude: publicly-checkable arithmetic](#magnitude-publicly-checkable-arithmetic)\n- [Readiness: a computed grade, not a claim](#readiness-a-computed-grade-not-a-claim)\n- [Modules](#modules)\n- [Verifying as a stranger](#verifying-as-a-stranger)\n- [Honest limitations](#honest-limitations-disclosed-not-hidden)\n- [Repository layout](#repository-layout)\n- [Legal posture](#legal-posture)\n- [Documentation](#documentation)\n\n---\n\n## The idea in 60 seconds\n\nEvery avoided inference call has a dollar value: the price you *would* have paid the\nfrontier model, minus what the cheaper path actually cost. KRY mints that retained value\ninto a tamper-evident, hash-chained ledger, and exposes a **public proof surface** so a\nthird party can independently re-derive the numbers without seeing a single prompt.\n\nWhat KRY refuses to do is pretend the proof is stronger than it is. A cache hit is a\n*counterfactual* — a call that never happened — and nothing outside your runtime can\nwitness a call that was never made. KRY makes that limit a first-class, labeled property\n(`veracity_floor`) instead of hiding it behind a green checkmark.\n\n| KRY **is** | KRY **is not** |\n|---|---|\n| An internal efficiency \u0026 integrity meter | A cryptocurrency or tradeable token |\n| A stranger-verifiable proof-of-savings artifact | A claim that savings are externally guaranteed by default |\n| An honest accounting discipline (integrity vs veracity, separated) | A speculation, treasury, or exchange |\n\n---\n\n## Quickstart\n\nNo runtime package dependencies. `pip install -e .` works without build-time\ndownloads. Tests use `pytest` and lint uses `ruff`.\n\n```bash\n# 0) Install the package from this checkout (no runtime dependencies)\npython3 -m pip install -e .\n\n# 1) Watch the whole thing run, narrated and paced (the GIF above, live)\nbash examples/demo.sh\n\n# 2) Or the core lifecycle directly (uses a throwaway temp data dir)\npython3 examples/try_kry.py\n# earn → retained_dollars → mint (hash chain) → attest → a STRANGER verifies → carbon estimate\n\n# 3) Turn a routing log into a verifiable savings statement\n# examples/sample_usage_log.jsonl is synthetic; use real logs for external validation.\ntmp=$(mktemp -d \"${TMPDIR:-/tmp}/kry-quickstart.XXXXXX\")\nexport KRY_DATA_DIR=\"$tmp/kry_data\"\npython3 scripts/kry_doctor.py\n# local health check for the verifier/reviewer surface; warns that external evidence is still required\npython3 scripts/kry_savings_report.py examples/sample_usage_log.jsonl\n# reports SAVED vs SPEND and the veracity_floor (holdout-validated vs self-reported)\npython3 scripts/kry_savings_report.py examples/sample_usage_log.jsonl --mint --attest \"$tmp/att.json\"\npython3 scripts/kry_verify.py \"$tmp/att.json\" # the stranger's check — stdlib only\n# ↑ WITHOUT --anchor, the externally-anchored fraction is operator-asserted (a genesis re-mint\n#   passes). The operator PUBLISHES this anchor out-of-band, then a stranger checks against it:\npython3 scripts/kry_chain_anchor.py export \u003e \"$tmp/anchor.json\"\npython3 scripts/kry_verify.py \"$tmp/att.json\" --anchor \"$tmp/anchor.json\" # re-mint now detectable\npython3 scripts/kry_verified_artifact.py examples/sample_usage_log.jsonl \\\n --attestation \"$tmp/att.json\" --mint-log \"$KRY_DATA_DIR/kry_mint_log.jsonl\" --bundle-dir \"$tmp/packet\"\npython3 scripts/kry_verified_artifact.py --verify-artifact \"$tmp/packet/artifact.json\"\npython3 scripts/kry_finops_report.py \"$tmp/packet/artifact.json\"\npython3 scripts/kry_verified_artifact.py examples/sample_usage_log.jsonl \\\n --attestation \"$tmp/att.json\" --template-dir \"$tmp/evidence_templates\"\n# emits explicit product/science/review/kill gates; sample data stays internal_or_demo_only\n# the bundled sample cannot satisfy --corpus real, even if copied elsewhere.\n# template mode also writes hash-bound request briefs for provider/reviewer/buyer/legal evidence.\n# bundle mode derives packet/t1_manifest.json and packet/finops_report.md; it does not copy the private mint log.\n# after collecting real provider data, use --write-provider-export-manifest and\n# --write-corpus-manifest to generate the live science-gate provenance files.\n\n# 4) Run the release checks\npython3 -m pytest tests/ -q # stdlib suite; optional crypto tests skip closed if unavailable\nbash lab/reproduce.sh 10 # reproducibility proof loop\npython3 scripts/kry_release_verify.py --full # one-command release gate\n```\n\n---\n\n## How it works\n\n```text\n EARN SPEND\n cache hit ┐ ┌ routing permission\n compression ┼──► value_multiplier(model) ──► KRY ──► (free tiers cost 0,\n displacement ┘ × EARN_RATES[event] ▲ paid tiers debit)\n │\n │ every mutation\n ▼\n ┌───────────────────────────────────────────────────────────────────────────┐\n │ MINT — SHA-256 hash-chained receipt │\n │ chain_hash[i] = SHA256(chain_hash[i-1] : receipt_hash[i]) │\n │ carries evidence_tier (T0/T1/T2) + T1 metered counts in the hash (v3) │\n └───────────────────────────────────────────────────────────────────────────┘\n │\n ┌──────────────────────────────┼──────────────────────────────┐\n ▼ ▼ ▼\n ATTEST (public proof) SETTLE (federated transfer) RECONCILE (F1, auditor)\n content-sealed balance + the conservation + double-spend match T1 mints to the\n veracity_floor surface guard (+ HOLE F rollback guard) provider's own usage record\n │\n ▼\n VERIFY (any stranger, stdlib only)\n chain integrity + conservation + magnitude (F2) + veracity surface\n```\n\nThe lifecycle is append-only and deterministic. Hashes are computed over\n`json.dumps(sort_keys=True)` — never raw concatenation — so any party re-derives the same\ndigest. Runtime ledgers live under `KRY_DATA_DIR` (default `./kry_data`, gitignored) and\n**are never committed** — they're tied to real traffic.\n\n---\n\n## Veracity: the trust ladder\n\nThe hash chain proves **integrity** (untampered + conserved). It says nothing about\nwhether the efficiency events *actually happened* — that is **veracity**. Every mint is\nclassified by *how the event was witnessed*, weakest to strongest:\n\n| Tier | Constant | Trust source | What earns it | Status |\n|------|----------|--------------|---------------|--------|\n| **T0** | `self_reported` | the operator's runtime, full stop | cache hits (counterfactual) — a **permanent** floor for them | shipped |\n| **T1** | `provider_metered` | the **provider**, for a call that *did* happen | a displacement's cheap leg, with a retained real `usage` payload | shipped + reconcilable (F1) |\n| **T2** | `tlsn_attested` (TLS-notary) / `tee_attested` (TEE slot) | a TLS-notary signature / hardware enclave | the only honest external anchor for counterfactual savings | **`tlsn_attested` mechanism proven on a TLSNotary prototype (provider-call + mint integration in progress); `tee_attested` is the not-yet-built hardware slot** |\n\n- The tier is **bound into the receipt hash** (`hash_version \u003e= 2`): editing one receipt's\n tier in place breaks the chain, and a legacy v1 receipt (which does not bind the tier) may\n only be `self_reported` — a v1 receipt claiming a higher tier is rejected. New T1 receipts\n also hash-bind their `metered_tokens` (`hash_version = 3`), so provider reconciliation\n cannot swap token counts under the same receipt hash. The current format (`hash_version = 6`)\n additionally binds each receipt's `receipt_id` into the chain hash, so a T2 tier-promotion's\n `supersedes` target cannot be relabeled onto a different (larger) receipt to inflate the\n externally-anchored fraction.\n- **`verify_chain` proves integrity, not veracity.** It cannot distinguish an honest chain\n from one an operator re-derived from genesis (keyless SHA-256 + a local checkpoint): a full\n re-mint with upgraded tiers and inflated value passes it clean. The external root of trust\n that closes this is the **chain-head anchor** — export a content-free `{count, tip}`\n commitment and *publish* it to an append-only medium (`scripts/kry_chain_anchor.py`); a\n verifier holding the published anchor then catches any retroactive re-mint\n (`kry_verify.py --anchor`). Absent a published anchor, a self-reported balance is\n operator-trusted by construction — which is exactly what `veracity_floor` discloses.\n- An attestation exposes a **`veracity_floor`** = the fraction backed by an *external* anchor\n (T1+T2), not operator self-report. `verify_attestation()` **re-derives** the floor from the\n per-link tiers (so it can't be misstated *relative to the tiers shown*) and only credits a\n tier the public surface actually binds (v4) — a pre-v4 link claiming an external tier is\n coerced to `self_reported`. That is tamper-evident against anyone who cannot recompute the\n chain; against the operator (who can), publish a chain anchor to be re-mint-evident.\n- A balance with no external traffic reads **`veracity_floor = 0.0`** (100% self-reported).\n That is the *honest label* for what KRY is by default: internal-operator measurement.\n It is published as-is, never hidden.\n\n\u003e **Why cache hits are structurally hard.** A cache hit is a call that *did not happen* —\n\u003e zero provider-side footprint — so no external party can attest to it even in principle,\n\u003e short of a witness inside the runtime (a TEE or a TLS notary). Displacement is\n\u003e different: the cheap leg that *did* happen leaves a real provider record. This asymmetry\n\u003e is the honest core of the problem, and it is why \"just meter it\" does not rescue the\n\u003e bulk of a cache-dominated balance. Full design: [docs/KRY_VERACITY_BINDING.md](docs/KRY_VERACITY_BINDING.md).\n\n---\n\n## Authenticity (optional): who signed this attestation\n\nIntegrity proves the ledger is untampered; veracity proves the events happened. Neither\nproves **who** vouched for an attestation — to a stranger, a real ledger and a fabricated\none are cryptographically indistinguishable, because the stdlib core has no public-key\ncrypto. The **optional `kry_pqc/` tier** fills exactly that gap: it signs an attestation's\nraw bytes with NIST **ML-DSA (FIPS 204)** so the holder of a published public key is\nprovably the signer **to a verifier who supplies that published key out-of-band**\n(`--public-key` / `--expect-fingerprint`) — a signature under the artifact's *own embedded*\nkey proves nothing (anyone can self-sign), so the verifier reports it UNVERIFIED. The\n**m-of-n council** mode distributes that trust **as long as the council's public keys are\nthemselves published/pinned** (otherwise an operator who generates all N keys is the council). It is opt-in and\n**zero-impact on the core**: `src/kry/*` stays pure stdlib and imports neither `oqs` nor\n`kry_pqc` (`grep -rn \"import oqs\\|import kry_pqc\" src/kry` → nothing; only a one-line comment\nmentions the optional tier). Signatures are post-quantum, so a\ncredit meant to retain value cannot be retroactively forged. This adds *authenticity +\ntrust-distribution + quantum-proofing — **not** veracity*: it proves who attested, never\nthat the savings were real (that remains the job of the T1/T2 tiers above). See\n[kry_pqc/README.md](kry_pqc/README.md).\n\n---\n\n## Magnitude: publicly-checkable arithmetic\n\nVeracity is \"*did the event happen*\"; **magnitude** is \"*is the KRY amount right*\". They\nare separate, and magnitude is fully fixable in software. Each receipt's amount is\n`tokens_saved × EARN_RATES[event] × value_multiplier(avoided_model)`, against a **dated,\nversioned price basis** (`PRICE_BASIS_AS_OF`, per-model `list` vs honest `estimate`\nquality, with provenance). The attestation exposes each link's `tokens_saved` + `earn_rate`\n(counts and a rate — no content, no model name), so the stranger's verifier **recomputes\nevery amount** and rejects any receipt whose implied multiplier isn't a published value.\nThis catches inflation **even when conservation is kept internally consistent** — a class\nof forgery the chain alone misses (the **F2** check).\n\n\u003e **Cross-language verification (`hash_version` 6):** new chains bind the economic numbers and `ts`\n\u003e into the chain hash as the **exact IEEE-754 double in big-endian hex** (`struct.pack('\u003ed')`, the v5\n\u003e encoding), so a _non-Python_ verifier (Rust / JS / Go) reproduces every hash byte-for-byte — no\n\u003e dependence on CPython's float→JSON formatting, no precision loss, no rounding or integer-size choice.\n\u003e **v6 also binds the receipt's `receipt_id`** (a plain string — emit it verbatim into the block) so a\n\u003e promotion's re-tiering target (`supersedes`) cannot be relabeled to move a _different_ receipt's value\n\u003e onto an anchored tier. A cross-language verifier must therefore add the `receipt_id` field to the v6\n\u003e block it reconstructs. Legacy **v4** (CPython float encoding) and **v5** (f64-hex, no `receipt_id`)\n\u003e receipts keep their original encoding and remain fully verifiable — the change is additive and\n\u003e version-dispatched, so existing receipts, anchors, and the evidence bundle are byte-unchanged.\n\n---\n\n## Readiness: a computed grade, not a claim\n\nKRY grades itself against an **external, pre-dated rubric** (a prior epistemic-readiness ladder), mechanically — `readiness_label()` computes it; nobody\nnarrates it.\n\n```text\nprototype \u003c prototype_plus \u003c internally_consistent \u003c research_grade \u003c production_ready (A+)\n```\n\n| Level | Evidence required | KRY today |\n|---|---|---|\n| `internally_consistent` | the synthetic suite is fully green | ✅ cleared |\n| `research_grade` | + ≥ 0.80 agreement with an **independent, non-self-referential** oracle | ✅ **COMMITTED 2026-06-10** — `confirm()` 50/50 within TTL; fresh corpus 52/52 @ 1.00 (note ↓). _Scope: **token-count** reconciliation of **n=52 free-tier** (`:free`, $0) self-traffic against the provider's records — it grounds that the calls existed, **not** that dollars were saved._ |\n| `production_ready` (**A+**) | + validation on an **independent real-world corpus** + clean audit | ❌ external — needs **live** real-world traffic + a real counterparty |\n\n**The top label structurally requires external evidence** — the grader refuses to let\n*more code* buy a grade only *real data* can earn (enforced by\n`tests/test_capabilities.py`). The two steps to A+ are both external and both already\nhave tooling: run real `provider_metered`/holdout traffic, then\n`kry_or_fetch.py` → `kry_reconcile.py` (Step 1), then a live holdout through\n`kry_savings_report.py` (Step 2). See [docs/KRY_READINESS.md](docs/KRY_READINESS.md).\n\n\u003e **Real-data evidence (2026-06-09/10).** The external mechanism has been exercised on real\n\u003e traffic, well beyond the first anchor: provider reconciliation **18/18, agreement 1.00**; an\n\u003e **accepted-savings** run (8/8); a **real-corpus cache-holdout** on organic WildChat traffic\n\u003e (`holdout_validated`, veracity_floor 1.0, **stranger-verified** by `kry_verify`); and **validated\n\u003e cheap-model adequacy** on real paid calls (GSM8K 87%; code-routing 84% adequacy → up to ~75%\n\u003e cost-avoidance — *model-pair-specific* and assuming the avoided frontier call would have been\n\u003e kept, which is not separately tested; 71% prefix-cacheable, 5-fold/bootstrap). The acceptance gate's correctness specificity was **measured\n\u003e (0% measured)** and a default-off **correctness layer** built + wired. **Committed `research_grade`\n\u003e (2026-06-10):** the host system wired `confirm()` to the general gate, **confirmed 50/50 within TTL** (the\n\u003e stall broken), and the fresh corpus reconciled **52/52 at agreement 1.00 → `research_grade`** — graded\n\u003e the `--since` fresh-run window; the all-time ~0.12 is purely OpenRouter-purged legacy gen-ids\n\u003e (un-fetchable, **not** refuted). A+ still needs **live** real-world traffic + a real counterparty.\n\u003e Evidence: [docs/evidence/](docs/evidence/) · [research-grade anchor](docs/KRY_RESEARCH_GRADE_ANCHOR.md) ·\n\u003e [first anchor](docs/KRY_FIRST_REAL_ANCHOR.md) · [savings](docs/KRY_SAVINGS_ANALYSIS.md).\n\n---\n\n## Modules\n\nAll under `src/kry/` — ~5,000 LOC, stdlib only.\n\n| Module | Responsibility |\n|---|---|\n| `kry_token.py` | earn / spend / cycle, edge-weighted; `retained_dollars()`, `supply()`, dated price provenance, flow-balance, CSD solvency early-warning |\n| `kry_mint.py` | SHA-256 hash-chain receipts, per-evidence supply decay, evidence tiers, dated-basis valuation |\n| `kry_attest.py` | content-sealed public proof-of-balance + the verifiable `veracity` surface |\n| `kry_settlement.py` | federated conservation transfer + double-spend guard (single-host multi-process: commit-time ceiling re-check under a cross-process lock; tamper-evident registry, rollback/HOLE-F checkpoint + published registry anchor, negative-offer guard) |\n| `kry_referee.py` | adversarial-stability gate + ascension (ratify / revoke / escalate, challenge budget, probation) |\n| `kry_carbon.py` | second denomination — avoided inference → kWh → CO₂ (clearly-labeled **estimate**) |\n| `kry_baseline.py` | counterfactual holdout — randomized holdout + Wilson CI → the `holdout_validated` tier |\n| `kry_sanctions.py` | makes cheating unprofitable — host-sanction reputation + reciprocal audit rate + an ESS condition (biomimicry) |\n| `kry_capabilities.py` | capability matrix + the readiness grader (`readiness_label`, `verify_capabilities`) |\n\n---\n\n## Verifying as a stranger\n\nThe point of KRY is that **someone who does not trust you can check the claim** with\nnothing but the Python standard library and the published attestation.\n\n```bash\npython3 scripts/kry_verify.py attestation.json\n# integrity (hash chain) + conservation + magnitude (F2) + veracity surface\n\npython3 scripts/kry_reconcile.py kry_data/kry_mint_log.jsonl --provider-export usage.json\n# F1 (operator/auditor): match each T1 mint to the provider's OWN usage record.\n# --mode per-request (OpenRouter/OpenAI per-call)\n# --mode aggregate (Google billing totals) requires --since/--until; external packets default to \u003c=2% tolerance (opt-in cap 5%).\n\npython3 scripts/kry_verified_artifact.py --mint-log kry_data/kry_mint_log.jsonl \\\n --write-t1-manifest t1_manifest.json\npython3 scripts/kry_verified_artifact.py usage.jsonl --attestation attestation.json \\\n --t1-manifest t1_manifest.json --provider-export usage.json --corpus real \\\n --provider-export-manifest provider_export_manifest.json \\\n --corpus-manifest corpus_manifest.json \\\n --outside-review outside_review.json --buyer-feedback buyer_feedback.json \\\n --legal-review legal_review.json --bundle-dir packet\npython3 scripts/kry_verified_artifact.py --verify-artifact packet/artifact.json\n# final packet gate: product + science + external-review evidence + kill triggers\n# packet/t1_manifest.json is the shareable T1 reconciliation source; the private mint log stays local.\n\npython3 scripts/kry_finops_report.py packet/artifact.json\n# smallest FinOps-facing retained-dollars report; verifies artifact.json first and\n# keeps blocked external claims blocked in the human-facing output.\n# includes the doctor command buyers should run before trusting the packet surface.\n\npython3 scripts/kry_doctor.py --artifact packet/artifact.json\n# local health check: Python/config/docs/verifier surface + saved-packet/checklist/report verification.\n# fails if artifact ship_scope is do_not_ship; warns if it is internal_or_demo_only.\n# reports artifact-specific external_evidence_status from the verified claim_register.\n# treats externally claimable artifacts as packet-shaped handoffs.\n# fails if a packet-shaped artifact is missing its checklist or report.\n# fails if handoff packet command_inputs depend on absolute local paths.\n# fails if private mint-log or ledger material appears in the shareable packet.\n# fails if symlinks appear in the shareable packet.\n# fails if unbound directories, files, or non-regular entries appear in the shareable packet.\n# WARN items are not proof failures; the external evidence warning stays until real\n# provider export, outside review, buyer feedback, and legal review exist.\n```\n\n`kry_verify.py` imports no part of the package — it re-implements the checks from the\nspec, so passing it is meaningful precisely because it doesn't trust the producer's code.\n\n---\n\n## Honest limitations (disclosed, not hidden)\n\nThese are **permanent, by-design scope boundaries** — declared as `not_guaranteed` in the\ncapability matrix, not defects:\n\n- **Per-event counterfactual proof** — a single cache hit cannot be externally witnessed;\n the holdout gives a *statistical* answer, never a per-event one.\n- **Source-truth of self-report** — a determined operator can still author conserved T0\n events for savings that didn't occur, and (controlling the runtime) re-derive the whole\n chain from genesis with upgraded tiers; `verify_chain` proves integrity, not veracity. The\n attestation *says so* (`veracity_floor = 0.0`), which is the contribution; publishing a\n `kry_chain_anchor` makes a retroactive re-mint detectable, but neither prevents it.\n- **Sybil-resistant identity** — settlement assumes parties are who they claim; KRY does\n not solve identity.\n- **Cross-node settlement (HOLE D)** — the double-spend guard is real-time atomic on a single\n HOST (multi-process: the ceiling is re-checked at _commit_ under a cross-process lock), and a\n _published_ `export_registry_anchor()` catches a rollback/un-spend. What is NOT real-time-safe is\n cross-NODE: two nodes settling the same balance against unmerged registries aren't caught until\n merge. Named now, ranked fix documented (lease/nonce/TTL first).\n- **Real-world validation** — every result here is on synthetic or internal data until a\n real provider export is reconciled. \"Tested on synthetic data\" ≠ \"validated on real\n traffic,\" and this README will not blur the two.\n\n---\n\n## Repository layout\n\n```text\nsrc/kry/ the package (stdlib only) — see Modules\nscripts/ kry_verify · kry_chain_anchor (re-mint/rollback evidence) · kry_reconcile (F1) · kry_or_fetch · kry_savings_report · kry_verified_artifact · kry_finops_report · kry_doctor\nexamples/ try_kry.py (30s demo) · gen_dataset.py (synthetic logs) · sample_usage_log.jsonl\ntests/ unit, adversarial regressions (test_hardening), at-scale + fuzz (test_stress)\ndocs/ SPEC · VERACITY_BINDING · COUNTERFACTUAL_HOLDOUT · BIOMIMICRY · SANCTIONS · READINESS · ...\nkry_data/ runtime ledgers (gitignored — never committed)\n```\n\n```bash\npython3 -m pip install -e \".[dev]\" # installs pytest/ruff; runtime package remains dependency-free\npython3 scripts/kry_release_verify.py # install + lint + tests + packet + reproducibility smoke\npython3 scripts/kry_release_verify.py --full # same gate + 10-round reproducibility proof\npython3 -m pytest tests/ -q # stdlib suite; optional crypto tests skip closed if unavailable\nruff check src/ scripts/ tests/ examples/ lab/ # must stay clean\nbash lab/reproduce.sh 10 # full local reproducibility loop\n```\n\n---\n\n## Legal posture\n\nDesigned as a **closed-loop, non-transferable consumptive credit** (rebate basis).\nSettlement is **federated, not an open exchange**. Nothing here is an offer of a security\nor a tradeable instrument. **Consult securities counsel before any external or tradeable\nuse.** Licensed under **PolyForm Noncommercial 1.0.0** (see [LICENSE.md](LICENSE.md)):\nfree for noncommercial use, research, and evaluation; **any commercial use requires a\nseparate license** from the licensor, Thomas Albrecht \u003cthequantumfalcon@gmail.com\u003e.\n\n**Trademarks \u0026 no affiliation.** Model and product names — OpenAI, GPT, Anthropic, Claude, Opus, Sonnet, OpenRouter, and any others — are trademarks of their respective owners, used here **descriptively** (nominative fair use) only to identify the systems measured. kry is **not affiliated with, endorsed by, or sponsored by** any of them. Every figure is reproducible on public benchmarks and labelled *measured* vs *projected*; nothing here is a guarantee of savings, financial advice, or a security, and the software is provided **as is, without warranty of any kind.**\n\n---\n\n## Documentation\n\n| Doc | What it covers |\n|---|---|\n| [KRY_TOKEN_SPEC.md](docs/KRY_TOKEN_SPEC.md) | the unit, rates, and the falsifier |\n| [KRY_VERACITY_BINDING.md](docs/KRY_VERACITY_BINDING.md) | integrity vs veracity, the tier ladder, F1/F2 |\n| [KRY_COUNTERFACTUAL_HOLDOUT.md](docs/KRY_COUNTERFACTUAL_HOLDOUT.md) | measuring the counterfactual (randomized holdout + Wilson CI) |\n| [KRY_BIOMIMICRY.md](docs/KRY_BIOMIMICRY.md) | how nature verifies unobservable claims (sanctions, costly signalling, ESS) |\n| [KRY_READINESS.md](docs/KRY_READINESS.md) | the pre-dated A+ rubric + the two external steps to reach it |\n| [KRY_VERIFIED_SAVINGS_ARTIFACT.md](docs/KRY_VERIFIED_SAVINGS_ARTIFACT.md) | the smallest packet + explicit product/science/review/kill gates |\n| [RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) | what ships, what is optional, what remains externally blocked |\n| [CLAIMS_BOUNDARY.md](docs/CLAIMS_BOUNDARY.md) | what is proven, blocked, forbidden, and optional |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthequantumfalcon%2Fkry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthequantumfalcon%2Fkry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthequantumfalcon%2Fkry/lists"}