# Parrhesia Nostr Relay Architecture

## 1) Goals

Build a **robust, high-performance Nostr relay** in Elixir/OTP with PostgreSQL as first adapter, while keeping a strict boundary so storage can be swapped later.

Primary targets:

- Broad relay feature support (core + modern relay-facing NIPs)
- Strong correctness around NIP-01 semantics
- Clear OTP supervision and failure isolation
- High fanout throughput and bounded resource usage
- Storage abstraction via behavior-driven ports/adapters
- Full test suite (unit, integration, conformance, perf, fault-injection)
- Support for experimental MLS flow (NIP-EE), behind feature flags

## 2) NIP support scope

### Mandatory baseline

- NIP-01 (includes behavior moved from NIP-12/NIP-16/NIP-20/NIP-33)
- NIP-11 (relay info document)

### Relay-facing features to include

- NIP-09 (deletion requests)
- NIP-13 (PoW gating)
- NIP-17 + NIP-44 + NIP-59 (private DMs / gift wraps)
- NIP-40 (expiration)
- NIP-42 (AUTH)
- NIP-43 (relay membership requests/metadata)
- NIP-45 (COUNT, optional HLL)
- NIP-50 (search)
- NIP-62 (request to vanish)
- NIP-66 (relay discovery events; store/serve as normal events)
- NIP-70 (protected events)
- NIP-77 (negentropy sync)
- NIP-86 + NIP-98 (relay management API auth)

### Experimental MLS

- NIP-EE (unrecommended/upstream-superseded, but requested):
  - kind `443` KeyPackage events
  - kind `445` group events (policy-controlled retention/ephemeral treatment)
  - kind `10051` keypackage relay lists
  - interop with wrapped delivery (`1059`) and auth/privacy policies

## 3) System architecture (high level)

```text
WS/HTTP Edge (Bandit/Plug)
  -> Protocol Decoder/Encoder
  -> Command Router (EVENT/REQ/CLOSE/AUTH/COUNT/NEG-*)
  -> Policy Pipeline (validation, auth, ACL, PoW, NIP-70)
  -> Event Service / Query Service
       -> Storage Port (behavior)
           -> Postgres Adapter (Ecto)
       -> Subscription Index (ETS)
       -> Fanout Dispatcher
  -> Telemetry + Metrics + Tracing
```

## 4) OTP supervision design

`Parrhesia.Application` children (top-level):

1. `Parrhesia.Telemetry` – metric definitions/reporters
2. `Parrhesia.Config` – runtime config cache (ETS-backed)
3. `Parrhesia.Storage.Supervisor` – adapter processes (`Repo`, pools)
4. `Parrhesia.Subscriptions.Supervisor` – subscription index + fanout workers
5. `Parrhesia.Auth.Supervisor` – AUTH challenge/session tracking
6. `Parrhesia.Policy.Supervisor` – rate limiters / ACL caches
7. `Parrhesia.Web.Endpoint` – WS + HTTP ingress
8. `Parrhesia.Tasks.Supervisor` – background jobs (expiry purge, maintenance)

Failure model:

- Connection failures are isolated per socket process.
- Storage outages degrade with explicit `OK/CLOSED` error prefixes (`error:`) per NIP-01.
- Non-critical workers are `:transient`; core infra is `:permanent`.

## 5) Core runtime components

### 5.1 Connection process

Per websocket connection:

- Parse frames, enforce max frame/message limits
- Maintain authenticated pubkeys (NIP-42)
- Track active subscriptions (`sub_id` scoped to connection)
- Handle backpressure (bounded outbound queue + drop/close strategy)

### 5.2 Command router

Dispatches:

- `EVENT` -> ingest pipeline
- `REQ` -> initial DB query + live subscription
- `CLOSE` -> unsubscribe
- `AUTH` -> challenge validation, session update
- `COUNT` -> aggregate path
- `NEG-OPEN`/`NEG-MSG`/`NEG-CLOSE` -> negentropy session engine

### 5.3 Event ingest pipeline

Ordered stages:

1. Decode + schema checks
2. `id` recomputation and signature verification
3. NIP semantic checks (timestamps, tag forms, size limits)
4. Policy checks (banlists, kind allowlists, auth-required, NIP-70, PoW)
5. Storage write (or no-store for ephemeral policy)
6. Live fanout to matching subscriptions
7. Return canonical `OK` response with machine prefix when needed

### 5.4 Subscription index + fanout

- ETS-backed inverted indices (`kind`, `author`, single-letter tags)
- Candidate narrowing before full filter evaluation
- OR semantics across filters, AND within filter
- `limit` only for initial query phase; ignored in live phase (NIP-01)

### 5.5 Query service

