receipt-ai

The problem

Execution records are easy to copy, edit, detach from context, or present later without a clear integrity check. receipt-ai creates a compact receipt for what was recorded at an execution boundary and makes later modification detectable relative to that receipt identity.

What it does

Each receipt binds:

• SHA-256 of the recorded input
• SHA-256 of the recorded output
• model / engine label
• configuration hash
• timestamp metadata
• optional metadata
• optional previous-receipt link
• optional chain index / terminal marker
• optional HMAC-SHA256 authentication using a shared secret

The canonicalized receipt body is hashed into receipt_hash. Verification is offline: no model call, API key, network connection, or database is required.

Demo

The CLI demonstrates:

• create → verify
• tamper → INVALID
• restore → VALID
• chain continuity checks
• optional HMAC verification
• chain truncation checks when an expected length and/or terminal marker is supplied
• Malbolge execution stress cases showing the same receipt contract across unusual execution domains

What VALID means

For an unsigned standalone receipt, VALID means the stored fields are internally consistent with the receipt's stored SHA-256 seal.

For HMAC verification, VALID additionally means the receipt hash matches an HMAC-SHA256 value computed with the supplied shared secret.

For chains, VALID means the verified entries are internally valid and their stored links are coherent. Tail truncation can be detected when verification is given external expectations such as expected_length or require_terminal.

Security boundary

A self-contained SHA-256 receipt is tamper-evident, not self-authenticating. Someone able to rewrite the entire unsigned artifact can also recompute its hash.

HMAC-SHA256 adds shared-secret authentication, but it is not a public-key digital signature and does not by itself establish a non-repudiable author identity.

receipt-ai does not prove:

• that a model answer is true or correct
• that the named model actually produced the output unless that claim is authenticated by a trusted surrounding system
• that the timestamp came from a trusted external clock
• provenance before receipt creation
• resistance to complete chain replacement without an external expectation or anchor

Strong provenance can be strengthened with independently retained hashes, authenticated keys, signatures from an external signing system, transparency logs, or another out-of-band anchor.

Canonicalization note

The implementation uses deterministic JSON key ordering plus explicit float normalization before hashing. Devpost does not claim full RFC 8785 compliance unless that behavior is independently validated against the RFC's complete requirements.

Why it matters

The project separates evidence from narrative: it records exactly what an execution record contained, provides explicit verification states, and keeps limitations visible instead of turning an integrity check into an authorship or truth claim.

Testing

The repository is dependency-free at runtime and includes pytest coverage, tamper/chain stress cases, Ruff lint/format checks, and GitHub Actions across Python 3.11, 3.12, and 3.13.

Built With

• github-actions
• hashlib
• hmac-sha256
• pytest
• python
• ruff
• sha-256