Format versions and long-term verification

1. Current versions#

In plain language: a receipt says which format version it uses, and that version never changes meaning. Old receipts keep verifying with the same four steps, whatever we add later.

2. What can change within format version "1"#

Within version "1", changes are additive only:

• new optional members in a receipt or a body;
• new receipt types, for new tools; and
• new versions of a single tool's body, marked inside the body as tls.watch does with bodyVersion. A body that has no bodyVersion member is the first version of that body; its next version adds the member.

None of these affects verification. The signature covers every member present in the receipt, whatever it is called, so a verifier that canonicalizes the whole receipt, as the four steps in Verifying receipts require, verifies receipts with members it has never seen. Software that reads the fields should ignore members it does not know.

3. What needs a new format version#

Any change to how receipts are canonicalized, to the signature scheme, or to the members every receipt must have, requires a new value of version. Version "1" receipts stay verifiable for good: we will not reinterpret them, and verifiers must keep accepting them alongside any later version.

Before any receipt is issued in a new format version, we will publish its description, support it in our verification libraries and on the /verify page, and announce it in the changelog. The move to post-quantum signatures, described on Post-quantum status, is the change most likely to need one.

4. The API#

The API is versioned by its path. Within /api/v1/, changes are additive: new endpoints, new optional request fields and new response fields. A change that would break existing callers gets a new path prefix, and /api/v1/ keeps working alongside it. There is no version header and no date-based versioning.

We announce API changes in the changelog. Removing a paid feature is announced by email at least 30 days ahead, as the Terms of Service say.

5. Verification libraries#

The verification libraries follow semantic versioning. A new major version may drop support for an old runtime, but never for an old receipt format or an old published key: every library version verifies every receipt format version that existed when it was released. There is no fixed support window for library versions yet; the four steps are simple enough that any current version, or your own code, will do.

6. Keeping receipts verifiable for decades#

Three things keep an old receipt verifiable without us:

1. The format is frozen. A version "1" receipt means the same thing in twenty years as it does today.
2. The key is pinned. Store the key set the receipt verified against with the receipt. Retired keys also stay in our published set, as Key management describes.
3. The algorithm is standard. Ed25519 and RFC 8785 have independent implementations in every major language. You do not need our code.

For evidence that must outlast a possible future quantum computer, see Post-quantum status.

7. Changes and contact#

We update this page when a version changes. Questions: support@agined.com.