- Compiles NIP filters into adapter-neutral query AST
- Pushes AST to storage adapter
- Deterministic ordering (`created_at` desc, `id` lexical tie-break)
- Emits `EOSE` exactly once per subscription initial catch-up

## 6) Storage boundary (swap-friendly by design)

### 6.1 Port/adapter contract

Define behaviors under `Parrhesia.Storage`:

- `Parrhesia.Storage.Events`
  - `put_event/2`, `get_event/2`, `query/3`, `count/3`
  - `delete_by_request/2`, `vanish/2`, `purge_expired/1`
- `Parrhesia.Storage.Moderation`
  - pubkey/event bans, allowlists, blocked IPs
- `Parrhesia.Storage.Groups`
  - NIP-29/NIP-43 membership + role operations
- `Parrhesia.Storage.Admin`
  - backing for NIP-86 methods

All domain logic depends only on these behaviors.

### 6.2 Postgres adapter notes

Initial adapter: `Parrhesia.Storage.Adapters.Postgres` with Ecto.

Schema outline:

- `events` (id PK, pubkey, created_at, kind, content, sig, d_tag, deleted_at, expires_at)
- `event_tags` (event_id, name, value, idx)
- moderation tables (banned/allowed pubkeys, banned events, blocked IPs)
- relay/group membership tables
- optional count/HLL helper tables

Indexing strategy:

- `(kind, created_at DESC)`
- `(pubkey, created_at DESC)`
- `(created_at DESC)`
- `(name, value, created_at DESC)` on `event_tags`
- partial/unique indexes for replaceable and addressable semantics

Retention strategy:

- Optional table partitioning by time for hot pruning
- Periodic purge job for expired/deleted tombstoned rows

## 7) Feature-specific implementation notes

### 7.1 NIP-11

- Serve on WS URL with `Accept: application/nostr+json`
- Include accurate `supported_nips` and `limitation`

### 7.2 NIP-42 + NIP-70

- Connection-scoped challenge store
- Protected (`["-"]`) events rejected by default unless auth+pubkey match

### 7.3 NIP-17/59 privacy guardrails

- Relay can enforce recipient-only reads for kind `1059` (AUTH required)
- Query path validates requester access for wrapped DM fetches

### 7.4 NIP-45 COUNT

- Exact count baseline
- Optional approximate mode and HLL payloads for common queries

### 7.5 NIP-50 search

- Use Postgres FTS (`tsvector`) with ranking
- Apply `limit` after ranking

### 7.6 NIP-77 negentropy

- Track per-negentropy-session state in dedicated GenServer
- Use bounded resources + inactivity timeout

### 7.7 NIP-62 vanish

- Hard-delete all events by pubkey up to `created_at`
- Also delete matching gift wraps where feasible (`#p` target)
- Persist minimal audit record if needed for operations/legal trace

### 7.8 NIP-EE MLS (feature-flagged)

- Accept/store kind `443` KeyPackage events
- Process kind `445` under configurable retention policy (default short TTL)
- Ensure kind `10051` replaceable semantics
- Keep relay MLS-agnostic cryptographically (no MLS decryption in relay path)

## 8) Performance model

- Bounded mailbox and queue limits on connections
- ETS-heavy hot path (subscription match, auth/session cache)
- DB writes batched where safe; reads via prepared plans
- Avoid global locks; prefer partitioned workers and sharded ETS tables
- Telemetry-first tuning: p50/p95/p99 for ingest, query, fanout
- Expose Prometheus-compatible `/metrics` endpoint for scraping

Targets (initial):

- p95 EVENT ack < 50ms under nominal load
- p95 REQ initial response start < 120ms on indexed queries
- predictable degradation under overload via rate-limit + backpressure

## 9) Testing strategy (full suite)

1. **Unit tests**: parser, filter evaluator, policy predicates, NIP validators
2. **Property tests**: filter semantics, replaceable/addressable conflict resolution
3. **Adapter contract tests**: shared behavior tests run against Postgres adapter
4. **Integration tests**: websocket protocol flows (`EVENT/REQ/CLOSE/AUTH/COUNT/NEG-*`)
5. **NIP conformance tests**: machine-prefix responses, ordering, EOSE behavior
6. **MLS scenario tests**: keypackage/group-event acceptance and policy handling
7. **Performance tests**: soak + burst + large fanout profiles
8. **Fault-injection tests**: DB outage, slow query, connection churn, node restart

## 10) Implementation principles

- Keep relay event-kind agnostic by default; special-case only where NIPs require
- Prefer explicit feature flags for expensive/experimental modules
- No direct Ecto usage outside Postgres adapter and migration layer
- Every feature lands with tests + telemetry hooks

---

Implementation task breakdown is tracked in `./PROGRESS.md`.