8. Wire Protocol & Encodings (fleetmesh_core.wire)

The fleetmesh_core.wire package handles transport serialization, CBOR encoding, schema validation, wire frame envelopes, and typing contracts.

8.1. Wire Types & Envelopes

The shapes that cross the wire, written down once.

Each TypedDict here mirrors one JSON schema under schemas/ - the peering bodies (propose/offer/accept/amend/decline), the sync bodies (open, range, have, need, deliver, done, handover), the compute bodies (quote, accept, sealed, settled, refute, stream, progress, cancel), the handover link a chain is made of, and the rows the grant store hands back. They exist so that the code reading a body can be checked against the schema’s field names and types instead of against untyped dicts, which check nothing. Every field is optional (total=False) because the wire is untrusted: a body is validated by node/validate.py against the schema before anything trusts a key to be present, and the readers keep their .get() guards. The types narrow what a field IS when it is there; they do not promise it is.

Nothing here changes a byte of what is sent. These are annotations only.

class fleetmesh_core.wire.wire_types.DIDCommMessage

Bases: TypedDict

id: str
type: str
from: str
to: list[str]
body: Mapping[str, Any]
thid: str
attachments: list[DIDCommAttachment]
ack: list[str]
please_ack: list[str]
created_time: int
expires_time: int
class fleetmesh_core.wire.wire_types.PeeringWant[source]

Bases: TypedDict

shard: str
filter: NostrFilter
mode: str
since: int
class fleetmesh_core.wire.wire_types.PeeringOfferItem[source]

Bases: TypedDict

shard: str
completeness: str
fingerprint: str
class fleetmesh_core.wire.wire_types.PeeringBudgetSelf[source]

Bases: TypedDict

events_in: int
bytes_in: int
window: int
class fleetmesh_core.wire.wire_types.PeeringPow[source]

Bases: TypedDict

bits: int
event: str
class fleetmesh_core.wire.wire_types.PeeringProposeBody[source]

Bases: TypedDict

schemas/didcomm/peering/propose.schema.json

protocol: list[str]
protocols: list[str]
want: list[PeeringWant] | list[Mapping[str, Any]]
offer: list[PeeringOfferItem] | list[Mapping[str, Any]]
transports: list[str]
budget_self: PeeringBudgetSelf | Mapping[str, Any]
policy: Any
pow: PeeringPow | Mapping[str, Any]
class fleetmesh_core.wire.wire_types.PeeringOfferBody[source]

Bases: TypedDict

schemas/didcomm/peering/offer.schema.json

tier: str
grant_envelope: str
transports: list[str]
limits: GrantLimits | Mapping[str, Any]
envelope_event: NostrEvent
class fleetmesh_core.wire.wire_types.PeeringAcceptBody[source]

Bases: TypedDict

schemas/didcomm/peering/accept.schema.json

grant_envelope: str
selected_transport: str
envelope_event: NostrEvent
class fleetmesh_core.wire.wire_types.PeeringAmendBody[source]

Bases: TypedDict

schemas/didcomm/peering/amend.schema.json

reason: str
cause: Literal['remedy', 'capacity', 'disuse', 'operator']
want: list[PeeringWant] | list[Mapping[str, Any]]
offer: list[PeeringOfferItem] | list[Mapping[str, Any]]
budget_self: PeeringBudgetSelf | Mapping[str, Any]
new_grant_envelope: str
envelope_event: NostrEvent
class fleetmesh_core.wire.wire_types.PeeringDeclineBody[source]

Bases: TypedDict

schemas/didcomm/peering/decline.schema.json

code: Literal['BAD_DESCRIPTOR', 'CAPACITY_EXCEEDED', 'DISCRETIONARY', 'INSUFFICIENT_POW', 'NO_MATCHING_SHARDS', 'POLICY_MISMATCH', 'UNSUPPORTED_PROTOCOL', 'UNSUPPORTED_TRANSPORTS', 'UNSUPPORTED_VERSION']
message: str
class fleetmesh_core.wire.wire_types.PeeringTerminateBody[source]

Bases: TypedDict

schemas/didcomm/peering/terminate.schema.json

reason: str
grace_seconds: int
class fleetmesh_core.wire.wire_types.SyncOpenBody[source]

Bases: TypedDict

schemas/didcomm/sync/open.schema.json

shard: str
filter: Any
since: int
until: int
initial_frame: str
class fleetmesh_core.wire.wire_types.SyncRangeBody[source]

Bases: TypedDict

schemas/didcomm/sync/range.schema.json

range_id: str
since: int
until: int
frame: str
class fleetmesh_core.wire.wire_types.SyncHaveBody[source]

Bases: TypedDict

schemas/didcomm/sync/have.schema.json

ids: list[str]
frame: str
class fleetmesh_core.wire.wire_types.SyncNeedBody[source]

Bases: TypedDict

schemas/didcomm/sync/need.schema.json

ids: list[str]
class fleetmesh_core.wire.wire_types.SyncDeliverBody[source]

Bases: TypedDict

schemas/didcomm/sync/deliver.schema.json - the events ride in the attachment on the wire; events is only present on the in-memory reply before it is re-shaped for sending.

count: int
events: list[NostrEvent]
class fleetmesh_core.wire.wire_types.SyncDoneBody[source]

Bases: TypedDict

schemas/didcomm/sync/done.schema.json

status: Literal['complete', 'in_sync', 'aborted']
events_transferred: int
class fleetmesh_core.wire.wire_types.SyncHandoverBody[source]

Bases: TypedDict

schemas/didcomm/sync/handover.schema.json

chain: list[HandoverLink]

Bases: TypedDict

from: str
to: str
shard: str
claim: str
filter: str
since: int | None
until: int
fingerprint: str
count: int
at: int
sig: str
class fleetmesh_core.wire.wire_types.SealedVerify[source]

