Provenance and receipts
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.
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
A public daemon appends one receipt event to a public job's event stream, just before end:
{"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
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:
key = HMAC-SHA256(nonce, "venom-sampler/1").- Sort tokens by
lp, ties to the lower id, and keep the firsttop_k. Attemp_milli = 0the first one is the answer. - Keep the shortest prefix whose cumulative probability at temperature
T = temp_milli/1000reachestop_p_milli/1000. - For each kept token
v:h = HMAC-SHA256(key, u32be(i) ‖ u32be(v)),ufrom the top 53 bits ofh,g = −ln(−ln u). - 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
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:
curl -s 'https://cloud.usevenom.dev/api/mesh/v1/epochs?from=2026-11-01T00:00:00Z&to=2026-11-01T06:00:00Z'{"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). 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
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.
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-provenancevenom 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.
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: audits, trust states and the auditor.
- Daemon API reference: the
epochsroute. - Public mesh hardening: what the audits catch and miss.