1.5. Protocol Conformance Catalogue
1.5.1. Conformance
How a second implementation proves it speaks fleetmesh, without reading Python.
docs/implementing.md says what a node must get right; vectors/ holds the
bytes. This page is the machine between them: a harness that drives any
implementation through every vector and says, per plane, whether it conforms.
1.5.1.1. The protocol
The implementation under test is a command that reads JSON lines on stdin and
writes one JSON line per request on stdout, matched by id:
-> {"id": 1, "op": "hello", "args": {}}
<- {"id": 1, "result": {"implementation": "mynode 0.3", "ops": ["fingerprint.of", ...]}}
-> {"id": 2, "op": "fingerprint.of", "args": {"ids": ["00...01", "00...02"]}}
<- {"id": 2, "result": "2973d890ce3e3f7a43d05d44eb4d4fcf"}
-> {"id": 3, "op": "projection.canonical_relay", "args": {"url": "https://x"}}
<- {"id": 3, "result": {"refused": "scheme must be ws or wss, not 'https'"}}
-> {"id": 4, "op": "no.such", "args": {}}
<- {"id": 4, "error": {"code": "unsupported", "message": "no.such"}}
Rules, all of them:
hellocomes first and lists the ops the implementation answers. Any op not listed is skipped by the harness, never failed. A partial implementation gets an honest score for the planes it speaks.A protocol refusal (a malformed event, a relay URL that is not a relay) is a result of the shape
{"refused": "<why>"}. The vectors pin the reason text where the reference has one.An error is about the harness-implementation contract, not the protocol. Three codes:
unsupported(op not in the catalogue),bad_args(args did not have the shape below),internal(the implementation fell over - always its bug).Bytes are hex strings. There are no other encodings; every value is plain JSON so any language can take part. Floats are compared to six places.
EOF on stdin ends the session. Blank lines are ignored; a line that is not JSON gets
bad_argswithid: null.
The reference speaks it as python3 -m fleetmesh_core.conformance (or
python3 -m fleetmesh_core.conformance from the core package); the loop is
fleetmesh_core/conformance/conformance.py, forty lines, and is the normative description of the
protocol above.
1.5.1.2. Running the harness
python3 scripts/conform.py -- python3 -m fleetmesh_core.conformance # the reference, on itself
python3 scripts/conform.py -- ./target/release/mynode conform # yours
python3 scripts/conform.py --list # the op catalogue, by plane
python3 scripts/conform.py --cases # every case the vectors produce
python3 scripts/conform.py --json -- <cmd> # machine-readable summary
Output is one line per plane:
implementation: fleetmesh-core (python reference) (111 ops)
identity conformant 146 passed 0 failed 0 skipped
store conformant 87 passed 0 failed 0 skipped
peering conformant 141 passed 0 failed 0 skipped
transport conformant 12 passed 0 failed 0 skipped
services conformant 73 passed 0 failed 0 skipped
operations conformant 64 passed 0 failed 0 skipped
A plane is conformant when every case in it passed and none were skipped; partial when some passed and the rest were skipped; not attempted when every case was skipped; FAILED when any case failed. Exit status is 1 on any failure and 0 otherwise - a partial implementation passes, and says so. Every failure prints what was got and what was wanted.
scripts/check-vectors.py runs the reference through this harness on every
push, so the harness’s reading of the vectors is proven against the code the
vectors were generated from. A harness that drifted from the vectors would
otherwise pass a wrong second implementation.
1.5.1.3. What the harness does not test
The harness tests mechanisms: given these bytes, produce those. It does not start a node, open a socket or hold a peering. Two things it cannot say:
that your node sends what it can compute - the live interop suite (
scripts/interop.sh, negentropy against strfry and nostr-veil) covers the relay side, and a peering-plane interop between two nodes is the open item;that your node refuses at the door what
validate.pyrefuses - the door is a boundary (docs/implementing.md, Transport & Doors), and the vectors for its refusals are per-kind, under the*.checkops.
1.5.1.4. A second implementation
meshctl conform (Rust, in the meshctl repo) speaks this wire for the
store/reconciliation mechanisms - NIP-77 fingerprints and varints, message
framing, bounds, reconciliation and store membership - and was written from
docs/, schema/ and vectors/ without reading fleetmesh_core/. It started as nine
ops scoring store partial; it now speaks all thirty-five store ops - receipt
chains, delivery envelopes, heartbeats and the endpoints digest, coverage
claims and handover chains, telemetry, Blossom mirror authorization - and
scored store conformant (87 cases, 0 skipped) first, and now every plane:
identity, peering, transport, services and operations, 523 cases, which its
CI enforces per plane. Docs gaps found on the way were fixed upstream rather
than worked around: store.replay’s result shape, that the Blossom
Authorization header carries the event in canonical form, the NIP-90 result
request tag’s serialisation, the nsite content-type table. The bar for any
further op is the same: docs and vectors in, a conformant plane out.
The operations plane’s cases are the release channel only (release.*,
vectors/release.json): the control socket and the sidecar manifest are
internal contracts, not wire a second node must match.
1.5.1.5. Stability
The op catalogue is not in the schema digest. Op names are a test
interface, not wire bytes, and a second implementer will want to rename or
split ops in their first weeks. It is published machine-readably as
schema/conformance.json (ops with plane and one-liner, the error codes,
verdicts and wire shapes), generated from fleetmesh_core/conformance/conformance_ops.py by
scripts/check-conformance.py --write and held in step by CI, so it is
versioned and tagged with the protocol without moving the digest. A rename is
a commit here plus a change in your hello; the table below and the JSON are
the same facts.
Argument shapes are the vector files’ shapes; result shapes are the vector’s
expect, except where an op’s one-liner says otherwise (the first Rust spike
found exactly one: store.replay answers a flat list of fingerprints, not the
vector’s named range objects, so the one-liner now says so). An implementer
should never need the Python to learn a shape - if you do, that is a docs bug
to report, not a thing to work around.
Argument shapes are the vector files’ shapes. scripts/conform.py derives
every request straight from a vectors/*.json entry, so when an argument’s
shape is in doubt the vector that produces the case is the answer; --cases
names the op for every case label.
1.5.1.6. The op catalogue
Generated from fleetmesh_core/conformance/conformance_ops.py by scripts/check-conformance.py --write.
1.5.1.6.1. identity (61 ops, 511 cases)
op |
about |
cases |
|---|---|---|
|
roles closed under implication, in canonical order |
9 |
|
a login body with method and short-field aliases filled in |
6 |
|
the principal dict the wire shows for a set of principal fields |
1 |
|
npub of a hex pubkey |
1 |
|
blinding scalar d from shared x, info and salt strings |
2 |
|
the sorted tool refs of a brand {brand} run by {authority}: tools both endorsed in {endorsements} and self-labelled in {claimed_events} at {now}, or refused brand_unsupported |
13 |
|
read a tool event {event}’s own NIP-32 brand self-label: {namespace, brand, kind, pubkey}, or refused |
10 |
|
read a kind 1985 NIP-32 brand endorsement {event} at {now}: {namespace, brand, target, issuer, created_at, expiration}, or refused |
13 |
|
x coordinate of the ECDH shared point |
3 |
|
HKDF-SHA256 (RFC 5869); ikm/info/salt hex, length bytes |
3 |
|
x-only public key of a secret key |
7 |
|
BIP-340 signature of a 32-byte message with zero aux |
2 |
|
problems a kind 11801 has at a given clock |
2 |
|
the resolved node profile for a kind 11801, aliases included |
1 |
|
did:key of a key kind over raw hex (node = x-only hex) |
3 |
|
{method, did, pubkey, slug, refusal} of an operator DID (bare hex, did:nostr, did:group), or refused |
12 |
|
{method, node[, kind]} of a did:nostr / did:key / did:peer, or refused |
9 |
|
did:peer:2 of node x-only hex, agreement hex or null, DIDComm service or null |
4 |
|
{node, agreement, service} read back from a did:peer:2, or refused |
9 |
|
problems a discovery event has against its descriptor |
4 |
|
NIP-66 discovery events from a descriptor and NIP-11 document |
2 |
|
NIP-66 network label of a URL |
3 |
|
the circle form of a fleet/enrol token: fmenrol1 + the member {copies} + the circle’s kind 30834 {group_events}, ~-joined; or refused (shape) |
5 |
|
the grant an fmenrol1 token carries ({ucan, id, operator, node, with, can, tier, exp, nbf}), shape-checked only, or refused token_malformed | token_legacy |
13 |
|
{token, ucan, id, operator, pubkey, node, with, can, tier, exp, nbf} of a fleet/enrol grant minted by {sk} for {node} (aud) with a fixed {nonce}, fmenrol1-encoded |
9 |
|
{token, operator, pubkey, node, id, exp[, group_events, quorum]} of a token whose fleet/enrol grant verifies for {node} (aud) at {now} given {revocations} (a circle token: by quorum, against its own controller documents), or refused |
25 |
|
NIP-40 expiration of an event, or null: the first well-formed tag, ASCII digits only |
11 |
|
id and signature of a Nostr event check out |
6 |
|
the roster {nodes} joined to {descriptors} and {heartbeats} by node pubkey at {now}: one entry per node, sorted, status online|stale|unknown |
4 |
|
sorted pubkeys of the current kind 11801s whose operator is {operator} in any spelling |
6 |
|
seal/live/stored kinds, skew max and retention |
1 |
|
open a wrap for a recipient: {payload, from}, or refused |
2 |
|
refusal text when wrapping a kind the profile forbids |
2 |
|
{ok, d, expected, problems}: whether a kind 30832 d is sha256 of its content |
7 |
|
the claims a grant token carries plus its id, shape-checked only, or refused token_malformed |
16 |
|
the unsigned kind 30832 event for a BIP340 {token} at {created_at}; for a NIP01 token the signed event it was cut from (created_at is the token’s own); or refused token_malformed |
14 |
|
{token, id} of the NIP01 token a signed kind 30832 {event} carries, or refused token_malformed (not a NIP01 envelope, tags not those the claims derive, pubkey not the iss) or bad_signature |
12 |
|
{token, id, iss, aud, exp} of a kind 30832 grant minted by {sk} to {aud} for {with}, {can[]}, {tier}, {exp}[, nbf, poll, ratify_by, nonce, group, epoch, alg, created_at]; alg NIP01 (plan D21) signs the envelope event at created_at |
23 |
|
whether a kind 30833 names {grant} |
4 |
|
the unsigned kind 30832 event that any nostr event signer signs to mint a NIP01 token: {iss} (a pubkey or did:nostr), {aud}, {with}, {can[]}, {tier}, {exp}, {created_at}[, nbf, poll, ratify_by, nonce, group, epoch], or refused with the issue error |
5 |
|
{accepted, via, operator, grantee, depth, capability, tier, grants[, quorum]} when {chain} authorises {audience} to {can} on {resource} at {now} under {operator}[, revocations, group_events, early], or refused |
80 |
|
{id, pubkey, created_at, did, type, epoch, controllers, thresholds, expiration, body} of a kind 30834 {event}, or refused (shape or signature) |
11 |
|
{did, genesis, current, epochs[{epoch, type, controllers, thresholds, expiration, signers, seen_at}]} of {group} from the kind 30834 {events} in the order seen, at {now}, or refused group_unresolved |
13 |
|
whether a kind 30833 at the group DID by a current controller of {group} (resolved from {events} at {now}) names {grant} |
4 |
|
NIP-44 conversation key from sk and pk |
2 |
|
NIP-44 v2 plaintext |
1 |
|
NIP-44 v2 payload with a given nonce |
1 |
|
padded length for an unpadded length |
11 |
|
canonical spelling of a relay URL, or refused |
40 |
|
problems an assertion has against its report ([] = holds) |
5 |
|
NIP-85 assertions from one report |
5 |
|
rank by outcome table |
1 |
|
relay endpoints a descriptor advertises |
1 |
|
[name, major, minor] of a fleetmesh protocol identifier, or null |
2 |
|
open a kind 30835 {event} with the owner key {key}: {name, nodes}, or refused |
18 |
|
the signed challenge string, its sha256, and the digest under every accepted scheme |
1 |
|
minted/accepted ticket prefixes and challenge schemes, ticket bounds, kinds, error codes |
1 |
|
the challenge reply for a fixed challenge id at a given clock |
1 |
|
the bundle inside a ticket string of any accepted prefix, or refused ticket_malformed |
3 |
|
a portable ticket (bundle and fmpass_ string) from a secret key, fixed nonce and clock |
2 |
|
verify a login body given the challenges issued and event ids seen: the verified result, or refused |
24 |
1.5.1.6.2. store (47 ops, 182 cases)
op |
about |
cases |
|---|---|---|
|
BUD-01 authorization event (unsigned fields given signer) |
1 |
|
Authorization header for an auth event |
1 |
|
pubkey an auth event authorizes for verb/now/sha, or refused |
6 |
|
BUD-04 mirror request body |
1 |
|
blob descriptor after a mirror |
1 |
|
auth event from an Authorization header |
1 |
|
the x tag of an auth event |
1 |
|
why a reporter is barred from reporting on a claim, or null |
5 |
|
problems a bare handover chain has |
2 |
|
problems a coverage claim has for a node class |
8 |
|
the from-pubkeys of a claim’s handover chain, in order |
1 |
|
problems a handover artefact has |
1 |
|
id of a handover artefact |
1 |
|
handover verifies under its signer |
1 |
|
the handover a replica claim carries inline |
1 |
|
sha256 hop message for domain|event|prev|at |
2 |
|
problems a delivery envelope path has ([] = verifies) |
3 |
|
range fingerprint of a set of event ids |
7 |
|
fingerprint of two disjoint id sets composed |
1 |
|
negentropy varint encoding |
6 |
|
[problems, notices] of a heartbeat against a descriptor |
1 |
|
heartbeat announces retirement |
2 |
|
digest of a descriptor endpoint tag set |
2 |
|
decode a message to [[timestamp, prefix_hex, mode], …] |
1 |
|
encode ranges: [[timestamp, prefix_hex, mode, payload], …] |
1 |
|
shortest prefix separating previous from item |
2 |
|
have/need after a full reconciliation |
1 |
|
protocol version byte, hex |
1 |
|
the product fiber of {product} (its {mime, schema, digest, bao_root, canonical, byte_length}) or the fields read back from {fiber}: an optional {mime} must be the fleetmesh product MIME, or refused |
6 |
|
verify a product {product} and its lifecycle log: {product_id, count, version, digest, bao_root, active_recall_id, attested_stages, price_points, events} or refused |
8 |
|
canonical JSON and sha256 of a receipt link |
5 |
|
insert events; result {enumerate: [id], ranges: [fingerprint hex, one per range in order]} |
1 |
|
order-of-magnitude bin of a counter |
11 |
|
problems a telemetry event has |
5 |
|
kind and bin labels |
1 |
|
the kind 21802 event for counters (unsigned fields) |
1 |
|
metrics read back from a telemetry event |
1 |
|
the built-in schema fiber of a strand {kind}: its payload and root; refused type_unknown |
5 |
|
the built-in strand types: schema_id -> published root, sorted |
1 |
|
the payload, root and schema_id read from a schema fiber ({canonical} or {bytes_hex}[, root]); refused schema_fiber_invalid |
4 |
|
read a kind 30821 strand {event}: {payload, root, kind, schema_root}, or refused |
17 |
|
a strand {manifest}’s type: {source (fiber|builtin), schema_id, kind, schema_fiber_root} given {known_schemas}; refused type_unknown|schema_fiber_invalid |
8 |
|
the fibers entry a strand carries for its type (role schema), from a {schema} and {layer} |
1 |
|
the Bao root and canonical bytes of a schema fiber payload ({schema} in its fields, {layer} strand|fabric) |
4 |
|
the unsigned kind 30821 strand event for {manifest} by {pubkey} at {created_at}[, primary_sha256, primary_mime]: content is the canonical root payload, tags d/strand_kind/root and, when the strand carries them, schema/x/m; refused strand_manifest_invalid when the manifest fails the strand document check |
11 |
|
a strand {manifest}’s root and version: v1 unchanged, v2 when it carries refs |
4 |
|
problems a strand {manifest} has against its type, as refusal codes ([{valid, errors, schema_id}]), from {schema} or by resolving with {known_schemas} |
26 |
1.5.1.6.3. peering (29 ops, 229 cases)
op |
about |
cases |
|---|---|---|
|
{pressure, binding} from measured against total |
6 |
|
ladder rungs at a pressure |
6 |
|
the floor a shed never crosses, from probation ceilings |
1 |
|
whether a complaint of a severity may be published now |
18 |
|
the disclose message a descriptor answers a query with |
5 |
|
disclosed ids of a disclose message |
5 |
|
query list of a discover-features queries message |
5 |
|
protocol ids a descriptor discloses |
1 |
|
the new signed kind 30830 that admits {node} to {definition}, signed by the controller {controller_sk} at {created_at}: the current tags plus one member tag, everything else unchanged, created_at strictly later; refused already_member when the roster already names the node |
2 |
|
open a sealed network/1.0 {wrap} with {recipient_sk} against the current {definition} at {now}, a created_time no older than {max_age} seconds and no more than {skew} seconds ahead: the join-request, or refused |
27 |
|
{current}: the newest unexpired well-formed kind 30830 at {id} among events at {now}, or null |
7 |
|
problems a kind 30830 has at a given clock ([] = well formed) |
19 |
|
{public, private} unsigned templates of a kind 11801 for {networks}; public carries no network/expose tag |
4 |
|
{verdict, code, reason} for a sender under {policy, roster[, credential, issuers, now]} |
15 |
|
{members, unresolved}: member node pubkeys of a definition given the descriptors seen on its relays |
5 |
|
an acceptor’s reply to a proposal (type, and code or tier/limits/transports) |
25 |
|
link hash of a receipt body (signature excluded) |
1 |
|
signature over an unsigned receipt |
1 |
|
a receipt verifies for its subject |
3 |
|
whether a roster-protected relay lets {pubkey} do {op} (auth|event|req) on {kind} |
9 |
|
a report is admissible given which referenced events resolve |
2 |
|
evidence id of a signed receipt |
1 |
|
standing tell after a sequence of windows |
2 |
|
weight of a reporter |
7 |
|
own view given weighted reports |
8 |
|
{limits_after, tier_after} after a severity; refused for a severity or tier not on the ladder |
22 |
|
ceilings of a tier |
3 |
|
severity of a window from limits, measured and claimed |
16 |
|
opening limits of a tier |
3 |
1.5.1.6.4. transport (4 ops, 30 cases)
op |
about |
cases |
|---|---|---|
|
open a sealed control/1.0 {wrap} with {recipient_sk} at {now} inside {window} seconds: {message, sender}, or refused |
18 |
|
the tags of the kind 10050 a node publishes for its own inbox |
4 |
|
inbox relays read from a kind 10050 event |
7 |
|
the REQ filter that fetches a pubkey’s kind 10050 |
1 |
1.5.1.6.5. services (20 ops, 106 cases)
op |
about |
cases |
|---|---|---|
|
whether {order} is paid under the fulfiller rule (plan D30): open the NIP-17 {statuses} with {key} against the maker of the kind 30402 {listing} at {now} -> {paid, order, maker, signer, status}, or refused |
7 |
|
whether the current period of a recurring {listing} is covered at {now} by {orders} ([{order, period_start, paid}] as a fulfiller resolved them): {covered, through, period_seconds, order}, or refused for a listing with no price frequency |
2 |
|
build a market-spec checkout message from {message} (kind 16 {type, p, order, amount, items, status, payments, expiration, subject} or a kind 17 receipt) or read one back from {event}: {kind, type, subject, order, p, amount, status, items, payments, expiration}; refused |
17 |
|
default kinds and feedback states |
1 |
|
a feedback event (unsigned fields given signer) |
1 |
|
{is_request, parsed, executor, job} of a job request |
10 |
|
a result event (unsigned fields given signer) |
1 |
|
result kind for a request kind |
3 |
|
base36 of a hex pubkey |
1 |
|
hex pubkey of a base36 label, or null |
1 |
|
content type of a path |
14 |
|
site ref of a host under suffixes |
4 |
|
{ref, filter, canonical} of a site label |
7 |
|
{paths, aggregate, domains, servers} of a manifest |
1 |
|
resolution of a request path against manifest paths |
11 |
|
site ref of a TXT binding |
7 |
|
{headers, body} of a 402 quote |
4 |
|
msat rounded up to sat |
5 |
|
tokens of an X-Cashu header |
2 |
|
build a kind 30402 NIP-99 listing for a product {strand} (with {listing_id, title, price, currency, frequency, description, status, categories}, price a GammaMarkets [amount, currency[, frequency]]), or read one back from {event}: {d, title, price, product_ref, status}; refused |
7 |
1.5.1.6.6. operations (6 ops, 64 cases)
op |
about |
cases |
|---|---|---|
|
‘major’|’minor’|’patch’ when candidate is newer than running, else null |
9 |
|
-1/0/1 for a <,==,> b; prerelease below its release; refused when either is not a semver |
13 |
|
a kind 9900 read for {release_key[, name]}: the ReleaseInfo dict, or the refusal string |
14 |
|
[revoked event id, reason] of a kind 9901 by release_key that verifies, else null |
5 |
|
newest_compatible / incompatible_newer / refused / revoked from events for {release_key, running, digest[, name, already_revoked]} |
10 |
|
[major, minor, patch, prerelease] of a semver, or refused |
13 |