Bases: TypedDict

Evidence for the mode the ask declared; under proof, the proof itself.

mode: Literal['sample', 'dual', 'proof', 'none', 'delivery', 'schema-bounds', 'tee-attestation', 'quasi-deterministic']
proof_system: str
proof: str
class fleetmesh_core.wire.wire_types.ProofFailure[source]

Bases: TypedDict

proof mode only: the verifier’s rejection.

proof_system: str
reason: Literal['invalid-proof', 'commitment-mismatch', 'unknown-system']
class fleetmesh_core.wire.wire_types.ComputeQuoteBody[source]

Bases: TypedDict

ask: str
price_msat: int
invoice: str
payment_hash: str
estimated_duration_s: int
class fleetmesh_core.wire.wire_types.ComputeAcceptBody[source]

Bases: TypedDict

payment_hash: str
held: bool
job: Mapping[str, Any]
input_key: str
class fleetmesh_core.wire.wire_types.ComputeSealedBody[source]

Bases: TypedDict

ciphertext: str
payment_hash: str
result: str
fuel_used: int
verify: SealedVerify
class fleetmesh_core.wire.wire_types.ComputeSettledBody[source]

Bases: TypedDict

payment_preimage: str
receipt_event: str
class fleetmesh_core.wire.wire_types.ComputeRefuteBody[source]

Bases: TypedDict

job_receipt: str
mode: Literal['sample', 'dual', 'proof']
claimed_result: str
actual_result: str
wasi_profile_digest: str
engine: str
engine_version: str
proof_failure: ProofFailure
class fleetmesh_core.wire.wire_types.ComputeStreamBody[source]

Bases: TypedDict

seq: int
delta: str
is_final: bool
counters: Mapping[str, Any]
class fleetmesh_core.wire.wire_types.ComputeProgressBody[source]

Bases: TypedDict

state: Literal['queued', 'downloading_inputs', 'running', 'uploading_outputs', 'completed', 'failed']
progress: float
elapsed_seconds: int
logs_tail: str
class fleetmesh_core.wire.wire_types.ComputeCancelBody[source]

Bases: TypedDict

reason: str
penalty_msat: int
class fleetmesh_core.wire.wire_types.Message

Bases: TypedDict

id: str
type: str
from: str
to: list[str]
body: MessageBody
thid: str
pthid: str
created_time: int
expires_time: int
attachments: list[Mapping[str, Any]]
class fleetmesh_core.wire.wire_types.BlobHaveBody[source]

Bases: TypedDict

sha256: list[str]
class fleetmesh_core.wire.wire_types.BlobOfferBody[source]

Bases: TypedDict

sha256: str
size: int
type: str
chunk_bytes: int
class fleetmesh_core.wire.wire_types.BlobPullBody[source]

Bases: TypedDict

sha256: str
offset: int
length: int
class fleetmesh_core.wire.wire_types.BlobChunkBody[source]

Bases: TypedDict

sha256: str
offset: int
data: str
class fleetmesh_core.wire.wire_types.BlobRefuseBody[source]

Bases: TypedDict

sha256: str
why: str
class fleetmesh_core.wire.wire_types.MediateGrantBody[source]

Bases: TypedDict

routing_keys: list[str]
endpoint: str
class fleetmesh_core.wire.wire_types.MediateDenyBody[source]

Bases: TypedDict

reason: str
class fleetmesh_core.wire.wire_types.KeylistUpdateBody[source]

Bases: TypedDict

updates: list[Mapping[str, str]]
class fleetmesh_core.wire.wire_types.KeylistUpdateResponseBody[source]

Bases: TypedDict

updated: list[Mapping[str, str]]
class fleetmesh_core.wire.wire_types.ForwardBody[source]

Bases: TypedDict

next: str
class fleetmesh_core.wire.wire_types.PickupStatusRequestBody[source]

Bases: TypedDict

recipient_key: str
class fleetmesh_core.wire.wire_types.PickupStatusBody[source]

Bases: TypedDict

message_count: int
recipient_key: str
longest_waited_seconds: int
newest_received_time: int
oldest_received_time: int
total_bytes: int
live_delivery: bool
class fleetmesh_core.wire.wire_types.PickupDeliveryRequestBody[source]

Bases: TypedDict

limit: int
recipient_key: str
class fleetmesh_core.wire.wire_types.PickupDeliveryBody[source]

Bases: TypedDict

messages: list[Mapping[str, Any]]
recipient_key: str
class fleetmesh_core.wire.wire_types.PickupMessagesReceivedBody[source]

Bases: TypedDict

message_id_list: list[str]
class fleetmesh_core.wire.wire_types.BudgetCloseBody[source]

Bases: TypedDict

grant: str
window: int
final_receipt_head: str
counters: Mapping[str, int]
class fleetmesh_core.wire.wire_types.BudgetReceiptAckBody[source]

Bases: TypedDict

seq: int
head: str
status: Literal['accepted', 'divergent', 'final']
class fleetmesh_core.wire.wire_types.BudgetDisputeBody[source]

Bases: TypedDict

grant: str
window: int
divergence_metric: str
claimed: float
observed: float
receipt_head: str
message: str
class fleetmesh_core.wire.wire_types.GossipGraftBody[source]

Bases: TypedDict

topic: str
membership: str
class fleetmesh_core.wire.wire_types.GossipPruneBody[source]

Bases: TypedDict

topic: str
reason: str
class fleetmesh_core.wire.wire_types.GossipIdsBody[source]

Bases: TypedDict

ihave and iwant: the wrap ids one side holds or wants.

topic: str
ids: list[str]
class fleetmesh_core.wire.wire_types.GossipPublishBody[source]

Bases: TypedDict

