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]
-
class fleetmesh_core.wire.wire_types.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:
-
- 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
-
backlink: str
-
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
-
backlink: str | None = None
-
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:
-
- 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
-
property backlink: str | None
-
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]