An open standard for verifiable execution provenance: a portable, third-party-verifiable record of what an agent did, in what order, and under what governance.
Status: DRAFT (pre-1.0). This repository publishes the specification, the conformance design, and the signed conformance vectors. A reference verifier ships in the Flynn runtime, and independent verifiers in Rust, Python, and JavaScript live in
clients/. The on-the-wire format is not frozen until v0.1.0, so nothing here should yet be relied on as a production security control. See Status and roadmap.
Autonomous and semi-autonomous agents increasingly take real actions: calling tools, writing files, moving money, talking to other agents. Provetrail defines a portable record that lets an independent third party answer, after the fact and without trusting the producer:
- What actions did this agent take, and in what order?
- Under what authority were they allowed to run?
- Can you prove the record itself was not tampered with?
A Provetrail record is an append-only, ordered log of events, where the run's state is a deterministic function of the log (replay = re-fold), each event carries the authority it ran under, and every event is committed as a leaf in an append-only Merkle log under a signed root, so any alteration is detectable.
For the design rationale, why a record is only as trustworthy as the runtime that emits it, and what separates a signed record from a proven one, see Proof requires a runtime.
Provetrail is deliberately one layer in a stack, and complements rather than replaces the neighbouring standards:
| Question | Layer |
|---|---|
| Is this media authentic / AI-generated? | C2PA (content provenance) |
| How does an agent connect to a tool? | MCP (tool connection) |
| How do two agents talk? | A2A (agent transport) |
| Who is this agent and what is it authorized to do? | agent-identity standards (did, verifiable credentials, agent passports) |
| What did the agent actually do, and can you prove it? | Provetrail (execution provenance) |
Provetrail is not a new identity system, a new transport, or a new tool protocol. It references those layers (an event's actor is an identity from whatever identity standard you use) and adds the missing half: a verifiable record of execution.
- The event envelope - the wire format of one immutable, ordered event (stream, monotonic sequence number, time, type, actor, payload, schema version, causal linkage).
- The verification-gate contract - a typed declaration of which checks an action passed before and while it ran, recorded as events. This is what turns "performed under governance" from a slogan into a checkable claim.
- The trust-to-containment admission record - every action is admitted against an authority grant and a containment decision before it executes, and that admission is recorded. A verifier can then prove "no action executed without admission."
Provetrail is designed so a verifier in any language can check a record without re-implementing the producer:
- The proof carries the exact canonical bytes of each event. A verifier rehashes the bytes it is given; it never re-serializes. Cross-language verification cannot drift on encoding differences.
- The canonical encoding is deterministic CBOR (CDE profile); signatures use COSE; the append-only log uses RFC 9162-style inclusion and consistency proofs; signatures are Ed25519. A non-canonical JSON projection may be emitted for humans, but it is never what is hashed or signed.
Conformance is defined by a public test-vector suite (see CONFORMANCE.md): a verifier is Provetrail-conformant if and only if it accepts every valid vector and rejects every tampered vector with the correct failure code.
SPEC.md the specification (DRAFT v0.1.0)
CONFORMANCE.md the conformance vector suite design + failure-code registry
predicates/run-provenance.md the run-provenance statement/predicate definition
docs/ design rationale (the "signed vs proven" argument)
vectors/ the published conformance vectors (structural L1 and cryptographic L2-L4)
clients/ independent verifiers (the provetrail crate, PyPI, and npm packages)
LICENSE Apache-2.0 (code, schemas, vectors)
LICENSE-docs CC-BY-4.0 (specification prose)
Provetrail assembles existing, audited standards rather than inventing cryptography: I-JSON / deterministic CBOR for the value model, COSE (RFC 9052) for signing, in-toto / SCITT statement layering, RFC 9162 (Certificate Transparency v2) Merkle mechanics for the transparency log, and Ed25519 (RFC 8032) for signatures.
A reference implementation and verifier ship in the Flynn agent runtime: the chain package (deterministic-CBOR encoding, the RFC 9162 Merkle log, COSE signing, and sealed run records) and the flynn spine verify command. Three further independent verifiers, in Rust, Python, and JavaScript, live in clients/; each is checked against the published vectors and agrees byte for byte with the others, so the cross-language claim is demonstrated rather than asserted. Provetrail itself is implementation-neutral: any conformant producer or verifier in any language is a first-class citizen, and the standard is intentionally not bound to any single implementation.
This is an early public draft published to invite review and to fix the format before the cryptographic layer lands. In rough order:
- Specification draft (primitives, canonicalization, proof artifact)
- Conformance suite design (tiers, taxonomy, failure-code registry)
- Reference implementation: deterministic-CBOR encoder + structural verifier
- Cryptographic layer: Merkle log, COSE signing, signed roots (the point at which "verifiable" is a claim with teeth)
- Golden-pinned conformance vectors published in this repository (structural L1 and cryptographic L2-L4, in
vectors/) - Independent verifiers in Rust, Python, and JavaScript, each checked against the published vectors
- v0.1.0 tag and format freeze
The cryptographic layer is implemented in the reference implementation, so a record can be cryptographically verified against a signing key today. The on-the-wire format is not frozen until v0.1.0, so do not rely on a Provetrail record as a production security control before then.
Specification prose is licensed under CC-BY-4.0. Code, schemas, and conformance vectors are licensed under Apache-2.0. Provetrail is a trademark of Ion Alpha.
This is a draft under active design. Issues and discussion are welcome. Please keep proposals grounded in the existing primitives above; the goal is to assemble proven building blocks, not to invent new cryptography.