topic: str
event_id: str
envelope: Mapping[str, Any]
class fleetmesh_core.wire.wire_types.TransitSolicitationBody[source]

Bases: TypedDict

video-transit/1.0/solicitation body.

stream_id: str
broadcaster: str
bitrate_kbps: int
max_transit_bytes: int
mode: Literal['pro-bono', 'commercial']
codecs: list[str]
at: int
class fleetmesh_core.wire.wire_types.TransitGrantBody[source]

Bases: TypedDict

video-transit/1.0/grant body.

grant_id: str
stream_id: str
broadcaster: str
operator: str
window_seconds: int
receipt_cadence_seconds: int
max_unsettled_transit_bytes: int
reflector_endpoints: list[str]
mode: Literal['pro-bono', 'commercial']
at: int
sig: str
class fleetmesh_core.wire.wire_types.TransitReceiptBody[source]

Bases: TypedDict

video-transit/1.0/receipt body.

grant: str
stream_id: str
window: int
seq: int
prev: str
counters: dict[str, int]
at: int
sig: str
class fleetmesh_core.wire.wire_types.TransitCloseBody[source]

Bases: TypedDict

video-transit/1.0/close body.

grant: str
stream_id: str
window: int
final_receipt_head: str
counters: dict[str, int]
reason: str
at: int
class fleetmesh_core.wire.wire_types.TransitReceiptAckBody[source]

Bases: TypedDict

video-transit/1.0/receipt-ack body.

grant: str
seq: int
head: str
status: Literal['accepted', 'divergent', 'final', 'degraded-audio-only']
unsettled_bytes: int
class fleetmesh_core.wire.wire_types.GrantRow[source]

Bases: TypedDict

One row of GrantStore.get: the grant as held, and the envelope it came in.

payload: GrantPayload
envelope_id: str
status: str
env_created_at: int | None
updated_at: int
class fleetmesh_core.wire.wire_types.PendingRow[source]

Bases: TypedDict

One row of GrantStore.pending: a decision waiting for the window boundary.

payload: GrantPayload
note: str
severity: str | None
decided_epoch: int
class fleetmesh_core.wire.wire_types.GoverningRow[source]

Bases: TypedDict

GrantStore.governing: the grant in force for one window. effective_epoch is None when the store predates the history table and the current row answered instead.

payload: GrantPayload
envelope_id: str
effective_epoch: int | None
class fleetmesh_core.wire.wire_types.HistoryRow[source]

Bases: TypedDict

GrantStore.history: one grant that has governed a window, by tier only.

envelope_id: str
effective_epoch: int
tier: str | None
class fleetmesh_core.wire.wire_types.GrantListRow[source]

Bases: TypedDict

GrantStore.list: every held grant, with the peer and direction it is for.

peer: str
direction: str
payload: GrantPayload
envelope_id: str
status: str
class fleetmesh_core.wire.wire_types.Inbound[source]

Bases: Protocol

What every transport’s receive() yields: the plaintext and who sent it.

property message: Mapping[str, Any]
property sender: str
__init__(*args, **kwargs)
class fleetmesh_core.wire.wire_types.PeerTransport[source]

Bases: Protocol

The three calls the peering and sync subsystems make on a transport.

Nostr gift-wrap, iroh, FIPS and the router in node/transport/router.py all satisfy this without inheriting from anything; a test double needs only these.

send(message, to_pubkey, *args, **kwargs)[source]
Parameters:
Return type:

Any

request(message, to_pubkey, *args, **kwargs)[source]
Parameters:
Return type:

Any

receive(timeout=None)[source]
Parameters:

timeout (float | None)

Return type:

Any

__init__(*args, **kwargs)
fleetmesh_core.wire.wire_types.is_event_shaped(obj)[source]

Does this carry every NIP-01 field with the right primitive type?

This is the structural half of “is it an event”; the signature is the other half and is checked separately (giftwrap.verify_event), because a reader wants to say which failed. Passing here does not make the event genuine, it makes the annotation honest.

Parameters:

obj (object)

Return type:

TypeGuard[NostrEvent]

8.2. Schema Validation

Shape checks at the door, before any handler sees a message.

Every handler was written to read the fields its protocol names, and a message that lacked one, or carried a string where an integer belongs, raised inside the handler. The serve loop caught that and logged handler failed, so the node lived - but a peer could make it log that on every message for ever, and whatever the handler had done before it raised stayed done. A message is checked here against the field lists messages.json declares and the types the reference reads. One that fails is dropped with a reason and counted, and no handler runs.

Nothing here decides anything about a peer. A malformed message is not an offence, because an offence needs something the peer signed and meant; it is noise, and the node’s only duty is to survive it. Standard library only.

fleetmesh_core.wire.validate.is_int(v)[source]
Parameters:

v (Any)

Return type:

bool

fleetmesh_core.wire.validate.is_num(v)[source]
Parameters:

v (Any)

Return type:

bool

fleetmesh_core.wire.validate.hex64(v)[source]
Parameters:

v (Any)

Return type:

bool

fleetmesh_core.wire.validate.check_handover_body(b)[source]

Why a sync/1.0/handover body has the wrong shape, or None.

Parameters:

b (Mapping[str, Any])

Return type:

str | None

fleetmesh_core.wire.validate.split_type(t)[source]

(‘budget’, ‘receipt’) from a fleetmesh or registered PIURI message type, else (None, None).

Parameters:

t (Any)

Return type:

tuple[str | None, str | None]

fleetmesh_core.wire.validate.EXTENSIONS: dict[str, set[str]] = {}

PIURI -> message kinds for protocols registered at runtime by out-of-tree compartments. Foreign origins only: fleetmesh.org protocols come from schema/messages.json and are governed by the digest, never by code.

fleetmesh_core.wire.validate.origin_of(identifier)[source]

https://<host>/grasp/1.0 -> https://<host>/.

