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.

exception fleetmesh_node.protocols.nostr.client.RelayError[source]

Bases: Exception

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]
Parameters:
Return type:

None

connect()[source]
Return type:

Relay

close()[source]
Return type:

None

publish(event)[source]

(accepted, message) for one event.

Parameters:

event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

tuple[bool, str]

query(filters, limit_time=None)[source]

Every stored event matching the filters, until EOSE.

Parameters:
Return type:

list[NostrEvent]

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.

Parameters:
Return type:

str

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.

Parameters:

sid (str)

Return type:

bool

all_confirmed()[source]

True once every open subscription on this connection has had its EOSE.

Return type:

bool

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.

Parameters:
Return type:

Iterator[NostrEvent]

unsubscribe(sid)[source]
Parameters:

sid (str)

Return type:

None

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.

Parameters:
Return type:

dict[str, tuple[bool, str]]

fleetmesh_node.protocols.nostr.client.query_all(urls, filters, timeout=15.0, auth_signer=None)[source]

Events from every relay, deduplicated by id.

Parameters:
Return type:

list[NostrEvent]

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.GossipTopicSummary[source]

Bases: TypedDict

topic: str
admin: str
members: int
mesh: int
expires: Any
roster_id: Any
class fleetmesh_node.protocols.nostr.relayserver.GossipViewReport[source]

Bases: TypedDict

enabled: bool
topics: list[GossipTopicSummary]
class fleetmesh_node.protocols.nostr.relayserver.RelayLimitation[source]

Bases: TypedDict

max_subscriptions: int
max_message_length: int
max_subid_length: int
max_limit: int
auth_required: bool
payment_required: bool
restricted_writes: bool
min_pow_difficulty: int
created_at_upper_limit: int
class fleetmesh_node.protocols.nostr.relayserver.NIP11RelayInformation[source]

Bases: TypedDict

name: str
software: str
version: str
supported_nips: list[int]
limitation: RelayLimitation
pubkey: str
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]
Parameters:
Return type:

None

store: Any
grants: Any | None
blob_store: Any | None
metrics_enabled: bool
metrics_provider: Callable[[], str] | None
node: Any | None
http_handlers: list[Callable[[socket, PlainHTTP], bool]]
blossom: Any | None
name: str
pubkey: str | None
clock: Callable[[], int]
require_auth: bool
admit: Callable[[str | None], bool] | None
restricted_read_kinds: frozenset[int]
future_seconds: int
host_router: Any | None
accepted: int
refused_future: int
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]

property server: Any
property host: str
property port: int
property url: str
start()[source]
Return type:

RelayServer

stop()[source]
Return type:

None

handle_http_request(conn, req)[source]

Handle an HTTP request. Returns True if handled, False if unhandled.

Parameters:
  • conn (socket)

  • req (PlainHTTP)

Return type:

bool

mount_ingress(host, owner='nostr')[source]

Mount Nostr relay WebSocket and HTTP endpoints onto ProtocolHostRouter.

Parameters:
Return type:

None

render_metrics()[source]

Render Prometheus / OpenMetrics exposition format.

Return type:

str

gossip_view()[source]
Return type:

GossipViewReport

nip11()[source]
Return type:

NIP11RelayInformation

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

MISS_TTL: int = 60
__init__(relay_urls=(), clock=None, timeout=15.0, resolver=None)[source]
Parameters:
Return type:

None

learn(desc)[source]

Accept a descriptor if it is genuine, validates and is newer than what we hold.

Parameters:

desc (NostrEvent)

Return type:

bool

descriptor(pubkey, refresh=False)[source]
Parameters:
Return type:

NostrEvent | None

agreement(pubkey)[source]
Parameters:

pubkey (str)

Return type:

X25519PublicKey | None

resolve_sender(skid)[source]

For didcomm.decrypt: the static agreement key a skid names, if the descriptor behind it is live. The kid must be the #agree fragment.

Parameters:

skid (str)

Return type:

X25519PublicKey | None

known()[source]
Return type:

list[str]

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.

Parameters:
Return type:

