4. Peering & Reputation (fleetmesh_core.peering)
The fleetmesh_core.peering package manages node-to-node peering sessions,
handshakes, coverage claims, standing reports, complaint recording, and reputation projection.
4.1. Peering Session & Handshake
peering/1.0: how two strangers end up holding a pair of grants.
Every other module assumes a grant already exists. This is the handshake that produces one, and it is the only place in the protocol where a node decides about somebody it has never carried traffic for.
What that decision is allowed to rest on is short, and deliberately so:
- the protocols the required protocols (peering, budget) MUST be
compatible: same major, the peer’s minor at or above this node’s floor (schema/constants.json protocol_floors). Every other protocol is shared or not; a peering whose policy needs one the peer lacks is declined, the rest are simply not used with it. The schema digest is provenance of the build and is surfaced, never a refusal on its own (since 0.3).
What it is not allowed to rest on is standing, because a stranger has none. A peering therefore always opens at the probation tier, whose ceilings are worth almost nothing and whose reporter weight is exactly zero. That is the whole sybil argument: enrolment can be open because admission buys nothing.
The result is two grants, not one. Each side issues its own, in its own direction, blinded to its own pair identifier - so neither can be read from a relay and neither depends on the other being honest.
Standard library only.
- class fleetmesh_core.peering.peering.Policy[source]
Bases:
objectWhat a node requires of a stranger. Its own choice, published as a digest in its descriptor, and nobody else’s business.
- exception fleetmesh_core.peering.peering.Declined[source]
Bases:
FleetmeshErrorRaised with a code so a caller cannot mistake a refusal for a failure.
- class fleetmesh_core.peering.peering.Node[source]
Bases:
objectOne node’s side of a peering handshake.
Holds the node key, the descriptor it publishes, its policy, and the grants it has issued. It never holds anything about the peer that the peer did not sign.
- __init__(sk_hex, descriptor, policy=None, node_class='edge')[source]
- Parameters:
sk_hex (str)
descriptor (NostrEvent | None)
policy (Policy | None)
node_class (str)
- Return type:
None
- propose(to_did, want, offer, budget_self, pow_event=None, pow_bits=None)[source]
peering/1.0/propose. Declares who I am and what I want.
want is the interest this peering is for and offer is what I claim to hold. Both are scoped: a peering is per shard, not per node, because a grant is scoped to an interest and there is no such thing as a general licence to send.
- Parameters:
- Return type:
- examine(proposal, peer_descriptor, now)[source]
Decide whether to peer. Raises Declined, or returns the tier to open at.
The tier is the operator’s, not the arithmetic’s: everyone opens at probation unless this operator decided otherwise about that peer out of band. See Policy.tier_for.
Ordered cheapest-first, and the order is not cosmetic: a digest comparison costs nothing and a descriptor validation costs a parse, so an incompatible node is turned away before anyone spends work on it.
- offer(proposal, peer_descriptor, now)[source]
peering/1.0/offer, or a decline. This is where the grant is written.
A leaf is refused as a counterparty to issue to only in the sense that it may not issue back: it is the subject of one grant from its mediator and nothing else. It is never refused admission for being a leaf.
now is the caller’s clock and is required: the envelope written here carries an epoch and an expiration, and a missing clock used to stamp both at 0, which published a grant already a lifetime expired.
- Parameters:
peer_descriptor (NostrEvent | None)
now (int)
- Return type:
- accept(offer, peer_did, want, now)[source]
peering/1.0/accept. Publishes the reverse grant, which is what makes the peering exist: acceptance is an event, not a message. now is required for the same reason as in offer().
- disclose(query=None)[source]
discover-features/2.0 disclose, answered from the descriptor.
The descriptor is the binding declaration and this is its echo, so the two cannot disagree by construction. query is the DIDComm shape, [{‘feature-type’: ‘protocol’, ‘match’: <identifier or prefix>}]. A match ending in * is a prefix; anything else must equal the id.
- on_revocation(revocation, ledger=None)[source]
A valid kind 11802 from a peer zeroes every grant issued to it.
Standing does not follow the successor tag: the ledger, if given, closes the subject’s record and opens nothing for anyone else. Returns what was done, or the problems that made the revocation invalid.
- Parameters:
revocation (NostrEvent)
ledger (Any | None)
- Return type:
- fleetmesh_core.peering.peering.handshake(proposer, acceptor, want, offer=None, budget_self=None, pow_event=None, proposer_descriptor=None, *, now)[source]
Run a whole peering and return both grants, or the decline.
The pair is the point. Each side issues in its own direction, so a peering is symmetric in structure and independent in substance: the limits, the tier and the scope on one side say nothing about the other.
now is the clock both envelopes are stamped with and has no default: a reference handshake that silently ran at epoch 0 proved nothing about expiry.
- Parameters:
- Return type:
DIDCommMessage | Mapping[str, Any]
4.2. Coverage Claims
Kind 30803: what a node says it holds, and the one door through the rule about what it may say.
A coverage claim is how data discovery happens at all - a node declares which shards it holds, as a filter plus a completeness claim and a NIP-77 fingerprint over the set. asserted is falsifiable and best-effort promises nothing, and the specification forbids asserting completeness over a shard held only through mesh replication, because that is how third-party replication launders unverified peer data into an authoritative record.
The door through that rule is the handover, and it lives here because it is not a separate mechanism: it is the one shape of asserted a node may publish over a set it did not receive first-hand, and every rule about it is a rule about what a claim may say. The node that holds the shard first-hand signs over the set it has already published, names one replica, and the replica carries that statement in its own claim.
Three rules keep the door narrow, and all three are decidable by a reader holding the claim and nothing else:
- the handed set the replica asserts exactly what it was handed, over a
range that had closed when it was signed for
- shared liability a handover is the signer’s own asserted claim over the
same set, so a hole in it is a hole in theirs
- no signer reports a hole filed by anyone who signed for the set is the
signer’s own fault, and the report would be the mechanism for laundering it onto the replica
The third is why a claim carries the whole CHAIN and not one link. A withheld event handed on twice would otherwise let the node that withheld it report the hole against the node two links down - liable for it by its own signature, and unbarred. Every signer travels so that every signer is barred.
Withdrawal is here for the same reason the claim is: a claim is addressable, so taking one back is republishing it at the same coordinate saying best-effort with an expiration, and a node that stopped republishing has not taken anything back.
- fleetmesh_core.peering.coverage.coverage_claim(pubkey, shard_id, filt, completeness, event_ids, now, since=None, until=None, handover=None, expiration=None)[source]
A kind 30803 over the events the node holds for one shard.
The fingerprint is NIP-77’s own, over the ids, and the count travels beside it. asserted is a falsifiable claim; best-effort is not reportable.
handover is the signed statement from the node that held the shard first-hand, and it is what lets a replica say asserted at all. It is carried inline in the content for the reason a report carries its evidence inline: a reader hashes it and checks the signature and resolves nothing.
It is a chain, ordered from the first-hand root to this claim, because a single link is not enough to say who answers for the set. A withheld event handed on twice would otherwise let the node that withheld it report the hole against the node two links down - liable for the hole and unbarred from reporting it, which is the attack the bar exists to stop, laundered through one intermediary. Every signer in the chain is carried, so every signer can be barred. A single artefact is accepted and means a chain of one. Whether the claim then satisfies the chain’s terms is check_coverage’s business, not this builder’s.
- fleetmesh_core.peering.coverage.withdraw_coverage(claim, now, lapses_in)[source]
The claim that takes an asserted one back, for the same shard.
A coverage claim is addressable, so a republication at the same d replaces what was there and relays drop the one it supersedes. The withdrawal is that republication, saying best-effort - which promises nothing and is not reportable - and carrying a NIP-40 expiration so it lapses rather than outliving the node that made it. A node that simply deleted its claim would leave every reader that already held one with no way to learn it had been taken back.
The set is not restated: a withdrawal is about what this node will still stand behind, and the answer is nothing. It keeps the filter and the range so a reader can see which claim was withdrawn.
- Parameters:
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
now (int)
lapses_in (int)
- Return type:
- fleetmesh_core.peering.coverage.check_coverage(claim, node_class=None)[source]
Structural checks, plus the one class rule. Returns a list of problems.
- Parameters:
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
node_class (str | None)
- Return type:
- fleetmesh_core.peering.coverage.handover_id(art)[source]
SHA-256 of the canonical form with sig excluded: the same construction as a receipt’s chain link, so a handover is cited by the same 32 bytes whether it sits in a claim’s content or in a report’s evidence.
- fleetmesh_core.peering.coverage.handover(sk_hex, to_pubkey, claim, now)[source]
Sign over the set an asserted claim of ours covers, to one named peer.
Everything a reader needs to check the replica’s claim against is copied out of ours, so the artefact stands alone: filter, range, fingerprint and count. until is the range the set is complete over and at is when we said so; a claim that extends past until is asserting something we never signed for. A handover is signed by the node that holds the shard and names the node that will, and those may not be the same key.
- Parameters:
sk_hex (str)
to_pubkey (str)
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
now (int)
- Return type:
- fleetmesh_core.peering.coverage.handover_message(chain, thid, mid=None)[source]
The sync/1.0/handover that carries a chain to its replica.
Sent after a done whose status is complete or in_sync, on that session’s thread. The body is the chain and nothing else, ordered from the first-hand root to the link this message makes; the DIDComm from and to are the DIDs of that last link, so the message says nothing the signature does not already say. The receiver will carry the whole chain in its own claim, so the whole chain has to travel.
- fleetmesh_core.peering.coverage.verify_handover(art, signer=None)[source]
The signature under from, and under signer if one is asked for.
- fleetmesh_core.peering.coverage.check_handover(art)[source]
Structural. Returns problems; an empty list is a well-formed signed handover.
- fleetmesh_core.peering.coverage.handover_chain(claim)[source]
The chain a claim carries, ordered from the first-hand root, or [].
Held to the tag: the last link must hash to the id the tag names, or this is not the chain the tag is about.
- Parameters:
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.peering.coverage.check_chain(chain)[source]
Is this an unbroken chain about one set? Returns problems.
Two rules and both are about what a reader can decide alone. Each link hands to the node that signs the next, so the chain is connected and a reader can follow it back to whoever held the shard first-hand. And every link names the same set, which is what makes the chain about one thing: an intermediary that had handed on something narrower or wider would be passing along a claim nobody above it ever made.
- fleetmesh_core.peering.coverage.inline_handover(claim)[source]
The last link of the chain: the handover made to this claim’s publisher.
- Parameters:
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
HandoverLink | None
- fleetmesh_core.peering.coverage.hole_in_handover(art, event, held)[source]
Evidence of a hole in a handover, against its signer.
A handover is the signer’s own asserted claim over the set it names, so the same event that is a hole in the replica’s claim is a hole in the upstream’s handover. held is what the signer holds, which only a reader syncing with the signer can answer; the replica’s own shelves say nothing about it.
- fleetmesh_core.peering.coverage.barred_reporter(claim, reporter)[source]
Why this reporter may not file a hole against this claim, or None.
The signer of a claim’s handover signed for the same set the claim asserts. A hole it files is an event it held and did not pass on, or one it never held and vouched for anyway; either way the fault is its own and the report is the mechanism for laundering it onto the replica. Decidable by any reader from the claim alone.
- Parameters:
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
reporter (str)
- Return type:
str | None
- fleetmesh_core.peering.coverage.reportable(claim)[source]
Only an asserted claim can be reported against; best-effort promises nothing.
- Parameters:
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.peering.coverage.hole(claim, event, held)[source]
Evidence of a hole in an asserted claim, or None.
An event inside the claim’s filter and time range that the claimant does not hold is the evidence tag a report carries. Against best-effort there is no hole, because nothing was promised.
- Parameters:
claim (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
4.3. Standing Reports
Whether a kind 30802 report may be counted at all.
Two rules do the work, and both are about the reporter rather than the finding: a report must cite a grant the reporter itself issued to the subject, and must carry evidence the subject signed. A report failing either is discarded unread, which is what keeps the reputation system evidence-backed rather than hearsay.
Evidence pins the subject’s half of a disagreement and nothing else. Nobody but the reporter saw the traffic, so a reader takes the measurement on the reporter’s standing and checks only that the subject really said what it is quoted as saying. That is why immune() lets two nodes disagree without either being refuted.
Evidence travels inline, in the report’s own content, and is verified there. It used to be a hash a reader resolved from a relay, which worked only for the one artefact that is a public nostr event. Everything else that proves what a subject did - its receipts, the hops it signed on a delivery envelope - is a private DIDComm body that no relay serves, so a report about the protocol’s central offence could not be checked by anybody. An artefact carried in the report needs nothing served: hash it, compare it to the tag, verify the subject’s signature on it. Resolution is still tried for an event, because a nostr event genuinely is public and need not be copied.
- fleetmesh_core.peering.reports.build(reporter_pubkey, subject_pubkey, severity, grant_id, windows, evidence, now, ttl_seconds, observed=None, claimed=None, notice=None, content='', grant_envelope=None)[source]
A kind 30802, shaped so that admissible() accepts it.
windows is (first_epoch, last_epoch). evidence is [(type, ref)], each ref something the subject signed. observed is (metric, measured, limit) and claimed (metric, value); notice is (thid, delivered_at) from complaint/1.0. The report is the reporter’s current verdict, not a log: d is the subject, so a later one replaces it.
grant_envelope is the kind 30801 the grant tag names, carried inline for the same reason the evidence is. A grant is addressable under a blinded tag, so every new grant to a subject replaces the last at that coordinate and relays drop the superseded one - and a report is about a window, so it cites the grant that governed then. The ladder amends a grant whenever it adjusts a limit, which includes the increase a clean window earns, so within about an hour of publication a report’s citation resolved to nothing and it became inadmissible to every reader. Measured on a running node: five envelopes issued to one peer, one still served. A report that carries its own is checkable for as long as it exists.
- fleetmesh_core.peering.reports.evidence_id(artefact)[source]
The identifier an evidence tag carries for an inline artefact.
SHA-256 of its canonical form, which for a receipt is exactly the chain link the issuer already acknowledges, so a receipt is cited by the same 32 bytes it was acked with.
- fleetmesh_core.peering.reports.inline_evidence(report)[source]
{id: artefact} carried in the report’s content, or {} if none is.
- Parameters:
report (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.peering.reports.note_of(report)[source]
The human half of the content, whatever shape the content is in.
- Parameters:
report (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.peering.reports.admissible(report, reporter_pubkey, resolve_event, verify_sig)[source]
Returns (ok, reasons). resolve_event(id) -> event or None.
- fleetmesh_core.peering.reports.refuted(report, cited_limits, cited_measured, cited_claimed, classifier)[source]
Does the report’s own cited evidence produce the outcome it claims?
The classifier is deterministic, so any reader holding the grant and the evidence can decide this alone. A reporter citing a valid receipt and then claiming a severity the arithmetic does not support is refuted - which is what puts a price on filing a finding, and what the attack surface means by a trusted node spending its standing exactly once.
- Parameters:
- Return type:
- fleetmesh_core.peering.reports.immune(evidence_verified, finding_follows)[source]
Objective evidence immunity, narrowed.
A reporter is immune when its evidence verifies AND the finding follows from that evidence. “Objective” means objectively checkable by the reader, not “unconditional”. Immunity on verification alone would make a false report free, which contradicts the price the severity ladder claims to put on one.
Two nodes that measured different traffic still disagree without either being refuted: they cited different evidence, and each one’s arithmetic follows.
4.4. Complaint Handling
complaint/1.0: present a finding to its subject before publishing it.
Mandatory-first for S1 and S2: an issuer MUST deliver a notice and wait one window before publishing a kind 30802 against a reachable peer. S3 and S4 MAY be published at once. The reason is in the specification: most conformance failures are clock skew, a bug or a misread limit, and a protocol that publishes before it asks produces a permanent public record of transient faults. The constants live in constants.json under complaint.
The remedy is the subject’s answer. Three of its four actions say the subject fixed something; the fourth contests the finding with counter-evidence. What the issuer does next is its own decision. resolve() states the reference’s: a fix makes the notice eligible for withdrawal, a contest sends the issuer back to the arithmetic, and neither changes what the window already measured.
- fleetmesh_core.peering.complaint.message(kind, body, frm, to, thid=None, mid=None)[source]
- Parameters:
kind (str)
body (ComplaintNoticeBody | ComplaintEvidenceBody | ComplaintRemedyBody | Mapping[str, Any])
frm (str)
to (str)
thid (str | None)
mid (str | None)
- Return type:
- fleetmesh_core.peering.complaint.notice(severity, grant_id, epoch, metric, detail, now, window_seconds, description='')[source]
The finding, presented. detail is one entry of evaluate_window()[‘per_limit’].
- fleetmesh_core.peering.complaint.evidence(evidence_type, payload, description='')[source]
What the notice rests on. proof_hash is over the canonical payload, so the subject can check it is being shown the thing it signed.
- Parameters:
- Return type:
- fleetmesh_core.peering.complaint.remedy(action, explanation='', counter_evidence=None)[source]
- Parameters:
- Return type:
- fleetmesh_core.peering.complaint.may_publish(severity, now, notice_at=None, window_seconds=None, reachable=True)[source]
Whether a kind 30802 with this outcome may be published now.
S3 and S4: yes. S1 and S2 against a reachable peer: only after a notice was delivered and a window has passed. Against an unreachable peer there is nobody to notify, and the rule says reachable.
4.5. Bad Peer Scoring & Ban Lists
A node that misbehaves on purpose, with a switch per offence.
The severity ladder is the part of this protocol that decides what happens to a peer, and until now it was only ever exercised by hand-built counters. A ladder tested against arithmetic somebody wrote for the test is not tested. This is the thing the specification’s conformance section asks for: a peer that actually commits each offence, so the finding is produced by the code path a real session would take rather than by a fixture.
Seven offences, named by § Conformance:
overrun-and-admit spends far past its limits and reports it truthfully overrun-and-lie spends the same and reports counters inside the limit out-of-scope-push delivers events outside the interest it was given duplicate-flood delivers events the receiver already holds over-long-path a delivery envelope with more hops than delivery allows replayed-receipt re-sends an earlier receipt rather than a new one forged-hop-signature a path entry whose signature is not the node’s
The first four are session behaviour and ride on fleetmesh_core/storage/sync.py. The last three are envelope and receipt behaviour, which a session never produces; they are built here directly so the same switch covers all seven.
An implementation claiming conformance should be run against this, in the role of the honest side, and should reach the same findings core/tests/test_badpeer.py asserts. Standard library only.
- class fleetmesh_core.peering.badpeer.BadPeer[source]
Bases:
SessionA sync/1.0 responder that breaks one rule and behaves normally otherwise.
offence=None is an honest peer, which is the control every one of these cases needs: the same code path with the switch off must produce no finding at all, or the finding says nothing about the offence.
flood is how many times a duplicate-flood repeats what it sends, and how far an overrun goes past what it was asked for. Both are multipliers rather than counts so a test can state the overrun it wants and let the tier ceiling come from constants.json.
- on_need(message)[source]
Responder. Serves only what its grant permits it to send.
An event it holds but may not push is simply not sent. Sending it would be the S3 the receiver would then file, so refusing is the responder protecting its own standing.
- receipt(seq=0, prev=None, at=None)[source]
A budget/1.0 receipt over what it pushed, or a lie about it.
overrun-and-lie halves the counters until they sit inside the limit it was granted, which is the shape of the lie that matters: not a wild number, but the largest believable one.
- Parameters:
- Return type:
- envelope(event, hop_keys, at=1787000000)[source]
A delivery envelope carrying whichever envelope offence is switched on.
hop_keys are (did, secret key hex) in path order. An honest envelope is produced when the switch is off or is a session offence, so the same call is the control.
- Parameters:
- Return type:
4.6. Reputation Projection
The relay score a node projects for clients: kind 30385 under NIP-85, derived from a kind 30802 and from nothing else.
A kind 30802 is a peer verdict, read by nodes setting budgets. A client choosing a relay reads none of that. It reads NIP-85, where a provider it has chosen publishes a rank for a subject, and for a URL the subject is a NIP-73 identifier: kind 30385, d the URL, k the word web. This module writes one of those per ws or wss endpoint the reported node declares, so a client that already understands NIP-85 learns what the mesh found without learning the mesh.
Adverse only. A node publishes a score for a peer it has reported and for no other peer. The rank is not the peer’s standing - standing lives in blinded grants and unpublished clean windows precisely so that it is not on a relay - it is how far the reporter’s own budget for the subject fell: 100 times the multiplier the ladder applied. The report is cited by coordinate in an a tag, so the evidence is one fetch away and the score never says more than the report does.
The specification had held this back while nostr-protocol/nips PR 2418, which proposes a differently shaped relay assertion under the same kind number, settled. It has not settled and never discussed the number. Merged NIP-85 already assigns kind 30385 to NIP-73 identifiers and a relay URL is one, so the projection is published under the documents that exist. If the proposal merges on another number a second serialiser follows it.
Everything here reads its shape from projection in constants.json.
- fleetmesh_core.peering.projection.canonical_relay(url)[source]
The one spelling of a relay address, per projection.canonical_relay.
Two nodes reporting the same relay must publish the same d, or a client sees two subjects where there is one. NIP-73 says a URL is normalised with no fragment and stops there; this says the rest, and it says it by refusing: a general URL parser (urlsplit, WHATWG) normalises IDNA, IP shorthand, dot segments and percent-encoding each in its own way, so two runtimes agree only if neither is asked to. The grammar is
scheme “://” host [“:” port] [path] [“?” …] [“#” …]
scheme ws | wss, any case, lowercased host an LDH domain name (lowercased; a non-ASCII name is presented as
its A-labels), a dotted-quad IPv4, or a bracketed IPv6 literal in its RFC 5952 spelling; nothing else, no userinfo
port ASCII digits 1..65535 without leading zeros; the default is dropped path “/”-separated segments of URL path characters (no “.”, “..”, “”,
space, backslash or non-ASCII); trailing slashes are dropped
query and fragment are not part of a relay’s identity and are dropped.
Raises ValueError for an address that is not a relay’s.
- fleetmesh_core.peering.projection.relay_endpoints(descriptor)[source]
The relay addresses a kind 11801 declares: ws and wss endpoints, canonical, deduplicated, sorted. An endpoint that does not canonicalise is skipped rather than fatal; it is the descriptor’s defect and the validator reports it there.
- Parameters:
descriptor (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.peering.projection.coordinate(report)[source]
The NIP-01 a value of a kind 30802: kind, author, and its d.
- Parameters:
report (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- fleetmesh_core.peering.projection.project(report, endpoints, now=None)[source]
The kind 30385 events a report projects to: one per endpoint, unsigned.
endpoints is what relay_endpoints() returned for the subject’s descriptor. A subject with none projects to nothing, which is right: a client cannot connect to it, so there is nothing to score. now is the created_at; a node stamps it past the last one at that coordinate, like every other addressable event it republishes.
- Parameters:
report (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
now (int | None)
- Return type:
- fleetmesh_core.peering.projection.check_projection(event, report=None, endpoints=None)[source]
Everything a reader may hold a projection to. Returns the problems.
Alone, the shape: the tags NIP-85 and this protocol require, a canonical d, a rank the ladder can produce. With the report, the derivation: same author, the coordinate really is that report’s, the rank is the report’s outcome priced, the expiry is the report’s. With the subject’s endpoints, that d is one of them.
- Parameters:
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
report (NostrEvent | UnsignedNostrEvent | Mapping[str, Any] | None)
- Return type:
- fleetmesh_core.peering.projection.label(report, now=None)[source]
Build a NIP-32 kind 1985 moderation/reputation label derived from an adverse report.
- Parameters:
report (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
now (int | None)
- Return type:
4.7. Release & Version Verification
Release channel (operations plane): kind 9900 releases, kind 9901 revocations, semver order, and which release a running node should mention.
Reused: kind 9900/9901 are npack’s release and revocation kinds; a release is read the way scripts/sign_release.py writes it. What fleetmesh adds is the provides fleetmesh/<version>@<digest> tag and the selection rule: among the releases by the pinned key that verify and name this package, the newest one newer than what runs and speaking this node’s digest is newest_compatible; the newest newer one speaking another digest is incompatible_newer - reported, never installed, because the digest is a reviewed commitment.
- fleetmesh_core.peering.release.parse_semver(v)[source]
(major, minor, patch, prerelease) or None when v is not a semver. Surrounding whitespace is tolerated; build metadata (+…) is not.
- fleetmesh_core.peering.release.compare(a, b)[source]
-1, 0, 1 for a <, ==, > b. A prerelease sorts below its release; two prereleases compare as plain strings (not SemVer 2 dotted-identifier order - this is the rule both nodes implement).
- fleetmesh_core.peering.release.classify(running, candidate)[source]
‘major’, ‘minor’ or ‘patch’ when candidate is newer than running; None otherwise.
- class fleetmesh_core.peering.release.SelectionDict[source]
Bases:
TypedDict- newest_compatible: ReleaseDict | None
- incompatible_newer: ReleaseDict | None
- class fleetmesh_core.peering.release.ReleaseInfo[source]
Bases:
objectReleaseInfo(event_id: ‘str’, signer: ‘str’, name: ‘str’, version: ‘str’, sha256: ‘str’, artifact_event: ‘Optional[str]’, protocols: ‘tuple[str, …]’, os: ‘str’, arch: ‘str’, created_at: ‘int’)
- fleetmesh_core.peering.release.parse_revocation(ev, release_key)[source]
(revoked release event id, reason) for a kind 9901 by the pinned key whose signature verifies; None for anything else. A revocation signed by another key is not a revocation of anything, so it is silently nothing. The reason is the reason tag, else the content.
- fleetmesh_core.peering.release.parse_release_event(ev, release_key, name='fleetmesh-node')[source]
A ReleaseInfo, or the one-line reason this event is not a release this node will mention. The reasons are refusals the compartment counts: an event under the project’s name from another key is a signal. Checks run in this order and the first failure is the reason: kind, key, signature, name (OTHER_PACKAGE - skipped, not counted), version, x, provides.
- class fleetmesh_core.peering.release.Selection[source]
Bases:
objectSelection(newest_compatible: ‘Optional[ReleaseInfo]’, incompatible_newer: ‘Optional[ReleaseInfo]’, refused: ‘tuple[tuple[str, str], …]’, revoked: ‘tuple[str, …]’)
- newest_compatible: ReleaseInfo | None
- incompatible_newer: ReleaseInfo | None
- __init__(newest_compatible, incompatible_newer, refused, revoked)
- Parameters:
newest_compatible (ReleaseInfo | None)
incompatible_newer (ReleaseInfo | None)
- Return type:
None
- fleetmesh_core.peering.release.select(events, release_key, running, digest, name='fleetmesh-node', already_revoked=())[source]
The pure half of an update check. Revocations are applied first whatever order the relays hand events back in; a revoked release is skipped silently. Releases not newer than running are skipped. Among the rest, the newest speaking digest is newest_compatible; the newest speaking anything else is incompatible_newer. Ties on version go to the first seen (compare > 0 to replace).