Scheme and host via urllib.parse, not a character-wise prefix: a prefix every identifier shares by accident would refuse one of our own protocols added later and admit a lookalike host as foreign. ValueError when the identifier is not https://<host>/…

Parameters:

identifier (str)

Return type:

str

fleetmesh_core.wire.validate.register_protocol(piuri, kinds, checks=None)[source]

Put a foreign protocol on the door so its bodies are checked like ours.

Parameters:
Return type:

str

fleetmesh_core.wire.validate.register_check(protocol, kind, fn)[source]

Add one body checker for a (protocol, kind) the node does not already check.

Parameters:
Return type:

None

fleetmesh_core.wire.validate.unregister_protocol(piuri)[source]

Undo register_protocol (tests and plugin stop()).

Parameters:

piuri (str)

Return type:

None

fleetmesh_core.wire.validate.check_body(protocol, kind, body)[source]

Why a body of this protocol message must not be handled, or None.

Parameters:
Return type:

str | None

fleetmesh_core.wire.validate.check(message)[source]

Why a DIDComm plaintext must not be handled, or None if it may be.

Parameters:

message (Any)

Return type:

str | None

8.3. CBOR Codec

CBOR (RFC 8949) and DAG-CBOR (IPLD), standard library only.

Supports the data types needed across Fleetmesh: - Hardware Enclave COSE keys and WebAuthn attestation documents. - Cashu V4 tokens and NUT-18 payment requests. - ATProto / IPLD repositories and records: Merkle Search Trees (MST),

commit blocks, and IPLD Link CIDs via Major Type 6 Tag 42.

Enforces deterministic canonical sorting for maps (length-first, then bytewise lexicographical per RFC 7049 / DAG-CBOR specification).

exception fleetmesh_core.wire.cbor.CBORError[source]

Bases: FleetmeshError, ValueError

fleetmesh_core.wire.cbor.cbor_encode(val, *, canonical=False)[source]

Minimal, deterministic CBOR encoder with Tag 42 IPLD Link and COSE support.

If canonical is True (or via dag_cbor_encode), map keys are sorted length-first, then bytewise per RFC 7049 / DAG-CBOR. Otherwise, dictionary insertion order is preserved (as required by Cashu V4 / COSE).

Parameters:
Return type:

bytes

fleetmesh_core.wire.cbor.dag_cbor_encode(val)[source]

Encode value to canonical DAG-CBOR bytes.

Parameters:

val (Any)

Return type:

bytes

fleetmesh_core.wire.cbor.dag_cbor_decode(data)[source]

Decode exact DAG-CBOR bytes, ensuring entire buffer is consumed.

Parameters:

data (bytes)

Return type:

Any

fleetmesh_core.wire.cbor.cbor_decode(data)[source]

Minimal CBOR decoder. Returns (decoded_value, bytes_consumed).

Parameters:

data (bytes)

Return type:

tuple[Any, int]

8.4. Schema File Loader

The one place the reference library reads its published schema files.

Every module used to json.load(open(…)) schema/constants.json for itself: sixteen file descriptors left to the garbage collector, three of them without an encoding, and no single place to say where the schema lives. Each loader here opens the file once, under with, as UTF-8, and lru_cache hands the same parsed object to every importer - so window.C, capacity.C and peering.CONSTANTS are views of one document, exactly as the digest promises.

Where the files are: the fleetmesh_schema package carries them (installed or as the sibling checkout on sys.path); a bare checkout of this repo with the schema -> ../schema/schema symlink and no such package falls back to that. Either way ROOT is the directory holding schema/ and schemas/, which is what the few callers that build their own paths need.

Standard library only. Nothing here reads the network or the wall clock.

fleetmesh_core.wire.schema_files.path(name)[source]

Absolute path of a file under schema/ (constants.json, kinds.json, …).

Parameters:

name (str)

Return type:

str

fleetmesh_core.wire.schema_files.schema_path(*parts)[source]

Absolute path of a JSON Schema document under schemas/ (plane, …, file).

Parameters:

parts (str)

Return type:

str

fleetmesh_core.wire.schema_files.load_json(name)[source]

Parse one schema file, once. The path is in any error so a broken checkout names itself instead of surfacing as a KeyError three modules later.

Parameters:

name (str)

Return type:

Any

fleetmesh_core.wire.schema_files.load_constants()[source]
Return type:

SchemaConstantsDocument

fleetmesh_core.wire.schema_files.load_kinds()[source]

The whole kinds.json document (callers index [‘kinds’] or [‘version’]).

Return type:

SchemaKindsDocument

fleetmesh_core.wire.schema_files.load_messages()[source]
Return type:

SchemaMessagesDocument

fleetmesh_core.wire.schema_files.digest()[source]

The published protocol digest, schema/DIGEST, stripped.

Return type:

str

8.5. Wire Interfaces

Formal interfaces, protocols, and data contracts for fleetmesh_core/.

Standard library only. All wire types reflect the normative JSON Schemas in schemas/ and the protocol invariants verified across the reference implementation.

class fleetmesh_core.wire.interfaces.NostrEvent[source]

Bases: TypedDict

id: str
pubkey: str
created_at: int
kind: int
tags: list[list[str]]
content: str
sig: str
class fleetmesh_core.wire.interfaces.UnsignedNostrEvent[source]

Bases: TypedDict

id: str
pubkey: str
created_at: int
kind: int
tags: list[list[str]]
content: str
class fleetmesh_core.wire.interfaces.NostrFilter

Bases: TypedDict

ids: list[str]
authors: list[str]
kinds: list[int]
since: int
until: int
limit: int
search: str
class fleetmesh_core.wire.interfaces.DeliveryHop[source]

Bases: TypedDict

node: str
at: int
sig: str
class fleetmesh_core.wire.interfaces.DeliveryEnvelope[source]

