Distributed Systems & CryptographyNovember 15, 2026

Building a Merkleized “Provenance Receipt” for Build Artifacts Using Ed25519

C

Written by

Cipher Stone

I got curious about one annoying reality in software supply chains: even when you have a hash of a build artifact, that hash alone doesn’t prove what inputs and steps were used to produce it—especially when you want to link provenance data to the artifact in a way that’s hard to tamper with.

So I built a tiny, niche “provenance receipt” format: a single JSON file that contains (1) a Merkle root over all recorded inputs and steps, and (2) an Ed25519 signature from a signer key. This gives you a compact, verifiable attestation: the artifact hash is “committed to” by the Merkle tree, and the signer can’t swap history without breaking the signature or the Merkle root.

Below is exactly how I implemented it, step by step, including code you can run.


What I mean by a “provenance receipt”

A Merkle tree (often used in blockchains and content-addressed storage) is a binary hash tree. Instead of signing a huge list, you hash each leaf, then repeatedly hash pairs of child hashes until you get one final hash: the Merkle root. Any change in any leaf changes the root.

An Ed25519 signature signs data with a private key so anyone with the public key can verify it was signed by the holder of that private key.

My receipt JSON includes:

  • artifact: the hash of the built artifact (SHA-256)
  • leaves: a deterministic set of leaf entries (inputs + steps + metadata)
  • merkle_root: Merkle root computed from those leaves
  • signature: Ed25519 signature over a canonical “receipt commitment” string
  • pubkey: the signer’s public key (so verification can be done offline)
  • version and timestamp

Project layout

I used Python 3.11+ and two lightweight dependencies:

  • pynacl for Ed25519
  • pysha3 is unnecessary because we use SHA-256 (built-in via hashlib)

Install:

pip install pynacl

Create a file provenance_receipt.py with the code below.


Step 1: Deterministic hashing of receipt leaves

The most important practical detail: if leaf hashing isn’t deterministic, you can sign something but verifying later produces a different root.

I represent each leaf as a small JSON object with stable ordering, then hash the canonical bytes.

Here’s the complete script, annotated.

import base64 import hashlib import json import os import time from dataclasses import dataclass from typing import List, Tuple from nacl.signing import SigningKey, VerifyKey def sha256(data: bytes) -> bytes: return hashlib.sha256(data).digest() def canonical_json(obj) -> bytes: """ Canonical JSON: - sort keys - remove unnecessary whitespace - ensure stable output across platforms """ return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode("utf-8") def leaf_hash(leaf: dict) -> bytes: """ Each leaf is hashed as SHA-256(canonical_json(leaf)). """ return sha256(canonical_json(leaf)) def merkle_root(leaf_hashes: List[bytes]) -> bytes: """ Computes Merkle root over a list of leaf hashes. If a level has an odd count, I duplicate the last hash (common Merkle tree convention). """ if not leaf_hashes: # Not typical for production Merkle trees, but keeps this demo deterministic. return sha256(b"empty") level = leaf_hashes[:] while len(level) > 1: if len(level) % 2 == 1: level.append(level[-1]) # duplicate last next_level = [] for i in range(0, len(level), 2): next_level.append(sha256(level[i] + level[i + 1])) level = next_level return level[0] def receipt_commitment(receipt_body: dict) -> bytes: """ This is what we sign. I canonicalize the body minus the signature field. """ return canonical_json(receipt_body) def b64(x: bytes) -> str: return base64.b64encode(x).decode("ascii") def unb64(s: str) -> bytes: return base64.b64decode(s.encode("ascii")) @dataclass class Receipt: version: int timestamp_utc: int artifact_sha256_b64: str leaves: List[dict] merkle_root_b64: str pubkey_b64: str signature_b64: str def to_dict(self) -> dict: return { "version": self.version, "timestamp_utc": self.timestamp_utc, "artifact_sha256_b64": self.artifact_sha256_b64, "leaves": self.leaves, "merkle_root_b64": self.merkle_root_b64, "pubkey_b64": self.pubkey_b64, "signature_b64": self.signature_b64, } @staticmethod def from_dict(d: dict) -> "Receipt": return Receipt( version=d["version"], timestamp_utc=d["timestamp_utc"], artifact_sha256_b64=d["artifact_sha256_b64"], leaves=d["leaves"], merkle_root_b64=d["merkle_root_b64"], pubkey_b64=d["pubkey_b64"], signature_b64=d["signature_b64"], ) def build_receipt(artifact_path: str, signer: SigningKey) -> Receipt: # 1) Hash the artifact bytes (what we intend to attest) with open(artifact_path, "rb") as f: artifact_bytes = f.read() artifact_sha = sha256(artifact_bytes) artifact_sha_b64 = b64(artifact_sha) # 2) Build a deterministic list of leaves # Here I include: # - artifact hash # - build “inputs” (examples) # - build “steps” (examples) # - metadata like toolchain version # # In a real pipeline you’d generate these from your actual build graph. leaves = [ {"type": "artifact", "sha256": artifact_sha_b64}, {"type": "input", "name": "go_mod_snapshot", "sha256": b64(sha256(b"go.sum contents example"))}, {"type": "input", "name": "source_tree_snapshot", "sha256": b64(sha256(b"git tree hash example"))}, {"type": "step", "name": "compile", "command_digest": b64(sha256(b"make build GOFLAGS=-trimpath"))}, {"type": "step", "name": "link", "command_digest": b64(sha256(b"ldflags -s -w"))}, {"type": "build_metadata", "toolchain": "example-toolchain", "version": "1.2.3"}, ] # 3) Hash leaves and compute Merkle root leaf_hashes = [leaf_hash(leaf) for leaf in leaves] root = merkle_root(leaf_hashes) root_b64 = b64(root) # 4) Create a receipt body (everything except signature) # We sign the canonical JSON of this body. pubkey = signer.verify_key receipt_body = { "version": 1, "timestamp_utc": int(time.time()), "artifact_sha256_b64": artifact_sha_b64, "leaves": leaves, "merkle_root_b64": root_b64, "pubkey_b64": b64(bytes(pubkey)), } # 5) Sign the commitment signature = signer.sign(receipt_commitment(receipt_body)).signature return Receipt( version=receipt_body["version"], timestamp_utc=receipt_body["timestamp_utc"], artifact_sha256_b64=receipt_body["artifact_sha256_b64"], leaves=receipt_body["leaves"], merkle_root_b64=receipt_body["merkle_root_b64"], pubkey_b64=receipt_body["pubkey_b64"], signature_b64=b64(signature), ) def verify_receipt(receipt: Receipt, artifact_path: str) -> Tuple[bool, str]: # 1) Verify artifact hash matches the receipt with open(artifact_path, "rb") as f: artifact_bytes = f.read() actual_artifact_sha_b64 = b64(sha256(artifact_bytes)) if actual_artifact_sha_b64 != receipt.artifact_sha256_b64: return False, "Artifact hash mismatch" # 2) Recompute Merkle root from leaves and compare recomputed_leaf_hashes = [leaf_hash(leaf) for leaf in receipt.leaves] recomputed_root = merkle_root(recomputed_leaf_hashes) if b64(recomputed_root) != receipt.merkle_root_b64: return False, "Merkle root mismatch" # 3) Verify signature over the canonical receipt body pubkey_bytes = unb64(receipt.pubkey_b64) verify_key = VerifyKey(pubkey_bytes) receipt_body = { "version": receipt.version, "timestamp_utc": receipt.timestamp_utc, "artifact_sha256_b64": receipt.artifact_sha256_b64, "leaves": receipt.leaves, "merkle_root_b64": receipt.merkle_root_b64, "pubkey_b64": receipt.pubkey_b64, } signature_bytes = unb64(receipt.signature_b64) commitment = receipt_commitment(receipt_body) try: verify_key.verify(commitment, signature_bytes) except Exception: return False, "Signature verification failed" return True, "OK" def generate_signer_keypair() -> Tuple[SigningKey, str]: """ Generates an Ed25519 keypair. Returns (signing_key, private_key_b64) for demo purposes. """ signer = SigningKey.generate() private_key_b64 = b64(bytes(signer)) return signer, private_key_b64 def main(): # Demo: create a fake “artifact” and receipt, then verify it. artifact_path = "artifact.bin" # Create a demo artifact with open(artifact_path, "wb") as f: f.write(b"example artifact bytes - provenance demo") signer, private_key_b64 = generate_signer_keypair() print("Generated demo signer private key (b64):", private_key_b64) receipt = build_receipt(artifact_path, signer) with open("provenance_receipt.json", "w", encoding="utf-8") as f: json.dump(receipt.to_dict(), f, indent=2) print("Wrote provenance_receipt.json") print("Receipt merkle_root_b64:", receipt.merkle_root_b64) # Load + verify with open("provenance_receipt.json", "r", encoding="utf-8") as f: loaded = json.load(f) loaded_receipt = Receipt.from_dict(loaded) ok, msg = verify_receipt(loaded_receipt, artifact_path) print("Verification:", msg) if __name__ == "__main__": main()