tuple[list[list[str]], str]

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)

  • endpoints (Sequence[tuple[str, str, int] | list[Any]])

  • operator_pubkey (Optional[str])

  • protocols (Sequence[str])

  • now (Optional[int])

  • capabilities (Sequence[str])

  • mediator (Optional[str])

  • policy (Optional[tuple[str, ...] | list[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:

NostrEvent

class fleetmesh_node.protocols.nostr.descriptor.ManifestEndpoint[source]

Bases: TypedDict

transport: str
address: str
ticket: str
priority: int
class fleetmesh_node.protocols.nostr.descriptor.ManifestOperator[source]

Bases: TypedDict

pubkey: str
policyUrl: str
class fleetmesh_node.protocols.nostr.descriptor.ManifestSpecDict

Bases: TypedDict

class: str
endpoints: list[ManifestEndpoint]
capabilities: list[str]
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:
Return type:

NostrEvent

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.

Parameters:
  • desc (Any)

  • pubkey (str | None)

Return type:

bool

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:
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.

Parameters:
Return type:

NostrEvent | 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:

Document

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.BridgeCursorRecord[source]

Bases: TypedDict

relay: str
last_reconciled_at: int
last_event_at: int
events_reconciled: int
class fleetmesh_node.protocols.nostr.eventstore.NodeStore[source]

Bases: BaseSqliteStore, SqliteStore

LOCAL: str = 'local'
MESH: str = 'mesh'
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))
__init__(path=':memory:', **kw)[source]
Parameters:
Return type:

None

origin_swept: int
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.

Parameters:
Return type:

Any

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.

Parameters:
Return type:

Any

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.

Parameters:
Return type:

list[NostrEvent]

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:

int

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.

Parameters:

event_id (str)

Return type:

bool

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.

Parameters:
Return type:

None

origin_of(event_id)[source]
Parameters:

event_id (str)

Return type:

str | None

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.

Parameters:

event_ids (Iterable[str])

Return type:

bool

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]
Parameters:
  • relay_url (str)

  • last_reconciled_at (int | None)

  • last_event_at (int | None)

  • count_increment (int)

Return type:

None

all_bridge_cursors()[source]
Return type:

list[BridgeCursorRecord]

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: TypedDict

Metadata descriptor for a stored or indexed blob.

sha256: str
size: int
type: str
uploaded: int
uploaded_by: str | None
cid: str
pinned: bool
accessed_at: int | None
class fleetmesh_node.protocols.nostr.blobstore.BlobMetadataStore[source]

Bases: BaseSqliteStore

Thread-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'))
meta_get(key)[source]
Parameters:

key (str)

Return type:

str | None

meta_set_if_absent(key, value)[source]

Record value under key unless one is already there; return the stored one.

Parameters:
Return type:

str

class fleetmesh_node.protocols.nostr.blobstore.BlobStore[source]

Bases: object

Content-Addressed Storage engine for SHA-256 blobs and artifacts.

__init__(directory, max_bytes=None, max_storage_bytes=None, fanout=1, data_dir=None)[source]

directory holds blobs.sqlite; blobs live under data_dir (default <directory>/data) at fanout two-hex-char levels.

fanout/data_dir exist 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.

Parameters:
  • directory (str)

  • max_bytes (int | None)

  • max_storage_bytes (int | None)

  • fanout (int)

  • data_dir (str | None)

Return type:

None

dir: str
data_dir: str
db_path: str
max_bytes: int | None
max_storage_bytes: int | None
fanout: int
db: BlobMetadataStore
put(data, content_type='application/octet-stream', uploaded_by=None, now=None)[source]

Store a blob by content hash. Returns normative descriptor.

Parameters:
  • data (bytes)

  • content_type (str)

  • uploaded_by (str | None)

  • now (int | None)

Return type:

BlobDescriptor

get(sha256_hex)[source]

Read full blob bytes, verifying SHA-256 integrity.

Parameters:

sha256_hex (str)

Return type:

bytes | None

has(sha256_hex)[source]

Check if blob exists on disk and is indexed.

Parameters:

sha256_hex (str)

Return type:

bool

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.

Parameters:

sha256_hex (str)

Return type:

bool

list_by(uploaded_by=None, limit=100, offset=0)[source]

List stored blobs matching uploader pubkey.