Bases: TypedDict

event: NostrEvent
path: list[DeliveryHop]
class fleetmesh_core.wire.interfaces.ReceiptCounters[source]

Bases: TypedDict

conn_open: int
conn_rate: int
req: int
events_in: int
bytes_in: int
bytes_out: int
blob_bytes: int
sync_ranges: int
errors: int
dups_sent: int
class fleetmesh_core.wire.interfaces.ReceiptBody[source]

Bases: TypedDict

grant: str
window: int
seq: int
prev: str
counters: dict[str, int]
at: int
sig: str
class fleetmesh_core.wire.interfaces.ReceiptChainEntry[source]

Bases: TypedDict

receipt: ReceiptBody
canonical: str
sha256: str
class fleetmesh_core.wire.interfaces.ReceiptChainDoc[source]

Bases: TypedDict

chain: list[ReceiptChainEntry]
head: str
class fleetmesh_core.wire.interfaces.SilenceEvaluation[source]

Bases: TypedDict

state: str
severity: str | None
remedy: str
class fleetmesh_core.wire.interfaces.WindowEvaluationDetail[source]

Bases: TypedDict

measured: int | float
claimed: int | float | None
limit: int | float
overrun: float
divergence: float
severity: str
class fleetmesh_core.wire.interfaces.CapacitySummary[source]

Bases: TypedDict

declared: bool
pressure: float | None
binding: str | None
rungs: list[str]
measured: dict[str, int | float]
class fleetmesh_core.wire.interfaces.DescriptorConstants[source]

Bases: TypedDict

max_lifetime_seconds_anchor_edge: int
max_lifetime_seconds_leaf: int
default_pow_bits: int
pow_bits_of: str
required_protocols: list[str]
protocol_floors: dict[str, str]
protocol_floors_note: str
required_protocols_note: str
optional_protocols: list[str]
optional_protocols_note: str
endpoints_digest: str
did_contexts: list[str]
did_contexts_note: str
class fleetmesh_core.wire.interfaces.GrantConstants[source]

Bases: TypedDict

window_seconds_default: int
window_grace_fraction: float
opening_limit_fraction: float
opening_applies_to: list[str]
opening_limit_why: str
divergence_floor_fraction: float
divergence_floor_sessions: int
divergence_floor_why: str
overrun_tolerance: float
aimd_increase_fraction: float
aimd_increase_is_load_weighted: bool
aimd_increase_weighting: str
aimd_min_increase_fraction: float
aimd_min_increase_why: str
decay_fraction: float
decay_idle_windows: int
decay_by_disuse: str
decay_floor: str
decay_is_not_adverse: str
aimd_used_is_required: str
aimd_decrease_s1: float
aimd_decrease_s2: float
s3_zero_hours: int
max_clock_skew_seconds: int
visibility: str
pair_blinding: str
divergence_tolerance: float
schedule_is_a_ratio: str
severity_classification: Mapping[str, Any]
epoch: str
epoch_note: str
window_evaluation: Mapping[str, Any]
receipt_signature: str
counter_of: dict[str, str]
advisory_limits: Mapping[str, Any]
evidence: str
class fleetmesh_core.wire.interfaces.HopSignatureConstants[source]

Bases: TypedDict

domain: str
hash: str
class fleetmesh_core.wire.interfaces.DeliveryConstants[source]

Bases: TypedDict

max_forward_hops: int
hop_signature: HopSignatureConstants
class fleetmesh_core.wire.interfaces.VerifyModeSpec[source]

Bases: TypedDict

param: str
evidence: str
needs_plaintext: bool
default_rate: float
status: str
class fleetmesh_core.wire.interfaces.MarketConstants[source]

Bases: TypedDict

default_verify_sample_rate: float
settlement: str
sampling_model: str
verify_modes: dict[str, VerifyModeSpec]
progress_states: list[str]
class fleetmesh_core.wire.interfaces.ProjectionConstants[source]

Bases: TypedDict

kind: int
subject: str
canonical_relay: str
rank_by_outcome: dict[str, int]
published_when: str
class fleetmesh_core.wire.interfaces.DiscoveryConstants[source]

Bases: TypedDict

kind: int
subject: str
tags: str
content: str
published_when: str
class fleetmesh_core.wire.interfaces.NIP11Limitation[source]

Bases: TypedDict

max_message_length: int
max_subscriptions: int
max_filters: int
max_limit: int
max_subid_length: int
min_pow_difficulty: int | float | str
auth_required: bool | int
payment_required: bool | int
restricted_writes: bool | int
class fleetmesh_core.wire.interfaces.NIP11RelayInfo[source]

Bases: TypedDict

name: str
description: str
pubkey: str
contact: str
supported_nips: list[int]
software: str
version: str
limitation: NIP11Limitation | Mapping[str, Any]
class fleetmesh_core.wire.interfaces.ComplaintConstants[source]

Bases: TypedDict

notice_required_for: list[str]
immediate: list[str]
wait_windows: int
remedy_actions: list[str]
class fleetmesh_core.wire.interfaces.TransportConstants[source]

Bases: TypedDict

ladder_rank: dict[str, int]
ladder_tie_break: str
attempt_timeout_seconds: int
class fleetmesh_core.wire.interfaces.SchemaConstantsDocument[source]

Bases: TypedDict

version: str
crypto: Mapping[str, Any]
grant: GrantConstants
blinding: Mapping[str, Any]
tier_weight: dict[str, float]
trust: Mapping[str, Any]
delivery: DeliveryConstants
descriptor: DescriptorConstants
did: Mapping[str, Any]
leaf: Mapping[str, Any]
market: MarketConstants
tier_limits: Mapping[str, Any]
capacity: Mapping[str, Any]
resilience: Mapping[str, Any]
commitment: Mapping[str, Any]
canonical: Mapping[str, Any]
transport: TransportConstants
blob_wire: Mapping[str, Any]
store: Mapping[str, Any]
complaint: ComplaintConstants
projection: ProjectionConstants
discovery: DiscoveryConstants
roster: Mapping[str, Any]
class fleetmesh_core.wire.interfaces.KindSpec[source]