Step 2: Run it and see what happens

Execute:

python provenance_receipt.py

You should get output similar to:

  • A generated private key (base64) for this demo
  • “Wrote provenance_receipt.json”
  • “Verification: OK”

Now try tampering with the artifact:

python -c "open('artifact.bin','ab').write(b'X')" python provenance_receipt.py

You’ll still rebuild a new receipt in the demo, so verification will pass for the new receipt. To see failure clearly, do this instead:

  1. Run the script once to create provenance_receipt.json.
  2. Modify artifact.bin manually.
  3. Run a separate verification-only script (or temporarily comment out receipt generation).

A quick one-liner for the “verify only” flow is to reuse the same verify_receipt function; the core idea is: artifact hash mismatch fails before signature verification.


Why Merkle + signature is the sweet spot here

Signing the entire list of leaves directly works, but it’s bulky and fragile: you’d either sign a huge blob or risk inconsistent serialization. Merkle roots are compact: the receipt commits to a whole set of provenance facts with one hash.

In this demo the Merkle tree binds:

  • the artifact SHA-256 (so the receipt can’t be transplanted)
  • the recorded build inputs/steps (so provenance data can’t be swapped silently)
  • the toolchain metadata (so “what produced this” can’t be rewritten)

Then the Ed25519 signature prevents anyone from forging a receipt that matches a different Merkle root.


What you’d store or publish

In a real system, I’d store:

  • the artifact itself in some content-addressed storage (so it’s addressed by its SHA-256)
  • the provenance_receipt.json alongside it (or in an append-only log)
  • the signer public key in a registry (so verifiers don’t need to trust a random identity)

This pattern also composes nicely with decentralized provenance systems: receipts can be anchored in higher-level networks without changing their internal verification rules.


Conclusion

I built a compact digital provenance receipt that combines a Merkle tree commitment over deterministic “inputs + build steps + metadata” with an Ed25519 signature over a canonical receipt body. The key lesson from my weekend tinkering is that provenance only stays trustworthy when the hashing and serialization are deterministic and when the artifact hash is bound into the signed commitment—then tampering breaks either the Merkle root or the signature.