13. Node Interfaces (fleetmesh_node.interfaces)

The fleetmesh_node.interfaces module provides abstract base protocols and type contracts shared across the Meshnode codebase.

13.1. Interfaces Reference

Formal interfaces, protocols, and data contracts for meshnode.

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

class fleetmesh_node.interfaces.DeliveryEnvelope[source]

Bases: TypedDict

event: NostrEvent
path: list[DeliveryHop]
class fleetmesh_node.interfaces.DeliveryHop[source]

Bases: TypedDict

node: str
at: int
sig: str
class fleetmesh_node.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_node.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_node.interfaces.GrantScope[source]

Bases: TypedDict

push: NostrFilter
pull: NostrFilter
class fleetmesh_node.interfaces.NostrEvent[source]

Bases: TypedDict

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

Bases: TypedDict

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

Bases: TypedDict

ids: list[str]
authors: list[str]
kinds: list[int]
since: int
until: int
limit: int
search: str
class fleetmesh_node.interfaces.DIDCommAttachmentData[source]

Bases: TypedDict

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

Bases: TypedDict

id: str
mime_type: str
data: DIDCommAttachmentData
class fleetmesh_node.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_node.interfaces.RelayHealthRow[source]

Bases: TypedDict

connected: bool
confirmed: bool
since: int | None
reconnects: int
last_event_at: int | None
last_error: str | None
class fleetmesh_node.interfaces.AwaitingAckRow[source]

Bases: TypedDict

peer: str
type: str
at: int
relays: list[str]
heard_at: int | None
class fleetmesh_node.interfaces.ThrottledRow[source]

Bases: TypedDict

peer: str
shard: str
why: str
until: int
class fleetmesh_node.interfaces.ReceiptRefusedRow[source]

Bases: TypedDict

peer: str | None
window: int | None
named: str | None
acceptable: list[str]
at: int
class fleetmesh_node.interfaces.GrantStatusRow[source]

Bases: TypedDict

peer: str
direction: str
tier: str | None
status: str
class fleetmesh_node.interfaces.PendingGrantRow[source]

Bases: TypedDict

peer: str
tier: str | None
from_epoch: int
class fleetmesh_node.interfaces.EvaluationRow[source]

Bases: TypedDict

peer: str
epoch: int
severity: str | None
state: str
class fleetmesh_node.interfaces.RepricedRow[source]

Bases: TypedDict

peer: str
epoch: int
was: str
severity: str
remedy_cancelled: bool
class fleetmesh_node.interfaces.HealthStatusDict[source]

Bases: TypedDict

subsystem_trouble: list[str]
config_error: str | None
handler_failures: int
tick_failures: int
last_tick_error: str | None
rejected: Mapping[str, int]
relays: Mapping[str, RelayHealthRow]
sessions_refused: int
receipts_refused: list[ReceiptRefusedRow]
awaiting_ack: list[AwaitingAckRow]
throttled: list[ThrottledRow]
grants: list[GrantStatusRow]
evaluations: list[EvaluationRow]
repriced: list[RepricedRow]
subsystems: Mapping[str, Any]
class fleetmesh_node.interfaces.NodeStatusDict

Bases: TypedDict

at: int
did: str
node_did: str
pubkey: str
class: str
release: Mapping[str, Any]
face: str
relays: list[str]
descriptor: str
visibility: VisibilityState
events_stored: int
grants: list[GrantStatusRow]
pending_grants: list[PendingGrantRow]
evaluations: list[EvaluationRow]
repriced: list[RepricedRow]
reports_published: int
pending_findings: int
refused_sessions: int
last_tick: list[list[str]]
uptime: int | float
health: HealthStatusDict
compartments: Mapping[str, Any]
subsystems: Mapping[str, Any]
class fleetmesh_node.interfaces.CommandSpec[source]

Bases: TypedDict

One control-socket command as the socket documents it under commands: the dispatch table is the documentation, so it cannot drift from it.

args: Mapping[str, str]
does: str
reply: str
subsystem: str
class fleetmesh_node.interfaces.KeyStoreProtocol[source]

Bases: Protocol

The node keys and identity.

node_sk: str
node_pk: str
did: str
multikeys()[source]
Return type:

dict[str, str]

kid(which='agreement')[source]
Parameters:

which (str)

Return type:

str

save(directory)[source]
Parameters:

directory (Any)

Return type:

str

__init__(*args, **kwargs)
class fleetmesh_node.interfaces.TransportProtocol[source]

Bases: Protocol

The transport adapter interface: sends and receives DIDComm envelopes.

scheme: str
health: Mapping[str, Mapping[str, Any]]
drop_counts: Counter[str]
send(peer_pk, message, authenticated=True)[source]
Parameters:
Return type:

Any

request(peer_pk, message, timeout=None, authenticated=True)[source]
Parameters:
Return type:

DIDCommMessage | Mapping[str, Any] | None

close()[source]
Return type:

None

__init__(*args, **kwargs)
class fleetmesh_node.interfaces.EventStoreProtocol[source]

Bases: Protocol

Storage for Nostr events and provenance.

insert_event(event)[source]
Parameters:

event (NostrEvent)

Return type:

str

get_event(event_id)[source]
Parameters:

event_id (str)

Return type:

NostrEvent | None

has_event(event_id)[source]
Parameters:

event_id (str)

Return type:

bool

note_origin(event_id, origin)[source]
Parameters:
Return type:

None

origin_of(event_id)[source]
Parameters:

event_id (str)

Return type:

str | None

any_replicated(event_ids)[source]
Parameters:

event_ids (Sequence[str])

Return type:

bool

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

str

__init__(*args, **kwargs)
class fleetmesh_node.interfaces.CompartmentProtocol[source]

Bases: Protocol

A compartment of the node, assembled and ticked uniformly.

name: str | None
reads: tuple[str, ...]
live: tuple[str, ...]
commands: Mapping[str, CommandSpec]
start()[source]
Return type:

None

tick(now)[source]
Parameters:

now (int)

Return type:

list[tuple[Any, …]]

stop()[source]
Return type:

Any

state()[source]
Return type:

Mapping[str, Any]

trouble()[source]
Return type:

list[str]

notes()[source]
Return type:

list[str]

report()[source]
Return type:

Mapping[str, Any]

command(name, args)[source]
Parameters:
Return type:

Any

capability_protocols()[source]
Return type:

Sequence[str]

descriptor_tags()[source]
Return type:

Sequence[Sequence[str]]

__init__(*args, **kwargs)
class fleetmesh_node.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_node.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_node.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_node.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_node.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)