Bases: TypedDict

description: str
rfc: str
tags: dict[str, list[str]]
required_tags: list[str]
class fleetmesh_core.wire.interfaces.SchemaKindsDocument[source]

Bases: TypedDict

version: str
kinds: dict[str, KindSpec]
reused: Mapping[str, Mapping[str, Any]]
class fleetmesh_core.wire.interfaces.SchemaMessagesDocument[source]

Bases: TypedDict

version: str
envelope: str
protocols: Mapping[str, Mapping[str, Any]]
reused_protocols: list[str]
transports: Mapping[str, Mapping[str, Any]]
topics: Mapping[str, Mapping[str, Any]]
surfaces: Mapping[str, Any]
class fleetmesh_core.wire.interfaces.PeeringWant[source]

Bases: TypedDict

shard: str
filter: NostrFilter
mode: str
since: int
class fleetmesh_core.wire.interfaces.PeeringOfferItem[source]

Bases: TypedDict

shard: str
completeness: str
fingerprint: str
class fleetmesh_core.wire.interfaces.PeeringBudgetSelf[source]

Bases: TypedDict

events_in: int
bytes_in: int
window: int
class fleetmesh_core.wire.interfaces.PeeringPow[source]

Bases: TypedDict

bits: int
event: str
class fleetmesh_core.wire.interfaces.GrantLimits[source]

Bases: TypedDict

conn_rate: int
req: int
events_in: int
bytes_in: int
bytes_out: int
blob_bytes: int
sync_ranges: int
errors: int
dup_ratio: float
class fleetmesh_core.wire.interfaces.GrantScope[source]

Bases: TypedDict

push: NostrFilter
pull: NostrFilter
class fleetmesh_core.wire.interfaces.GrantPayload[source]

Bases: TypedDict

subject: str
tier: str
window: int
limits: Mapping[str, Any]
scope: GrantScope | Mapping[str, Any]
receipt: list[int]
settlement: str
blinding: str
class fleetmesh_core.wire.interfaces.DIDCommAttachmentData[source]

Bases: TypedDict

json: Mapping[str, Any]
base64: str
class fleetmesh_core.wire.interfaces.DIDCommAttachment[source]

Bases: TypedDict

id: str
mime_type: str
data: DIDCommAttachmentData
class fleetmesh_core.wire.interfaces.DIDCommMessage

Bases: TypedDict

id: str
type: str
from: str
to: list[str]
body: Mapping[str, Any]
thid: str
attachments: list[DIDCommAttachment]
ack: list[str]
please_ack: list[str]
created_time: int
expires_time: int
class fleetmesh_core.wire.interfaces.StandingTellBody[source]

Bases: TypedDict

target: str
tier: str
clean_windows: int
evaluated_windows: int
has_adverse_reports: bool
class fleetmesh_core.wire.interfaces.StandingAskBody[source]

Bases: TypedDict

target: str
query: list[str]
class fleetmesh_core.wire.interfaces.ComplaintNoticeBody[source]

Bases: TypedDict

outcome: str
grant: str
window: int
metric: str
observed: int | float
limit: int | float
deadline: int
claimed: int | float
description: str
class fleetmesh_core.wire.interfaces.ComplaintEvidenceBody[source]

Bases: TypedDict

evidence_type: str
proof_hash: str
payload: Any
description: str
class fleetmesh_core.wire.interfaces.ComplaintRemedyBody[source]

Bases: TypedDict

action: str
explanation: str
counter_evidence: Any
class fleetmesh_core.wire.interfaces.MeshStoreProtocol[source]

Bases: Protocol

Storage backend contract for Nostr events and range queries.

get_event(event_id)[source]
Parameters:

event_id (str)

Return type:

Mapping[str, Any] | None

has_event(event_id)[source]
Parameters:

event_id (str)

Return type:

bool

insert_event(event, now)[source]
Parameters:
Return type:

str

enumerate_range(filt, since, until, now)[source]
Parameters:
Return type:

list[str]

items_range(filt, since, until, now)[source]
Parameters:
Return type:

list[tuple[int, str]]

fingerprint_range(filt, since, until, now)[source]
Parameters:
Return type:

str

newest_matching(filt, since, until, now, cap)[source]
Parameters:
Return type:

list[Mapping[str, Any]]

__init__(*args, **kwargs)
class fleetmesh_core.wire.interfaces.GrantProtocol[source]

Bases: Protocol

Bilateral grant contract governing session capacity and filtering.

event_id: str
tier: str
limits: Mapping[str, Any]
scope: Mapping[str, Any]
window: int
permits(event, direction='push')[source]
Parameters:
Return type:

bool

exceeded(counters)[source]
Parameters:

counters (Mapping[str, int])

Return type:

dict[str, float]

__init__(*args, **kwargs)
class fleetmesh_core.wire.interfaces.SessionProtocol[source]

Bases: Protocol

Sync session state machine interface.

grant: GrantProtocol
counters: dict[str, int]
findings: list[tuple[str, str]]
shard: str
since: int
until: int
now: int
is_initiator: bool
open()[source]
Return type:

Mapping[str, Any]

on_open(msg)[source]
Parameters:

msg (Mapping[str, Any])

Return type:

Mapping[str, Any] | None

on_range(msg)[source]
Parameters:

msg (Mapping[str, Any])

Return type:

Mapping[str, Any] | None

on_need(msg)[source]
Parameters:

msg (Mapping[str, Any])

Return type:

