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:

  • hello comes 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_args with id: 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.py refuses - the door is a boundary (docs/implementing.md, Transport & Doors), and the vectors for its refusals are per-kind, under the *.check ops.

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

auth.expand_roles

roles closed under implication, in canonical order

9

auth.normalize_payload

a login body with method and short-field aliases filled in

6

auth.principal

the principal dict the wire shows for a set of principal fields

1

bech32.npub

npub of a hex pubkey

1

blinding.derive

blinding scalar d from shared x, info and salt strings

2

brand.members

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

brand.read_claim

read a tool event {event}’s own NIP-32 brand self-label: {namespace, brand, kind, pubkey}, or refused (not_a_tool, wrong_namespace, bad_signature, not_claimed)

10

brand.read_endorsement

read a kind 1985 NIP-32 brand endorsement {event} at {now}: {namespace, brand, target, issuer, created_at, expiration}, or refused (not_brand_label, wrong_namespace, bad_signature, expired, ttl_exceeded)

13

crypto.ecdh_x

x coordinate of the ECDH shared point

3

crypto.hkdf

HKDF-SHA256 (RFC 5869); ikm/info/salt hex, length bytes

3

crypto.pubkey

x-only public key of a secret key

7

crypto.schnorr_sign

BIP-340 signature of a 32-byte message with zero aux

2

descriptor.validate

problems a kind 11801 has at a given clock

2

did.document

the resolved node profile for a kind 11801, aliases included

1

did.key

did:key of a key kind over raw hex (node = x-only hex)

3

did.operator_parse

{method, did, pubkey, slug, refusal} of an operator DID (bare hex, did:nostr, did:group), or refused

12

did.parse

{method, node[, kind]} of a did:nostr / did:key / did:peer, or refused

9

did.peer

did:peer:2 of node x-only hex, agreement hex or null, DIDComm service or null

4

did.peer_parse

{node, agreement, service} read back from a did:peer:2, or refused

9

discovery.check

problems a discovery event has against its descriptor

4

discovery.events

NIP-66 discovery events from a descriptor and NIP-11 document

2

discovery.network

NIP-66 network label of a URL

3

enrol.token_assemble

the circle form of a fleet/enrol token: fmenrol1 + the member {copies} + the circle’s kind 30834 {group_events}, ~-joined; or refused (shape)

5

enrol.token_decode

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

enrol.token_issue

