event

event

Immutable Nostr event wrapper with database serialization.

Wraps nostr_sdk.Event in a frozen dataclass that transparently delegates attribute access to the underlying SDK object while adding database conversion via to_db_params() and from_db_params().

See Also

bigbrotr.models.event_relay: Junction model linking an Event to the Relay where it was observed. bigbrotr.services.synchronizer: The service that collects events from relays and persists them via this model.

Classes

EventDbParams

Bases: NamedTuple

Positional parameters for the event database insert procedure.

Produced by Event.to_db_params() and consumed by the event_insert stored procedure in PostgreSQL.

Attributes:

• id (bytes) –

  Event ID as 32-byte binary (SHA-256 of the serialized event).

• pubkey (bytes) –

  Author public key as 32-byte binary.

• created_at (int) –

  Unix timestamp of event creation.

• kind (int) –

  Integer event kind (e.g., 1 for text notes, 10002 for relay lists).

• tags (str) –

  JSON-encoded array of tag arrays.

• content (str) –

  Raw event content string.

• sig (bytes) –

  Schnorr signature as 64-byte binary.

See Also

Event: The model that produces these parameters. Event.from_db_params(): Reconstructs an Event from these parameters. EventRelayDbParams: Extends these fields with relay and junction data for cascade inserts.

Event dataclass

Event(_nostr_event: Event)

Immutable Nostr event with database conversion.

All attribute access is transparently delegated to the inner nostr_sdk.Event via __getattr__, so SDK methods like id(), kind(), and content() work directly.

Validation is performed eagerly at construction time:

• Content and tag values are checked for null bytes, which PostgreSQL TEXT columns reject.
• to_db_params() is called to ensure the event can be serialized before it leaves the constructor (fail-fast).

Parameters:

• _nostr_event (Event) –

  The underlying nostr_sdk.Event instance.

Raises:

• ValueError –

  If content or tags contain null bytes, or if database parameter conversion fails.

Examples:

from nostr_sdk import Event as NostrEvent

nostr_event = NostrEvent.from_json('{"id": "ab...", ...}')
event = Event(nostr_event)
event.id()         # Delegates to nostr_sdk.Event
event.content()    # Delegates to nostr_sdk.Event
params = event.to_db_params()
params.kind        # Integer event kind (e.g. 1)

Note

Binary fields (id, pubkey, sig) are stored as bytes in EventDbParams for direct insertion into PostgreSQL BYTEA columns. The hex-to-bytes conversion happens once during __post_init__ and is cached.

The __getattr__ delegation means this class does not define id, kind, content, etc. as attributes -- they are resolved at runtime from the wrapped nostr_sdk.Event.

See Also

EventDbParams: Database parameter container produced by to_db_params(). EventRelay: Junction linking this event to the Relay where it was observed. EventKind: Well-known Nostr event kinds used across services.

Functions

to_db_params

to_db_params() -> EventDbParams

Return cached positional parameters for the database insert procedure.

The result is computed once during construction and cached for the lifetime of the (frozen) instance, avoiding repeated hex conversions and tag serialization.

Returns:

• EventDbParams –

  EventDbParams with binary

• EventDbParams –

  id/pubkey/sig, integer timestamps, JSON-encoded tags, and raw

• EventDbParams –

  content string.

Source code in src/bigbrotr/models/event.py

def to_db_params(self) -> EventDbParams:
    """Return cached positional parameters for the database insert procedure.

    The result is computed once during construction and cached for the
    lifetime of the (frozen) instance, avoiding repeated hex conversions
    and tag serialization.

    Returns:
        [EventDbParams][bigbrotr.models.event.EventDbParams] with binary
        id/pubkey/sig, integer timestamps, JSON-encoded tags, and raw
        content string.
    """
    return self._db_params

from_db_params classmethod

from_db_params(params: EventDbParams) -> Event

Reconstruct an Event from database parameters.

Converts the stored binary/integer fields back into a JSON representation that nostr_sdk.Event.from_json() can parse.

Parameters:

• params (EventDbParams) –

  Database row values previously produced by to_db_params().

Returns:

• Event –

  A new Event wrapping the

• Event –

  reconstructed nostr_sdk.Event.

Note

The reconstructed event passes through __post_init__ validation again, including null-byte checks and DB parameter caching, ensuring consistency regardless of the data source.

Source code in src/bigbrotr/models/event.py

@classmethod
def from_db_params(cls, params: EventDbParams) -> Event:
    """Reconstruct an [Event][bigbrotr.models.event.Event] from database parameters.

    Converts the stored binary/integer fields back into a JSON
    representation that ``nostr_sdk.Event.from_json()`` can parse.

    Args:
        params: Database row values previously produced by
            [to_db_params()][bigbrotr.models.event.Event.to_db_params].

    Returns:
        A new [Event][bigbrotr.models.event.Event] wrapping the
        reconstructed ``nostr_sdk.Event``.

    Note:
        The reconstructed event passes through ``__post_init__`` validation
        again, including null-byte checks and DB parameter caching, ensuring
        consistency regardless of the data source.
    """
    tags = json.loads(params.tags)
    inner = NostrEvent.from_json(
        json.dumps(
            {
                "id": params.id.hex(),
                "pubkey": params.pubkey.hex(),
                "created_at": params.created_at,
                "kind": params.kind,
                "tags": tags,
                "content": params.content,
                "sig": params.sig.hex(),
            }
        )
    )
    return cls(inner)

Functions