Mapping[str, Any] | None

on_deliver(msg)[source]
Parameters:

msg (Mapping[str, Any])

Return type:

Mapping[str, Any] | None

dup_ratio()[source]
Return type:

float

receipt(seq=0, prev=None, at=None)[source]
Parameters:
  • seq (int)

  • prev (str | None)

  • at (int | None)

Return type:

ReceiptBody

__init__(*args, **kwargs)
class fleetmesh_core.wire.interfaces.LedgerProtocol[source]

Bases: Protocol

Standing ledger query and evaluation protocol.

windows: dict[str, list[tuple[int, str]]]
tier: dict[str, str]
reported: set[str]
reports_seen: dict[str, dict[str, bool]]
record(subject, epoch, severity, tier)[source]
Parameters:
Return type:

None

severity_of(subject, epoch)[source]
Parameters:
Return type:

str | None

amend(subject, epoch, severity)[source]
Parameters:
Return type:

str | None

reported_against(subject)[source]
Parameters:

subject (str)

Return type:

None

on_revocation(subject)[source]
Parameters:

subject (str)

Return type:

None

knows(subject)[source]
Parameters:

subject (str)

Return type:

bool

record_report(reporter, report_id, contradicted)[source]
Parameters:
  • reporter (str)

  • report_id (str)

  • contradicted (bool)

Return type:

None

report_record(reporter)[source]
Parameters:

reporter (str)

Return type:

tuple[int, int]

evaluated_windows(subject)[source]
Parameters:

subject (str)

Return type:

int

clean_windows(subject)[source]
Parameters:

subject (str)

Return type:

int

tell(subject)[source]
Parameters:

subject (str)

Return type:

Mapping[str, Any] | None

answer(ask_body, willing=True)[source]
Parameters:
Return type:

tuple[str, Mapping[str, Any]]

__init__(*args, **kwargs)
class fleetmesh_core.wire.interfaces.PolicyProtocol[source]

Bases: Protocol

Peering policy requirements for admitting a peer.

pow_bits: int
transports: dict[str, int]
shards: Mapping[str, Any]
open_enrolment: bool
opening_tier: str
protocols: set[str]
tiers: dict[str, str]
tier_for(subject_pubkey)[source]
Parameters:

subject_pubkey (str)

Return type:

str

__init__(*args, **kwargs)
class fleetmesh_core.wire.interfaces.ProtocolHealth[source]

Bases: object

Operational telemetry and status of a protocol package.

healthy: bool
status: str
connections_active: int
messages_in: int
messages_out: int
errors: Sequence[str] = ()
__init__(healthy, status, connections_active, messages_in, messages_out, errors=())
Parameters:
Return type:

None

class fleetmesh_core.wire.interfaces.RouteMatch[source]

Bases: object

A matched HTTP or WebSocket route handler.

path_prefix: str
methods: tuple[str, ...]
handler: Callable[[Any], Any]
is_websocket: bool = False
__init__(path_prefix, methods, handler, is_websocket=False)
Parameters:
Return type:

None

class fleetmesh_core.wire.interfaces.ProtocolHostRouter[source]

Bases: Protocol

Unified HTTP / WebSocket multiplexer mounted on the node’s public port.

mount_route(prefix, handler, methods=('GET',), owner='')[source]
Parameters:
Return type:

None

mount_websocket(path, handler, owner='')[source]
Parameters:
Return type:

None

unmount_all(owner)[source]
Parameters:

owner (str)

Return type:

None

__init__(*args, **kwargs)
class fleetmesh_core.wire.interfaces.ProtocolIdentityAdapter[source]

Bases: Protocol

Translates between Fleetmesh keys and foreign protocol identity models.

resolve_id(uri)[source]
Parameters:

uri (str)

Return type:

str | None

sign_assertion(payload)[source]
Parameters:

payload (bytes)

Return type:

bytes

verify_assertion(payload, signature, pubkey)[source]
Parameters:
Return type:

bool

__init__(*args, **kwargs)
class fleetmesh_core.wire.interfaces.ProtocolPackage[source]

Bases: Protocol

The formal interface implemented by every pluggable protocol package.

name: str
version: str
standards: tuple[str, ...]
configure(config)[source]

Parse, validate, and store the protocol-specific configuration block.

Parameters:

config (Mapping[str, Any])

Return type:

None

identity_adapter(keystore)[source]

Return the identity and cryptographic adapter for this protocol family.

The node does not call this yet: packages build and use their adapters themselves, and nothing resolves an identity across packages. It is kept as the extension point for that, not as a contract anything exercises - an implementation is tested by its own suite, not by a running node (audit 2026-10-15). storage_adapter beside it was removed: every package already receives its stores in its constructor.

Parameters:

keystore (Any)

Return type:

ProtocolIdentityAdapter | None

mount_ingress(host)[source]

Register HTTP and WebSocket route handlers onto the shared public host face.

Parameters:

host (ProtocolHostRouter)

Return type:

None

transport_rung(context)[source]

Return an outbound TransportProtocol rung for TransportRouter, if supported.

Parameters:

context (Any)

Return type:

Any | None

compartments()[source]

Return any background Compartment classes to splice into NodeApp MANIFEST.

Return type:

tuple[type[Any], …]

start()[source]

Boot the protocol runtime (open sockets, connect to upstreams).

Return type:

None

stop()[source]

Gracefully terminate connections and release listeners.

Return type:

None

health()[source]

Return real-time operational metrics and health status.

Return type:

ProtocolHealth

descriptor_capabilities()[source]

