Skip to content
Docs menu

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.

View .md

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:

  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

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-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.

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.