1.4. Implementing a Second Node
1.4.1. Implementing a fleetmesh node
This is the map a second implementation works from. It says what a node must
get byte-for-byte right, what it may do its own way, and where each obligation
lives in the schema, the vectors and the reference. It does not describe how
the Python node is decomposed internally: the compartments in
docs/compartments.md are one runtime’s answer, and a Rust node is free to
give a different one inside every plane below.
Three sources are normative, in this order. Where they disagree the earlier wins.
schema/—kinds.json,messages.json,constants.jsonand the JSON schemas underschemas/. Their digest is the protocol version a node declares (fleetmesh/0.1-draft@<digest>;scripts/check-package.py).vectors/— conformance vectors generated from the reference (scripts/gen-vectors.py); an implementation that reproduces every vector and refuses every refusal case is wire-compatible for that mechanism.fleetmesh_core/— the stdlib-only reference (core/fleetmesh_core). Where prose, schema and vector leave a gap, the reference’s bytes are the answer, and the gap is a bug to file against the schema.
docs/mechanisms.md is the prose closure over all three: one section per
mechanism asking “could two people implement this from the prose and get the
same bytes?”. docs/conformance.md is the machine that asks it: a harness
(scripts/conform.py) that drives any implementation through every vector
over stdin/stdout and gives a verdict per plane below.
1.4.1.1. Labels
Every wire surface the node has carries exactly one label, recorded in
schema/messages.json under surfaces. scripts/check-implementing.py fails
when the code names a surface the table does not, or the table names one the
code no longer does.
label |
meaning |
what is normative |
|---|---|---|
owned |
fleetmesh invented the bytes |
|
reused |
an upstream spec (NIP, BUD, NUT, DIDComm) is spoken unchanged |
the upstream spec; |
profiled |
upstream spec plus fleetmesh constraints |
the profile section below and its vector |
internal |
between fleetmesh components only (meshctl, sidecars) |
pinned by the component contracts, outside the protocol digest |
planned |
the identifier is reserved under owned or reused and no fleetmesh node speaks it yet |
nothing yet; a second implementation may skip it without losing conformance |
local |
never observed by another node |
nothing; differ freely |
planned is listed under surfaces.planned and replaces the label the
surface would otherwise carry, so the tables below never say “declared only”:
either the reference speaks a surface and names where, or the schema says out
loud that nobody does. Today: kinds 1984, 10002, 10040, 10166, NIP-65,
and the DIDComm out-of-band/2.0 and report-problem/2.0 protocols.
surfaces.reused.fronted names the reused surfaces an off-the-shelf sidecar
speaks on the node’s behalf — GRASP’s NIP-34 kinds, ncontainer’s kind 30624,
NostrHub’s kind 30817 — declared by the node as a c tag and never parsed by
it. Their evidence in the tables is the sidecar manifest, not node code.
Anything not listed under surfaces is local. A second implementation that
disagrees with the Python node about a local matter — tick order, retention
policy, where state is kept, what the CLI prints — is not wrong.
The transport table in messages.json carries a status per rung:
implemented means the reference node serves it; declared means the
protocol names it and a node MAY serve it, and a node that does not MUST
answer 501 Not Implemented on that face so a peer records a refusal rather
than a miss. Today https (POST /didcomm) is declared.
1.4.1.2. The six planes
A plane is a bundle of obligations that a Rust author can build and test as
one unit. Each plane names the mechanisms it owns, the surfaces it speaks and
their labels, and the persistence a node needs for it. The persistence column
is descriptive of what state exists, not of how it is stored: every .sqlite
name below is local.
The tables between the markers are regenerated from the code with
scripts/check-implementing.py --write; the prose is hand-written.
1.4.1.2.1. 1. Identity & Keys
Who a node is, how it proves it, and how it tells others.
Mechanisms: key derivation and the DID document with its did:key / did:peer
aliases (fleetmesh_core/crypto/keys, fleetmesh_core/identity/identity, fleetmesh_core/crypto/crypto, fleetmesh_core/identity/did), the descriptor and its NIP-66 / NIP-85 derivations
(fleetmesh_core/services/discovery, fleetmesh_core/peering/projection), the shared-protocol match two peers make
before anything else (shared_protocols in fleetmesh_core/identity/identity), DIDComm sealing and
the gift-wrap carrier (fleetmesh_core/identity/didcomm), CBOR for the places bytes must be
canonical (fleetmesh_core/wire/cbor).
A node is wire-compatible for this plane when it reproduces
vectors/discovery.json, vectors/projection.json, vectors/envelope.json,
vectors/roster.json
and vectors/did.json and refuses what they refuse.
1.4.1.2.1.1. Reading the wire strictly
Two implementations once disagreed because each leaned on its language’s
parser. vectors/strict.json pins the reading every plane shares; an
implementation reproduces it, in every language, by these rules:
A wire integer is ASCII digits. A tag value that means a number (
expiration,rank,N, an endpoint preference, a protocol major or minor,sample_window) is one or more of0–9and nothing else: no sign, no whitespace, no_, no other script’s digits, no., no0x. Anything else is not a number; the tag is skipped where a value is optional and reported where it is required.A JSON integer means integer. A
kindof30166.0, acreated_atoftrue, annof"5"are not the integers they resemble. In an event they are a problem (or a refusal to project); as an argument on the conformance wire they arebad_args.A tag is a non-empty array of strings. Anything else in
tagsis not a tag: skipped by readers, reported by validators, never a crash. The first well-formedexpirationtag wins; malformed ones are skipped, not fatal.A key is exactly 64 hex digits — lowercase on the wire, a secret key additionally
1 <= d < n. A caller handing a bad key tocrypto.*orgiftwrap.*getsbad_args; a signature over a bad pubkey verifiesfalse, never errors.A sender is
did:nostr:plus 64 lowercase hex. A proposal from anything else is declinedBAD_DESCRIPTOR, not dropped on the floor.Only null or absent means absent. A policy with
transports: {}declares none (every proposal declinesUNSUPPORTED_TRANSPORTS); only the JSON literalfalseclosesopen_enrolment, and0,"","false"arebad_args; awindow_secondsof0isbad_args, not a default.did:peer:2 is strict base64url. No padding, no
+//, canonical (re-encoding reproduces the input), decoding to a JSON object; an empty element is refused.idis dropped only at the top level of the service and abbreviation recurses into nested objects and lists.A relay address is spelt canonically or refused.
canonical_relaylowercases the scheme and host, drops the default port, trailing slashes, query and fragment, and does nothing else: a U-label,127.1, an IPv4-mapped or non-RFC-5952 IPv6 literal,/a/../b,//, a percent-escape in the host, a zone id, a port with leading zeros are refused, not fixed, because no two URL parsers fix them the same way.vectors/projection.jsonlists both columns.Problem and refusal text is informative. A
check_*returns a list of problems and never raises; a refusal carries a message. Vectors compare the count of problems and therefusedflag, never the wording, so an implementation phrases them in its own language’s idiom (Python%rquotes with', Rust{:?}with"). Decline codes are the wire.
1.4.1.2.1.2. The owner’s private fleet roster (kind 30835)
Plan D26 blinds node ownership. A node’s public descriptor (kind 11801) no
longer names its operator unless the node opts in with config
publish_operator (a public anchor or mediator, so a leaf can check operator
independence), so nobody can list the nodes a person or circle operates by
reading public descriptors. The node still knows and enforces its operator from
its own config and enrolment, never from its own descriptor.
The fleet is then the owner’s own roster: an addressable kind 30835 signed
by the owner, whose content is NIP-44 v2 to the author’s OWN pubkey - the
conversation key of (author_sk, author_pk), which is exactly what a browser
extension’s nip44.encrypt(own_pubkey, text) produces - of the canonical JSON
{"v": 1, "nodes": [{"pubkey", "label"?, "hosted"?, "added_at"}]}, nodes
sorted by pubkey with no duplicates. Only the owner can open it, and the
NIP-44 padding hides how many nodes there are, so a relay learns only that this
key keeps a roster, never who is in it. The tags are exactly one d - the
roster name, "fleet" by default - and nothing else: no operator, no
expiration, because a roster does not expire, it is replaced. The newest
event at the coordinate is the whole roster, so adding or removing a node
republishes it.
fleetmesh_core/network/roster implements it: seal (a raw key, or an event
signer with get_public_key / sign_event / nip44_encrypt), open (a raw
key, or a signer with nip44_decrypt) returning {name, nodes} or refusing
with one of roster.refusal_codes (not_roster, not_author, bad_content,
bad_shape - another key opening a roster is not_author, never an empty
fleet), and the pure edits add / remove. fleet.from_roster joins the
roster to the newest current kind 11801 and the newest kind 21801 read by each
node’s own pubkey - the roster decides membership, the descriptor decorates -
and reports online / stale / unknown by roster.status.max_age_seconds
(7200, two missed hourly heartbeats), the same rule the web client uses.
fleet.members stays for the nodes that opt in to publishing an operator tag.
A circle’s roster reserves d = the group DID, sealed under the circle’s
current epoch key; that form is the browser’s (circles) and the reference does
not open it.
Reference: fleetmesh_core/network/roster, fleetmesh_core/network/fleet
(from_roster, heartbeat_status). Vector: vectors/roster.json (a raw-key
and an event-signer roster, the empty roster, labels and hosted, one case per
refusal code, and the joined entries with their liveness).
1.4.1.2.1.3. Brands: a NIP-32 label and the tool’s own claim (plan D28)
A brand is run by an authority key: a person’s own key (an attributable brand) or a key kept only for the brand (a blinded brand, where nothing public links it to the person behind it). It is built from standards this protocol already speaks - NIP-32 labels, NIP-99 listings, NIP-40 expiry, a NIP-09 deletion - and adds no new event kind, tag name or fiber role.
The profile is a
brandstrand of one identity fiber (name, mark, description) authored by the authority; the fiber describes the brand and never makes it a principal. The strand kind is declared with the others infleetmesh_core/textile/strand.py(STRAND_KINDS).The endorsement is a kind 1985 NIP-32 label the authority signs:
["L", "org.fleetmesh.brand"],["l", "<brand strand id>", "org.fleetmesh.brand"], a target and a NIP-40 expiration. The target isa/efor a strand or product listing event andpfor a node key. NIP-09 withdraws it.The claim is NIP-32 self-reporting: the same
L/ltags on the tool’s own event - a node descriptor (kind 11801’sL/loptional tags, written by meshnode from itsbrandsconfig), a tool-kind strand event (kind 30821, itsstrand_kinda tool kind) or a NIP-99 product listing (kind 30402) - signed by its author or key. The claim doubles as the request for recognition: the authority finds claimants with one query on the label.
Fleetmesh adds two rules, and fleetmesh_core/network/brand.py is the whole of
them. A brand shows on a tool only when BOTH the endorsement and the claim
exist - a tool cannot borrow a brand, a brand cannot conscript a tool - so
brand.members returns exactly the refs that are both endorsed and claimed.
A claim counts only on a node descriptor, a tool-kind strand event or a
product listing, never on a person’s or circle’s profile (kind 0, a quilt, a
group document); read_claim refuses anything else not_a_tool. An endorsement
outlives nothing: its expiration is no later than created_at plus
brand.max_endorsement_lifetime_sec (90 days, the grant standing tier’s
MAX_TTL), so a brand is re-issued, not granted forever.
Reference: fleetmesh_core/network/brand (read_endorsement, read_claim,
members, BrandRefused). Ops: brand.read_endorsement, brand.read_claim,
brand.members. Vector: vectors/brand.json (a p, an a and an e endorsement;
each tool kind; one case per refusal code - not_brand_label,
wrong_namespace, bad_signature, expired, ttl_exceeded, not_claimed,
not_a_tool, brand_unsupported; and members showing both halves, hiding a
claim-only and a label-only tool, keeping two brands apart, and never counting a
kind 0 self-label). CLI: meshctl brand endorse|withdraw|members. Kind 30831
(the old node-only fleet profile) is retired, superseded by the brand strand.
surface |
label |
named in |
|---|---|---|
Kinds |
||
|
planned |
|
|
planned |
|
|
reused (declared only) |
|
|
reused |
|
|
reused |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
Standards |
||
|
reused |
|
|
reused |
|
|
reused |
|
|
reused (declared only) |
|
Profiles |
||
|
profiled |
|
|
profiled |
|
|
profiled |
|
|
profiled |
|
Reference modules |
||
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
Compartments (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Config blocks (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
1.4.1.2.2. 2. Store & Reconciliation
What a node keeps for others and how two nodes agree on it.
Mechanisms: the event store and its admission door (fleetmesh_core/storage/store), shards and
coverage claims (fleetmesh_core/peering/coverage), negentropy set reconciliation and the
sync/1.0 protocol over it (fleetmesh_core/storage/negentropy, fleetmesh_core/storage/sync), blob replication
over the peering transport and the Blossom face (fleetmesh_core/storage/replication,
blob/1.0, BUD-01..04), retention and handover (fleetmesh_core/services/lifecycle).
Rules of the store every backend shares, stated once:
The filter subset. A coverage claim’s filter is NIP-01’s, narrowed:
ids,authors,kinds,since,untiland#xwherexis one character.since/until/kindsare JSON integers (4.5is not a time,"1"is not a kind); a filter key outside the subset (#tt,limit,search) is not a condition a claim can make, and a claim that makes one should be refused rather than read with the key ignored. An empty list for any field matches nothing: the field is present and names no value.Ids and pubkeys are lowercase hex on the wire, and
verifyholds them to that. The replaceable-event tie-break at equalcreated_atis bytewise on the lowercase id, so it is the same comparison in any language.The first
dtag wins, NIP-01’s rule, including a value-less["d"], which is the empty identifier""and shadows a later["d","x"].
1.4.1.2.2.1. Products: the fiber, the lifecycle log and the NIP-99 listing (plan D29)
A product is a product strand (the kind is declared in
fleetmesh_core/textile/strand.py). The rules live in fleetmesh core, so any
maker builds on one implementation, with the canonical byte forms fixed
there: a product or an event sealed by either implementation has the same digest
and Bao root. An application’s own store, waterfall metrics, health summary,
credit/USD conversions and tool catalog stay in the application.
The record fiber (
fleetmesh_core/products/fiber.py) is canonical JSON of the manifest:schema,product_id,slug,title,product_kind,current_version,owner_did,sku,upc, the three price fields, andsupply_chain_count/lifecycle_count(the lengths of those arrays, not the arrays - the fiber commits to how many, so an appended event moves the product’s digest). Whole floats are written as integers. The fiber’s MIME isapplication/vnd.fleetmesh.product+json; any other MIME is refusedbad_mime. The twoschemastrings inside the sealed bytes arefleetmesh.*: they are part of the bytes, so they are stated once and used verbatim.The lifecycle log (
fleetmesh_core/products/lifecycle.py) is the product’slifecycle_eventsarray. An event’s canonical bytes are the schema then every present, non-empty field of the fifteenlifecycle_event_fields,created_atas a number and the rest as strings;resolvedis log state, not part of the identity. The append rule seals each event (event_digest_hex= sha256 of its bytes,bao_root= the 1,024-byte Bao root - the digest a signature names and the link back to the event’s own bytes), makes an unresolvedrecall_noticethe product’sactive_recall, advancescurrent_versionfor a release/BOM/upgrade, and recomputes the product’s ownsha256/bao_rootover the new fiber. Verifying the log recomputes everything: the product’s stored commitment against its current fields (fiber_digest_mismatchcatches an event appended or removed after sealing), then each event’s kind, product, recall severity and digest.Attestations already live in
fleetmesh_core/textile/attestations.py; the product read/verify path applies the same rule (attestation_holds, askeep_verified_attestationsdoes) - a stage counts only while its signature verifies, names its signer and signs the hop as it stands, andverify_logreports the stage ids that still hold.The NIP-99 listing (
fleetmesh_core/products/listing.py, kind 30402, GammaMarkets market-spec) is what a buyer discovers:d,title, aprice[amount, currency[, frequency]]whose frequency states a subscription interval, and a reference to the product strand. Fleetmesh layers the strand onto NIP-99’sa/etags, so anareference’s coordinate kind is30821. Reading one back refusesnot_a_listing,bad_listing,bad_price,no_product_ref. No checkout happens here (plan D30/P3c).
Reference: fleetmesh_core/products (fiber, lifecycle, listing,
ProductRefused). Ops: product.read_fiber, product.verify_log,
product.listing. Vector: vectors/products.json (the fiber built and read
back, a foreign MIME refused; a sealed log verified with an attested stage
and a price point; a one-time and a recurring listing built and read back; one
case per refusal code - not_a_product, bad_mime, bad_price, bad_recall,
bad_event_digest, event_wrong_product, unknown_event_kind,
fiber_digest_mismatch, not_a_listing, bad_listing, no_product_ref).
surface |
label |
named in |
|---|---|---|
Protocols |
||
|
owned |
|
|
owned |
|
Kinds |
||
|
reused |
|
|
reused |
|
|
owned |
|
|
planned |
|
|
owned |
|
|
planned |
|
|
planned |
|
Standards |
||
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
Profiles |
||
|
profiled |
|
Transports & faces |
||
|
reused via |
|
|
reused via |
|
|
profiled via |
|
|
reused via |
|
Reference modules |
||
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
Compartments (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Config blocks (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Persistence (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
1.4.1.2.3. 3. Peering & Accounting
Who a node talks to, on what terms, and how it keeps the terms honest.
Mechanisms: offers, grants and amendments (fleetmesh_core/peering/peering), budget windows,
receipts and closes (fleetmesh_core/accounting/accounting, fleetmesh_core/accounting/window, budget/1.0), capacity
and strain (fleetmesh_core/accounting/capacity, fleetmesh_core/accounting/strain), reports and complaints
(fleetmesh_core/peering/reports, fleetmesh_core/peering/complaint, complaint/1.0), standing and bad-peer
memory (fleetmesh_core/accounting/standing, fleetmesh_core/peering/badpeer, standing/1.0).
surface |
label |
named in |
|---|---|---|
Protocols |
||
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
Kinds |
||
|
owned |
|
|
owned |
|
|
owned |
|
|
planned |
|
|
reused |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
reused (declared only) |
|
|
owned |
|
Standards |
||
|
reused |
|
Reference modules |
||
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
Compartments (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Config blocks (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Persistence (reference node) |
||
|
local |
|
|
local |
|
What a second implementation must reproduce, stated so that it can be written
without reading fleetmesh_core/ (the conformance cases in schema/conformance.json
drive every line of this):
Pricing a window. Every limit is priced against the receipt counter
grant.counter_ofnames for it (conn_rateagainstconn_open; every other limit against its own name). Overrun ismax(0, measured/limit − 1);infinitewhen the limit is 0 and anything was measured. Divergence is|measured − claimed| / max(measured, floor)and is not evaluated whenmeasured < floor, wherefloor = max(limit × divergence_floor_fraction, divergence_floor_sessions × per_session)andper_sessionis 1 excepttier_limits.ranges_per_sessionforsync_ranges.dup_ratioisdups_sent / events_in, priced only whenevents_inis at or above theevents_infloor, with a claimed value of null and zero divergence. Severity by overrun: S1 ats1_overrun_fraction, S2 ats2_overrun_fraction, S3 ats3_overrun_fraction; a divergence aboves2_divergence_fractionis a floor of S2, never a ceiling. The window’s severity is the worst limit’s. Overrun and divergence are reported rounded to six places.The remedy ladder.
window.adjust(limits, tier, severity, measured): S0 — each limit grows byceiling × max(aimd_min_increase_fraction, aimd_increase_fraction × strain)wherestrain = min(1, used/limit); an evaluation that offers no counters gets the floor step; a limit above its opening value that a measured window used nothing of instead decays tomax(opening, limit × decay_fraction). Results are held inside the tier ceilings. S1 — every limit halves (decrease_s1_fraction), floored at the probation ceiling, tier unchanged. S2 — every limit quarters (decrease_s2_fraction), floored at probation, tier becomes probation. S3 — every limit is 0, tier unchanged. S4 — every limit is 0, tierrevoked. Limits are integers: floor after arithmetic.Opening limits of a tier are the ceilings with the four volume limits (
events_in,bytes_in,bytes_out,blob_bytes) atopening_fraction, floored;dup_ratiois not a grant limit.Reporter weight is
tier_weight × min(1, clean_windows / age_factor_windows) × (1 − contradicted/evaluated), the false-report rate being 0 when nothing has been evaluated. View is a threshold, not a mean: the most severe of S4..S1 whose backing weight (reports at or above it) reachesview_threshold_theta, or the node’s own severity if worse.Capacity pressure is the largest
measured/totalshare over the declared counters, with the binding counter named; rungs are everyshed_ladderentry at or below the pressure, in order; the shed floor isshed_floor_fractionof the probation ceilings, floored.Offer. Checks run cheapest first and the first failure is the decline code:
UNSUPPORTED_VERSION(protocol name),BAD_DESCRIPTOR(class),UNSUPPORTED_PROTOCOL(the required protocols, then the acceptor’s own policy list, by sharedname/majorat or above the floor),BAD_DESCRIPTOR(the signed descriptor’s own problems, or itsctags disagreeing with the proposal’sprotocols),INSUFFICIENT_POW(leading zero bits ofpow.event),UNSUPPORTED_TRANSPORTS,POLICY_MISMATCH(closed enrolment). Transports are the mutually supported schemes ranked by the sum of both preferences (the proposer’s list order is its preference), ties bytewise. An offer carries the subject’s configured tier or the policy’s opening tier, that tier’s opening limits, and the ladder. Two edges of that order: the version check precedes the body-shape check, so a body that is both unversioned and malformed declinesUNSUPPORTED_VERSION; and a missingprotocolsis an empty declaration (UNSUPPORTED_PROTOCOL) while a present non-arrayprotocols(includingnull) isBAD_DESCRIPTOR: absent is not null.Policy keys.
policy.tiersis keyed by the 64-hex pubkey, not thedid:nostr:form; a DID-keyed entry is never matched and the subject takes the opening tier. Unknown policy keys are ignored, so a policy file can carry forward-looking settings.Receipts. The chain link is SHA-256 of the canonical body with
sigremoved; the signature is BIP-340 over that link; an evidence tag cites an inline receipt by the same link. A report (kind 30802) is admissible only if itsoutcomeis S1..S4, it names a subject ind, itsgrantresolves (or is carried inline) to a kind 30801 published by the reporter, and at least oneevidenceentry is something the subject itself signed (receipt, envelope hop, event, or handover); an inline artefact that does not hash to its id is ignored, and a reporter barred by a handover it signed is refused.Standing tell reports the tier the newest window left,
clean_windowsas the trailing streak of S0, andevaluated_windowsas the count.Complaints of S3/S4 publish at once; S1/S2 wait
notice_wait_windowswindows after the notice unless the subject is unreachable.discover-features/2.0 discloses the fleetmesh
ctags of the descriptor; amatchending in*is a prefix, anything else an exact id; non-protocol feature types are ignored.Join request (
network/1.0, vectorjoin-request.json). Under anapprovedpolicy a node asks the controller on the wire: it publishes ajoin-request-{network, descriptor, note?}- as the plaintext of a kind 13 seal inside the usual kind 1059 wrap (thesealed-controlbinding), signed by the node key, addressed to the controller, and sent to the definition’s relays and nowhere else. The controller accepts it only when all of these hold, else it refuses with the code naming the rule (constants.jsonjoin_request.codes):typeishttps://fleetmesh.org/network/1.0/join-requestand the body is that shape - elsenot_join_request;fromnames the seal signer - elsefrom_mismatch;tois exactly the definition’s controller - elseto_mismatch;created_timeis present and numeric, no more thangrant.max_clock_skew_secondsin the future and no older thanjoin_request.max_age_seconds(7 days: a join request is an asynchronous ask, so the bound is age and not skew - a controller reviews it later and replay is harmless) - elsestale;body.networkis the definition’s id - elsewrong_network; the current policy isapproved- elsenot_approved; the current roster does not already name the node - elsealready_member; the embedded descriptor is present, verifies, is unexpired and is the sender’s - elsebad_descriptor. Adid:groupcontroller iscontroller_unsupportedat both build and open (circle controllers wait on the D23/D26 design). Approval is not a message: the controller publishes a new version of the kind 30830 whose tags are the current ones plus onemembertag naming the node, everything else unchanged andcreated_atstrictly later. Ajoin-decline({network, code: "declined"},thid= the request id) is the controller’s optional sealed refusal and leaves no roster trace.
1.4.1.2.4. 4. Transport & Doors
How bytes reach a node and what is checked before anything acts on them.
Mechanisms: the transport ladder and its negotiation (iroh, libp2p, https,
nostr gift wrap), the relay face (NIP-01/11/42/77), mDNS LAN discovery, the
DIDComm mediation protocols for nodes that cannot be reached directly, the
announce topic, and the single validation door every plaintext passes
(fleetmesh_node/validate in the reference; the schema’s body fields are what it
checks).
surface |
label |
named in |
|---|---|---|
Kinds |
||
|
planned |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
Standards |
||
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
planned |
|
|
planned |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
planned |
|
Profiles |
||
|
profiled |
|
Transports & faces |
||
|
owned via |
|
|
local |
|
|
local |
|
|
reused via |
|
|
local |
|
|
internal |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
|
owned |
|
Reference modules |
||
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
Compartments (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Config blocks (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Persistence (reference node) |
||
|
local |
|
1.4.1.2.5. 5. Services
What a node offers beyond keeping and forwarding: compute, group gossip, paid fetch, sidecars, DVM ingress, static sites.
Mechanisms: the compute market (fleetmesh_core/accounting/market, compute/1.0, compute/1.1),
epidemic gossip (gossip/1.0), paid fetch over Blossom and sidecar sessions
(profile paid-fetch-402), the NIP-90 DVM gateway (profile nip90-ingress),
nsite static hosting (profile nsite-face), settlement rails (Cashu NUTs,
NIP-47, NIP-60/61 — all reused; the ledger is local).
1.4.1.2.5.1. Commerce: checkout on the market-spec, and the fulfiller’s rule (plan D30)
Checkout follows the GammaMarkets market-spec (the e-commerce extension
NIP-99 names), pinned in constants.json#commerce.market_spec at commit
5dc79c5db0d41c0bea774debf445cce041192840 (GammaMarkets/market-spec, spec.md,
a draft). Order traffic is NIP-17 sealed DMs: an unsigned kind 16 rumor
carries the order process, distinguished by a type tag (1 order, 2 payment
request, 3 status, 4 shipping), and a kind 17 receipt carries the buyer’s payment
inside a kind 13 seal in a kind 1059 store-and-forward wrap. The seal’s own
BIP-340 signature is the sender’s proof, so a reader learns which key wrote the
message and the rumor’s pubkey must be that signer. The carrier is the
reference gift wrap unchanged (fleetmesh_core/crypto/giftwrap.py, the same one
control/1.0 rides) - no new cryptography.
The messages (
fleetmesh_core/commerce/messages.py) are built and read: the four kind 16 rumors and the kind 17 receipt. Reading is deliberately small and refuses only the shapes the market-spec fixes -not_order_message(not a kind 16/17 order message),wrong_type(a kind 16typethat is not one of the four),bad_amount(an amount that is not a non-negative integer of sats),bad_payment(a payment option malformed for a named medium, or a request with none) andexpired_request(a payment request dated past itsexpiration). The maker chooses how to be paid: the payment request offers lightning (bolt11 or lud16), bitcoin, ecash (Cashu) or any other non-empty medium (a card processor’s, say) - only the three named mediums have their shape validated.The fulfiller’s rule (
fleetmesh_core/commerce/payment.py) is the one thing fleetmesh adds. An order is PAID when a kind 16type 3statusconfirmedfor that order id arrives sealed, with the seal signed by the product’s maker - the author of the kind 30402 listing the order’s items name. A buyer’s kind 17 receipt is evidence for the maker, never proof for the fulfiller, and in v1 only the maker’s own key counts (no delegated processor keys). Whoever fulfils acts only onorder_paid, the way the operator acts only under a valid host grant (D27). It refusesnot_sealed_by_maker,unknown_order(a status for another order, or none for this one) andnot_confirmed.Recurring billing is the listing’s
pricefrequency: each period is a new order, andpaid_throughtells a fulfiller whether the current period is covered, from the orders it has already resolved withorder_paid. Existing subscriptions keep paying through the current rails, which then send the period’sconfirmed, so nobody re-subscribes.
Reference: fleetmesh_core/commerce (messages, sealed, payment,
CommerceRefused). Ops: commerce.read_message, commerce.order_paid,
commerce.paid_through. Vector: vectors/commerce.json (the four kind 16
rumors and the kind 17 receipt built and read back; the maker’s sealed
confirmed accepted; a buyer receipt alone, a confirmed status from anyone but
the maker, a status for another order and a pending status each refused; a
recurring listing covered for one period and not the next; one case per refusal
code - not_order_message, wrong_type, not_sealed_by_maker,
unknown_order, bad_amount, bad_payment, expired_request,
not_confirmed).
surface |
label |
named in |
|---|---|---|
Protocols |
||
|
owned |
|
|
owned |
|
|
owned |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
owned |
|
Kinds |
||
|
reused |
|
|
reused (declared only) |
|
|
reused |
|
|
reused (declared only) |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
Standards |
||
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
|
reused |
|
Profiles |
||
|
profiled |
|
|
profiled |
|
|
profiled |
|
|
profiled |
|
Transports & faces |
||
|
profiled via |
|
|
profiled via |
|
|
profiled via |
|
|
local |
|
Reference modules |
||
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
Compartments (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Config blocks (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Persistence (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
|
local |
|
1.4.1.2.6. 6. Operations
What an operator sees and does. Almost entirely local; the two exceptions are the control socket, which meshctl (Rust) speaks, and the sidecar manifest, which a sidecar author writes.
surface |
label |
named in |
|---|---|---|
Protocols |
||
|
owned |
|
Kinds |
||
|
reused |
|
|
reused |
|
Transports & faces |
||
|
internal |
|
|
internal |
|
Reference modules |
||
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
|
reference |
|
Compartments (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
Config blocks (reference node) |
||
|
local |
|
|
local |
|
|
local |
|
|
local |
|
Persistence (reference node) |
||
|
local |
|
Release channel (fleetmesh_core/peering/release, kinds 9900/9901, vectors release.json).
A release is an npack kind 9900 by the operator’s pinned release key, read in
this order with the first failure as the one-line refusal: kind, pubkey (the
hex compared case-folded), signature, name tag (a different package is
skipped silently, never counted), version tag, x tag, provides tags. The
version grammar is N.N.N with an optional - prerelease of
[0-9A-Za-z.-]+; whitespace around it is tolerated; v1.2.3, 1.2.3+build
and a fourth component are not semvers. Order is numeric on the three
components, a prerelease below its release, and two prereleases compared as
plain strings (rc.10 < rc.9) - SemVer 2’s dotted-identifier rule is not
used. x must be 64 characters and is lower-cased; os and arch default
to any. provides values are fleetmesh/0.1-draft@<digest>; only the
digests after that prefix are kept, and a release naming none is refused.
A kind 9901 by the same key that verifies and names an e revokes that
release; its reason is the reason tag, else the content. A 9901 by any
other key, or without an e, is nothing - not a refusal.
Selection (release.select): apply every revocation first regardless of the
order events arrived, skip revoked and not-newer-than-running releases, then
the newest release speaking this node’s digest is newest_compatible and the
newest speaking another digest is incompatible_newer - reported, never
installed (docs/versioning.md). A tie on version keeps the first seen.
classify(running, candidate) names the jump major/minor/patch by the
first differing component, or null when the candidate is not newer.
1.4.1.3. Profiles
A profile is the fleetmesh-specific constraint on a reused protocol. Each
has a name in messages.json under surfaces.profiled, a normative
paragraph here, and a vector where the constraint is on bytes.
1.4.1.3.1. paid-fetch-402
Applies to Blossom GET /<sha256> and to GET /sidecar-session/<name>,
GET /grasp-session/. When a fetch is priced the node answers 402 Payment Required with header X-Price-Msat: <int> and, when a Cashu offer exists,
X-Cashu: <request>[, <request>] (one NUT-18 payment request per priced
item, NUT-24 header form), and a JSON body
{sha256, size, price_msat, items: [{to, payee, msat}], offers: [{rail, request, item, ...}], expires}.
The client retries the same request carrying one X-Cashu: <cashuB token>
per item in item order. A free fetch carries no price headers at all; a 402
that follows a payment that did not settle adds error to the body.
price_msat is always the sum of items[].msat. Reference: fleetmesh_core/accounting/paidfetch.
Vector: vectors/paid-fetch.json.
What a second implementation must reproduce: X-Cashu joins the
request of every offer whose rail is cashu with , and is omitted
when there is none; body key order is sha256, size, price_msat, items, offers, expires[, error], each item reduced to {to, payee, msat};
msat → sat rounds up (ceil(msat / 1000), at least 1 for any positive
price, 0 for 0); an X-Cashu header is split on , with blanks dropped.
1.4.1.3.2. didcomm-over-giftwrap
A DIDComm JWE travels as the content of a NIP-59 rumor, wrapped and
addressed to the peer’s node pubkey. Kind 21059 (ephemeral) is the default;
kind 1059 when store-and-forward is required (the peer is unreachable and
has a kind 10050 relay list). A stored wrap is published to the relays the
peer’s kind 10050 names (NIP-17, read by fleetmesh_core/identity/relaylist: relay tags, ws(s)
only, deduplicated, at most 8) and then to the sender’s own; a peer with no
list gets the sender’s relays alone. The wrap carries no other tags than NIP-59
requires; any other wrap kind is refused. The seal, and a stored (1059)
wrap, carry a created_at randomised backwards within two days less twice
grant.max_clock_skew_seconds of now (NIP-59’s two-day window, kept honest
under skew). A live (21059) wrap is dated now, not randomised: relays
(strfry, and the public relays) refuse an ephemeral event whose created_at is
more than about a minute old with invalid: ephemeral event expired, so a
skewed live wrap never reaches anyone. The wrap’s date says nothing the
relay’s own receipt time does not; the privacy the randomisation buys sits on
the seal inside, which stays randomised. The NIP-44 v2 bytes are fleetmesh_core/crypto/nip44’s.
A relay that answers a wrap with an OK whose reason is prefixed rate-limited:
or banned:, or refuses the handshake with HTTP 429, is left out of publishing
for a window that starts at a minute and doubles per repeat up to fifteen,
while the subscription on it stays up; meshnode health lists it under
cooling and the node reports it as a note, not a fault.
Reference: fleetmesh_core/crypto/giftwrap. Vector: vectors/giftwrap.json (NIP-44 under a
fixed nonce, one live and one stored wrap opened, with the three dates pinned).
1.4.1.3.3. sealed-control
For control/1.0 only, a request, result or refused may travel as the
plaintext of the kind 13 seal inside the usual wrap, with no DIDComm JWE.
A node accepted a control sender before only through authcrypt, which needs the
sender’s X25519 agreement key from a published descriptor, so only a node could
send: not a person on a NIP-07 extension or a NIP-46 signer (they can NIP-44
encrypt and sign events, nothing more), not meshctl without a running node,
not a browser. With the message as the seal’s plaintext, the seal’s own BIP-340
signature is the proof of who sent it and the receiver needs no descriptor: the
seal signer is the sender.
A receiver accepts the plaintext only when all of these hold, and otherwise
refuses with the code naming the rule (constants.json control.seal.codes):
it is a JSON object with a string
idandtype, andtypeis one ofhttps://fleetmesh.org/control/1.0/{request,result,refused}- elsenot_control;fromnames the seal signer, asdid:nostr:<hex>or the bare hex spelling (the same-operator comparisonfleetmesh_core/identity/did) - elsefrom_mismatch;tois a list naming the receiving key’sdid:nostr- elseto_mismatch;created_timeis present, a number, and withingrant.max_clock_skew_secondsof the receiver’snow- elsestale. Absent counts as stale here, unlike the JWE path where an absentcreated_timeis tolerated;the body passes the receiver’s own control body check (
fleetmesh_core/wire/validate) - elsebody_invalid.
Replay is the receiver’s state, not the transport’s: the message comes back and
the node applies its own seen-id guard, exactly as it does for a JWE. A reply
travels the same way - result or refused as the seal’s plaintext to the sender’s
key, wrapped and published to the node’s relays, with thid = the request id -
and never needs the sender’s descriptor. Every other fleetmesh protocol stays
authcrypt-only.
Reference: fleetmesh_core/network/control (seal, open_sealed) over
fleetmesh_core/crypto/giftwrap. Vector: vectors/control.json (an accepted
request, result and refused, a stored wrap, a message sealed by an event signer,
and one case per refusal code).
1.4.1.3.4. nip66-descriptor
Kind 30166 is derived from the node descriptor as fleetmesh_core/services/discovery does, one
event per ws/wss endpoint, with d the canonical relay URL. Liveness
tags are a monitor’s to add, never the node’s. Vector: vectors/discovery.json.
The derivation is deterministic so that two implementations produce the same
id: the event is unsigned (the publisher signs it), its pubkey and
created_at are the descriptor’s, and the tags come in this order: d, n
(tor for a .onion host, i2p for .i2p, else clearnet), one N per
entry of the NIP-11 document’s supported_nips in the order given, one R
per limitation the document mentions in the order auth_required → auth,
payment_required → payment, restricted_writes → writes,
min_pow_difficulty → pow (! prefix when false; pow is true only above
zero; a key the document omits is asserted neither way), one t per claimed
shard sorted and deduplicated, then expiration copied from the descriptor
when it has one. content is the NIP-11 document in canonical form, or empty
when there is none. A validator’s d check uses the same canonical form and
relay_endpoints as the derivation.
1.4.1.3.5. nip85-projection
Kind 30385 is derived from the node’s own kind 30802 reports as
fleetmesh_core/peering/projection does: d is the subject relay URL in canonical form, k
is web, a cites the report. Vector: vectors/projection.json.
Deterministic like the discovery event: unsigned, pubkey and created_at
the report’s, content empty, tags in the order d, k, p (the report’s
d, the subject pubkey), a (30802:<reporter>:<subject>), rank (the
report’s outcome priced by constants.json#projection.rank_by_outcome:
S1 50, S2 25, S3 0, S4 0, as a decimal string), then expiration copied from
the report when it has one. Endpoints are deduplicated and sorted; an endpoint
that is not already canonical, a report of another kind, or an outcome the
ladder does not price is refused rather than silently fixed.
1.4.1.3.6. nip90-ingress
A NIP-90 request (kind 5000–5999) is translated to a job descriptor by the
mapping in fleetmesh_core/services/dvm: i tags are inputs, param tags a map (last wins),
the executor is chosen zk → llm → bacalhau → agent → wasm from the kind first
and then the executor/engine params. Feedback is kind 7000 with tags
e, p, status[, extra] and status one of NIP-90’s payment-required,
processing, error, success, partial; the result is kind request+1000
with tags e, p, request (the request JSON, compact) then amount /
commit when non-zero. A WASM request that names no param module is
refused rather than run. Kind 5128 is nsite’s and is dispatched by the
nsite face, never as a job. Vector: vectors/nip90.json.
What a second implementation must reproduce. Parsing: output sets
output_mime (default text/plain), bid is an integer of msat (default
0), relays keeps only ws:///wss:// entries; parsed is
{id, pubkey, kind, content, inputs, params, output_mime, bid_msat, relays}.
Executor choice: zk when the kind is 5055/5905 or executor/engine is one
of zk-verify-groth16|zk|zkvm; else llm when the kind is 5050 or the name
is llm|ai|inference|vllm|ollama; else bacalhau when the kind is 59xx or
the name is bacalhau|docker|container; else agent for agent|react; else
wasm. Every job carries fuel_max 2 500 000 000 unless overridden. The wasm
job’s input.raw is the canonical form of {prompt: content, inputs, params}, input.sha256 its digest, module = {runtime: wasm[, sha256: param module lower-cased][, url: param module_url]}, wasi_profile
fleetmesh-wasi-v1, nonce = request id, verify none. The llm job
defaults to model meta-llama/Llama-3.3-70B-Instruct, sampling
{max_tokens 512, temperature 0.7, top_p 1.0[, seed]}, messages from a
json input’s messages/prompt else one user message of the content;
param schema makes a json_schema grammar, response_format /
regex likewise, and verify is schema-bounds when any grammar is asked
for, else delivery. The zk job’s module runtime is zk-verify-groth16,
its module.sha256 = sha256(nip90-zk-verify-<curve>) with curve default
bn254; proof / public_inputs / vk come from JSON content or from
i tags whose role is proof|zk-proof, inputs|public_inputs (JSON
array), input|public_input (one each), vk|verification_key; verify is
{mode: proof, proof_system}. The bacalhau job is engine docker, image
alpine:latest, entrypoint /bin/sh -c split on whitespace, one
storage_mount {cas_provider blossom, source_cid, mount_path} per i
tag (third field or /inputs), resources cpu 2, gpu 0, memory_gib 4.0, timeout_seconds 300. The agent job is {task: content, max_steps 25, verify delivery}. Feedback with an unknown status is refused (null);
feedback content is the extra text, else the status. The result’s
request tag is the request event in the protocol’s canonical form
(constants.json#canonical.form: sorted keys, no whitespace, UTF-8) - the
same bytes every digest here is taken over, so two nodes answering one
request embed identical bytes; a verifier still re-parses and re-checks the
embedded signature rather than byte-comparing. amount appears only when positive,
commit only when non-empty, extra tags after both. Non-integer values for
integer params (max_tokens, seed, cpu, gpu, timeout, max_steps)
are refused, not rounded. A zk request whose executor param names some
other proof system keeps that name as executor/module.runtime/
proof_system; an empty or groth16-containing name, or a zk kind, means
zk-verify-groth16.
1.4.1.3.7. nsite-face
Host routing by the left-most label selects a site, as fleetmesh_core/services/nsite parses
it: <npub> is the owner’s root site (kind 15128), <base36 pubkey, 50 chars><name> a named site (kind 35128, d = name, 1–13 chars of
[a-z0-9-]), v<base36 event id> a pinned snapshot (kind 5128); legacy
34128 is read for compatibility and never written. A manifest’s path
tags map /<path> to a blob sha256; / and /<dir>/ fall to index.html,
anything missing to /404.html with status 404; .. is normalised before
lookup. Blossom servers are tried in manifest order, then the owner’s kind
10063, then the node’s own, deduplicated. GET /nsite/_ask returns the
resolved manifest as JSON. Vector: vectors/nsite.json.
What a second implementation must reproduce. Base36 is the 32-byte big-endian
integer in 0-9a-z, left-padded with 0 to exactly 50 chars; decoding
rejects any other width and values ≥ 2^256. A site ref is
{kind, pubkey, d, event_id} with the unused fields empty strings; its
filter is {ids: [id], kinds: [5128]}, {kinds: [35128], authors, #d, limit 1} or {kinds: [15128], authors, limit 1}. A host is lower-cased,
a single :port stripped, a trailing . dropped, then matched against each
suffix (lower-cased, dots trimmed): the remainder must be exactly one label.
A TXT binding is trimmed of whitespace and quotes and may carry the DNS
key convention nsite=; it is then npub1…, npub1…:<name> (name folded
to lower case, then the named-site grammar) or v<snapshot>; anything else
is not a binding. domain tags are trimmed, lower-cased, stripped of a
trailing ., and a tag left empty by that names no domain. path tags
count only when the path is absolute and the digest is 64 hex chars
(lower-cased); the aggregate is sha256 over the sorted "<sha> <path>\n"
lines. Resolution strips ?/#, prefixes /, collapses a leading //,
normalises ./.., and appends index.html when the request ended in /
or its last segment has no extension (an extension is text after a . that
is not the segment’s first character: /..a and /.hidden have none).
Content types come from the pinned table fleetmesh_core/services/nsite.EXT_TYPES (html htm
css js mjs json txt md xml svg png jpg jpeg gif webp ico woff woff2 ttf otf
wasm pdf mp4 webm mp3 csv; extension case-folded) with ; charset=utf-8
appended to text/*, application/json and image/svg+xml; unknown is
application/octet-stream - never the host’s mime database. Blossom server
URLs must be http(s), lose a trailing /, and are deduplicated first-seen.
1.4.1.3.8. blossom-mirror
Blob replication asks a partner to PUT /mirror (BUD-04) with {url} naming
this node’s public Blossom URL for the blob (<base>/<sha256>), authorised
by a kind 24242 event with t=mirror, x=<sha256> and an expiration
tag, carried as Authorization: Nostr <base64 JSON>. The receiver checks
signature, kind, verb, hash and expiry in that order and answers 200 with the
blob descriptor plus cid. Nothing beyond BUD-04 is required of the
receiver; the constraint is on what the sender puts in the auth event.
Reference: fleetmesh_core/storage/blossom_auth. Vector: vectors/blossom-mirror.json.
1.4.1.3.9. did-aliases
A node is its did:nostr; nothing here changes that. did:key and
did:peer are deterministic re-encodings of the keys the descriptor already
carries, so DIDComm and verifiable-credential tooling that has never heard of
nostr can address a node without a did:nostr resolver. The node key’s
did:key is z + base58btc of multicodec 0xe7 0x01 over the compressed
point 02 || x (the even-y point a BIP-340 x-only key stands for); the
agreement and transport keys use 0xec 0x01 and 0xed 0x01 over their raw 32
bytes - the same bytes the descriptor’s f-prefixed Multikeys carry, in a
different base. The did:peer is numalgo 2: .V the node key, .E the
agreement key, .S the DIDCommMessaging service abbreviated per the
did:peer spec as base64url-nopad JSON with sorted keys; elements appear in
that order and are omitted when the descriptor lacks them. A did:peer:2 is
a snapshot - it changes when the endpoint or a key does - so the descriptor
is the source of truth and a node compares the parsed node key, never the
string. The resolved node profile lists the node did:key then the
did:peer in alsoKnownAs. A did:key on another curve is refused: a
different curve is a different network. Constants: constants.json#did.
Reference: fleetmesh_core/identity/did. Vector: vectors/did.json.
1.4.1.3.10. market-spec-checkout
The GammaMarkets market-spec checkout (plan D30): an unsigned kind 16 rumor
(the order process - order, payment request, status update or shipping update,
by its type tag) or a kind 17 receipt travels as the plaintext of a NIP-59
kind 13 seal inside a kind 1059 store-and-forward wrap, addressed to the other
party, and the seal’s signer is the message’s author. The maker’s own sealed
confirmed status is the proof of payment (commerce.order_paid); a listing’s
price frequency makes a subscription (commerce.paid_through). Constants:
constants.json#commerce (the pinned market_spec.commit,
5dc79c5db0d41c0bea774debf445cce041192840).
Reference: fleetmesh_core/commerce. Vector: vectors/commerce.json.
1.4.1.4. Declared and now spoken
Three surfaces the schema reserved before any node spoke them. Each has a
reference module and shares vectors/declared.json.
1.4.1.4.1. kind 21802 — diagnostic telemetry
Owned, opt-in (telemetry: true in the node config; off by default). One
ephemeral event per sample window, aggregated over the whole node. Tags:
sample_window (seconds, positive), then one ["metric", name, bin] per
metric in the fixed order wraps_in, wraps_seen_again, wraps_dropped, strain, peers, then expiration if given; content empty. A bin is the largest of
0, 1, 10, 100, 1000, 10000 at or below the count — an order of magnitude and
nothing finer — and a metric name outside the five is dropped, not carried, so
a node cannot leak a per-peer counter under a name of its own. A reader
refuses a non-positive window, an unknown metric, a bin that is not a floor, a
metric given twice, or non-empty content. Reference: fleetmesh_core/services/telemetry.
1.4.1.4.2. kind 10050 — inbox relays
Reused (NIP-17). Every node publishes one. The relay rung is the floor of
the transport ladder - not a node class, not a capability, but the one way a
node can always be reached - and a kind 10050 is where that floor is stated,
in the place any Nostr client already looks. A node publishes the relays it
reads as relay tags (relaylist.build: ws(s) only, deduplicated, at most
8, a non-relay URL refused rather than dropped), signed by the node key, on
its first presence tick and again only when the set changes. A kind 11801
descriptor therefore need not, and does not, carry its inbox relays:
endpoint wss on a descriptor means the node hosts a relay face, which is
a different fact.
Read by the transport when it must store a wrap for a peer that is not
listening; the shape and the delivery rule are under didcomm-over-giftwrap
above. The list is trusted for an hour before it is read again. Reference:
fleetmesh_core/identity/relaylist.
1.4.1.4.3. discover-features/2.0
Reused (DIDComm). A queries message, anonymous allowed, carries
[{feature-type, match}]; a match ending in * is a prefix, anything else
must equal a protocol identifier, and only feature-type: protocol is
answered. The disclose reply is threaded to the query’s id and its
disclosures are the descriptor’s c tags that are protocol identifiers
(plain capability hints such as relay are not protocols and are not
disclosed). The answer comes from fleetmesh_core/peering/peering.Node.disclose, which reads
the descriptor, so a disclose cannot name a protocol the descriptor does not.
Reference: fleetmesh_core/services/discover.
1.4.1.5. Internal contracts
contract |
spoken by |
where defined |
|---|---|---|
|
meshctl ↔ meshnode |
|
|
meshnode ↔ FIPS sidecar |
|
|
meshnode ↔ a sidecar’s manifest |
|
These are pinned by schema/INTERNAL, a digest over the contract texts,
separate from the protocol digest so a control-verb rename does not move the
version a node declares to peers.