---
name: receipt
description: 'Work with fragletc run receipts -- attest one against the script that ran, or typeset a bundle of them as a ledger that links each run''s inputs to earlier outputs. Tools: attest, ledger. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: engineering, computation
  tools: attest.py, ledger.py
---

# Receipt

Work with fragletc run receipts -- attest one against the script that ran, or typeset a bundle of them as a ledger that links each run's inputs to earlier outputs.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/attest.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `attest.py`

Attest a fragletc run receipt (fraglet-receipt/2) the way OKF's Attested Computation attester does -- deterministic, no re-execution -- and report RESULT: ATTESTED or RESULT: REJECTED with every reason. Checks that the computation that ran is the sanctioned script (procedure_hash equals sha256 of the computation file, or the expected hash), that the receipt is internally consistent (memo_key recomputes from its own procedure_hash, params, and inputs under fragletc's documented formula, so an edited params field fails), that any claimed params match, that the run succeeded, and that an artifact claimed to be an output of the run hashes to what the receipt recorded.

Use when a result (a number, a phrase, an image) claims to have come from a tool run and you need to confirm the run was the sanctioned script with those parameters, or when checking the receipts bundled with a published document, image, or poem.

```sh
<skill-dir>/attest.py -p receipt="<receipt>" [-p computation="<computation>"] [-p procedure_hash="<procedure_hash>"] [-p params="<params>"] [-p artifact="<artifact>"] [-p artifact_name="<artifact_name>"]
```

Parameters:
- `receipt` (file, required) — The fragletc --receipt JSON to attest
- `computation` (file, optional) — The sanctioned script the run must have executed (its sha256 must equal the receipt's procedure_hash)
- `procedure_hash` (string, optional) — Expected procedure_hash (sha256:<hex>), for when the script file is not at hand
- `params` (string, optional) — Claimed parameters as key=value pairs separated by |, e.g. location=Edmonton|day=0; each must match the receipt exactly
- `artifact` (file, optional) — A file claimed to be one of the run's outputs (a figure, a document); its sha256 must appear in the receipt's outputs
- `artifact_name` (string, optional) — Which declared output the artifact claims to be (a relpath under /output); omitted, any output may match

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `ledger.py`

Typeset an archive of fragletc receipts (fraglet-receipt/2) as a ledger: one row per run with its tool, memo key, params, inputs and outputs by content hash, and exit code, in run order. Where a run's input hash is an earlier run's output hash the row says so, which makes the archive a provenance graph a reader can follow by hand. If the archive also carries blobs/<sha256 hex> files, every hash present in it is marked, so the reader knows which bytes travel with the ledger and which are hash-only. Emits an HTML fragment (default) or Markdown to stdout, for embedding in a page such as a Daily Fraglet edition.

Use when a bundle of receipts must be presented to a reader as evidence -- an appendix, a ledger page, a provenance table -- rather than handed over as raw JSON.

```sh
<skill-dir>/ledger.py -p receipts="<receipts>" [-p format=html] [-p prefix=12]
```

Parameters:
- `receipts` (file, required) — tar/tar.gz/zip containing receipts/*.json and optionally blobs/<hex>
- `format` (string, optional, default `html`) — html (a fragment with class="ledger") or md
- `prefix` (string, optional, default `12`) — How many hex characters of each hash to print

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.
