--- title: "HDK technology" author: "Jakub Ćwirlej" id: hdk-tech language: en url: "https://jakubcwirlej.com/articles/hdk-tech.md" page: "https://jakubcwirlej.com/apps/" translations: pl: "https://jakubcwirlej.com/pl/articles/hdk-tech.md" fr: "https://jakubcwirlej.com/fr/articles/hdk-tech.md" nl: "https://jakubcwirlej.com/nl/articles/hdk-tech.md" updated: 2026-10-14 words: 758 summary: "The author describes HDK, a free Python library (CC BY-NC 4.0; earlier versions Apache 2.0) spun off from OrsonAI that makes records of conversations with language models tamper-evident. It hashes every event with all its ancestors, adds a secret-bound canary counter and anchors Merkle roots on the Hedera Consensus Service." summary_type: editorial --- # HDK technology Jakub Ćwirlej · text language: EN · 758 words ## Summary (editorial) The author describes HDK, a free Python library (CC BY-NC 4.0; earlier versions Apache 2.0) spun off from OrsonAI that makes records of conversations with language models tamper-evident. It hashes every event with all its ancestors, adds a secret-bound canary counter and anchors Merkle roots on the Hedera Consensus Service. ## Key points (editorial) - Changing anything at any level, from one word of a prompt to a whole document, changes the hashes of every descendant event. - By default HDK anchors a Merkle root on Hedera after every 1,000 events; one anchor costs $0.0001, which is $0.0000001 per interaction. - In the measurements described in the paper, on standard x86 cloud infrastructure, the overhead is below a millisecond per event. - The text relates HDK to the record-keeping and transparency requirements of Articles 12 and 13 of the EU AI Act. - Its stated limits: the canary does not detect passive copying at the infrastructure level, and random checks alone do not catch a single surgical change. ## Full text (the author's own words) HDK (Hedera Detection Key) is a small, free Python library that I spun off from OrsonAI as a separate, open tool. From version 0.1.3 it is under the CC BY-NC 4.0 licence (earlier versions, released under Apache 2.0, remain under it). The download is a free library (alpha 0.1.3) with optional Hedera anchoring (install from the downloaded file: pip install ./hdk-audit-0.1.3.zip). It ran for a while in a demo application, anchoring its records on Hedera; the application did not go to production, so HDK is not used in production today. It sits between an application and a language model’s API and records every interaction in a way that makes later tampering detectable. It does not change the prompts or the answers: it adds cryptographic proof of what was asked, what came back, when, and from which model. ### The problem Companies and newsrooms rely more and more on AI-generated text, yet they have no verifiable proof of what a model actually produced. Application logs sit in databases controlled by the operator: they can be changed or deleted, and nobody outside can check that this has not happened. Even where hash chains exist, a change is found only by comparing records by hand – nothing makes unauthorised access reveal itself at the moment it happens. ### Hierarchical hash genealogy HDK computes a SHA-256 hash of every event together with the hashes of all its ancestors: project, document, conversation, query and response. The hash of an answer therefore contains the whole path back to the project. Change anything at any level – one word of a prompt, one document – and the hashes of all its descendants change too. For each project HDK computes a Merkle root: a single hash that stands for the state of the whole project at a given moment. ### The canary The second layer is a “canary”: a secret 256-bit value and a counter that goes up with every read. Their hash (the commitment) is woven into every record and checkpointed regularly. If someone reads data through the middleware without updating the counter, the counter no longer matches; if they update it without knowing the secret, the commitment no longer matches. Either way, verification fails. The idea carries over to ordinary infrastructure a principle from my earlier, conceptual work on detecting breaches in AI containment. ### Anchoring on Hedera From time to time – by default after every 1,000 new events – HDK publishes the Merkle root on the Hedera Consensus Service, a public ledger that adds a consensus timestamp and a sequence number. Only hashes leave the user’s system; content, identities and prompts stay private (“data private, proof public”). Anyone can then check the record independently, for example on hashscan.io (OrsonAI’s anchors from February–May 2026: topic 0.0.10278996 on the Hedera mainnet). Because the ancestor chains of new events reach into the range of the previous anchor, every anchor implicitly confirms all the earlier ones: the longer the system runs, the harder it is to rewrite history unnoticed. ### Overhead and cost In the measurements described in the paper, on standard x86 cloud infrastructure, HDK adds less than a millisecond per event. One anchor costs $0.0001, so at the default interval of 1,000 events anchoring costs $0.0000001 per interaction – about 0.0001% of the price of a typical model call ($0.01–$0.10). Anchoring every single event, for the highest security, costs $0.0001 per event. ### Why it matters: the EU AI Act The EU AI Act requires high-risk AI systems to keep records (Article 12) and to be transparent (Article 13). HDK provides an audit trail that a third party can verify without seeing any private content. In OrsonAI, this mechanism was the basis of the certificate of human authorship of a text. ### Limitations HDK’s guarantees are computational – they rest on the strength of SHA-256 and on external anchoring – not absolute. The canary works at the application level: it detects access through the HDK middleware, but not passive copying of data at the operating-system or infrastructure level, because copied bits leave no trace. A copy does not make it possible to falsify history, though: changing any past event breaks the genealogy, and the anchors on Hedera keep the original state. Random integrity checks catch mass changes, but not a single, surgical modification – against that, the protection comes from the genealogy and the anchoring. Security assumes that at least one of three layers stays uncompromised: the user-side data, the anchored record on Hedera, or the secret material. Next steps: formal verification of the hash-chain properties (Coq/Lean), federation of systems on shared HCS topics, and content-provenance certificates with selective disclosure. - [Read the paper on ResearchGate](https://www.researchgate.net/publication/400762996) - [Download the free HDK library](https://jakubcwirlej.com/files/hdk/hdk-audit-0.1.3.zip) - [HDK on Hugging Face](https://huggingface.co/JakCwi/hdk-audit) --- Jakub Ćwirlej — Journalist who builds with AI · on the site: https://jakubcwirlej.com/apps/ Full context: https://jakubcwirlej.com/context/en.md · https://jakubcwirlej.com/llms.txt