How to propose a protocol change

What a change to the wire format or to normative behaviour has to touch, and how versioning lets implementations survive it.

Where the protocol stands #

Protocol 0.1 is a first version. The wire format may change before 1.0, and a version change is announced in the handshake.

The repository does not define a formal process for changes: no proposal template and no review board. What it does have is a set of checks that every change to the protocol has to pass, and they describe what a complete proposal looks like. This page explains them.

What counts as a protocol change #

Anything another implementation would have to follow:

  • a new or changed frame, method, event, error code or data shape;
  • a change to a formula two parties compute independently: proofs, seal keys and MACs, canonical JSON, the pointer frame, delta application, the prompt card;
  • a change to a normative sentence of the specification (MUST, SHOULD, MAY);
  • a change to a limit or a default the specification states;
  • a change to one of the 16 security requirements of section 14.

A change inside the reference implementation that no peer can observe is not a protocol change.

What a change has to touch #

In one pull request:

  1. docs/SPEC.md. The behaviour, in normative words. Say what a receiver does with input it does not expect.
  2. packages/core/src/protocol.ts. The wire types. The file's own rule: if the specification and the types ever disagree, fix both in one change.
  3. conformance/requirements.json and a test. Each new normative sentence needs an entry that quotes it and names at least one test. The meta-test fails otherwise, and it also fails when a quote no longer occurs in the specification, so an edited sentence needs its entry updated.
  4. The vectors, when a computed value changes. Edit the generator, conformance/tools/make-vectors.mjs, which computes from the specification's formulas with node:crypto only, then regenerate. Do not edit the JSON by hand.
  5. The reference implementation, with its own tests.
  6. docs/SECURITY.md, when the change moves what an attacker can do: a new row in the threat table, or a new entry under what Reins does not protect against.
  7. This wiki, where a page explains what changed. Pages that include tables from the specification follow by themselves.

Compatibility #

Within a version:

  • receivers ignore unknown fields on frames;
  • receivers ignore unknown event topics;
  • receivers refuse unknown methods with E_UNKNOWN_METHOD;
  • a receiver reads an unknown error code in a response as E_INTERNAL and in a bye as E_GONE.

So a change that only adds an optional field, an event topic, a method or an error code can be made without breaking a peer that does not know it. A peer that does not know a new method refuses it; an agent has to cope with that.

A change that alters what existing frames mean, or what two parties compute, needs a new version. challenge.v lists the versions the hub speaks; the peer picks one and states it in hello.v; no common version is E_VERSION.

Before you write the pull request #

Open an issue in the repository and describe the problem first, before the solution. A protocol change is easier to accept when it is clear what cannot be done today. Useful things to include:

  • what you are trying to build, and where 0.1 stops you;
  • whether the change is additive or needs a version;
  • which party enforces it, the hub or the surface, and what a hostile agent could do with it;
  • what it costs in tokens: the protocol's economy is a goal, not an accident.

The security requirements set the bar for anything that gives an agent a new ability: it has to be covered by a scope, a rate, the policy, and where it matters the person's consent, and it must not evaluate anything an agent supplied.

If you maintain another implementation #

Say so in an issue. Nothing in the repository tracks other implementations yet, and a change is easier to judge when its cost to others is known.

Further reading #