Parameters:
  • uploaded_by (str | None)

  • limit (int)

  • offset (int)

Return type:

list[BlobDescriptor]

total_bytes()[source]

Total size in bytes of all indexed blobs.

Return type:

int

count()[source]

Number of indexed blobs.

Return type:

int

pin(sha256_hex)[source]

Pin a blob to prevent LRU eviction.

Parameters:

sha256_hex (str)

Return type:

bool

unpin(sha256_hex)[source]

Unpin a blob, allowing LRU eviction.

Parameters:

sha256_hex (str)

Return type:

bool

is_pinned(sha256_hex)[source]

Check if blob is pinned against LRU eviction.

Parameters:

sha256_hex (str)

Return type:

bool

evict_lru(needed_bytes=0)[source]

Evict oldest unpinned blobs by accessed_at timestamp to free needed_bytes.

Returns total bytes freed.

Parameters:

needed_bytes (int)

Return type:

int

close()[source]

Safely close underlying metadata database.

Return type:

None

fleetmesh_node.protocols.nostr.blobstore.cid_to_sha256(cid_str)[source]

Extract SHA-256 hex digest from standard IPFS CIDv1 multibase ‘b’ string.

Parameters:

cid_str (str)

Return type:

str

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.

Parameters:

sha256_hex (str)

Return type:

str

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: TypedDict

Metadata returned by HEAD /<sha256> (BUD-02).

sha256: str
size: int
type: str
cid: str | None
class fleetmesh_node.protocols.nostr.blossom.BlossomUploadDescriptor[source]

Bases: TypedDict

Descriptor returned by PUT /upload (BUD-01).

url: str
sha256: str
size: int
type: str
uploaded: int
class fleetmesh_node.protocols.nostr.blossom.BlossomMirrorDescriptor[source]

Bases: TypedDict

Descriptor returned by PUT /mirror (BUD-04).

url: str
sha256: str
size: int
type: str
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.

Parameters:
  • signer_sk (str)

  • action (str)

  • sha256_hex (str)

  • now (int | None)

  • expiration_seconds (int)

  • content (str)

Return type:

NostrEvent

class fleetmesh_node.protocols.nostr.blossom.BlossomServer[source]

Bases: object

Blossom HTTP service provider (BUD-01 to BUD-04).

__init__(store, node_pk=None, operator_pk=None, require_auth=False, max_upload_bytes=67108864, clock=None, allow_private_mirror=False, pricing=None, admit=None)[source]
Parameters:
Return type:

None

store: BlobStore
pricing: Any | None
node_pk: str | None
operator_pk: str | None
require_auth: bool
admit: Callable[[str | None], bool] | None
max_upload_bytes: int
allow_private_mirror: Any
handle_request(conn, req)[source]

Route PlainHTTP request to appropriate Blossom handler.

Returns True if request was handled, False if not a Blossom path.

Parameters:
  • conn (socket)

  • req (PlainHTTP)

Return type:

bool

class fleetmesh_node.protocols.nostr.blossom.BlossomClient[source]

Bases: object

Standard-library HTTP client for Blossom servers.

DEFAULT_MAX_BYTES: int = 67108864
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_bytes caps the body (default DEFAULT_MAX_BYTES); a server that sends more raises netfetch.FetchTooLarge rather than filling memory.

Parameters:
  • server_url (str)

  • sha256_hex (str)

  • timeout (float)

  • max_bytes (int | None)

  • allow_private (Any)

Return type:

bytes

static head_blob(server_url, sha256_hex, timeout=5.0, *, allow_private=False)[source]

Query blob metadata via HEAD request.

Parameters:
  • server_url (str)

  • sha256_hex (str)

  • timeout (float)

  • allow_private (Any)

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).

Parameters:
Return type:

BlossomUploadDescriptor

static mirror_blob(server_url, source_url, sha256_hex, signer_sk=None, timeout=30.0, *, allow_private=False)[source]

Mirror remote blob to Blossom server (BUD-04).

Parameters:
  • server_url (str)

  • source_url (str)

  • sha256_hex (str)

  • signer_sk (str | None)

  • timeout (float)

  • allow_private (Any)

Return type:

BlossomMirrorDescriptor