{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

enrol.token_verify

{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

event.expiration

NIP-40 expiration of an event, or null: the first well-formed tag, ASCII digits only

11

event.verify

id and signature of a Nostr event check out

6

fleet.from_roster

the roster {nodes} joined to {descriptors} and {heartbeats} by node pubkey at {now}: one entry per node, sorted, status online|stale|unknown

4

fleet.members

sorted pubkeys of the current kind 11801s whose operator is {operator} in any spelling

6

giftwrap.constants

seal/live/stored kinds, skew max and retention

1

giftwrap.unwrap

open a wrap for a recipient: {payload, from}, or refused

2

giftwrap.wrap_kind_allowed

refusal text when wrapping a kind the profile forbids

2

grant.coordinate

{ok, d, expected, problems}: whether a kind 30832 d is sha256 of its content

7

grant.decode

the claims a grant token carries plus its id, shape-checked only, or refused token_malformed

16

grant.envelope

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

grant.from_event

{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

grant.issue

{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

grant.revoked

whether a kind 30833 names {grant}

4

grant.template

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

grant.verify

{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

group.read

{id, pubkey, created_at, did, type, epoch, controllers, thresholds, expiration, body} of a kind 30834 {event}, or refused (shape or signature)

11

group.resolve

{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

group.revoked

whether a kind 30833 at the group DID by a current controller of {group} (resolved from {events} at {now}) names {grant}

4

nip44.conversation_key

NIP-44 conversation key from sk and pk

2

nip44.decrypt

NIP-44 v2 plaintext

1

nip44.encrypt

NIP-44 v2 payload with a given nonce

1

nip44.padded_len

padded length for an unpadded length

11

projection.canonical_relay

canonical spelling of a relay URL, or refused

40

projection.check

problems an assertion has against its report ([] = holds)

5

projection.project

NIP-85 assertions from one report

5

projection.rank

rank by outcome table

1

projection.relay_endpoints

relay endpoints a descriptor advertises

1

protocol.version

[name, major, minor] of a fleetmesh protocol identifier, or null

2

roster.open

open a kind 30835 {event} with the owner key {key}: {name, nodes}, or refused (not_roster, not_author, bad_content, bad_shape)

18

webauth.challenge_message

the signed challenge string, its sha256, and the digest under every accepted scheme

1

webauth.constants

minted/accepted ticket prefixes and challenge schemes, ticket bounds, kinds, error codes

1

webauth.issue_challenge

the challenge reply for a fixed challenge id at a given clock

1

webauth.ticket_decode

the bundle inside a ticket string of any accepted prefix, or refused ticket_malformed

3

webauth.ticket_mint

a portable ticket (bundle and fmpass_ string) from a secret key, fixed nonce and clock

2

webauth.verify

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

blossom.auth_event

BUD-01 authorization event (unsigned fields given signer)

1

blossom.auth_header

Authorization header for an auth event

1

blossom.check_auth

pubkey an auth event authorizes for verb/now/sha, or refused

6

blossom.mirror_request

BUD-04 mirror request body

1

blossom.mirror_response

blob descriptor after a mirror

1

blossom.parse_auth_header

auth event from an Authorization header

1

blossom.x_tag

the x tag of an auth event

1

coverage.barred_reporter

why a reporter is barred from reporting on a claim, or null

5

coverage.chain_check

problems a bare handover chain has

2

coverage.check

problems a coverage claim has for a node class

8

coverage.handover_chain

the from-pubkeys of a claim’s handover chain, in order

1

coverage.handover_check

problems a handover artefact has

1

coverage.handover_id

id of a handover artefact

1

coverage.handover_verify

handover verifies under its signer

1

coverage.inline_handover

the handover a replica claim carries inline

1

envelope.hop_message

sha256 hop message for domain|event|prev|at

2

envelope.verify

problems a delivery envelope path has ([] = verifies)

3

fingerprint.of

range fingerprint of a set of event ids

7

fingerprint.union

fingerprint of two disjoint id sets composed

1

fingerprint.varint

negentropy varint encoding

6

heartbeat.check

[problems, notices] of a heartbeat against a descriptor

1

heartbeat.is_retiring

heartbeat announces retirement

2

lifecycle.endpoints_digest

digest of a descriptor endpoint tag set

2

negentropy.decode

decode a message to [[timestamp, prefix_hex, mode], …]

1

negentropy.encode

encode ranges: [[timestamp, prefix_hex, mode, payload], …]

1

negentropy.minimal_bound

shortest prefix separating previous from item

2

negentropy.reconcile

have/need after a full reconciliation

1

negentropy.version

protocol version byte, hex

1

product.read_fiber

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 (not_a_product, bad_mime, bad_price)

6

product.verify_log

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 (not_a_product, bad_price, fiber_digest_mismatch, unknown_event_kind, event_wrong_product, bad_recall, bad_event_digest)

8

receipt_chain.sha256

canonical JSON and sha256 of a receipt link

5

store.replay

insert events; result {enumerate: [id], ranges: [fingerprint hex, one per range in order]}

1

telemetry.bin_of

order-of-magnitude bin of a counter

11

telemetry.check

problems a telemetry event has

5

telemetry.constants

kind and bin labels

1

telemetry.event

the kind 21802 event for counters (unsigned fields)

1

telemetry.read

metrics read back from a telemetry event

1

textile.builtin_schema

the built-in schema fiber of a strand {kind}: its payload and root; refused type_unknown

5

textile.catalog

the built-in strand types: schema_id -> published root, sorted

1

textile.read_schema_fiber

the payload, root and schema_id read from a schema fiber ({canonical} or {bytes_hex}[, root]); refused schema_fiber_invalid

4

textile.read_strand_event

read a kind 30821 strand {event}: {payload, root, kind, schema_root}, or refused (strand_event_invalid, strand_content_missing, strand_root_mismatch, strand_d_mismatch, strand_kind_mismatch, strand_schema_mismatch)

17

textile.resolve_type

a strand {manifest}’s type: {source (fiber|builtin), schema_id, kind, schema_fiber_root} given {known_schemas}; refused type_unknown|schema_fiber_invalid

8

textile.schema_fiber

the fibers entry a strand carries for its type (role schema), from a {schema} and {layer}

1

textile.schema_root

the Bao root and canonical bytes of a schema fiber payload ({schema} in its fields, {layer} strand|fabric)

4

textile.strand_event

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

textile.strand_root

a strand {manifest}’s root and version: v1 unchanged, v2 when it carries refs

4

textile.validate_typed

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

capacity.pressure

{pressure, binding} from measured against total

6

capacity.rungs

ladder rungs at a pressure

6

capacity.shed_floor

the floor a shed never crosses, from probation ceilings

1

complaint.may_publish

whether a complaint of a severity may be published now

18

discover.answer

the disclose message a descriptor answers a query with

5

discover.ids

disclosed ids of a disclose message

5

discover.parse

query list of a discover-features queries message

5

discover.protocols

protocol ids a descriptor discloses

1

join_request.approve

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

join_request.open

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 (not_join_request, from_mismatch, to_mismatch, stale, wrong_network, not_approved, already_member, bad_descriptor, controller_unsupported)

27

network.current

{current}: the newest unexpired well-formed kind 30830 at {id} among events at {now}, or null

7

network.definition_validate

problems a kind 30830 has at a given clock ([] = well formed)

19

network.descriptor_split

{public, private} unsigned templates of a kind 11801 for {networks}; public carries no network/expose tag

4

network.join_decide

{verdict, code, reason} for a sender under {policy, roster[, credential, issuers, now]}

15

network.roster

{members, unresolved}: member node pubkeys of a definition given the descriptors seen on its relays

5

peering.offer

an acceptor’s reply to a proposal (type, and code or tier/limits/transports)

25

receipt.link

link hash of a receipt body (signature excluded)

1

receipt.sign

signature over an unsigned receipt

1

receipt.verify

a receipt verifies for its subject

3

relay.allow

whether a roster-protected relay lets {pubkey} do {op} (auth|event|req) on {kind}

9

report.admissible

a report is admissible given which referenced events resolve

2

report.evidence_id

evidence id of a signed receipt

1

standing.tell

standing tell after a sequence of windows

2

trust.reporter_weight

weight of a reporter

7

trust.view

own view given weighted reports

8

window.adjust

{limits_after, tier_after} after a severity; refused for a severity or tier not on the ladder

22

window.ceilings

ceilings of a tier

3

window.evaluate

severity of a window from limits, measured and claimed

16

window.opening_limits

opening limits of a tier

3

1.5.1.6.4. transport (4 ops, 30 cases)

op

about

cases

control.open_sealed

open a sealed control/1.0 {wrap} with {recipient_sk} at {now} inside {window} seconds: {message, sender}, or refused (not_control, from_mismatch, to_mismatch, stale, body_invalid)

18

relaylist.build

the tags of the kind 10050 a node publishes for its own inbox

4

relaylist.dm_relays

inbox relays read from a kind 10050 event

7

relaylist.filter

the REQ filter that fetches a pubkey’s kind 10050

1

1.5.1.6.5. services (20 ops, 106 cases)

op

about

cases

commerce.order_paid

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 (not_order_message, wrong_type, not_sealed_by_maker, unknown_order, not_confirmed)

7

commerce.paid_through

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

commerce.read_message

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 (not_order_message, wrong_type, bad_amount, bad_payment, expired_request)

17

nip90.constants

default kinds and feedback states

1

nip90.feedback

a feedback event (unsigned fields given signer)

1

nip90.parse

{is_request, parsed, executor, job} of a job request

10

nip90.result

a result event (unsigned fields given signer)

1

nip90.result_kind

result kind for a request kind

3

nsite.base36

base36 of a hex pubkey

1

nsite.base36_decode

hex pubkey of a base36 label, or null

1

nsite.guess_type

content type of a path

14

nsite.host

site ref of a host under suffixes

4

nsite.label

{ref, filter, canonical} of a site label

7

nsite.manifest

{paths, aggregate, domains, servers} of a manifest

1

nsite.resolve

resolution of a request path against manifest paths

11

nsite.txt

site ref of a TXT binding

7

paidfetch.quote

{headers, body} of a 402 quote

4

paidfetch.sat_ceil

msat rounded up to sat

5

paidfetch.tokens

tokens of an X-Cashu header

2

product.listing

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 (not_a_listing, bad_listing, bad_price, no_product_ref)

7

1.5.1.6.6. operations (6 ops, 64 cases)

op

about

cases

release.classify

‘major’|’minor’|’patch’ when candidate is newer than running, else null

9

release.compare

-1/0/1 for a <,==,> b; prerelease below its release; refused when either is not a semver

13

release.parse

a kind 9900 read for {release_key[, name]}: the ReleaseInfo dict, or the refusal string

14

release.revocation

[revoked event id, reason] of a kind 9901 by release_key that verifies, else null

5

release.select

newest_compatible / incompatible_newer / refused / revoked from events for {release_key, running, digest[, name, already_revoked]}

10

release.semver

[major, minor, patch, prerelease] of a semver, or refused

13