Return protocol capability tags (e.g. (‘c’, ‘https://example.org/atproto/…’)) for kind 11801.

Return type:

tuple[tuple[str, str], …]

__init__(*args, **kwargs)

8.6. p2panda Wire & Append-Only Log Protocol

The fleetmesh_core.wire.p2panda module implements the p2panda specification (v0.4.0):

  • Canonical deterministic CBOR encoding (RFC 8949) of operation headers and payloads.

  • Ed25519 author identity signatures over canonical unsigned header digests.

  • Strict monotonic sequence numbering (seq_num), predecessor sequencing, and backlink integrity.

  • Payload integrity hashing with configurable digest algorithms.

  • Ordered multi-operation chain validation.

p2panda protocol wire data structures and cryptographic operations.

Conforms to p2panda specification v0.4.0: - Canonical CBOR deterministic encoding (RFC 8949) using fleetmesh_core.wire.cbor. - Ed25519 author identities and signatures. - Append-only cryptographic operation logs with monotonic sequence numbers and backlinks.

class fleetmesh_core.wire.p2panda.P2PandaHeaderDict[source]

Bases: TypedDict

version: int
public_key: str
signature: str
payload_size: int
payload_hash: str
timestamp: int
seq_num: int
previous_seq_num: int
extensions: Mapping[str, Any]
class fleetmesh_core.wire.p2panda.P2PandaOperationDict[source]

Bases: TypedDict

header: P2PandaHeaderDict
body: bytes | str
exception fleetmesh_core.wire.p2panda.P2PandaError[source]

Bases: FleetmeshError, ValueError

Base error for p2panda wire parsing, serialization, and validation.

class fleetmesh_core.wire.p2panda.P2PandaHeader[source]

Bases: object

Header for a p2panda operation.

Contains cryptographic provenance, log ordering, author identity, and payload integrity metadata.

version: int = 1
public_key: str = ''
signature: str | None = None
payload_size: int = 0
payload_hash: str = ''
timestamp: int = 0
seq_num: int = 0
previous_seq_num: int | None = None
extensions: Mapping[str, Any] | None = None
to_unsigned_dict()[source]

Return canonical mapping of fields covered by the author’s signature.

Return type:

P2PandaHeaderDict

to_dict(include_signature=True)[source]

Return dictionary representation of the header.

Parameters:

include_signature (bool)

Return type:

P2PandaHeaderDict

to_cbor(include_signature=True)[source]

Encode header into canonical CBOR (RFC 8949).

Parameters:

include_signature (bool)

Return type:

bytes

unsigned_cbor()[source]

Encode unsigned header fields into canonical CBOR for signing/verifying.

Return type:

bytes

unsigned_hash(algo='sha256')[source]

Compute digest of the unsigned canonical CBOR bytes.

Parameters:

algo (str)

Return type:

str

hash(algo='sha256')[source]

Compute digest of the complete (signed) canonical CBOR header bytes.

This serves as the operation identifier (op_id).

Parameters:

algo (str)

Return type:

str

classmethod from_dict(raw)[source]

Construct P2PandaHeader from a dictionary.

Parameters:

raw (Mapping[str, Any])

Return type:

P2PandaHeader

classmethod from_cbor(data)[source]

Decode P2PandaHeader from canonical CBOR bytes.

Parameters:

data (bytes)

Return type:

P2PandaHeader

__init__(version=1, public_key='', signature=None, payload_size=0, payload_hash='', timestamp=0, seq_num=0, backlink=None, previous_seq_num=None, extensions=None)
Parameters:
  • version (int)

  • public_key (str)

  • signature (str | None)

  • payload_size (int)

  • payload_hash (str)

  • timestamp (int)

  • seq_num (int)

  • backlink (str | None)

  • previous_seq_num (int | None)

  • extensions (Mapping[str, Any] | None)

Return type:

None

class fleetmesh_core.wire.p2panda.P2PandaOperation[source]

Bases: object

A complete p2panda operation comprising a signed header and body payload.

header: P2PandaHeader
body: bytes | None = None
property id: str

Unique operation ID derived from the signed header hash.

property author: str

Author’s Ed25519 public key hex string.

property seq_num: int
verify_signature()[source]

Verify the author’s Ed25519 signature over the canonical unsigned header bytes.

Return type:

bool

verify_payload()[source]

Verify that the payload size and hash match the body (if body is present).

Return type:

bool

verify()[source]

Verify both cryptographic signature and payload integrity.

Return type:

bool

sign(private_key)[source]

Sign this operation with the given Ed25519 private key, returning a new operation with signature set.

Parameters:

private_key (Ed25519PrivateKey)

Return type:

P2PandaOperation

to_dict(json_safe=False)[source]

Serialize operation to dictionary.

Parameters:

json_safe (bool)

Return type:

P2PandaOperationDict

to_cbor()[source]

Serialize entire operation to canonical CBOR.

Return type:

bytes

classmethod from_dict(raw)[source]

Construct P2PandaOperation from dictionary.

Parameters:

raw (Mapping[str, Any])

Return type:

P2PandaOperation

classmethod from_cbor(data)[source]

Decode P2PandaOperation from CBOR bytes.

Parameters:

data (bytes)

Return type:

P2PandaOperation

classmethod create(public_key, body=None, seq_num=0, backlink=None, timestamp=None, private_key=None, extensions=None)[source]

Factory method to assemble, hash, and optionally sign a new operation.

Parameters:
Return type:

P2PandaOperation

__init__(header, body=None)
Parameters:
Return type:

None

fleetmesh_core.wire.p2panda.validate_operation_chain(ops)[source]

Validate an ordered append-only sequence of operations by an author.

Checks: 1. Signature validity for every operation. 2. Payload integrity for operations containing bodies. 3. Author consistency across all operations in the chain. 4. Strict monotonic sequence numbers (seq_num == prev_seq_num + 1). 5. Backlink continuity (backlink == prev_operation.id). 6. Non-decreasing chronological timestamps.

Parameters:

ops (Sequence[P2PandaOperation])

Return type:

tuple[bool, str | None]