---
title: Provenance and receipts
description: The two kinds of signed receipt venom produces, for a completion a public node served and for a commit an agent made, what each proves, and how to check them yourself.
section: mesh
order: 40
audience: [operator, builder, agent]
sources: [docs/public-mesh.md, docs/provenance.md, services/vllm-venom-sampler, services/nodejs-cloud/contracts/fixtures/provenance, services/nodejs-cloud/app/api/mesh/v1/epochs/route.ts]
features: []
---

Venom signs two kinds of record with Ed25519 keys, both checked by a second party:

| Receipt | Signed by | Covers | Checked by |
|---|---|---|---|
| Inference receipt (`venom-receipt/1`) | a public daemon's enrolled key | one public mesh job: the prompt, the sampled tokens, the streamed text, the counts | the cloud on every job; the auditor on sampled jobs; anyone afterwards |
| Commit receipt (`venom.provenance/v1`) | the machine's key in `~/.venom/provenance.key` | one git commit: the agent, models, tools, permission decisions and approvals | `venom provenance <sha>` |

## Inference receipts {#receipts}

A public daemon appends one `receipt` event to a public job's event stream, just before `end`:

```json
{"seq": 57, "type": "receipt", "receipt": {"v": 1, "job_id": "…", "sig": "…"}, "output_ids": [1234, 99]}
```

`output_ids` is outside the signed receipt and bound to it by `output_ids_sha256`; the cloud keeps it only for jobs selected for audit. Integers are JSON integers, hashes lowercase hex, and the nonce base64url without padding.

| Field | Meaning |
|---|---|
| `v` | `1` |
| `job_id`, `attempt` | from the dispatch |
| `daemon_id`, `registry_id` | the signer and the registry entry it claims to serve |
| `sampler` | `venom-sampler/1` |
| `nonce` | the dispatch's per-job nonce |
| `temp_milli`, `top_p_milli`, `top_k`, `max_tokens` | the sampling parameters actually used |
| `prompt_ids_sha256` | SHA-256 over the prompt token ids after the chat template, each as a big-endian u32 |
| `output_ids_sha256` | the same over choice 0's output token ids |
| `output_text_sha256` | SHA-256 of choice 0's `content`, a zero byte, `reasoning_content`, a zero byte, then each tool call's `name`, zero, `arguments`, zero, exactly as streamed |
| `prompt_tokens`, `completion_tokens`, `finish_reason` | as billed |
| `t_first_ms`, `t_done_ms` | the daemon's clock at the first output token and at the end |
| `engine` | for example `vllm/0.11.0`, or `vllm/llamacpp-shim/<build>` through `venom-llamacpp` |
| `sig` | Ed25519 signature, base64url without padding |

The signed bytes are `venom-receipt/1\n` followed by the canonical JSON of the receipt without `sig`: keys sorted, no whitespace (RFC 8785 for this all-integer, all-string object). Test vectors, including tampered receipts that must fail, are in `services/nodejs-cloud/contracts/fixtures/provenance/receipt-vectors.json`.

A receipt proves that the daemon committed to these tokens and this text before it could know whether the job would be audited. It does not by itself prove the model was the registered one; the audit replay does that, for the jobs selected.

### venom-sampler/1 {#sampler}

The sampler makes a random-looking draw replayable. Inputs per job: a 16-byte `nonce`, `temp_milli` (0 to 2000), `top_p_milli` (1 to 1000), `top_k` (1 to 64). At each output position `i`, from the raw log-softmax `lp`:

1. `key = HMAC-SHA256(nonce, "venom-sampler/1")`.
2. Sort tokens by `lp`, ties to the lower id, and keep the first `top_k`. At `temp_milli = 0` the first one is the answer.
3. Keep the shortest prefix whose cumulative probability at temperature `T = temp_milli/1000` reaches `top_p_milli/1000`.
4. For each kept token `v`: `h = HMAC-SHA256(key, u32be(i) ‖ u32be(v))`, `u` from the top 53 bits of `h`, `g = −ln(−ln u)`.
5. Pick the kept token with the highest `lp[v]/T + g[v]`, ties to the lower id.

Implementations in Go, Python and TypeScript must agree with `sampler-vectors.json` in the same directory to 1e-9 on every score and exactly on every choice. On vLLM, the daemon passes the parameters as `vllm_xargs` (`venom_nonce`, `venom_temp_milli`, `venom_top_p_milli`, `venom_top_k`); a request without `venom_nonce` is untouched by the plugin.

### Check audit selection yourself {#epochs}

Selection uses an hourly epoch secret. The cloud publishes each epoch's `secret_sha256` in advance and the secret itself once the epoch has ended, with no credentials needed:

```bash
curl -s 'https://cloud.usevenom.dev/api/mesh/v1/epochs?from=2026-11-01T00:00:00Z&to=2026-11-01T06:00:00Z'
```

```json
{"epoch_ms": 3600000, "data": [
  {"epoch": 498192, "starts_at": "…", "ends_at": "…", "secret_sha256": "…", "secret": "…"}
]}
```

A job's epoch is `floor(dispatched_at_ms / 3600000)`. It was selected when `uint64be(HMAC-SHA256(secret, SHA-256(signed receipt bytes))[0:8]) · 10^6 < p_ppm · 2^64`, where `p_ppm` is the audit rate in parts per million (20,000 by default, see [The public mesh](/docs/mesh/public-mesh.md#verification)). Check that the secret hashes to the `secret_sha256` published before the epoch started; then neither the cloud nor the daemon could have chosen which jobs were audited after seeing them.

## Commit receipts {#commits}

`venom provenance record` signs a receipt for `HEAD` from the newest session in the directory, stores it as a git note in `refs/notes/venom-provenance` and adds a `Venom-Receipt: sha256:<digest>` trailer to the commit message. The receipt holds the commit's tree and parents, the agent, the models that served the session (subagents included), a hash of the user's prompts (not the text), tool call counts, permission decision counts, how many asks a person approved, an optional intent id, and the digest of this key's previous receipt.

```bash
venom provenance record            # sign HEAD from the newest session here
venom provenance <sha>             # verify and print the chain of receipts behind it
venom provenance key               # this machine's key id
git push origin refs/notes/venom-provenance
```

`venom provenance <sha>` exits 0 when the signature, trailer, tree, parents and chain all check out and the signer is trusted (this machine's key, or `--trust <key id>`), 1 otherwise. `venom revert <intent>` finds commits by the intent their receipts name. The commands and flags are in [Git commands](/docs/cli/git-commands.md#provenance).

Limits: whoever can read the key file can sign as you; a receipt records what the signing process saw, not that the agent was honest; a rebase or squash breaks the binding until `record` signs the new commit; and `git push` does not send the notes ref unless you name it.

## Related

- [The public mesh](/docs/mesh/public-mesh.md): audits, trust states and the auditor.
- [Daemon API reference](/docs/mesh/daemon-api.md#epochs): the `epochs` route.
- [Public mesh hardening](/docs/reference/public-mesh-hardening.md): what the audits catch and miss.
