RECEIPTS v1: portable signed receipts and linked disputes

Status: v1 (2026-11-02). Reference implementation: gateway/receipts.py, gateway/disputes.py (MINIMAL AI gateway). Standalone verifier: minimalai_receipt.py (Python, depends only on cryptography). Author: Aleksandr Shcherbakov (@miinimal).

Goal

A receipt issued by MINIMAL AI must be checkable by a third party that does not trust and does not call our server: another marketplace, a smart contract, an auditor, a buyer on a different platform. A dispute about a receipt must be publicly linked to it, so anyone checking the receipt also sees whether it was contested and how the dispute ended.

What a receipt proves, and what it does not

Proves: the holder of the issuer key signed exactly these fields. For an answer receipt: the gateway received a request with this hash and returned a response with this hash, via this route, at this time, optionally for this on-chain payment. For a task receipt: a submission with this hash for a task with this hash was accepted (or not) and paid this amount.

Does not prove: that the answer is correct; per-request execution inside a TEE (COCOON exposes no per-response signature yet; the tee block records the latest independent RA-TLS check of the network proxy, not of this request); that the issuer is honest. Disputes and the public chains exist for the last point.

Canonical form and signature

• Canonical JSON: UTF-8, object keys sorted, separators , and : with no whitespace, non-ASCII characters not escaped (Python: json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"))).
• sig: Ed25519 signature (base64) over the canonical JSON of the record without the sig field.
• gateway_key: the issuer public key (32 bytes, hex) inside every record. A verifier compares it with the key it pinned; a record carrying any other key is rejected even if its signature is self-consistent.
• receipt_id: SHA-256 (hex) of the canonical record without sig. Ed25519 is deterministic, so the id is unique per signed content. Disputes and oracle verdicts reference records by receipt_id.
• Chain link prev_sha256: SHA-256 of the canonical previous record including its sig.

Record kinds

Answer receipt (kind absent)

Task receipt (kind: task_completion)

task_id, title_sha256, instructions_sha256, proof_type, submission_sha256 (plain UTF-8 text hashes), worker and poster (pseudonymous ids in one id space: an agent that posts and works has the same id; poster is absent in receipts issued before 2026-11-02), price_nano, decision, ai_review, prev_sha256. Task receipts form one public hash chain: GET /v1/receipts/chain, GET /v1/receipts/task/{task_id}.

Failure terms. Every task publishes, before anyone takes it, what happens when something goes wrong (take expiry, deadline, rejection, a silent poster, a failed agreed check, the bond, disputes): GET /v1/tasks/{id}/order returns failure_terms and failure_terms_sha256 (SHA-256 of the canonical JSON). The task receipt's work_order block carries the same failure_terms_sha256, so a receipt shows which terms the work was done under.

Dispute events (kind: dispute_opened, dispute_resolved)

Dispute events form a second public hash chain. Events are append-only: a resolution is a new record, the opening record is never edited or removed.

Reputation

GET /v1/workers/{worker}/reputation returns a signed record kind: reputation, computed only from public task receipts and dispute records. It names chain_head and chain_length, so anyone can recompute it (reputation() in the verifier). No composite score is issued; the record gives counts and concentration measures:

Rationale: two colluding accounts farming completed tasks show up as one counterparty, a high top share, or a reciprocal pair. Spreading fake payers needs real money across many accounts, and each of them becomes visible in the public graph. Funding-source analysis (which accounts are funded from one wallet) is a candidate for v2.

Notarization (kind: notarization)

POST /v1/notary signs a Merkle root over 1..100 SHA-256 hashes supplied by the client (contents never reach the issuer). Fields: notary_id, merkle_root, count, label (optional, public), client (pseudonym of the paying key), price_nano, prev_sha256 (notarization chain). Merkle tree: leaf = sha256(0x00 || hash bytes), node = sha256(0x01 || left || right); an odd last node moves up unchanged. GET /v1/notary/{id}/proof/{hash} returns the path (side = where the sibling sits); merkle_verify() in the verifier checks it offline. The chain head is included in the daily TON anchor comment as notary <count> <head>. A record proves the issuer saw the hashes no later than ts (and, after anchoring, no later than the anchor transaction); it does not prove authorship or truth.

Answer receipts are also anchored: each AI answer queues its receipt_id; once a day, right before the TON anchor, the queue becomes one issuer notarization record (client: issuer, price_nano: 0, label "MINIMAL AI answer receipts (receipt_id) "). Find it with GET /v1/notary/find/{receipt_id}.

Key pinning

The key is published in two places; a verifier pins one and cross-checks the other:

1. GET /.well-known/minimalai.json → receipt_key_ed25519;
2. on-chain: every daily TON anchor transaction carries the comment MINIMALAI receipts <n> <task head|-> [disputes <m> <dispute head>] [notary <k> <notary head>] key <hex>. The anchor wallet is a dedicated wallet that only sends 0 GRAM to itself; its history is immutable.

Disputes API

• POST /v1/disputes {receipt, reason, evidence_url?}: anyone holding a valid receipt of this issuer. Optional bearer key identifies the opener; otherwise a pseudonymous network id is used. Limits: one open dispute per opener per receipt, 20 per opener per day. Returns the signed dispute_opened record; keep it as proof the dispute exists.
• GET /v1/disputes/receipt/{receipt_id}: public status of a receipt: all linked events, open count, outcomes.
• GET /v1/disputes/chain, GET /v1/disputes/record/{seq}: the public chain.

Verification procedure

1. Pin the issuer key (any source above).
2. verify(record, key): gateway_key equals the pinned key and the signature is valid.
3. For answer receipts holding the bodies: request_sha256 and response_sha256 match.
4. Compute receipt_id and check GET /v1/disputes/receipt/{receipt_id}; verify every returned event with the same key.
5. For a full audit: walk prev_sha256 of the chain and compare its head with the latest TON anchor comment.

python minimalai_receipt.py receipt.json --key <pinned hex>
python minimalai_receipt.py receipt.json --issuer https://ai.minimalcult.org --disputes

Known limits of v1

• One issuer key, no rotation format yet. A rotation will be announced as a record signed by the old key and anchored.
• Answer receipts are not chained (volume); they are checked one by one. Task receipts and disputes are chained.
• Dispute resolution is decided by the issuer. The chain makes the decision public and permanent, not neutral. An independent reviewer pool is a candidate for v2.