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:
docs/SPEC.md. The behaviour, in normative words. Say what a receiver does with input it does not expect.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.conformance/requirements.jsonand 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.- The vectors, when a computed value changes. Edit the generator,
conformance/tools/make-vectors.mjs, which computes from the specification's formulas withnode:cryptoonly, then regenerate. Do not edit the JSON by hand. - The reference implementation, with its own tests.
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.- 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_INTERNALand in abyeasE_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.