7. Nostr Protocol Layer (fleetmesh_node.protocols.nostr)
The fleetmesh_node.protocols.nostr package (with compatibility facades under node.nostr)
encapsulates interaction with Nostr relays, local relay server hosting,
peer descriptor announcements, event persistence, and Blossom media storage.
7.1. Nostr Client
A nostr relay client: publish an event and wait for its OK, or query.
The only module in the node that speaks the relay wire (REQ/EVENT/OK/EOSE/ AUTH). Two kinds of caller: the relay rung (fleetmesh_node.transport.relay_rung), for gift wraps to and from peers, and the control-plane publishers (descriptor, presence, discovery, reports), for the node’s own signed events. Neither is the other’s business, so they share this and nothing else.
The node talks to relays for three things: to publish its own descriptor, grants and reports; to read other nodes’ descriptors; and, as its default transport, to send and receive gift wraps. Query collects until EOSE; a subscription yields events as they arrive and is how the transport listens.
- class fleetmesh_node.protocols.nostr.client.Relay[source]
Bases:
object- __init__(url, timeout=15.0, auth_signer=None, ping_after=60.0, dead_after=150.0, on_eose=None)[source]
- publish(event)[source]
(accepted, message) for one event.
- Parameters:
event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
- query(filters, limit_time=None)[source]
Every stored event matching the filters, until EOSE.
- Parameters:
- Return type:
- subscribe(filters, ready=False)[source]
Open a subscription; returns its id. Read with events().
ready waits for the relay’s EOSE before returning, which is the only way a caller can know the subscription is registered. Without it this sends REQ and returns, so a caller that subscribes and then causes an event races the server: an ephemeral kind fanned out before the REQ is processed reaches nobody, is never stored, and no timeout on events() can recover it. Stored events that arrive before the EOSE are kept and handed to events() rather than dropped on the floor.
- confirmed(sid)[source]
True if the relay answered this subscription’s REQ with an EOSE.
Only ever true for a subscribe(ready=True). A caller that waited and did not get one has a socket that is up and a subscription the relay has not owned up to, which is worth saying rather than assuming either way.
- all_confirmed()[source]
True once every open subscription on this connection has had its EOSE.
- Return type:
- events(sid, until=None)[source]
Yield events on one subscription, or several on this connection, until until (a time) or the socket closes.
Several, because a gating relay (strfry restrictedReadKinds) serves a filter that mixes a gated kind with an open one by silently dropping the gated events - no CLOSED, no AUTH, an EOSE as if nothing were missing. A caller that needs both kinds holds two subscriptions on one authenticated socket and reads them here as one stream.
- fleetmesh_node.protocols.nostr.client.publish_all(urls, event, timeout=15.0, auth_signer=None)[source]
{url: (accepted, message)}; one failed relay does not stop the others.
7.2. Embedded Relay Server
The relay face: a minimal NIP-01 relay over a MeshStore.
EVENT is verified, stored and fanned out to every live subscription that matches; REQ answers from the store and stays open; CLOSE ends it. Ephemeral kinds are fanned out and never stored, which is what lets kind 21059 gift wraps be a transport. NIP-11 answers on GET. This is the seed of the node’s relay face (step 5), and the fixture the identity and transport tests run against; NIP-77 frames come with the sync step.
- class fleetmesh_node.protocols.nostr.relayserver.GossipViewReport[source]
Bases:
TypedDict- topics: list[GossipTopicSummary]
- class fleetmesh_node.protocols.nostr.relayserver.NIP11RelayInformation[source]
Bases:
TypedDict- limitation: RelayLimitation
- class fleetmesh_node.protocols.nostr.relayserver.RelayServer[source]
Bases:
object- __init__(backend=None, host='127.0.0.1', port=0, name='meshnode', clock=None, pubkey=None, require_auth=False, restricted_read_kinds=(), admit=None, challenge=None, future_seconds=900, blob_store=None, metrics_enabled=True, metrics_provider=None, node=None, grants=None, host_router=None)[source]
- on_event_handlers: list[Callable[[NostrEvent], None]]
- add_event_handler(handler)[source]
Call handler with every event this face accepts; returns the call that removes it.
A handler that raises is skipped for that event, never the face.
- Parameters:
handler (Callable[[NostrEvent], None])
- Return type:
Callable[[], None]
- handle_http_request(conn, req)[source]
Handle an HTTP request. Returns True if handled, False if unhandled.
- mount_ingress(host, owner='nostr')[source]
Mount Nostr relay WebSocket and HTTP endpoints onto ProtocolHostRouter.
7.3. Peer Table
What this node knows about other nodes: their live descriptors.
A peer is addressed by its node pubkey. From its descriptor come the agreement key an envelope is encrypted to, the class, the protocols it implements and the endpoints. Descriptors are cached and refreshed from relays when missing or expired, and every one goes through fleetmesh_core.identity.validate_descriptor before it is believed.
- class fleetmesh_node.protocols.nostr.peers.Peers[source]
Bases:
object- learn(desc)[source]
Accept a descriptor if it is genuine, validates and is newer than what we hold.
- Parameters:
desc (NostrEvent)
- Return type:
- descriptor(pubkey, refresh=False)[source]
- Parameters:
- Return type:
NostrEvent | None
- fleetmesh_node.protocols.nostr.peers.agreement_key(desc)[source]
The X25519 public key a descriptor’s agreement Multikey names, or None.
- Parameters:
desc (NostrEvent)
- Return type:
X25519PublicKey | None
7.4. Peer Descriptor Parser
The kind 11801 a node publishes, and the DID document a resolver derives.
Built from the node’s keys and its MeshNode manifest: class, endpoints, operator, the protocols it implements as c tags, the plain capabilities as hints, expiry within the class maximum, and a NIP-13 nonce mined to the policy’s bits. Every descriptor is run through fleetmesh_core.identity.validate_descriptor before it leaves, so this node can never publish what it would decline.
- fleetmesh_node.protocols.nostr.descriptor.mine(pubkey, created_at, kind, tags, content, bits, max_tries=67108864)[source]
Find a NIP-13 nonce so the event id has at least bits leading zeros.
The nonce tag is [‘nonce’, ‘<n>’, ‘<target bits>’] and it is the last tag, so everything else about the event is fixed before mining starts.
- fleetmesh_node.protocols.nostr.descriptor.build(keystore, node_class, endpoints, operator_pubkey, protocols, now=None, capabilities=(), mediator=None, policy=None, coverage=None, nips=None, lifetime=None, bits=None, content='', fips_key=None, extra_tags=())[source]
A signed kind 11801.
endpoints: [(scheme, address, preference)]. protocols: the fleetmesh protocol identifiers this node implements; peering/1.0 and budget/1.0 are required of every class and are added if missing. policy: (sha256 hex, url). extra_tags: optional tags a subsystem contributes (mint, price), placed before operator so the fixed tail stays where readers expect it.
- Parameters:
keystore (Keystore)
node_class (str)
operator_pubkey (Optional[str])
protocols (Sequence[str])
now (Optional[int])
capabilities (Sequence[str])
mediator (Optional[str])
coverage (Optional[str])
nips (Optional[Sequence[int]])
lifetime (Optional[int])
bits (Optional[int])
content (str)
fips_key (Optional[str])
extra_tags (Sequence[Sequence[str]])
- Return type:
- class fleetmesh_node.protocols.nostr.descriptor.ManifestSpecDict
Bases:
TypedDict- endpoints: list[ManifestEndpoint]
- operator: ManifestOperator
- class fleetmesh_node.protocols.nostr.descriptor.MeshNodeManifest[source]
Bases:
TypedDict- spec: ManifestSpecDict
- fleetmesh_node.protocols.nostr.descriptor.from_manifest(keystore, manifest, now=None, bits=None)[source]
A descriptor from a MeshNode manifest (manifests/meshnode-*.yaml, parsed).
- Parameters:
keystore (Keystore)
manifest (MeshNodeManifest | Mapping[str, Any])
now (Optional[int])
bits (Optional[int])
- Return type:
- fleetmesh_node.protocols.nostr.descriptor.genuine(desc, pubkey=None)[source]
Signed by its own pubkey, and by the pubkey it was asked for.
A relay answers a query by author with whatever it chooses to serve under that name. Nothing verified the signature of a resolved descriptor, so a relay could hand a node a descriptor naming an agreement key of the relay’s choosing, and every envelope to that peer would then be encrypted to it. The rule for heartbeats already says it: believing an event unsigned lets a relay speak as any peer.
- fleetmesh_node.protocols.nostr.descriptor.newest(descriptors, now=None, digest='a3074ca76a554e27e85e63465bcab46b3063a0a9fe97f10d079e591b017b1fa5', pubkey=None)[source]
The live, genuine descriptor among candidates for one pubkey, or None.
- Parameters:
descriptors (Sequence[NostrEvent | UnsignedNostrEvent | Mapping[str, Any]])
now (int | None)
digest (str)
pubkey (str | None)
- Return type:
NostrEvent | None
- fleetmesh_node.protocols.nostr.descriptor.resolve(pubkey, relay_urls, now=None, timeout=15.0)[source]
The live kind 11801 for a pubkey from these relays, or None.
- fleetmesh_node.protocols.nostr.descriptor.did_document(desc)[source]
The node profile a did:nostr resolver emits for a kind 11801 (fleetmesh_core/did).
- Parameters:
desc (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])
- Return type:
7.5. Event Store
The node’s event store: the reference SqliteStore, safe to share across threads.
The relay face serves every connection on its own thread and the sync sessions run on others, all against one store. sqlite3 connections refuse use from a thread other than the one that opened them unless told otherwise, and even then two threads must not interleave statements. So: one connection opened for any thread, and one lock around every primitive the reference defines. The reference’s own semantics - what supersedes what, tombstones, ranges, fingerprints - are inherited untouched.
- class fleetmesh_node.protocols.nostr.eventstore.NodeStore[source]
Bases:
BaseSqliteStore,SqliteStore- SCHEMA: tuple[Any, ...] = (Table(name='events', columns=(Column(name='id', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='pubkey', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='created_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='kind', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='json', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='events_created_at', columns=('created_at', 'id'), table='events', unique=False), Index(name='events_author_kind', columns=('pubkey', 'kind'), table='events', unique=False), Index(name='events_kind_created_at', columns=('kind', 'created_at', 'id'), table='events', unique=False)), without_rowid=False), Table(name='tombstones', columns=(Column(name='key', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='deleter', type='TEXT', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('key', 'deleter'), indices=(), without_rowid=False), Table(name='origin', columns=(Column(name='id', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='origin', type='TEXT', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='tags', columns=(Column(name='id', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='name', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='value', type='TEXT', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('id', 'name', 'value'), indices=(Index(name='tags_name_value', columns=('name', 'value'), table='tags', unique=False),), without_rowid=True), Table(name='bridge_cursor', columns=(Column(name='relay', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='last_reconciled_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='last_event_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='events_reconciled', type='INTEGER', nullable=True, primary_key=False, default=0, unique=False)), primary_key=(), indices=(), without_rowid=False))
- newest_matching(*a, **k)
The bounded answer, read newest first and stopped at cap.
The inherited version narrows in SQL and then holds every match as a parsed event so it can be sorted. That is the whole store on an open face - which is how a 1 GB box serving 8,923 events died on a REQ for the newest twenty. Here sqlite does the ordering on the index the events table already has, and rows are parsed one at a time until enough of them have matched.
- insert_event(*a, **k)
Returns one of: stored, duplicate, ephemeral, expired, superseded, deleted, or a deletion outcome. now is explicit rather than read from the clock so that two backends fed the same history agree exactly.
All or nothing, through _atomic: every write one insertion makes lands together or not at all.
- by_kind_before(kind, cutoff, cap=None, after=None)[source]
Events of one kind dated before a cutoff, oldest first, one page.
For retention, which is the only caller. The index is on (created_at, id), so this reads a range rather than the table.
cap and after are what keep the sweep from being the thing that kills the node: a policy set for the first time on a face holding days of gift wraps has every one of them past the cutoff at once, and this used to answer with all of them parsed. after is the (created_at, id) of the last row of the previous page, and the cursor rather than an offset because the sweep is deleting as it walks - and because an event held back inside a claimed shard stays, so a page that re-read what it had refused would never end.
- count()[source]
How many events this node holds, as one number from the index.
Written into status.json on every tick, and until this existed it was len(self._all()): the whole store parsed into dicts to be thrown away, so the node’s peak heap was the size of its store and the allocator kept it. On the public face that was 600 MB of a 1 GB box for a number that a COUNT answers without reading a row.
- Return type:
- forget(event_id)[source]
Drop one event because this node stopped keeping it. NOT a deletion.
A NIP-09 kind 5 tombstones an id so a later re-offer cannot resurrect it, because there the author said the thing should not exist. Retention says only that THIS node stopped holding it, which is a fact about a disk and not about the event: a peer may hand it back tomorrow and be right to. So the row goes and no tombstone is written.
- note_origin(event_id, origin)[source]
Record how one event reached this node. First writer wins: an event this node already held locally is not reclassified because a peer later sent it too.
- any_replicated(event_ids)[source]
True if any of these arrived through the mesh, or is of unknown origin.
Unknown counts as replicated. A claim of completeness is a falsifiable assertion about data this node stands behind, and an event it cannot account for the arrival of is not data it can stand behind.
- get_bridge_cursor(relay_url)[source]
- Parameters:
relay_url (str)
- Return type:
BridgeCursorRecord | None
- set_bridge_cursor(relay_url, last_reconciled_at=None, last_event_at=None, count_increment=0)[source]
7.6. Blob Store & Blossom Integration
Content-Addressed Storage (CAS) for blobs and IPFS CIDv1 interoperability.
Spec reference: spec.html section “Content Addressing & CIDs” (lines 3470-3476) and “Blobs” (lines 3768-3776). - Blossom blobs are SHA-256 addressed. - Maps directly to IPFS Content Identifiers (CIDs):
multibase ‘b’ (RFC 4648 Base32 lowercase), CIDv1 (0x01), raw binary codec (0x55), multihash sha2-256 (0x12, 0x20).
Standard CAS on-disk sharded directory layout: blobs/data/<sha256[:2]>/<sha256> (fanout depth 1). The depth is configurable (0..8 two-hex-char levels) so an operator may point the store at a tree another CAS already lays out the same way (magpie: <data>/objects/<ab>/<cd>/<sha>, depth 2) - see docs/sidecars.md. The depth a directory was created with is recorded in blobs.sqlite and a store opened with a different depth refuses rather than silently 404 every blob.
SQLite metadata index in blobs.sqlite tracking size, content-type, uploader attribution, and upload timestamps.
- class fleetmesh_node.protocols.nostr.blobstore.BlobDescriptor[source]
Bases:
TypedDictMetadata descriptor for a stored or indexed blob.
- class fleetmesh_node.protocols.nostr.blobstore.BlobMetadataStore[source]
Bases:
BaseSqliteStoreThread-safe SQLite metadata index for Content-Addressed Storage.
- SCHEMA: tuple[Any, ...] = (Table(name='blobs', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='size', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='type', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='uploaded_by', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='created_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='accessed_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='pinned', type='INTEGER', nullable=True, primary_key=False, default=0, unique=False)), primary_key=(), indices=(Index(name='idx_blobs_uploaded', columns=('uploaded_by',), table='blobs', unique=False),), without_rowid=False), Table(name='meta', columns=(Column(name='key', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='value', type='TEXT', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False))
- MIGRATIONS: tuple[Migration | tuple[int, str], ...] = (Migration(version=1, up=('ALTER TABLE blobs ADD COLUMN accessed_at INTEGER',), down=None, name='blobs_accessed_at'), Migration(version=2, up=('ALTER TABLE blobs ADD COLUMN pinned INTEGER DEFAULT 0',), down=None, name='blobs_pinned'), Migration(version=3, up=('CREATE INDEX IF NOT EXISTS idx_blobs_lru ON blobs(pinned, accessed_at)',), down=None, name='idx_blobs_lru'))
- class fleetmesh_node.protocols.nostr.blobstore.BlobStore[source]
Bases:
objectContent-Addressed Storage engine for SHA-256 blobs and artifacts.
- __init__(directory, max_bytes=None, max_storage_bytes=None, fanout=1, data_dir=None)[source]
directoryholdsblobs.sqlite; blobs live underdata_dir(default<directory>/data) atfanouttwo-hex-char levels.fanout/data_direxist so a node may share a tree with another CAS that uses the same sha256 layout. Shared disk is not a shared catalogue - each index knows only what it wrote - and the other writer’s file modes/ownership must let this process read and unlink.
- put(data, content_type='application/octet-stream', uploaded_by=None, now=None)[source]
Store a blob by content hash. Returns normative descriptor.
- Parameters:
- Return type:
- stat(sha256_hex)[source]
Retrieve metadata descriptor without loading blob content.
- Parameters:
sha256_hex (str)
- Return type:
BlobDescriptor | None
- delete(sha256_hex)[source]
Delete blob from disk and metadata index.
The digest is validated before it touches the filesystem: get/has already refuse anything but 64 hex chars, and delete is the one path here that unlinks, so ‘../..’ must never reach _blob_path.
- list_by(uploaded_by=None, limit=100, offset=0)[source]
List stored blobs matching uploader pubkey.
- Parameters:
- Return type:
- fleetmesh_node.protocols.nostr.blobstore.cid_to_sha256(cid_str)[source]
Extract SHA-256 hex digest from standard IPFS CIDv1 multibase ‘b’ string.
- fleetmesh_node.protocols.nostr.blobstore.sha256_to_cid(sha256_hex)[source]
Map SHA-256 hex digest to standard IPFS CIDv1 multibase ‘b’ (raw sha2-256).
CIDv1 format: - 0x01: CIDv1 - 0x55: raw codec (varint 0x55) - 0x12: sha2-256 multihash function - 0x20: 32 bytes digest length - raw 32-byte SHA-256 digest Encoded in lowercase RFC 4648 Base32 with ‘b’ multibase prefix. Produces canonical ‘bafkrei…’ prefix.
7.7. Blossom Protocol Handlers
Blossom Media Protocol (BUD-01..BUD-04) server and client implementation.
Spec reference: spec.html section “Content Addressing & CIDs” and “Blobs” (lines 3768-3776). Provides HTTP endpoints on the node relay face: - GET /<sha256>[.<ext>]: Download blob with SHA-256 integrity verification. - HEAD /<sha256>[.<ext>]: Check blob presence and size (BUD-02). - GET /cid/<cid>: Download blob by standard IPFS CIDv1 (raw-sha2-256). - HEAD /cid/<cid>: Check blob by CIDv1. - PUT /upload: Upload blob with BUD-01 Nostr Kind 24242 authorization. - PUT /mirror: Mirror blob from remote HTTP source with BUD-04 hash verification. - GET /list/<pubkey>: List blobs uploaded by a pubkey. - DELETE /<sha256>: Delete blob (requires uploader authorization).
- class fleetmesh_node.protocols.nostr.blossom.BlossomBlobMetadata[source]
Bases:
TypedDictMetadata returned by HEAD /<sha256> (BUD-02).
- class fleetmesh_node.protocols.nostr.blossom.BlossomUploadDescriptor[source]
Bases:
TypedDictDescriptor returned by PUT /upload (BUD-01).
- class fleetmesh_node.protocols.nostr.blossom.BlossomMirrorDescriptor[source]
Bases:
TypedDictDescriptor returned by PUT /mirror (BUD-04).
- fleetmesh_node.protocols.nostr.blossom.create_auth_event(signer_sk, action, sha256_hex, now=None, expiration_seconds=300, content='')[source]
A signed BUD-01/BUD-04 authorization (kind 24242); the bytes are fleetmesh_core/blossom_auth.py’s.
- class fleetmesh_node.protocols.nostr.blossom.BlossomServer[source]
Bases:
objectBlossom HTTP service provider (BUD-01 to BUD-04).
- class fleetmesh_node.protocols.nostr.blossom.BlossomClient[source]
Bases:
objectStandard-library HTTP client for Blossom servers.
- static get_blob(server_url, sha256_hex, timeout=10.0, *, max_bytes=None, allow_private=False)[source]
Download and verify blob from Blossom server.
max_bytescaps the body (default DEFAULT_MAX_BYTES); a server that sends more raises netfetch.FetchTooLarge rather than filling memory.
- static head_blob(server_url, sha256_hex, timeout=5.0, *, allow_private=False)[source]
Query blob metadata via HEAD request.
- Parameters:
- Return type:
BlossomBlobMetadata | None
- static upload_blob(server_url, data, content_type='application/octet-stream', signer_sk=None, timeout=30.0, *, allow_private=False)[source]
Upload blob to Blossom server (BUD-01).