BigBrotr | Blog

Dead Keys: The Unsolved Problem of Marking Compromised Nostr Identities

Fri, 20 Mar 2026 00:00:00 GMT

Once a Nostr private key leaks, how do you mark the identity as dead?

Not temporarily. Not probabilistically. Permanently — in a way the attacker cannot undo, and that every client on the network can verify.

We went through every mechanism currently available in the protocol. None of them solve it. Here is why — and what could actually work.

This article is about remediation — what to do after a key has already leaked. Prevention is a separate problem with a good existing answer: NIP-46 (Nostr Connect) lets users delegate signing to a remote bunker without ever exposing the raw nsec. If your key has not been compromised, adopt NIP-46. But for accounts already operating on a leaked key — like the 38 we identified in our nsec exposure analysis — prevention has already failed. The question is what happens now.

The Constraint Nobody Can Work Around

Before examining specific solutions, there is one principle that rules out most approaches immediately.

Any event signed by key A can be replaced or repudiated by key A.

This is not a flaw. It is intentional. Your key is your identity and you have sovereign control over your own event stream. The moment an attacker holds your nsec, they inherit that sovereignty. They can publish, delete, and replace anything in your name with equal authority.

Any warning broadcast using the compromised key can be overwritten with the same key. A kind:0 profile update announcing compromise can be replaced by a newer kind:0 without the flag. A warning note can be targeted by a kind:5 deletion request. It does not matter that NIP-09 says relays SHOULD honor deletions rather than MUST — even if some relays ignore the deletion, the attacker can always publish a newer replaceable event that supersedes the warning. The result is a network where some clients see the warning and others do not. You cannot build a trust mechanism on a signal that is visible to some users sometimes.

The tombstone cannot live in the event stream of the compromised key.

Everything else follows from this.

Why Every Obvious Solution Fails

Self-reporting with the leaked key

The intuitive first move: publish a note or update your profile announcing the key is compromised. But in the cases that matter most — like the keys in our dataset, published in plaintext on Nostr — the attacker typically has the nsec before the owner even knows it leaked. There is no race condition to win. The attacker is already watching.

Even in the best case, where the owner discovers the leak first and broadcasts a warning to hundreds of relays simultaneously, the attacker can overwrite the kind:0 profile with a clean version moments later. The warning becomes inconsistent across the network — present on some relays, gone on others. A security mechanism that depends on who queries which relay first is not a mechanism. It is a bet.

Kind 5 against kind 5

NIP-09 is explicit: publishing a deletion request against another deletion request has no effect. You cannot make an event undeletable by chaining deletion mechanics. The model does not support it.

A compromise tag on kind 0

kind:0 is a replaceable event. Clients always adopt the most recent version. An attacker publishes a new kind:0 without the compromise tag — it becomes the canonical profile. The flag is gone.

NIP-56 Reporting (kind 1984)

A kind:1984 report is an external declaration from a third party. It carries a report type — including impersonation — but no proof that the reporter actually holds the private key. Anyone can report anyone. It is a claim, not a demonstration. The signal-to-noise ratio makes it useless as a trust mechanism for this specific use case.

NIP-32 Labeling (kind 1985)

More flexible than NIP-56, but the same fundamental weakness: arbitrary labels from arbitrary keys with no embedded proof of nsec possession. A compromised label means nothing if anyone can attach it to anyone.

NIP-58 Badges (kind 8)

Badge awards are non-transferable by spec — which sounds promising. But the fundamental problem is the same as NIP-56 and NIP-32: anyone can define a compromised badge and award it to any account without proving they hold the private key. It is still just a claim. The issuer can also delete their own kind:8 with a kind:5 at any time, so the award is not even reliably persistent. No proof of key possession, no guarantee of permanence — NIP-58 does not help here.

NIP-62 Request to Vanish (kind 62)

This NIP actually worsens the threat model. An attacker holding the nsec can issue a kind:62 requesting all relays to permanently delete every event from that pubkey — including received DMs. The entire account history is erased before the victim knows anything happened.

What the Solutions Have in Common

Every failed approach shares one of two flaws:

The warning lives on the compromised key’s event stream — repudiable by the attacker.
The warning is a claim with no cryptographic proof — gameable by anyone.

A real solution requires both properties simultaneously: signed by an external key (so the attacker cannot touch it) and containing proof of nsec possession (so it cannot be faked).

What Could Actually Work

NIP-85 (kind 30382) + embedded `proof` tag

NIP-85 defines Trusted Assertions — addressable events published by external service keys that attest facts about other pubkeys. The infrastructure is already there. What is missing is a mechanism to attach a cryptographic proof of key possession.

The proposal is a minimal extension to kind:30382:

{
  "kind": 30382,
  "pubkey": "<discoverer key B>",
  "tags": [
    ["d", "<compromised pubkey A>"],
    ["rank", "0"],
    ["compromised", "true"],
    ["proof", "<sig of key A over canonical message>"]
  ],
  "content": ""
}

The proof tag contains a valid Schnorr signature produced with the leaked key over a canonical message defined independently of the attestation event itself — for example, the fixed string "compromised:<pubkey A>". Using the event’s own id would create a circular dependency: the id is a hash of the full serialized event including the proof tag, so it cannot exist before the signature, and the signature cannot be produced without it. A pre-defined canonical message breaks the cycle and keeps verification straightforward. Anyone who encounters this event can perform two independent verifications:

The outer event signature is valid → key B authored this.
The proof field is a valid signature of key A → whoever wrote this possessed the nsec.

The attacker controls key A but not key B. They cannot delete or modify this event. Clients that implement NIP-85 can zero out the WoT score and display a permanent warning banner on the profile — regardless of what the compromised key subsequently publishes or deletes.

Why false flags are not a real risk

A reasonable concern: what stops a malicious actor from falsely flagging an account as compromised?

The proof tag makes this impossible. To produce a valid proof, you must hold the nsec of the target key. If you have the nsec, the account is compromised — by definition, regardless of how you obtained it. In Nostr, your key is your identity. Not your keys, not your account. If a custodial service or a signer app holds the nsec, the account was never fully sovereign to begin with — and reporting it is the least harmful thing anyone could do with that key.

Key B is also permanently linked to the attestation. A false flag would be a public, on-chain declaration that you hold someone’s private key. The reputational cost is significant. The incentive structure self-selects for honest reporting.

The discovery problem

For this mechanism to work, clients need a way to find compromise attestations. When loading a profile, a client must answer: “does a verified compromise attestation exist for this pubkey?”

NIP-85 events are addressable by their d tag, which in this proposal is the compromised pubkey. A client can query any relay for kind:30382 events with a matching d tag. But which relays? And whose attestations should it trust?

The practical path is the same one NIP-85 already assumes: clients maintain a list of trusted attestation services — similar to how browsers ship with a list of trusted certificate authorities. A client might trust attestations from BigBrotr, from a well-known WoT scoring service, or from keys in the user’s own follow graph. These services earn trust over time through consistent, verifiable reporting. The trust model is explicit, not implicit.

This is a centralization pressure point. A future extension could define a relay-level index — a dedicated kind that aggregates verified compromise attestations across multiple attestors — but that is beyond the scope of this proposal. For now, the CA-like model is the realistic starting point, and the proof tag ensures that even a centralized attestor cannot fabricate compromise claims — they still need the nsec.

What Needs to Happen Next

This is a proposal, not a standard. For it to become useful, three things need to happen.

Protocol. The proof tag and compromised field need to be formally specified — either as an extension to NIP-85 or as a new NIP — with a defined canonical message format for the embedded signature.

Clients. At least two clients need to implement verification and rendering of the warning banner for the proposal to meet NIP acceptance criteria. Until a client implements this check, its users remain exposed to compromised keys with no warning. Implementing this is not optional overhead — it is a duty of care toward the people who use the client.

Relays. Relays should index kind:30382 events by their d tag (already required by NIP-85) so that clients can efficiently query “does a verified compromise attestation exist for pubkey X?” at profile load time.

The 38 accounts in our dataset — and the dozens more that will surface as relay archives grow — deserve a protocol that can tell their followers the truth. Right now, there is no way to do that.

There should be.

Self-Hosting BigBrotr: From Bare Metal to Production in One Afternoon

Wed, 18 Mar 2026 00:00:00 GMT

Running a Nostr relay observatory means storing a lot of data. Events, metadata, health checks, materialized views — the database grows by gigabytes per day once all eight services are humming. Cloud hosting works, but the storage costs add up fast, and you’re always one terraform destroy away from losing your dataset.

Self-hosting solves that. A dedicated machine with a few terabytes of SSD storage, a properly tuned PostgreSQL, and a Cloudflare Tunnel for secure API exposure gives you everything a cloud deployment would — minus the recurring bill.

This post walks through the entire deployment: from a fresh Proxmox install to a fully operational BigBrotr instance serving api.yourdomain.com over HTTPS with zero inbound ports. It’s the same process we used for our own production deployment.

The full step-by-step guide with every command is available at Self-Hosting Guide.

The Hardware

You don’t need anything exotic. A used server or a mini PC with enough RAM and a few SSDs is plenty. Here’s the minimum and what we actually used:

Component	Minimum	Our Setup
CPU	8 cores	16 cores / 32 threads
RAM	32 GB	96 GB
Boot	1x SSD (any size)	2x NVMe 1TB (ZFS mirror)
Database	2x SSD, 1TB+ (mirror)	4x 4TB SATA SSD (ZFS RAID10)
Backups	Any spare disk	2x 4TB SATA SSD (ZFS stripe)

The CPU isn’t the bottleneck — PostgreSQL and the services are mostly I/O-bound. RAM matters a lot (it’s PostgreSQL’s buffer cache), and SSD IOPS matter for write-heavy workloads like event archiving.

Why ZFS?

Every disk in the system runs ZFS. It solves specific problems for a database workload that other filesystems don’t:

Data integrity. ZFS checksums every block. A silent bit flip on a SATA disk doesn’t corrupt your relay table — ZFS detects it and repairs from the mirror.

Compression. LZ4 compression is practically free on modern CPUs and PostgreSQL data compresses well (~1.5-2x). That 4TB disk effectively holds 6-8TB of database pages.

Tunable record size. PostgreSQL uses 8KB pages. We set recordsize=8K on the database pool, so every ZFS block maps exactly to one PostgreSQL page. No read-modify-write amplification, no wasted space.

Metadata-only caching. PostgreSQL manages its own buffer cache via shared_buffers. Having ZFS also cache the same data in ARC wastes RAM. Setting primarycache=metadata tells ZFS to only cache filesystem metadata, leaving the actual data caching to PostgreSQL where it belongs.

The database pool is RAID10 (two mirrored pairs striped) — fast reads, fast writes, survives a disk failure in each pair. The backup pool is a stripe (no redundancy) because dump files are reproducible.

The VM Architecture

BigBrotr runs in a single Proxmox VM with three virtual disks, each backed by a different ZFS pool:

┌──────────────────────────────────────────────────┐
│              Proxmox Host (NVMe)                 │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │         VM "bigbrotr" (Debian 13)          │  │
│  │                                            │  │
│  │  scsi0  →  NVMe pool  →  OS (50 GiB)       │  │
│  │  scsi1  →  datapool   →  /mnt/pgdata       │  │
│  │  scsi2  →  workpool   →  /mnt/work         │  │
│  │                                            │  │
│  │  Docker Compose (15 containers)            │  │
│  │  cloudflared (Cloudflare Tunnel)           │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

The OS disk lives on fast NVMe (for Docker image pulls, container startups, and general OS operations). The database data directory is symlinked to /mnt/pgdata, which is an XFS filesystem on a dedicated virtual disk backed by the RAID10 pool. The work disk holds dump files and research exports.

Why a VM instead of bare metal? Proxmox lets you snapshot the entire VM before risky operations, easily resize disks, and run additional VMs (like a research environment) on the same hardware. The overhead of KVM virtualization with VirtIO paravirtualized devices is negligible for this workload.

Why XFS inside the VM? The virtual disk already sits on ZFS (which handles checksumming, compression, and mirroring). Inside the VM, XFS adds journal tuning options (logbufs=8,logbsize=256k) that improve PostgreSQL write throughput. It’s one of the few filesystems that performs well under sustained sequential writes from WAL and checkpoint I/O.

PostgreSQL Tuning — It’s Mostly About RAM

The shipped postgresql.conf is tuned for a small 4GB development environment. For production, the most impactful changes are memory-related:

# 64GB RAM example
shared_buffers = 16GB          # 25% of RAM
effective_cache_size = 48GB    # 75% of RAM (includes OS page cache)
work_mem = 64MB                # per-sort/hash, generous for analytics
maintenance_work_mem = 2GB     # fast VACUUM and CREATE INDEX

Setting shared_buffers to 25% of RAM is the standard starting point — going higher rarely helps because the OS page cache handles the rest, and effective_cache_size tells the query planner how much total cache (PostgreSQL + OS) is available. Scale to your hardware:

RAM	shared_buffers	effective_cache_size	work_mem	maintenance_work_mem
32 GB	8 GB	24 GB	32 MB	1 GB
64 GB	16 GB	48 GB	64 MB	2 GB
96 GB	24 GB	72 GB	128 MB	4 GB
128 GB	32 GB	96 GB	128 MB	4 GB

For a write-heavy workload like BigBrotr (the Synchronizer can insert thousands of events per cycle), these settings matter:

synchronous_commit = off       # async commits, ~10ms data risk
checkpoint_timeout = 15min     # less frequent checkpoints
max_wal_size = 8GB             # more WAL before forced checkpoint

synchronous_commit = off is the single biggest performance lever. It means PostgreSQL acknowledges commits before the WAL is flushed to disk. You could lose up to ~10ms of recent transactions in a crash. For Nostr event archiving, this is perfectly acceptable — events can be re-fetched from relays.

The autovacuum settings are also aggressive because BigBrotr tables see constant inserts and updates:

autovacuum_naptime = 30s
autovacuum_vacuum_scale_factor = 0.05
autovacuum_vacuum_cost_delay = 2ms
autovacuum_vacuum_cost_limit = 2000

This tells PostgreSQL: check for dead tuples every 30 seconds, vacuum after just 5% of rows are dead, and don’t throttle vacuum I/O. On a dedicated server, there’s no reason to hold back.

Zero-Port API Exposure with Cloudflare Tunnel

The traditional way to expose a web service is: open a port, get a certificate, configure a reverse proxy. Each step is a potential attack surface.

Cloudflare Tunnel flips this. Instead of opening inbound ports, a daemon (cloudflared) inside the VM creates an outbound HTTPS connection to Cloudflare’s edge network. Cloudflare then routes incoming requests for api.yourdomain.com through this tunnel to your local API.

User  ──HTTPS──▶  Cloudflare Edge  ──encrypted tunnel──▶  cloudflared  ──HTTP──▶  localhost:8080
                  (TLS, WAF, DDoS)                        (inside VM)              (FastAPI)

The result:

Zero open inbound ports on the server
Free TLS certificates managed by Cloudflare
DDoS protection on the free tier
No firewall rules to maintain for the API

The last hop — cloudflared to localhost:8080 — is plain HTTP, which is fine because it never leaves the VM. Setting HTTPS here would just add unnecessary TLS overhead for a loopback connection.

Setup is three steps: add your domain to Cloudflare, create a tunnel in the Zero Trust dashboard, install cloudflared with the provided token. Five minutes, and your API is live on https://api.yourdomain.com.

Security Layers

Defense in depth, not a single point of trust:

Cloudflare Tunnel — No inbound ports, DDoS protection, WAF
UFW Firewall — Default deny incoming, allow only SSH (custom port) and local-network services
SSH hardening — Key-only authentication, non-standard port, fail2ban (24-hour ban after 3 failures)
PostgreSQL roles — Four database roles with least-privilege access (admin, writer, reader, refresher)
PGBouncer — Connection pooling with SCRAM-SHA-256 authentication
Docker isolation — All services run as non-root users inside containers

The firewall allows PostgreSQL, Grafana, and Prometheus only from the local subnet — for research queries and monitoring. Everything else is denied.

The Production Deployment Folder

One lesson from deploying: keep your production configuration completely separate from the repository. You don’t even need git on the server. BigBrotr ships deployment templates in each release — you download just the deployment folder and run it standalone:

cd /opt
VARIANT=bigbrotr  # or lilbrotr
RELEASE=$(curl -s https://api.github.com/repos/BigBrotr/bigbrotr/releases/latest | grep tarball_url | cut -d '"' -f 4)
curl -sL "$RELEASE" | tar xz
mv BigBrotr-bigbrotr-*/deployments/$VARIANT "${VARIANT}-production"
rm -rf BigBrotr-bigbrotr-*

This gives you a standalone folder at /opt/bigbrotr-production/ with everything: Docker Compose config, PostgreSQL tuning, PGBouncer settings, monitoring stack, SQL init scripts, and backup script. No repository checkout needed.

Then swap the build: blocks in docker-compose.yaml for pre-built Docker Hub images:

# Replace every build: block with:
    image: vincenzoimp/bigbrotr:6    # or vincenzoimp/lilbrotr:6

The :6 tag always points to the latest 6.x.x release. Updating becomes a single command:

cd /opt/bigbrotr-production
docker compose pull && docker compose up -d

No git, no builds, no merge conflicts. Your local configuration (.env, postgresql.conf, port bindings) is never touched by updates.

If you don’t need full event storage (tags, content, signatures), LilBrotr is a lightweight alternative that uses the same codebase but stores only event metadata — roughly 60% less disk usage. Same deployment process, just swap bigbrotr for lilbrotr in the variant and image name. Both can even run on the same hardware with isolated databases.

What It Looks Like Running

After starting all services with docker compose up -d, you get 15 containers (14 running at steady state — the Seeder exits after its one-shot run):

PostgreSQL 16 — the shared database, tuned for your hardware
PGBouncer — connection pooling in transaction mode
Tor — SOCKS5 proxy for .onion relay monitoring
8 BigBrotr services — seeder, finder, validator, monitor, synchronizer, refresher, api, dvm
Prometheus + Alertmanager + Grafana — full observability stack
postgres-exporter — database metrics

The Seeder runs once and inserts ~7,500 known relay URLs as candidates. The Validator starts checking them via WebSocket — clearnet relays at 50 concurrent connections, Tor relays at 10 (through the SOCKS5 proxy). Within 30 minutes, validated relays start appearing in the database. The Monitor begins health-checking them, the Synchronizer starts archiving events, and the Refresher keeps the materialized views up to date.

The API is reachable at https://api.yourdomain.com/health — no port forwarding, no NGINX config, no Let’s Encrypt renewal scripts.

Lessons From the First Boot

No deployment survives first contact without surprises. Here’s what bit us on the actual production bring-up.

The vanishing DNS resolver. We configured a static IP in /etc/network/interfaces and everything worked — until the first reboot. Turns out, when you switch from DHCP to static, nothing populates /etc/resolv.conf anymore. It was empty after boot. Cloudflared couldn’t resolve its SRV records and crashed in a restart loop, apt couldn’t reach any repository, and the services that needed to reach external APIs quietly failed. The fix is dead simple: write your nameservers manually and lock the file with chattr +i /etc/resolv.conf so nothing overwrites it.

Docker’s 64MB shared memory trap. We tuned PostgreSQL with shared_buffers = 16GB and everything looked fine — until the Refresher tried to refresh materialized views. Three out of eleven views failed with could not resize shared memory segment: No space left on device. Confusing, because the data disk had 7TB free. The problem is Docker’s default /dev/shm size: 64MB. PostgreSQL parallel workers need shared memory segments proportional to shared_buffers. The fix is one line in docker-compose: shm_size: 16g on the postgres service. Match it to your shared_buffers.

GeoLite2 permission denied. The Monitor downloads MaxMind GeoIP databases on first run to geolocate relay IPs. It tried to write them to the static/ directory — which is bind-mounted from the host and owned by root. The container runs as uid 1000. Permission denied, five consecutive failures, service stops. A chown -R 1000:1000 on the host directory fixed it permanently.

None of these are BigBrotr bugs — they’re infrastructure gotchas that apply to any Docker + PostgreSQL deployment on self-hosted hardware. But they’re the kind of thing that wastes hours if you don’t know to look for them.

Backups

The deployment folder includes a backup.sh script that dumps the database (compressed with gzip) and keeps the 7 most recent dumps. If you have a dedicated backup disk, symlink the dumps/ directory to it. For automated daily backups:

echo '0 4 * * * root /opt/bigbrotr-production/backup.sh >> /var/log/bigbrotr-backup.log 2>&1' > /etc/cron.d/bigbrotr-backup

Since BigBrotr data is re-fetchable from Nostr relays, backups are more about convenience than disaster recovery — restoring from a dump is faster than re-syncing from scratch.

What’s Next

If you’re interested in running your own instance:

Check the Self-Hosting Guide for every command, line by line
The Architecture Deep Dive explains the service design
Open an issue on GitHub if you run into problems

BigBrotr is designed to run unattended. Once deployed, the services handle their own lifecycle — retrying failed connections, rotating through relays, refreshing views on schedule. Your main ongoing tasks are checking Grafana occasionally, running docker compose logs if an alert fires, and doing a docker compose pull && docker compose up -d when a new release drops.

The Nostr network is growing. The more independent observers running, the more complete the picture. If you’ve got spare hardware and a domain, this is a weekend project that keeps paying off.

Uncovering Exposed Private Keys Across the Nostr Network

Tue, 17 Mar 2026 00:00:00 GMT

Your Nostr identity is a key pair. The npub is public — share it everywhere. The nsec is private — leak it and anyone can impersonate you. There is no password reset, no support ticket, no recovery. The nsec is the account.

So what happens when private keys end up published in plaintext on the very network they grant access to?

We set out to answer this question using BigBrotr’s event archive — over 41 million events collected from 1,085 relays across clearnet, Tor, and I2P networks over 48 hours of continuous synchronization.

Searching for nsec Strings

We searched every archived event — both the content field and tags — for strings matching the nsec1 Bech32 prefix. Each match was extracted via regex and validated by attempting to derive a public key from it using the secp256k1 curve.

Metric	Count
Events containing `nsec1`	17,956
Unique nsec strings found	16,941
Valid private keys	16,599
Invalid (truncated or fake)	342

16,599 valid Nostr private keys, published in plaintext, recoverable by anyone with access to a relay archive. But that number is misleading.

The Headline Number Is Noise

Anyone can publish a private key — including bots that mass-produce throwaway accounts. A single bot, which we call “Mr.nsec,” accounts for 15,285 of those 16,599 keys (92%). It creates throwaway accounts named Mr.{nsec} with the bio "Just your average nostr enjoyer" — each publishing a single profile event exposing a different private key, each from a unique throwaway pubkey that is never used again.

By key count, the bot dominates the dataset. But the accounts whose keys it republishes have almost no followers. By social impact, the bot is irrelevant.

The real question is not how many keys are exposed but how many real identities are at risk.

From 16,599 to 38

We applied successive filters to narrow down to the accounts that actually matter:

Filter	Keys	%
nsec1 strings found	16,941	100%
Valid private keys	16,599	98.0%
With at least 1 follower	463	2.7%
Real identity at risk	86	0.5%
Still active (last 90 days)	40	0.24%
No signs of compromise	38	0.22%

A “real identity at risk” is defined as: at least 10 followers, a profile with a name, at least 10 events published, and the nsec was not published by the account itself (excluding intentional sharing and self-leaks). Of those 86, we checked which ones were still active and manually inspected each profile for signs of unauthorized use.

38 accounts are actively using a compromised key with no visible signs of awareness. They collectively have over 21,000 followers. Two additional accounts show clear signs of unauthorized use (profile defaced, spam content).

Who Leaked the Keys?

Excluding the bot, 1,314 organically leaked keys remain. Two questions matter: who published them, and how.

Authorship

Authorship	Keys	% of keys	Followers exposed	% of followers
Self-leak	742	56.5%	26,924	29.6%
Third-party	572	43.5%	63,945	70.4%

The split is nearly even by key count — 56% self-leak, 44% third-party. But the follower distribution is heavily skewed: third-party leaks account for 70% of all follower exposure, because they disproportionately target accounts with social presence. Self-leaks are mostly users pasting their nsec into a profile field, confusing it with their npub — typically new accounts with few followers.

By follower exposure — the metric that actually matters — profile-field leaks dominate at 74%. The real damage is done by users who accidentally pasted their nsec into a profile field. Smaller categories include nsec strings in contact list relay fields, bare nsec posts, and AI agents publishing credentials in operational logs.

When we exclude bot-generated keys, 35% of organically leaked keys belong to accounts with at least one follower:

The Organic Leak Rate

Removing the bot reveals the underlying trend of organic key exposure:

The bot operated in a single burst. The organic rate is steady and ongoing — a persistent UX problem, not a one-time attack. As long as clients allow users to paste nsec strings into profile fields without warning, new keys will continue to be exposed.

Relay Spread

How many relays serve each leaked key?

The median leaked key is available on just 1 relay. But accounts with more followers tend to see their leak events on more relays — up to 30+ for the most popular ones. This is expected: popular accounts’ events are replicated more widely in general, not just leak events. Regardless of the cause, the practical implication is the same: for accounts with wide relay distribution, deleting the event from one relay is insufficient. Key rotation is the only reliable remediation.

The 38 Accounts That Need to Know

Of the 86 real identities with exposed keys, 40 have posted in the last 90 days. We manually inspected each profile to determine whether the account showed signs of compromise (spam, defaced profile, incoherent content) or appeared to be used normally.

38 accounts show no signs of compromise — they appear to be used normally by the original owner, who likely does not know their private key is publicly available. Two accounts show clear signs of unauthorized use.

Followers	Events	Leak date	Last active	Status
18,900	5,288	2024-12-27	2026-03-15	compromised
13,657	1,525	2023-11-18	2026-02-10	compromised
3,995	4,485	2023-08-24	2026-03-15	no signs
2,543	3,195	2024-11-18	2026-03-16	no signs
1,887	102	2023-12-01	2026-01-24	no signs
1,800	16,050	2023-12-11	2026-03-15	no signs
1,337	525	2024-04-12	2026-03-15	no signs
1,295	14,069	2023-12-05	2026-03-16	no signs
1,034	8,949	2024-11-03	2026-03-16	no signs
1,006	2,349	2023-09-17	2026-03-16	no signs

The remaining 30 accounts (12–851 followers) all show no signs of compromise.

Check If Your Key Is Exposed

We deployed an nsec-leak-checker — a Nostr DVM (Data Vending Machine) that lets you check if your private key has been found in public events. Send a Kind 5300 event signed with your keys (with a p tag pointing to the DVM’s pubkey), and it responds with a NIP-44 encrypted message that only you can read.

What Clients and Relay Operators Can Do

This isn’t a protocol vulnerability — Nostr’s key-based identity model is sound. The leaks are user errors, client oversights, and AI agent carelessness.

Clients should reject nsec strings in profile fields before signing the event. A regex check on Kind 0 content before broadcast would prevent the most damaging leak category entirely.

Relay operators could reject events containing valid nsec strings. This is more aggressive and has trade-offs (false positives on educational content, shared accounts), but it would neutralize the bot completely.

AI agent developers should sanitize logs before publishing them as events. Private keys and credentials have no place in broadcast messages.

Users should understand the difference: npub is your address, nsec is your password. If you’ve ever pasted an nsec into a profile field, generate a new key pair immediately.

Limitations

This analysis covers 1,085 of 2,009 known relays over approximately 48 hours of synchronization. The actual number of exposed keys across the full network is likely higher. We search only for the literal string nsec1 — keys in hexadecimal format or obfuscated in any way are not detected. Follower counts reflect the current state of the network, not the state at the time of the leak. Account lifespan calculations are based on the earliest and latest events in our archive, which may not correspond to the account’s true creation date. The self-leak exclusion filter is conservative: it removes all keys published by the account itself, including accidental self-leaks by users who are genuine victims of UX confusion.

Methodology

All data was collected by BigBrotr’s Synchronizer service, archiving events from 1,085 relays using cursor-based pagination with binary-split windowing. nsec validation was performed using the nostr-sdk Python library. Follower counts were computed from the latest Kind 3 (contact list) event per pubkey. Profile data was extracted from the latest Kind 0 event. Recent activity was defined as any event published in the last 90 days. The 40 active at-risk accounts were manually inspected via their public profiles.

The full dataset is available for researchers upon request.

BigBrotr vs Pensieve: Two Approaches to Indexing the Nostr Network

Sun, 15 Mar 2026 00:00:00 GMT

The Nostr network has no central authority, no canonical event store, no official list of relays. If you want to understand what’s happening on the network — how many relays exist, what events are flowing through them, who’s publishing, what’s growing — you have to build your own observation infrastructure.

Two open-source projects tackle this problem from fundamentally different angles: BigBrotr and Pensieve. Both connect to Nostr relays, both store events, both produce analytics. But they ask different questions, make different trade-offs, and arrive at architectures that barely resemble each other.

This post is a detailed technical comparison — not a “which is better” piece, but an honest look at what each does, how, and why.

The Core Question

BigBrotr asks: What relays exist on the Nostr network, how healthy are they, and what events are they publishing?

Pensieve asks: What events exist on the Nostr network, and how fast can we archive all of them?

BigBrotr is a relay observatory — relay health, relay metadata, relay distribution, with events as one dimension of relay analysis. Pensieve is an event archive — capture every event as fast as possible, with relay management as a means to maximize coverage.

This distinction shapes everything that follows.

	BigBrotr	Pensieve
Language	Python 3.11+ (asyncio)	Rust 2024 edition (tokio)
Codebase	~18,000 lines	~12,000 lines
License	MIT	PolyForm Noncommercial 1.0.0
Primary database	PostgreSQL 16	ClickHouse + notepack archive
Event fetching	Cursor-based crawler with completeness verification	Live subscription (firehose)

How They Fetch Events

This is the most fundamental architectural difference — not what they store, but how they get events from relays.

BigBrotr: Systematic Crawling

BigBrotr’s Synchronizer does not subscribe to live events. It operates as a systematic crawler: for each validated relay, it opens a connection, requests a precise time window [since, until], fetches events, and then verifies the response is complete before advancing the cursor.

Request events in window [cursor_timestamp, end_time] with a limit (default 500)
Receive the events — verify Ed25519 signatures, match NIP-01 filters, deduplicate in memory
Verify completeness: re-fetch at the boundary timestamp and confirm no events were missed. This catches relay truncation that would otherwise be invisible
If the relay truncated: binary split — halve the time window and retry each half recursively, down to single-second granularity if needed
Only after verification: yield the events, record which relay had them, advance the cursor

Each relay has an independent cursor stored in the database. A relay that has never been synced starts at timestamp 0 — BigBrotr will crawl its entire history. On restart, each relay resumes from its last verified position. Intentionally, the Synchronizer stays one day behind real-time (end_lag=86400) to let events settle on relays before crawling.

Pensieve: Live Subscription

Pensieve opens a WebSocket subscription with Filter::new() — “send me everything.” The relay pushes events in real time. For catch-up after restart, a since filter is applied based on the last checkpoint. Events flow through the pipeline as they arrive: dedupe → notepack → gzip → ClickHouse.

Fast and simple. But the relay decides what to send and how much. If a relay silently truncates, enforces an internal limit, or drops events under load, Pensieve has no way to detect the gap.

NIP-77 (Negentropy) is the recovery mechanism — periodically, Pensieve performs set reconciliation with trusted relays to identify missing events. But this is separate from live ingestion, works only with relays that support NIP-77 (very few currently), and covers only a configurable lookback window (default 14 days). A separate --catchup mode uses checkpoint-based resumption, though most relays don’t efficiently serve historical data.

When a new relay is added, Pensieve only receives events published after the connection. There is no historical backfill.

The Trade-off

	BigBrotr	Pensieve
Completeness	Verified per time window, per relay	Best-effort (relay decides what to send)
Historical coverage	Full history from epoch, per relay	From connection time + 14-day negentropy lookback
New relay added	Synchronized from the beginning	Only future events
Truncation detection	Binary-split fallback, automatic	Not detected
Throughput	Lower (verification overhead)	Higher (passive reception)
Latency	Minutes to hours behind real-time	Real-time

Pensieve optimizes for volume and speed. BigBrotr optimizes for completeness and accuracy. Everything else — storage engines, analytics, APIs — follows from this choice.

Architecture

BigBrotr: Eight Independent Services, One Database

     Seeder    Finder    Validator    Monitor    Synchronizer    Refresher    API    DVM
       │         │          │           │            │              │          │      │
       └─────────┴──────────┴───────────┴────────────┴──────────────┴──────────┴──────┘
                                        │
                                   PostgreSQL

All eight services are independent processes — no imports between them, no message queues, no shared state outside the database. Each reads what it needs from PostgreSQL, does its work, writes results back. A service can crash, restart, or scale without affecting the others.

Each service is a separate Docker container. You start only what you need — docker compose up -d seeder monitor refresher api is a valid deployment. This modularity, combined with deep YAML configurability, means the same codebase serves very different purposes:

Full observatory: all services, all health checks, all events. The default.
Relay health only: Seeder + Finder + Validator + Monitor + Refresher + API. No Synchronizer means no events stored, no event_relay tracking. Minimal storage, maximum relay intelligence.
Event archive only: Seeder + Validator + Synchronizer + Refresher + API. No Monitor, no health checks. Just events and their relay distribution.
Kind-specific archive: NIP-01 filters on the Synchronizer — archive only specific event kinds, authors, or tag patterns. The same filter syntax relays understand.
No junction tracking: override the event_relay_insert_cascade stored procedure to skip the event_relay table. All mutations flow through stored procedures, so this is a SQL-level change — no Python modifications.
Lightweight mode (LilBrotr): a separate deployment variant that stores only event metadata (id, pubkey, created_at, kind, tagvalues) without tags, content, or signatures — ~60% disk savings.

The internal architecture follows a strict diamond DAG: services at the top, core/nips/utils in the middle, pure frozen dataclass models at the bottom. Imports flow strictly downward, enforced by linter rules.

Pensieve: Pipeline with Archive as Source of Truth

Sources (Relays | JSONL | Protobuf)
    → DedupeIndex (RocksDB)
    → SegmentWriter (notepack binary files)
    → Compression (gzip, background thread)
    → ClickHouseIndexer (background thread)
    → rclone sync (offsite backup)

The notepack archive (compressed binary segments on disk) is the source of truth. ClickHouse is a derived index — if corrupted, it can be rebuilt from the archive. This “archive-first” design means Pensieve can survive database loss, something PostgreSQL-based BigBrotr cannot do without backups.

Four Rust crates: pensieve-core (shared types, event validation, notepack encoding), pensieve-ingest (the pipeline), pensieve-serve (analytics API), and pensieve-preview (Open Graph previews and JSON API for Nostr events).

Beyond live relay ingestion, Pensieve supports JSONL and Protobuf backfill from external archives (including S3 with resumable progress), and ships maintenance utilities: relay-cleanup (URL normalization, duplicate merging, dry-run mode) and repair-dedupe (RocksDB repair, integrity checks, data recovery).

Storage

BigBrotr: One Database, Full Relational Model

Everything lives in PostgreSQL 16: 6 tables, 25 stored procedures, 11 materialized views, 31 indexes, 4 least-privilege database roles. PGBouncer handles connection pooling. All mutations go through stored procedures for atomicity — cascade functions insert across multiple tables in a single SQL call.

The most distinctive structure is the event_relay junction table: a many-to-many relationship between events and relays. When the Synchronizer fetches an event from a relay, it records (event_id, relay_url, seen_at). The same event on 50 relays produces 50 junction rows. This enables queries no other Nostr indexer can answer: replication factor per event, exclusive content per relay, distribution patterns by kind or network.

Metadata is content-addressed — SHA-256 hashed, so identical health check results across time or relays deduplicate automatically. The relay_metadata junction is time-series: the same relay accumulates metadata records over time, building a complete health history.

The trade-off: PostgreSQL gives ACID, arbitrary JOINs, a massive ecosystem (Grafana, psql, pandas, any language with a PostgreSQL driver). But it’s a row store — full scans over hundreds of millions of events are slower than columnar, and storage is less compact.

Pensieve: Five Storage Engines

Engine	Purpose
RocksDB (dedupe)	Event ID → status. Bloom filters (10 bits/key) for fast “not seen” checks
RocksDB (sync state)	NIP-77 Negentropy state. Timestamp-keyed for range scans
Notepack segments	Gzipped binary archive. Immutable, ~128 bytes smaller per event than JSON
ClickHouse	Columnar analytics. ReplacingMergeTree, 3 projections, ZSTD(3) on content
SQLite	Relay quality metrics. Hourly/daily stats with automatic rollup

Events are checked against the dedupe index before notepack serialization — since ~90% of events from multiple relays are duplicates, this avoids wasting CPU on packing events that will be discarded.

ClickHouse’s columnar storage excels at analytics: scanning only the kind column for a count-by-kind query, ZSTD compression on content, projections for pre-sorted alternate orderings. Materialized views use SummingMergeTree for incremental aggregation (reactions, comments, reposts) and AggregatingMergeTree for efficient unique counting — no full refresh needed.

The trade-off: five storage engines means five failure modes and five backup strategies. If a segment fails to compress (fire-and-forget background thread) or ClickHouse indexing fails (no retry), data can be left inconsistent. The notepack archive doesn’t include checksums or format version headers.

Relay Management

BigBrotr: Deep Health Profiling

Three dedicated services handle relays:

Finder discovers relays from external HTTP APIs (nostr.watch by default, with JMESPath extraction and per-source cooldowns) and by scanning tagvalues of all archived events for relay URLs — not just kind:10002 NIP-65 events, but any tag in any event kind that contains a relay URL.

Validator checks each candidate via WebSocket protocol handshake (including NIP-42 AUTH acceptance), promotes valid ones to the relay table, and tracks failures with exponential backoff. After 720 failures (~30 days at hourly checks), candidates are permanently removed.

Monitor performs 7 health checks per relay per cycle, each with independent retry configuration (exponential backoff + jitter):

Check	Data Collected
NIP-11	20+ fields: name, software, version, supported NIPs, limitations (13 subfields), fees, countries, languages
RTT	Three-phase: connection open, event read, event write with publish verification. Respects relay’s PoW difficulty
SSL	Issuer, expiry, SANs, cipher, protocol, SHA-256 fingerprint. Two-connection methodology
DNS	A/AAAA/CNAME/NS/PTR records, TTL
Geolocation	Country, city, coordinates, timezone, geohash (precision 9) via GeoLite2 (auto-downloaded)
Network/ASN	IPv4/IPv6, ASN number and organization, network range
HTTP	Server and X-Powered-By headers from WebSocket upgrade

Results are published to the Nostr network as Kind 30166 relay discovery events (with NIP-32 labels for ASN/country/timezone, relay type tags, requirement tags for auth/payment/PoW, geohash g tags for spatial indexing), Kind 10166 monitor announcements, and Kind 0 operator profiles. Each publishing type has independent relay lists and intervals.

Pensieve: Coverage-Optimized Relay Rotation

Pensieve doesn’t profile relays for external consumption — it manages them to maximize unique event capture:

novel_normalized = min(novel_rate_7d / network_median_novel_rate, 2.0)
score = (novel_normalized * 0.7) + (uptime_7d * 0.3)

Every 5 minutes, the optimizer can swap up to 5% of connected relays, with 3 exploration slots reserved for untested relays. Seed relays get a minimum score floor and are never evicted. The SQLite-backed RelayManager tracks hourly and daily statistics with automatic rollup.

A thorough ConnectionGuard provides security: SSRF protection (private IPs, CGNAT, documentation, and reserved ranges), port filtering (only standard web ports), per-IP deduplication (max 2 connections per IP), connection rate limiting, and URL blocklisting (including Umbrel detection for misconfigured home servers).

Analytics and Data Access

BigBrotr: SQL + REST API + Nostr DVM

Three access paths to the same data:

Direct SQL — connect to PostgreSQL from any compatible client. Full JOINs, CTEs, window functions. The reader role has SELECT-only access.
REST API (FastAPI) — schema-aware route generation from database introspection. Every table and materialized view gets automatic endpoints with filtering, sorting, and pagination. 16 resources exposed.
NIP-90 DVM — native Nostr access. Clients query data by publishing Kind 5050 job requests; BigBrotr responds with Kind 6050 results. Per-table pricing in millisats. NIP-89 handler announcements for discoverability.

11 materialized views cover: global event statistics with rolling windows (1h/24h/7d/30d), per-relay stats (event counts, unique pubkeys, average RTT), kind and pubkey distributions (global and per-relay), network-level aggregates, relay software and NIP support distributions, daily time-series counts, and the latest metadata snapshot per relay.

Pensieve: ClickHouse + REST API + Preview Pages

ClickHouse SQL — direct columnar queries. Excellent for aggregations over billions of rows.
REST API (Axum) — 30+ bearer-token authenticated endpoints: event/pubkey/kind totals, throughput (7-day rolling average), hourly activity patterns, per-kind breakdowns with content length and time windows, new users per period, retention cohort analysis (weekly and monthly), DAU/WAU/MAU segmented by user quality (has profile, has follow list, has both — excluding throwaway keys), zap statistics with amount histograms, long-form content analytics, top publishers, relay distribution from NIP-65 lists. ETag-based caching.
Preview pages — HTML pages for notes, profiles, articles, videos, reposts with inline quote cards. Dynamic OG image generation (SVG-to-PNG with author avatar compositing). JSON API (append .json to any preview URL) with full event data, author profile, mentioned profiles, and engagement counts. llms.txt convention for AI agent discoverability.

ClickHouse views include: flattened tag analytics (via ARRAY JOIN), incremental engagement counters (SummingMergeTree), NIP-09 deletion tracking, video content analytics (trending, hashtags, top creators), first-seen tracking for new user analysis, and scheduled cohort retention refreshes.

The retention cohort analysis is the data source behind recent Nostr network reports — it answers “of users who first appeared in week X, what percentage returned in weeks X+1, X+2, etc.” with user quality segmentation to distinguish real users from throwaway keys.

Network Support

Network	BigBrotr	Pensieve
Clearnet (wss://)	50 concurrent tasks	Up to 30 relays
Tor (.onion)	SOCKS5, 10 tasks	Supported via `--tor-proxy`
I2P (.i2p)	SOCKS5, 5 tasks	Not supported
Lokinet (.loki)	SOCKS5, 5 tasks	Not supported

BigBrotr auto-detects network type from relay URLs using full RFC 3986 parsing (TLD for overlays, IP range checks against 27 IANA ranges). Per-network semaphores control concurrency. Clearnet relays with invalid SSL certificates are handled via a 15-pattern SSL error classifier that falls back to a custom insecure WebSocket transport — configurable per-service.

Engineering and Operations

Monitoring

BigBrotr runs a full Prometheus + Grafana + Alertmanager stack with per-service metrics, 7 alert rules, postgres-exporter with custom queries, and auto-provisioned dashboards. Pensieve exposes Prometheus metrics with 5-second rolling rate calculations and three Grafana dashboards (ingestion, backfill, user analytics).

Deployment

BigBrotr runs entirely in Docker Compose (15 containers). Pensieve uses a hybrid model: Docker for infrastructure (ClickHouse, Grafana, Prometheus, Caddy), native Rust binaries with systemd for the ingestion and serving layers.

Testing and CI/CD

	BigBrotr	Pensieve
Tests	~2,955 (2,739 unit + 216 integration)	Minimal
Coverage	80% branch minimum (enforced)	None
CI matrix	Python 3.11–3.14	Single Rust version
Pre-commit	23 hooks (ruff, mypy, detect-secrets, hadolint, sqlfluff, codespell, …)	Standard Rust toolchain
Security	Trivy scanning, CodeQL analysis, SBOM generation, dependency auditing	N/A
Distribution	PyPI + multi-arch Docker (amd64 + arm64) to GHCR	Native binary

NIP Support

NIP	BigBrotr	Pensieve
NIP-01	Event model, validation, protocol	Event validation, signature verification
NIP-09	—	Deletion tracking (materialized view)
NIP-11	Full info document fetch (20+ fields)	—
NIP-32	Labels in published events	—
NIP-42	Recognized during validation	Automatic auth with ephemeral keys
NIP-65	Relay URLs from event tags (Finder)	Relay discovery via nostr-sdk
NIP-66	6 health check types + event publishing	—
NIP-77	—	Negentropy set reconciliation
NIP-89	DVM handler announcements	—
NIP-90	Data Vending Machine	—

Trade-offs and Limitations

Every architectural choice has a cost. Here’s where each project pays.

BigBrotr’s costs:

PostgreSQL row store is less efficient than columnar for pure analytics over billions of rows
No incremental materialized view refresh — full REFRESH CONCURRENTLY each cycle
Single PostgreSQL instance — horizontal scaling requires read replicas or partitioning
The completeness-first crawling approach means higher latency (events arrive minutes to hours after publication, not real-time) and lower raw throughput than a firehose

Pensieve’s costs:

Event-relay attribution is lost in the archive (notepack doesn’t store relay source)
If a segment write fails after the dedupe mark, the event is permanently lost. 8MB BufWriter buffer means up to 8MB lost on unclean shutdown
The global dedupe mutex serializes all event processing — bottleneck above ~10K events/sec
Failed ClickHouse indexing is not retried — recovery requires manual re-indexing from archive
Fire-and-forget compression threads can leave corrupt files on crash
No archive checksums or format version headers
Five storage engines means five failure modes and five backup strategies
Relay scoring cold start: new relays always score 0, takes ~11.5 days to try 10K discovered relays at 3 exploration slots per 5-minute cycle

Complementary, Not Competing

These projects answer different questions and would be most valuable running side by side.

BigBrotr tells you about the infrastructure of Nostr — which relays are healthy, what software they run, how fast they respond, what NIPs they support, which events they carry, how events are distributed across the network. It’s the tool for understanding the relay landscape, detecting outages, tracking network growth, and building relay recommendation systems.

Pensieve tells you about the content of Nostr — what events exist, who’s active, what kinds are trending, how users retain, how zaps flow. It’s the tool for understanding user behavior, measuring network health from a social perspective, and producing the analytics that appear in network reports.

A BigBrotr instance could feed validated relay URLs to Pensieve. A Pensieve instance could feed event data back into BigBrotr’s analytics. BigBrotr’s event_relay junction answers distribution questions that Pensieve’s architecture cannot. Pensieve’s ClickHouse-powered retention cohorts answer behavioral questions that BigBrotr’s PostgreSQL views don’t address.

Different tools. Different questions. Same network. The Nostr ecosystem benefits from having multiple independent observers with different perspectives — just like the protocol itself benefits from having multiple independent relays.

Build what you need. Run what answers your questions. Or run both.

Building a Nostr Relay Monitor with BigBrotr

Fri, 13 Mar 2026 00:00:00 GMT

There’s a surprising amount of information you can extract from a Nostr relay beyond just “is it online.” RTT latency across WebSocket open, read, and write. TLS certificate details and chain validity. DNS records, reverse lookups, nameservers. IP geolocation down to city level. ASN and network operator. The actual server software from HTTP headers. The relay’s self-reported capabilities, limitations, and supported NIPs.

All of this data is useful — for relay operators debugging their infrastructure, for clients picking the best relay, for researchers mapping the Nostr network. Why leave any of it on the table?

Everything, or Just What You Need

BigBrotr lets you collect all of it. Or just the parts you care about. Both NIP-11 and NIP-66 checks are controlled by selection objects:

# Run everything (default)
nip66_selection = Nip66Selection()

# Or pick exactly what you need
nip66_selection = Nip66Selection(
    rtt=True,
    ssl=True,
    dns=False,
    geo=True,
    net=False,
    http=True,
)

Same for NIP-11 — Nip11Selection(info=True) fetches the relay information document, info=False skips it. Mix and match however you want. Checks you disable don’t run at all — no wasted time, no wasted bandwidth.

Once you’ve collected the data, build_relay_discovery() packages exactly what you computed into a kind 30166 event fully compliant with NIP-66. No manual tag construction, no guessing at the spec. The announcement event (kind 10166) automatically declares which checks you have enabled via c (capability) tags and timeout tags per check type, so other clients know what to expect from your monitor.

The Code

The full example is in examples/monitor_relays.py — under 80 lines for a complete, working monitor:

import geoip2.database
from nostr_sdk import Client, Keys, NostrSigner, RelayUrl

from bigbrotr.models.constants import NetworkType
from bigbrotr.models.relay import Relay
from bigbrotr.nips.event_builders import (
    build_monitor_announcement,
    build_profile_event,
    build_relay_discovery,
)
from bigbrotr.nips.nip11 import Nip11, Nip11Selection
from bigbrotr.nips.nip66 import Nip66, Nip66Dependencies, Nip66Selection

# 1. Prepare dependencies (reused across all relays)
city_reader = geoip2.database.Reader("GeoLite2-City.mmdb")
asn_reader = geoip2.database.Reader("GeoLite2-ASN.mmdb")
deps = Nip66Dependencies(city_reader=city_reader, asn_reader=asn_reader)

# 2. Connect and announce
signer = NostrSigner.keys(Keys.generate())
client = Client(signer)
await client.add_relay(RelayUrl.parse("wss://nos.lol"))
await client.connect()

await client.send_event_builder(build_profile_event(name="My Monitor"))
await client.send_event_builder(
    build_monitor_announcement(
        interval=3600,
        timeout_ms=10000,
        enabled_networks=[NetworkType.CLEARNET],
        nip11_selection=Nip11Selection(),
        nip66_selection=Nip66Selection(),
    )
)

# 3. Monitor and publish
for url in ["wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"]:
    relay = Relay(url)
    nip11 = await Nip11.create(relay)
    nip66 = await Nip66.create(relay, deps=deps)
    await client.send_event_builder(build_relay_discovery(relay, nip11, nip66))

Three calls per relay. Nip11.create() and Nip66.create() are async factory methods that never raise — all errors are captured in their respective logs fields, so you can iterate over hundreds of relays without a single try/except. build_relay_discovery() takes whatever data was successfully collected and serializes it into a fully tagged NIP-66 event.

Nip66Dependencies bundles the GeoIP readers and a throwaway keypair used for the RTT write test, so they can be reused across all relays without repeated initialization.

NIP-11: Relay Information

Nip11.create() fetches the relay’s information document over HTTP. It converts the WebSocket URL to its HTTP equivalent (wss:// → https://) and sends a request with Accept: application/nostr+json.

The response is validated for correct Content-Type (application/nostr+json or application/json), maximum size (64 KB), and JSON structure (must be a dict, not a list or scalar). The resulting Nip11InfoData model captures the relay’s name, description, pubkey, contact, supported NIPs, software, version, and limitations.

For relays with certificate issues, the allow_insecure option enables SSL fallback. Overlay networks (Tor, I2P, Lokinet) automatically use a non-validating SSL context since the proxy layer provides encryption.

NIP-66: Six Concurrent Health Checks

Nip66.create() runs up to six checks in parallel via asyncio.gather(). Each check is independent — a failure in one doesn’t affect the others. Checks for which the required dependency is missing (e.g. no city_reader for geo) are silently skipped.

RTT (Round-Trip Time)

Three sequential phases measuring actual WebSocket performance — not just a ping, but real protocol-level operations:

Open — measures connection establishment time via connect_relay(). If this fails, read and write are automatically marked as failed with the same reason (cascading failure).
Read — streams events with a limit(1) filter and measures time to first event. Times out if no events arrive.
Write — publishes a kind 22456 ephemeral test event and verifies it was stored by immediately re-querying. Reports the total time including verification. Distinguishes between rejection (relay refused), unverified (accepted but not retrievable), and success.

Output: rtt_open, rtt_read, rtt_write in milliseconds.

SSL (Certificate Inspection)

A two-connection strategy:

Extraction — connects with ssl.CERT_NONE to read the certificate regardless of chain validity. Parses with cryptography.x509 to extract subject CN, issuer, validity dates, SANs, serial number, fingerprint (SHA256:AA:BB:CC:...), TLS protocol version, and cipher details.
Validation — a separate connection with the system default SSL context to validate the certificate chain against the trust store.

Both connections run in a thread pool to avoid blocking the event loop. Clearnet only — overlay networks get an immediate skip.

DNS (Resolution)

Comprehensive lookups via dnspython:

A records (IPv4 addresses + TTL)
AAAA records (IPv6 addresses)
CNAME (canonical name)
NS records — resolved against the registered domain (uses tldextract to identify the public suffix, so relay.damus.io queries NS for damus.io)
PTR (reverse DNS from the first IPv4 address)

Each record type is queried independently — a failure in one doesn’t prevent the others. Synchronous DNS operations run in a thread pool.

Geo (Geolocation)

Resolves the relay’s hostname to an IP (preferring IPv4, falling back to IPv6), then looks it up in the GeoLite2 City database. Extracts country (ISO 3166-1 alpha-2, preferring physical over registered country), continent, city, region, postal code, coordinates, accuracy radius, and timezone. Computes a geohash at precision 9 (~5 m accuracy) from the coordinates.

Net (Network/ASN)

Resolves both IPv4 and IPv6 addresses, then looks up the ASN in the GeoLite2 ASN database. IPv4 data takes priority — IPv6 ASN/org is used only as fallback when no IPv4 is available. Records the autonomous system number, organization name, and network CIDRs for both address families.

HTTP (Header Capture)

Initiates a WebSocket connection and intercepts the HTTP upgrade response using aiohttp’s TraceConfig hooks. Captures the Server and X-Powered-By headers, then immediately closes. This reveals the relay’s actual software stack without relying on self-reported NIP-11 data.

What Gets Published

Kind 10166 — Monitor Announcement

Declares what your monitor does: check interval, timeout, enabled networks, and c (capability) tags for each active check — open, read, write, nip11, ssl, dns, geo, net, http. Clients reading your monitor events know exactly what data to expect.

Kind 30166 — Relay Discovery

One event per relay. The content is the NIP-11 information document as canonical JSON. The tags carry all NIP-66 health check results:

RTT: rtt-open, rtt-read, rtt-write (milliseconds)
SSL: ssl (valid/invalid), ssl-expires (Unix timestamp), ssl-issuer
DNS: dns-ip, dns-ip6, dns-cname, dns-ttl
Geo: g (geohash), geo-country, geo-city, geo-lat, geo-lon, geo-tz, plus NIP-32 l labels for country and continent
Net: net-ip, net-ipv6, net-asn, net-asn-org, plus NIP-32 l labels
HTTP: http-server, http-powered-by
NIP-11 derived: N tags for supported NIPs, R tags for requirements (auth, payment, pow), T tags for relay type classification (Search, Community, Paid, etc.)

All tag names and semantics follow the NIP-66 specification — no custom extensions, full interoperability with any NIP-66 aware client.

Prerequisites

The geo and net checks require GeoLite2 databases. Download GeoLite2-City.mmdb and GeoLite2-ASN.mmdb into the examples directory. If they’re missing, those checks are silently skipped — the rest still run.

Running It

cd examples
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python monitor_relays.py

The script prints the full NIP-11 and NIP-66 results as JSON for each relay, and publishes kind 30166 events to the target relay. Here’s what a complete NIP-66 output looks like for wss://nos.lol:

{
  "rtt": {
    "data": {
      "rtt_open": 197,
      "rtt_read": 64,
      "rtt_write": 82
    },
    "logs": {
      "open_success": true,
      "open_reason": null,
      "read_success": true,
      "read_reason": null,
      "write_success": true,
      "write_reason": null
    }
  },
  "ssl": {
    "data": {
      "ssl_valid": true,
      "ssl_subject_cn": "nos.lol",
      "ssl_issuer": "Let's Encrypt",
      "ssl_issuer_cn": "R13",
      "ssl_expires": 1777079086,
      "ssl_not_before": 1769303087,
      "ssl_san": ["nos.lol"],
      "ssl_serial": "6CCA2CA89CFC918B9759546D124552CE936",
      "ssl_version": 2,
      "ssl_fingerprint": "SHA256:FB:0B:35:B5:03:B3:54:36:3C:DC:56:8F:E3:38:E5:61:A6:0E:BA:49:4E:A2:51:5B:E0:C8:50:97:B2:71:A9:A8",
      "ssl_protocol": "TLSv1.3",
      "ssl_cipher": "TLS_AES_256_GCM_SHA384",
      "ssl_cipher_bits": 256
    },
    "logs": { "success": true, "reason": null }
  },
  "geo": {
    "data": {
      "geo_country": "DE",
      "geo_country_name": "Germany",
      "geo_continent": "EU",
      "geo_continent_name": "Europe",
      "geo_is_eu": true,
      "geo_region": "Saxony",
      "geo_city": "Falkenstein",
      "geo_postal": "08223",
      "geo_lat": 50.4777,
      "geo_lon": 12.3649,
      "geo_accuracy": 20,
      "geo_tz": "Europe/Berlin",
      "geo_hash": "u2bz1m5vg",
      "geo_geoname_id": 2927913
    },
    "logs": { "success": true, "reason": null }
  },
  "net": {
    "data": {
      "net_ip": "5.9.78.12",
      "net_ipv6": "::ffff:5.9.78.12",
      "net_asn": 24940,
      "net_asn_org": "Hetzner Online GmbH",
      "net_network": "5.9.0.0/16",
      "net_network_v6": "::ffff:5.9.0.0/112"
    },
    "logs": { "success": true, "reason": null }
  },
  "dns": {
    "data": {
      "dns_ips": ["5.9.78.12"],
      "dns_ips_v6": null,
      "dns_cname": null,
      "dns_reverse": "f56.nos.lol",
      "dns_ns": ["kiki.bunny.net", "coco.bunny.net"],
      "dns_ttl": 1105
    },
    "logs": { "success": true, "reason": null }
  },
  "http": {
    "data": {
      "http_server": "nginx/1.18.0 (Ubuntu)",
      "http_powered_by": null
    },
    "logs": { "success": true, "reason": null }
  }
}

Every check carries both data and logs — when a check fails, logs.reason tells you exactly why while the rest of the checks still complete normally.

Going Further

This example uses randomly generated keys. For a production monitor, use a persistent keypair so clients can verify and trust your results over time. BigBrotr’s Monitor service builds on the same primitives — adding scheduled execution, database persistence, configurable check selections, and overlay network support via SOCKS5 proxies.

Streaming Events from Nostr Relays

Fri, 13 Mar 2026 00:00:00 GMT

Getting all events from a Nostr relay for a given time window sounds like it should be simple. Pick a since, pick an until, send a REQ, done. In practice, it’s anything but.

Relays cap how many events they return per request. Some enforce a hard LIMIT lower than what you ask for — silently. You get back 100 events with no indication of whether that’s everything or just a truncated slice. Multiple events can share the same created_at timestamp, so paginating by “last timestamp seen” risks skipping or duplicating events. And if you want results in chronological order, good luck — relays don’t guarantee any sort.

Building a correct, complete, ordered dump from a relay means writing retry logic, deduplication, signature checks, boundary probing, and adaptive windowing. It’s a lot of code for something that should be straightforward.

`stream_events`: Zero Stress

BigBrotr’s stream_events reduces all of that to an async for loop:

import asyncio
import time

from nostr_sdk import Client, Filter, RelayUrl
from bigbrotr.utils.streaming import stream_events

RELAY = "wss://relay.damus.io"
FILTERS = [Filter()]
SINCE = 0
UNTIL = int(time.time())
LIMIT = 500
TIMEOUT_SECS = 10.0


async def main() -> None:
    client = Client()
    await client.add_relay(RelayUrl.parse(RELAY))
    await client.connect()

    async for event in stream_events(
        client=client,
        filters=FILTERS,
        start_time=SINCE,
        end_time=UNTIL,
        limit=LIMIT,
        request_timeout=TIMEOUT_SECS,
    ):
        print(
            f"{event.created_at().as_secs():>12}  "
            f"{event.kind().as_u16():>5}  "
            f"{event.id().to_hex()}  "
            f"{event.author().to_hex()}"
        )

    await client.disconnect()


asyncio.run(main())

That’s it. Every event matching your filters, for any time window, from any relay, yielded in ascending (created_at, event_id) order. No missing events, no duplicates, no manual pagination. The full example is in examples/stream_events.py.

You choose the filters — all events, specific kinds, specific authors, tag queries, whatever Nostr filters support. You choose the time window — the last hour, the last year, or the entire relay history since epoch. stream_events handles the rest.

Resumable by Design

If the stream gets interrupted — network error, timeout, you hit Ctrl+C — just restart from the created_at of the last event you received. Since events are yielded in strict chronological order, there’s no ambiguity about where you left off. No checkpoint files, no cursor management, no state to persist. The function is stateless — your resume point is just the last timestamp you saw.

Parameters

Parameter	Description
`RELAY`	The relay URL to connect to
`FILTERS`	Nostr filters — `[Filter()]` matches all events
`SINCE` / `UNTIL`	Inclusive time window boundaries (Unix timestamps)
`LIMIT`	Page size per `REQ` — controls the split threshold, not the total output
`TIMEOUT_SECS`	How long to wait for each relay response

LIMIT controls the page size per individual REQ to the relay, not the total number of events returned. The function will issue as many requests as needed to cover the entire window — you don’t set a cap on the output.

How It Works Under the Hood

The simplicity on the surface hides a careful algorithm underneath.

Data-Driven Windowing with Binary-Split Fallback

The function maintains a stack of upper bounds and a moving lower bound, processing windows left-to-right in a depth-first traversal. For each window [current_since, current_until]:

Fetch — requests events with a three-layer validation pipeline: filter matching, cryptographic signature verification, and deduplication by event ID. Events are consumed via streaming (not bulk fetch) to prevent relay flooding.
Verify completeness — if the fetch hits the limit, the function doesn’t immediately split. Instead, it runs a data-driven verification:
- Fetches all events at the minimum created_at timestamp from the original batch
- Checks that the boundary fetch is consistent (max timestamp equals the expected boundary)
- Probes for events before that minimum timestamp — if any exist, the window was incomplete
- If all checks pass, the combined result is complete — no split needed
Binary split — only when verification fails (inconsistent boundary, or earlier events detected), the window is split at mid = current_since + (current_until - current_since) // 2. The left half is pushed to the front of the stack for depth-first processing.
Bottom out — when current_since == current_until (a single-second window), no further splitting is possible. All events in that second are yielded regardless of count.

This means most windows resolve without splitting — the binary split only kicks in when the relay genuinely has more events than the page size allows. The algorithm converges in O(log N) splits in the worst case, with each split halving the time window.

Events are always yielded in ascending (created_at, event_id) order, regardless of how many splits were needed.

Validation Pipeline

Every event passes through three layers before being yielded:

Filter matching — Filter.match_event() verifies the event matches the requested kinds, authors, tags, and time range. This catches relays that return out-of-scope events.
Signature verification — Event.verify() checks the cryptographic signature. Invalid signatures are silently skipped.
Deduplication — events are tracked by ID across all filters, so the same event seen through different filter paths is only yielded once.

Events that fail domain conversion (null bytes in content/tags, timestamp overflow) are silently dropped with a debug log — the stream continues without interruption.

Running It

cd examples
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python stream_events.py

  created_at   kind  id                                                                pubkey
-----------------------------------------------------------------------------------------------
  1672531200       1  a1b2c3d4e5f6...                                                  e5f6a7b8c9d0...
  1672531201       0  c9d0e1f2a3b4...                                                  a3b4c5d6e7f8...

Use Cases

Complete event dumps open up a lot of possibilities: building search indexes, computing analytics, migrating data between relays, auditing what a relay has seen, or simply archiving everything for offline analysis. BigBrotr’s Synchronizer service uses the same stream_events function internally for its cursor-based archiving pipeline — if it’s reliable enough for production ingestion at scale, it’ll work for your scripts too.

Inside BigBrotr: Building a Distributed Relay Observatory for the Nostr Network

Sat, 28 Feb 2026 00:00:00 GMT

If you’ve spent any time on Nostr, you’ve probably wondered: how many relays are actually out there? Which ones are healthy? What kind of events are flowing through them? There’s no central registry, no dashboard, no authority you can ask. Relays come and go, some are solid, some are broken, some lie about their capabilities.

BigBrotr exists to answer those questions. It’s a distributed system that discovers relays across clearnet, Tor, I2P, and Lokinet, monitors their health, archives the events they publish, and makes all of that data accessible through both a REST API and a native Nostr DVM interface.

This post walks through the architecture — not as a sales pitch, but as a technical deep dive into how the system is put together, what problems we ran into, and why certain decisions were made. If you like distributed systems, async Python, or PostgreSQL internals, there’s probably something here for you.

The project started in August 2025, funded by an OpenSats grant. It’s about ~18,000 lines of Python across 88 modules, ~2,955 tests (~2,739 unit + ~216 integration), 8 independent services, and 13 Docker containers. One person, start to finish.

The Problem

Nostr is decentralized. Thousands of relays are scattered across the globe on four different networks: clearnet (public internet), Tor (.onion), I2P (.i2p), and Lokinet (.loki). Nobody knows for certain how many relays exist, how healthy they are, or what events are being published through them.

BigBrotr tackles this through five pillars:

Relay Discovery — Finding relays automatically from external APIs, seed files, and mining URLs from event tags.
Relay Health Monitoring — Running 7 health checks per relay: NIP-11 info fetch, RTT latency (WebSocket open/read/write), SSL certificate inspection, DNS records, IP geolocation, network/ASN info, and HTTP headers.
Event Archiving — Connecting to relays via WebSocket and archiving events with cursor-based pagination, tracking progress per relay.
Analytics — 11 PostgreSQL materialized views pre-computing aggregate statistics (event distribution by kind, per-relay stats, author counts, NIP adoption, software distribution, daily time series). These views are the foundation for present and future analysis of the Nostr network.
Data Access — Two parallel interfaces exposing the same data: a REST API (FastAPI) for traditional HTTP clients, and a DVM (NIP-90 Data Vending Machine) for native Nostr clients over WebSocket.

All of this with full observability: Prometheus metrics for every service, pre-provisioned Grafana dashboards, AlertManager for alerting, postgres-exporter for DB metrics, and structured key=value logging with JSON output.

The system has to deal with:

Thousands of relays on 4 different networks with different proxies (SOCKS5 for Tor)
Relays with unpredictable behavior (malformed JSON, timeouts, expired certificates, unreliable self-reports)
Efficient deduplication of identical metadata across different relays (content-addressed SHA-256)
Bulk PostgreSQL operations (tens of thousands of inserts per cycle)
Publishing results back to the Nostr protocol itself (the monitor publishes NIP-66 relay discovery events readable by other Nostr clients)

High-Level Architecture — 8 Services, Zero Coupling

The Core Principle

All services share PostgreSQL as their sole communication channel. No service calls another directly — no RPC, no message queue, no shared memory. The database acts as an implicit event log.

                  ┌───────────────────────────────────────────────┐
                  │                PostgreSQL 16                  │
                  │      6 tables · 11 views · 25 procedures      │
                  └──┬───────────┬──────────┬───────────┬─────────┘
                     │           │          │           │
        ┌────────────┘           │          │           └──────────┐
        │                        │          │                      │
┌───────┴────────┐  ┌────────────┴───┐  ┌───┴───────────┐  ┌───────┴──────────┐
│ relay          │  │ relay          │  │ event         │  │ analysis &       │
│ discovery      │  │ monitoring     │  │ archive       │  │ access           │
│                │  │                │  │               │  │                  │
│ Seeder  (boot) │  │ Monitor        │  │ Synchronizer  │  │ Refresher (views)│
│ Finder  (disc) │  │  7 health      │  │  cursor-based │  │ Api       (http) │
│ Validator (ws) │  │  checks/relay  │  │  pagination   │  │ Dvm      (nostr) │
└────────────────┘  └────────────────┘  └───────────────┘  └──────────────────┘

Five pillars, eight services.

The Data Pipeline

Seeder (one-shot) — Bootstrap: loads relay URLs from a seed file as “candidates.”
Finder (recurring) — Discovers new relays from external APIs + mines URLs from tags in already-archived events. Inserts candidates.
Validator (recurring) — Picks up candidates, tests them with a WebSocket handshake. If a relay speaks proper Nostr protocol, it gets promoted to the relay table. If it fails, the error counter increments. After N consecutive failures, the candidate gets dropped.
Monitor (recurring) — For every validated relay, runs 7 health checks in parallel (NIP-11 info + 6 NIP-66 tests). Produces content-addressed metadata with SHA-256. Publishes relay discovery events (Kind 30166) back onto the Nostr network itself.
Synchronizer (recurring) — Connects to relays via WebSocket and archives events with cursor-based pagination. Tracks progress per relay.
Refresher (recurring) — Refreshes 11 materialized views in dependency order. Pre-computes aggregate statistics that power the API responses.
Api (continuous) — REST API with automatic schema discovery. Exposes all tables and materialized views with filtering, sorting, pagination. A parameterized query builder that prevents SQL injection by construction.
Dvm (continuous) — NIP-90 Data Vending Machine: responds to Nostr requests over WebSocket, exposing the same data as the API on the native Nostr protocol. Any Nostr client can query BigBrotr without HTTP.

Why the Database as Communication Channel

The good stuff:

Total decoupling: each service scales independently
Fault isolation: if Monitor goes down, Finder/Validator/Synchronizer keep running
Observability: all interactions are visible in the DB
Idempotency: upsert, insert-or-skip, atomic cascades
No additional infrastructure to maintain (no Redis, no RabbitMQ, no Kafka)

The conscious trade-off: higher inter-service latency compared to direct RPC. But that’s fine — this isn’t a real-time system. Services run on 1-5 minute cycles. The simplicity is worth it.

Package Architecture — The Diamond DAG

Imports flow strictly downward, enforced by ruff’s linter rules:

              services         ← Business logic (8 services)
             /   |   \
          core  nips  utils    ← Infrastructure, protocol, network primitives
             \   |   /
              models           ← Pure domain (zero I/O, frozen dataclasses)

This is a diamond DAG — services at the top, models at the bottom, three middle layers that can import from models and be imported by services, but never from each other. The DAG guarantees no circular imports and lets you use any subset of the package without pulling in unnecessary dependencies.

`models/` — Pure Domain, Immutable, Fail-Fast

The core principle here: no invalid object can exist. All validation happens in the constructor (__post_init__). If data is invalid, the constructor raises.

Every model follows the same pattern:

@dataclass(frozen=True, slots=True)
class Metadata:
    type: MetadataType
    data: Mapping[str, Any]

    # Computed fields, excluded from repr/compare/hash
    _canonical_json: str = field(default="", init=False, repr=False, compare=False)
    _content_hash: bytes = field(default=b"", init=False, repr=False, compare=False)
    _db_params: MetadataDbParams = field(default=None, init=False, repr=False, compare=False)

    def __post_init__(self) -> None:
        # 1. Validate
        validate_instance(self.type, MetadataType, "type")
        validate_mapping(self.data, "data")

        # 2. Sanitize (remove None, empty containers, null bytes)
        sanitized = sanitize_data(self.data, "data")

        # 3. Canonical JSON (sort_keys, compact separators, UTF-8)
        canonical = json.dumps(sanitized, sort_keys=True, separators=(",", ":"))

        # 4. SHA-256 hash of canonical JSON
        content_hash = hashlib.sha256(canonical.encode("utf-8")).digest()

        # 5. Deep freeze (recursive MappingProxyType) for total immutability
        object.__setattr__(self, "data", deep_freeze(sanitized))
        object.__setattr__(self, "_canonical_json", canonical)
        object.__setattr__(self, "_content_hash", content_hash)
        object.__setattr__(self, "_db_params", self._compute_db_params())

A few things worth noting:

frozen=True means the hash never changes after construction. You can safely use these as dict keys or set members.
object.__setattr__ is a documented workaround for setting computed fields in frozen dataclasses. It looks odd, but it’s the right way to do it.
deep_freeze() wraps dicts with MappingProxyType and lists with tuple. Trying metadata.data["key"] = "value" raises TypeError. The data is genuinely immutable, not just “please don’t mutate this.”
_db_params is cached: conversion to a NamedTuple (what asyncpg wants) happens once at construction time, not on every DB call.

Content-addressed deduplication is the key insight. Two relays reporting the same NIP-11 data produce the same SHA-256 hash → one row in the metadata table. The composite PK (id, type) allows the same hash for different types (which is valid — different data structures can hash to the same value, and we need to distinguish them).

Relay URL validation (relay.py) does full RFC 3986 parsing with the rfc3986 library, auto-detects network type (clearnet/tor/i2p/loki) from TLD and IP, rejects local addresses (26 IANA IPv4/IPv6 ranges), normalizes the scheme (wss:// for clearnet, ws:// for overlay networks that handle encryption themselves), and strips default ports.

“Never trust stored data” is a design invariant. Every constructor re-validates everything, even data that “should” already be validated. A Relay read from the DB gets re-parsed completely. A Metadata read from the DB gets its hash recomputed. If the data is corrupt, the constructor fails immediately. This catches a class of bugs that “trust the DB” approaches miss.

`core/` — Infrastructure and Lifecycle

Connection Pool (`pool.py`, 738 lines)

The asyncpg pool with configurable retry/backoff is one of the more carefully designed pieces:

5 nested Pydantic models for configuration: DatabaseConfig, LimitsConfig, TimeoutsConfig, RetryConfig, ServerSettingsConfig → aggregated in PoolConfig.
Password from environment variable (never in YAML): the password_env pattern with a @model_validator(mode="before") that resolves from os.getenv(). Pydantic’s SecretStr never appears in logs or repr.
Exponential vs linear backoff: configurable via boolean. 2^attempt vs (attempt + 1), both bounded by max_delay.
Async lock for thread-safe connection: prevents race conditions if multiple coroutines call connect() simultaneously. Idempotent — the second call returns immediately.
Error discrimination in retry: retry ONLY on transient errors (InterfaceError, ConnectionDoesNotExistError). Query errors (syntax, constraint violations) propagate immediately — this prevents infinite loops on bad SQL, which is a surprisingly common mistake in retry logic.
Fresh connection per retry attempt: each attempt acquires a new connection from the pool. If the previous one was broken mid-query, the new socket works.
Dual JSON codec: handles both pre-serialized JSON strings (from Metadata.canonical_json) and raw Python dicts. Without this, double serialization would corrupt the data silently.

DB Facade (`brotr.py`, 964 lines)

High-level facade wrapping all PostgreSQL stored procedures:

3-level cascading timeouts: asyncpg client-side (configurable per type: query=60s, batch=120s, cleanup=90s, refresh=unlimited) → PgBouncer query_timeout (300s safety net) → PostgreSQL statement_timeout. The tightest level wins. A runaway query doesn’t block other connections.
_call_procedure(): central private method that executes all stored procedures with the appropriate timeout, automatic retry, and parameter conversion.
Generic methods: fetch(), fetchrow(), fetchval(), execute(), transaction() — services use ONLY these, never the pool directly.

Service Lifecycle (`base_service.py`, 418 lines)

This combines Template Method + State Machine + Async Context Manager:

Bounded generics: BaseService[ConfigT] with ConfigT = TypeVar("ConfigT", bound=BaseServiceConfig) → mypy does type-narrowing of the config in derived services. Your service config is correctly typed everywhere.
run_forever() loop: the ONLY broad except Exception in the entire codebase. Documented and justified as the event loop boundary. CancelledError, KeyboardInterrupt, SystemExit always propagate.
Interruptible wait: wait(timeout) wraps asyncio.wait_for(event.wait()). The service wakes up immediately on shutdown signal, even with a 5-minute interval between cycles. Never asyncio.sleep() — it’s not interruptible.
Consecutive failure tracking: error counter that resets to 0 on success. If it exceeds max_consecutive_failures, the service exits. If set to 0, no limit.
Automatic Prometheus metrics: cycle duration, timestamp, successes, errors, error type — all wired in run_forever(), not in derived services.
Factory methods: from_yaml() and from_dict() use cls.CONFIG_CLASS for dynamic config parsing without boilerplate in services.

Structured Logging (`logger.py`, 249 lines)

Key=value logging with optional JSON output. format_kv_pairs() for consistent formatting. Integrated with Prometheus: every cycle log includes metrics.

Prometheus Metrics (`metrics.py`, 209 lines)

Four metric types: SERVICE_INFO (identity), SERVICE_GAUGE (per-cycle snapshot), SERVICE_COUNTER (cumulative), CYCLE_DURATION_SECONDS (histogram). HTTP server on port 8000 for scraping.

`nips/` — Protocol Layer with Graceful Degradation

The golden rule: NIP fetch methods never raise exceptions. Errors are captured in logs.success / logs.reason, allowing batch processing of hundreds of relays without individual error handling.

Declarative Parsing (`FieldSpec`)

@dataclass(frozen=True, slots=True)
class FieldSpec:
    int_fields: frozenset[str]       # Excludes bool (Python: bool is a subclass of int!)
    bool_fields: frozenset[str]
    str_fields: frozenset[str]
    str_list_fields: frozenset[str]  # list[str], invalid elements filtered out
    float_fields: frozenset[str]     # int or float → float
    int_list_fields: frozenset[str]  # list[int], bool excluded

Each data model declares a _FIELD_SPEC and the parse_fields() function applies type coercion with silent failure. Invalid or missing fields get skipped — because relay JSON is “garbage-in.” NIP implementations must never crash on corrupt data. The schema can be declared once and the parser handles the messy reality of the open internet.

NIP-11: Relay Info Fetch

HTTP(S) fetch with aiohttp, SOCKS5 proxy support for overlay networks
SSL strategy: verify first → fallback to CERT_NONE if allow_insecure is configured → error otherwise
Response limited to 64 KB, Content-Type validated (application/nostr+json or application/json)
Data parsed into Nip11InfoData (30+ fields: name, description, pubkey, supported NIPs, limitations, fees, retention policies)
Python reserved keyword handling: NIP-11 field "self" aliased to self_pubkey with populate_by_name=True

NIP-66: 6 Concurrent Health Tests

Six independent tests per relay, each producing a MetadataType:

Test	Type	I/O	Notes
RTT	`NIP66_RTT`	WebSocket open/read/write	3 sequential phases with cascading failure
SSL	`NIP66_SSL`	TCP socket (2 connections)	Clearnet only. Extracts with CERT_NONE, validates separately
DNS	`NIP66_DNS`	dnspython (thread pool)	A, AAAA, CNAME, NS, PTR records
Geo	`NIP66_GEO`	GeoIP2 City (thread pool)	Latitude, longitude, geohash (precision 9)
Net	`NIP66_NET`	GeoIP2 ASN	ASN, organization, CIDR. IPv4 takes priority over IPv6
HTTP	`NIP66_HTTP`	aiohttp TraceConfig	Captures headers from WebSocket upgrade handshake

The execution uses asyncio.gather(*tasks, return_exceptions=True):

results = await asyncio.gather(*tasks, return_exceptions=True)

for name, result in zip(task_names, results, strict=True):
    if isinstance(result, (asyncio.CancelledError, KeyboardInterrupt, SystemExit)):
        raise result  # Shutdown signals ALWAYS propagate
    if isinstance(result, BaseException):
        logger.error("test=%s error=%r", name, result)
        metadata_map[name] = None  # Failed test → None
    else:
        metadata_map[name] = result

One crashing test doesn’t kill the others. The operator sees in the log which test failed. The field is None in the result.

RTT — Cascading Failure Pattern: if the WebSocket open fails, read and write are automatically marked as failed with the same reason. No point testing read/write if the connection didn’t open.

RTT — Coroutine Factory for Retry: the retry pattern uses a coro_factory: Callable[[], Coroutine] because Python coroutines are single-use. Once awaited, they can’t be re-awaited. The retry creates a fresh coroutine on each attempt:

async def _with_retry(self, coro_factory, retry_config):
    for attempt in range(retry_config.max_attempts):
        result = await coro_factory()
        if result is not None:
            return result
        delay = min(retry_config.initial_delay * (2 ** attempt), retry_config.max_delay)
        jitter = random.uniform(0, retry_config.jitter)
        await asyncio.sleep(delay + jitter)
    return None

Exponential backoff + jitter decorrelates concurrent retries, preventing thundering herd when multiple relays fail simultaneously.

SSL — Two-Connection Methodology: Connection 1 with CERT_NONE to extract the certificate even from invalid/self-signed chains. Connection 2 with default context to validate the chain. This lets us monitor relays with expired certificates — monitoring should see the state, not just valid certs.

Dependency Injection for Optional Features: if GeoIP databases aren’t available, Geo/Net tests are silently skipped. If signing keys aren’t configured, the RTT test is skipped. Same code handles deployments with and without optional features.

Event Builders: Ground Truth > Self-Report

When building discovery event tags (Kind 30166), NIP-66 probe results (ground truth) override NIP-11 self-reports:

if write_success is True:
    # Probe wrote successfully without auth/payment → relay is open
    auth = False
    payment = False
elif write_success is False and write_reason:
    # Probe failed → trust the reason, supplement with NIP-11
    auth = bool("auth" in write_reason or nip11_auth)
    payment = bool("pay" in write_reason or nip11_payment)
else:
    # No probe result → NIP-11 is all we have
    auth = bool(nip11_auth)
    payment = bool(nip11_payment)

Relays can lie about auth/payment requirements. The NIP-66 probe result is authoritative.

`utils/` — Network Primitives

DNS: A/AAAA resolution with dnspython, executed in thread pool via asyncio.to_thread() to avoid blocking the event loop
Transport: WebSocket/HTTP with SSL fallback, InsecureWebSocketTransport for overlay networks, configurable DEFAULT_TIMEOUT
Keys: load_keys_from_env() loads Nostr keys from environment variables, KeysConfig Pydantic model with validation
Protocol: create_client(), connect_relay(), broadcast_events(), is_nostr_relay() — all Nostr operations wrapped with error handling

`services/` — Business Logic

Let me go through each service briefly, highlighting what makes each one interesting.

Seeder (111 lines) — Bootstrap

One-shot parsing of a seed file (one URL per line). Validates each URL → Relay object. Inserts as candidates or directly as relays. No retry, no cycle. restart: no in Docker Compose. It runs once and exits.

Finder (398 lines) — Multi-Source Discovery

Two discovery sources:

Event Mining: for each relay in the DB, scans events archived by Synchronizer looking for relay URLs in tags. Uses composite cursors (seen_at, event_id) for deterministic pagination. Cursors are persisted in the DB — if Finder restarts, it resumes where it left off.
External APIs: HTTP GET on configurable endpoints (e.g., Nostr aggregator APIs). Parsing with JMESPath to extract URLs from arbitrary JSON structures.

Concurrency via asyncio.TaskGroup + semaphore to limit parallel event scans per relay.

Validator (237 lines) — WebSocket Handshake Test

Cycle: cleanup stale → cleanup exhausted → validate.

Priority queue: candidates ordered by (failures ASC, updated_at ASC) — those with fewer failures get priority
Per-network semaphores: Tor gets fewer simultaneous connections than clearnet
Atomic promotion: promote_candidates() = insert_relay() + DELETE service_state CANDIDATE in a single operation
Per-cycle budget: configurable max_candidates; the validator processes at most N candidates per cycle
allow_insecure: configurable SSL fallback for relays with invalid certificates

Monitor (669 lines) — The Most Complex Service

Quadruple mixin composition:

class Monitor(
    ConcurrentStreamMixin,    # TaskGroup + Queue streaming
    NetworkSemaphoresMixin,   # Per-network semaphores
    GeoReaderMixin,           # GeoIP database lifecycle
    ClientsMixin,             # Managed Nostr client pool
    BaseService[MonitorConfig],
):

Cooperative initialization via MRO: super().__init__(**kwargs) in every mixin. The method resolution order handles the initialization chain automatically.

The run() cycle:

Update GeoIP databases (download if missing/expired)
Open GeoIP readers (in thread pool — blocking I/O)
Publish profile (Kind 0) if due (configurable interval)
Publish monitor announcement (Kind 10166) if due
For each relay (ordered by “least recently checked”):
- Acquire per-network semaphore
- NIP-11 fetch with retry
- NIP-66 RTT with retry (can apply PoW if relay requires min_pow_difficulty)
- 5 NIP-66 tests in parallel with retry
- Return CheckResult (NamedTuple with 7 nullable fields)
Publish discovery events (Kind 30166) for relays with data
Persist metadata (atomic cascade) + monitoring state
Close GeoIP readers

Publication interval state management: the monitor uses the service_state table with type PUBLICATION to track when it last published each event type. If the interval hasn’t elapsed, it skips publishing. This prevents publishing the same event thousands of times per hour.

Synchronizer (449 lines) — Event Archiving with Binary-Split Windowing

Relay shuffle: random.shuffle() prevents thundering herd when multiple instances hit the same relays in the same order
Cursor-based resumption: per-relay cursor {last_synced_at: timestamp} in the DB. On restart, resumes where it left off.
Binary-split windowing: data-driven time windows with completeness verification. If a relay’s response appears incomplete, the window is split in half and retried — ensuring no events are missed even from high-volume relays.
Per-relay overrides: custom timeouts for high-traffic relays
Event validation: signature verification (evt.verify()), temporal bounds, null bytes. Invalid events counted but not inserted.
allow_insecure: configurable SSL fallback for relays with invalid certificates, same as Validator and Dvm.

Refresher (92 lines) — The Simplest

Sequential, no parallelism. For each view in the configured list: REFRESH MATERIALIZED VIEW CONCURRENTLY view_name. One view failing doesn’t block the others.

Api (389 lines) — Dynamic REST API

Automatic schema discovery: on startup, queries information_schema and pg_catalog to discover tables, columns, PKs, unique indexes. Generates endpoints automatically for each enabled table.
Parameterized query builder: filters (col=value, col=>=:100, col=ILIKE:%pattern%), sorting, pagination. Operator whitelist. Type transforms for bytea (hex), timestamp (text), numeric (float).
CatalogError: client-safe exception that never exposes raw DB errors. Controlled messages or validated identifiers only.
Offset limit: 100,000 max to prevent deep pagination abuse.
Middleware: request/response logging, timing, status code tracking, configurable CORS.

Dvm (396 lines) — Nostr Data Vending Machine (NIP-90)

NIP-90 protocol: listens for Kind 5050 requests via WebSocket, responds with results (Kind 6050) or errors (Kind 7000) on the Nostr network
Same Catalog as API: uses the same query builder for consistency
Request deduplication: in-memory set (flushed at 10K) + temporal since window to prevent duplicate processing
Per-table pricing: each table can have a price in millisatoshi. If the bid is insufficient, publishes payment_required (Kind 7000)
NIP-89 announcement: on startup publishes Kind 31990 with available tables

`services/common/` — Shared Code

Query Functions (1,012 lines total across 6 modules): domain SQL queries are distributed across service-specific queries.py modules (monitor 248, finder 260, validator 241, synchronizer 98, seeder 29) plus a shared common/queries.py (136 lines). Parameterized $1/$2 placeholders (never f-strings for values). Timeouts from config. Batching via _batched_insert() that splits records into chunks of max_size. Composite cursors for deterministic pagination.

Mixins (423 lines, 5 cooperative mixins):

ConcurrentStreamMixin: _iter_concurrent() with asyncio.TaskGroup + asyncio.Queue streaming — results are yielded as workers complete, not buffered until all finish.
NetworkSemaphoresMixin: maps NetworkType → asyncio.Semaphore. Different networks get different concurrency. LOCAL/UNKNOWN return None (no concurrency limiting).
GeoReaderMixin: GeoIP2 database lifecycle (opening in thread pool via asyncio.to_thread(), synchronous close). Idempotent — opening or closing twice is safe.
ClientsMixin: managed Nostr client pool with per-relay proxy URL resolution, auto-configured from MonitorConfig.
CatalogAccessMixin: schema discovery + table access policy, used by Api and Dvm for safe parameterized queries.

Catalog (532 lines): the safe query builder shared between Api and Dvm. Schema discovery via information_schema + pg_catalog. Whitelist-by-construction: only tables/columns discovered from the DB can be used. Type transforms. Operator validation. CatalogError for client-safe errors.

Extensibility and Reusability — The Hardest Challenge

The most complex part of the project wasn’t implementing individual services. It was designing a system that works both as a deployable application and as a reusable Python library, and that can be extended without modifying existing code.

BigBrotr as a Python Library

The package is designed for independent use at any level of the DAG:

# Just relay URL validation (models, zero I/O)
from bigbrotr.models import Relay, NetworkType
relay = Relay("wss://relay.damus.io")  # Validates, parses, detects network

# Just DB infrastructure (core)
from bigbrotr.core import Brotr, Pool
brotr = Brotr.from_dict({"pool": {"database": {...}}})

# Just health checking a relay (nips, I/O)
from bigbrotr.nips import Nip11, Nip66
nip11 = await Nip11.create(relay)
nip66 = await Nip66.create(relay, selection=Nip66Selection(dns=False))

# Full service with lifecycle, metrics, logging
from bigbrotr import Monitor

The package’s __init__.py exposes 32 symbols with lazy loading: imports happen only on first access, reducing startup time for consumers who use only a subset. The diamond DAG guarantees you can import any subset without unnecessary dependencies and without circular imports.

Adding a New Service — Minimal Boilerplate

A new service requires only ~50 lines of code and 4-5 files. You write just the business logic; all infrastructure is “free”:

from bigbrotr.core.base_service import BaseService, BaseServiceConfig

class MyConfig(BaseServiceConfig):
    batch_size: int = 100

class MyService(BaseService[MyConfig]):
    SERVICE_NAME = ServiceName.MYSERVICE
    CONFIG_CLASS = MyConfig

    async def run(self) -> None:
        relays = await fetch_all_relays(self._brotr)
        # ... business logic ...

Registration: one line in the SERVICE_REGISTRY in __main__.py + a YAML config file. Then python -m bigbrotr myservice --config config/services/myservice.yaml.

What you get for free:

Feature	Provided by	Notes
YAML config parsing	`BaseService.from_yaml()`	Standard Pydantic fields
Structured logging	`self._logger`	key=value with JSON output
Prometheus metrics	`SERVICE_COUNTER`, `GAUGE`	`/metrics` endpoint on port 8000
Graceful shutdown	`run_forever()`	SIGINT/SIGTERM → clean shutdown
Failure tracking	`run_forever()`	Consecutive error counter
DB access	`self._brotr`	Pool, queries, transactions, stored procedures
Connection pooling	`Pool`	Retry/backoff, health-checked acquisition
Run/wait cycle	`run_forever()`	Configurable interval, interruptible wait

You don’t have to manage connections, logging, metrics, shutdown, or retry — the framework handles all of it. Your service just implements async def run().

Adding New NIPs and MetadataTypes — The Hardest Part

This was the most complex architectural challenge: modeling the nips/ layer with robust validation that doesn’t block future extensions.

The problem: today BigBrotr supports 7 metadata types (NIP-11 info + 6 NIP-66 tests). Tomorrow someone might want to add NIP-66 DNSSEC, or an entirely new NIP (e.g., NIP-XX for content analysis). The model must accommodate new types without modifying existing code and without database migrations.

The solution is a 3-level forward-compatible schema.

Level 1 — Database: the metadata table accepts any string as type. Adding NIP66_DNSSEC requires no ALTER TABLE. Content is free-form JSONB. The SHA-256 hash is computed in Python, not in the DB. Existing code ignores unknown types.

Level 2 — Python Models: MetadataType is a StrEnum. Adding a member is one line:

class MetadataType(StrEnum):
    NIP11_INFO = "nip11_info"
    NIP66_RTT = "nip66_rtt"
    # ...
    NIP66_DNSSEC = "nip66_dnssec"  # NEW: one line, zero breaking change

The Metadata model is agnostic about the internal data structure. It accepts any Mapping[str, Any], sanitizes it, serializes to canonical JSON, and computes the hash. The same model works for NIP-11, NIP-66, and any future NIP without modifications.

Level 3 — NIP Implementation: every NIP follows the BaseNip contract:

class BaseNip:
    @classmethod
    async def create(cls, relay, **kwargs) -> Self:
        """Async factory. NEVER raises exceptions."""
        ...

    def to_relay_metadata_tuple(self) -> tuple[RelayMetadata | None, ...]:
        """Converts results to DB-ready records."""
        ...

Adding a new NIP-66 test requires:

A StrEnum member in MetadataType (1 line)
A frozen data model with _FIELD_SPEC for declarative parsing (~30 lines)
An execute() method with the I/O logic (~50 lines)
A field in Nip66Selection to enable/disable (1 line)
A field in the Nip66 orchestrator (1 line)

The Monitor doesn’t change. It calls Nip66.create() and iterates over results. New tests appear automatically because the Monitor has no switch/case on types — it uses to_relay_metadata_tuple() which returns all results (those that are None get skipped).

The Selection/Options/Dependencies pattern lets you add parameters without changing signatures:

Selection: which tests to run (boolean flag per type)
Options: how to run them (e.g., allow_insecure for SSL)
Dependencies: what’s available (Nostr keys, GeoIP databases)

If a dependency is None, the test is silently skipped — same code handles deployments with and without optional features.

Configurable Deployments — Zero Code

Everything is configurable via YAML without touching a single line of code:

Pool: size, timeouts, retry, backoff strategy
Services: enabled networks (clearnet/tor/i2p/loki), per-network concurrency, proxy URLs, batch size, intervals, limits, cleanup thresholds
Monitor: enabled checks, retry config per test, publication intervals, GeoIP database paths
Synchronizer: per-relay timeout overrides, temporal ranges, event filters
Api/Dvm: exposed tables, pagination limits, CORS, per-table pricing

Creating a new deployment requires zero code:

Copy deployments/bigbrotr/ to deployments/mydeployment/
Edit the YAML config files
Optionally customize the event table schema (the only table with a variable schema — from a minimal id-only version to the full version with all fields)
docker compose up — the parametric Dockerfile (ARG DEPLOYMENT) handles everything

The result: you can have N different deployments of the same codebase, each with a different schema, different ports, different configurations — and zero code duplication.

Backward Compatibility by Design

The fundamental principle: extend, never modify.

New MetadataType → the DB accepts it without migration, existing code ignores it
New services → hook into the existing framework, use the same queries, same pool, same lifecycle
New NIPs → follow the BaseNip contract, the Monitor orchestrates them transparently
New deployments → same Dockerfile, same CI, just different config

This means you can build heavy, complex services on top of the BigBrotr infrastructure without having to modify it. You get a managed pool, DB facade, logging, metrics, lifecycle, and a validated and immutable domain model — all ready to go.

Database Schema

Core Tables (6)

-- Relay: identity + network
CREATE TABLE relay (
    url TEXT PRIMARY KEY,
    network TEXT NOT NULL,
    discovered_at BIGINT NOT NULL
);

-- Event: complete Nostr event
CREATE TABLE event (
    id BYTEA PRIMARY KEY,
    pubkey BYTEA NOT NULL,
    created_at BIGINT NOT NULL,
    kind INTEGER NOT NULL,
    tags JSONB NOT NULL,
    tagvalues TEXT[] GENERATED ALWAYS AS (tags_to_tagvalues(tags)) STORED,
    content TEXT NOT NULL,
    sig BYTEA NOT NULL
);

-- Junction: which event was seen on which relay
CREATE TABLE event_relay (
    event_id BYTEA REFERENCES event(id),
    relay_url TEXT REFERENCES relay(url),
    seen_at BIGINT NOT NULL,
    PRIMARY KEY (event_id, relay_url)
);

-- Metadata: content-addressed (SHA-256 hash)
CREATE TABLE metadata (
    id BYTEA NOT NULL,
    type TEXT NOT NULL,
    data JSONB NOT NULL,
    PRIMARY KEY (id, type)
);

-- Time-series junction: health check history per relay
CREATE TABLE relay_metadata (
    relay_url TEXT REFERENCES relay(url),
    metadata_id BYTEA,
    metadata_type TEXT,
    generated_at BIGINT NOT NULL,
    PRIMARY KEY (relay_url, generated_at, metadata_type),
    FOREIGN KEY (metadata_id, metadata_type) REFERENCES metadata(id, type)
);

-- Generic key-value store for service state
CREATE TABLE service_state (
    service_name TEXT,
    state_type TEXT,
    state_key TEXT,
    state_value JSONB NOT NULL DEFAULT '{}',
    updated_at BIGINT NOT NULL,
    PRIMARY KEY (service_name, state_type, state_key)
);

Schema Design Decisions

tagvalues as GENERATED ALWAYS STORED: computed column, calculated once on INSERT. Feeds a GIN index for containment queries (WHERE tagvalues @> ARRAY['<id>']). Avoids recalculation on every query.

Composite FK in relay_metadata: (metadata_id, metadata_type) references metadata(id, type). Maintains referential integrity on the pair, not just the hash.

Composite PK in relay_metadata: (relay_url, generated_at, metadata_type). Each relay can have many instances of each metadata type over time — it’s a time-series of health checks.

service_state as generic store: 3-field PK (service_name, state_type, state_key). Each service uses it differently: Finder for cursors, Validator for candidates, Monitor for last-check timestamps, Synchronizer for sync cursors. Zero schema migration when adding a new state type.

Stored Procedures (25)

Level 1 — Single operations: relay_insert(), event_insert(), metadata_insert(), service_state_upsert(). All accept bulk arrays (UNNEST($1::text[], $2::text[], ...)) for batch insertion.

Level 2 — Atomic cascades:

event_relay_insert_cascade(): in a single SQL call, inserts relay (if not exists) + event (if not exists) + junction. DISTINCT ON (event_id, relay_url) for intra-batch deduplication. Atomic.
relay_metadata_insert_cascade(): relay + metadata + junction in one call.

Why two levels: Synchronizer can use event_relay_insert() when events already exist, or the cascade when discovering new relays with new events.

Batched cleanup: orphan_metadata_delete() and orphan_event_delete() remove orphaned records in batches of 10,000 to limit lock duration.

Materialized Views (11)

Pre-compute aggregate statistics so the API doesn’t need expensive JOINs at runtime:

relay_metadata_latest — Latest snapshot per relay/type (DISTINCT ON pattern)
event_stats — Global event counts (singleton with singleton_key)
relay_stats — Per-relay stats with LATERAL join for average RTT from last 10 measurements
kind_counts — Distribution by event kind
kind_counts_by_relay — Distribution by relay
pubkey_counts — Global author activity
pubkey_counts_by_relay — Per-relay author activity (HAVING COUNT >= 2)
network_stats — Aggregate by network type
relay_software_counts — Relay software distribution (from NIP-11)
supported_nip_counts — NIP adoption (CROSS JOIN LATERAL jsonb_array_elements)
event_daily_counts — Daily time-series (UTC dates)

Refresh strategy: REFRESH MATERIALIZED VIEW CONCURRENTLY requires a unique index on each view. The Refresher updates them in dependency order (3 levels).

Indexes (31)

Strategically placed to support the query patterns of each service:

7 on event: timeline (DESC), by kind, by author, compound (author + kind + timeline), GIN on tagvalues, cursor-based pagination (ASC)
3 on event_relay: by relay, by timestamp, compound for index-only scan
3 on relay_metadata: by timestamp, compound FK, latest-per-type
3 on service_state: by service, by type, expression index on JSON for Validator
15 on materialized views: unique indexes required for CONCURRENTLY

Deployment Infrastructure

Docker: 13 Containers on 2 Networks

# Network isolation
networks:
  bigbrotr-data-network:        # PostgreSQL + services
  bigbrotr-monitoring-network:  # Prometheus + Grafana + AlertManager

Container	Role
postgres	Primary database (PostgreSQL 16)
pgbouncer	Connection pooling (transaction mode)
tor	SOCKS5 proxy for .onion relays
seeder	Bootstrap (one-shot, `restart: no`)
finder	Relay discovery
validator	WebSocket validation
monitor	NIP-11 + NIP-66 health checks
synchronizer	Event archiving
refresher	Materialized view refresh
api	REST API (FastAPI)
dvm	Nostr DVM (NIP-90)
postgres-exporter	PostgreSQL metrics for Prometheus
prometheus	Metrics collection (30 day retention)
alertmanager	Alert routing
grafana	Visualization dashboards

Plus I2P and Lokinet as optional containers (commented out but documented for enablement).

Dependency graph: PgBouncer depends on PostgreSQL (service_healthy). All services depend on PgBouncer + Tor (service_healthy). Grafana depends on Prometheus.

Health checks: PostgreSQL uses pg_isready. BigBrotr services use /metrics (port 8000). Api uses /health (port 8080). Prometheus and Grafana use their native endpoints.

Parametric Multi-Stage Dockerfile

A single Dockerfile serves 2 deployment variants (bigbrotr and lilbrotr):

Stage 1 (Builder): python:3.11.14-slim base, uv from ghcr.io/astral-sh/uv:0.10.2 (fast, deterministic build tool), layer caching with dependencies separated from source code, BuildKit cache mounts to avoid re-downloading.

Stage 2 (Production): non-root user (UID 1000, name = deployment), runtime-only libraries (libpq5, libsecp256k1-dev), pip/setuptools removed from base image (reduced attack surface), tini as PID 1 (proper signal handling, no zombie processes), explicit STOPSIGNAL SIGTERM, config copied from specific deployment.

PgBouncer

Connection pooler in front of PostgreSQL. Connection multiplexing to reduce DB load. Password templating via custom entrypoint. 300s safety net timeout.

Monitoring Stack

Prometheus (v2.51.0): scraping every 30s from all services + postgres-exporter. 30-day TSDB retention. 7 alert rules covering service health, failure rates, cycle performance, database connections, cache hit ratios, and view refresh failures.
AlertManager (v0.27.0): grouping by alertname/service. Critical alerts repeated every 1h, normal every 4h.
Grafana (10.4.1): automatic datasource + dashboard provisioning. Zero manual setup.
postgres-exporter (v0.16.0): PostgreSQL metrics (connections, cache hit ratio, table stats).

CI/CD Pipeline

GitHub Actions (306 lines)

Trigger: push/PR on main/develop (excludes docs, README)

┌─────────────────────────────────────────────┐
│ pre-commit (10 min)                         │
│ ruff, mypy, pre-commit hooks                │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┼────────────────────────────────┐
       │       │                                │
       ▼       ▼                                ▼
  unit-test   integration-test               docs
  (matrix     (testcontainers PG)            (mkdocs
   3.11-3.14)  (10 min)                      --strict)
  (15 min)                                   (5 min)
  (codecov)
       │       │                                │
       └───────┼────────────────────────────────┘
               │
               ▼
           build (main/develop only)
           (matrix: bigbrotr/lilbrotr)
           (Trivy security scan)
           (SARIF → GitHub Security)
           (20 min)
               │
               ▼
           ci-success (gate for branch protection)

Key details:

Unit test matrix: Python 3.11, 3.12, 3.13, 3.14 (pre-release, allowed to fail)
SQL drift detection: tools/generate_sql.py --check verifies SQL templates match generated files
Dependency audit: uv-secure uv.lock for known vulnerabilities
Trivy scan: gates on CRITICAL/HIGH, reports MEDIUM. SARIF uploaded to GitHub Security tab.
Concurrency: one run per branch; new pushes cancel previous runs.

Pre-commit Hooks (23 hooks)

File hygiene: trailing-whitespace, end-of-file-fixer, check-yaml/json/toml, check-large-files (max 1MB), detect-private-key, mixed-line-ending (LF)
Python: ruff (lint + format), mypy (strict on src/)
SQL: sqlfluff (PostgreSQL dialect)
Security: detect-secrets with baseline
Dependency: uv-lock (verifies pyproject.toml ↔ uv.lock sync)
Docker: hadolint
Markdown: markdownlint-cli
Spell check: codespell

Recurring Architectural Patterns

A few patterns show up everywhere in the codebase. Recognizing them makes it easier to understand any part of the system.

Content-Addressed Deduplication: identical data → same SHA-256 hash → one row in the DB. Trades CPU (Python hashing) for reduced storage and disk I/O. The bottleneck is network, not CPU, so this is a good trade.

Cascade Atomicity: stored procedures that insert across multiple tables in a single SQL call. Referential integrity guaranteed even on connection failure.

Never-Raising Factories: NIP fetch methods always return a result (with logs.success indicating success/failure). Enables batch processing without individual try/catch.

Interruptible Wait: asyncio.wait_for(event.wait(), timeout) for cycles with immediate shutdown. Never bare asyncio.sleep() (not interruptible).

Per-Network Semaphores: different concurrency for clearnet, Tor, I2P, Lokinet. Configurable, zero magic numbers.

Cooperative Multiple Inheritance: mixins with super().__init__(**kwargs) via MRO. No manual _init_*() calls.

Layered Timeouts: asyncpg → PgBouncer → PostgreSQL. Three independent levels, the tightest wins.

Coroutine Factory for Retry: Python coroutines are single-use. Retry creates a fresh coroutine on each attempt.

Declarative Parsing: FieldSpec + parse_fields() for type-safe parsing of untrusted JSON. Silent failure for invalid fields.

Ground Truth > Self-Report: NIP-66 probe results are authoritative over NIP-11 relay self-reports.

Conscious Trade-offs

Every architectural decision is a trade-off. Here are the ones that mattered most and why we landed where we did:

Decision	Upside	Downside	Reasoning
DB as inter-service channel	Decoupling, fault isolation, observability	Higher latency than RPC	Not real-time; 1-5 min cycles are fine
Content-addressed dedup	Less storage, less disk I/O	CPU for hashing in Python	Network is the bottleneck, not CPU
Materialized views	Fast API queries, zero JOINs at runtime	Slightly stale data (periodic refresh)	Analytics don’t need real-time data
Frozen dataclasses	Correctness, thread-safety, stable hash	`object.__setattr__` verbosity	Correctness > ergonomics
Stored procedures for mutations	Atomicity, fewer roundtrips, logic in DB	More complex SQL, two languages	Acceptable trade for data integrity
`ws://` for overlay, `wss://` for clearnet	Overlay handles encryption; no TLS overhead	Non-uniform scheme	Semantically correct: TLS is redundant on Tor
No message queue	Less infrastructure to maintain	No native backpressure	DB + semaphores are sufficient for this workload

By the Numbers

Dimension	Value
Source code	~18,000 lines Python, 88 modules
Tests	~2,739 unit + ~216 integration (~2,955 total)
SQL	1,759 lines, 10 init files
Services	8 independent
Stored procedures	25
Materialized views	11
Indexes	31 (16 table + 15 matview)
Docker containers	13 (+ 2 optional)
Core dependencies	18
Dev dependencies	18
Pre-commit hooks	23
Coverage	80% branch coverage (enforced)

Closing Thoughts

BigBrotr started as “let’s index some Nostr relays” and turned into a distributed system with 8 services, 25 stored procedures, 11 materialized views, and a monitoring stack that could probably run a small startup.

The most important lesson was resisting the urge to solve future problems today. The forward-compatible schema wasn’t designed on day one — it evolved from real pain points when adding the second and third metadata type. The mixin system emerged when Monitor’s __init__ hit 40 lines. The configurable deployments came from actually needing two different setups.

Every pattern in this codebase exists because of a real problem, not because it looked good on a whiteboard. That’s the difference between architecture and architecture astronautics.

If you want to explore the code, it’s all open source. Questions, feedback, and contributions are welcome.

Welcome to BigBrotr

Thu, 15 Jan 2026 00:00:00 GMT

BigBrotr is a relay observatory for the Nostr network. It discovers relays across four networks, monitors their health with NIP-11 and NIP-66 checks, archives events, pre-computes analytics through materialized views, and exposes everything through a REST API and a native Nostr Data Vending Machine.

What We Built

BigBrotr tackles the Nostr network through five pillars:

Discovery — find relays across clearnet, Tor, I2P, and Lokinet using seed files, external APIs, and event tag mining
Monitoring — 7 health checks per relay: NIP-11 info fetch, RTT latency (WebSocket open/read/write), SSL certificate inspection, DNS records, IP geolocation, network/ASN info, and HTTP headers
Archiving — cursor-based event synchronization with binary-split windowing for completeness verification
Analytics — 11 materialized views pre-computing aggregate statistics refreshed concurrently by a dedicated service
Data Access — REST API (FastAPI) for HTTP clients and a NIP-90 Data Vending Machine for native Nostr clients over WebSocket

Architecture

The system follows a diamond DAG dependency structure — imports flow strictly downward, enforced by linter rules:

models — pure frozen dataclasses with fail-fast validation, content-addressed deduplication (SHA-256), zero I/O
core — asyncpg connection pool with retry/backoff, database facade (Brotr) wrapping 25 stored procedures, base service with lifecycle management
nips — NIP-11 relay information fetch with graceful degradation, NIP-66 health monitoring (6 concurrent tests per relay)
utils — DNS resolution, HTTP/WebSocket transport with SSL fallback, Nostr key management, relay protocol helpers
services — eight independent services communicating exclusively through PostgreSQL

Eight Services

Each service runs independently — no direct service-to-service dependencies, all communication via the database:

Service	Role	Description
Seeder	Bootstrap	One-shot: loads relay URLs from seed files as candidates
Finder	Discovery	Discovers relays from external APIs and mines URLs from archived event tags
Validator	Validation	Tests WebSocket connectivity, promotes candidates to validated relays
Monitor	Health	NIP-11 info + 6 NIP-66 tests per relay, publishes results to the Nostr network
Synchronizer	Archiving	Cursor-based event collection with binary-split windowing and per-relay progress
Refresher	Analytics	Refreshes 11 materialized views concurrently in dependency order
Api	HTTP access	FastAPI REST API with automatic schema discovery, filtering, sorting, pagination
Dvm	Nostr access	NIP-90 Data Vending Machine: responds to Nostr job requests over WebSocket

Get Started

Check out the Quick Start guide to run BigBrotr with Docker Compose, or read the full technical deep dive for a comprehensive look at the architecture and design decisions.

The full source code is available on GitHub under the MIT license.

BigBrotr | Blog

Dead Keys: The Unsolved Problem of Marking Compromised Nostr Identities

The Constraint Nobody Can Work Around

Why Every Obvious Solution Fails

Self-reporting with the leaked key

Kind 5 against kind 5

A compromise tag on kind 0

NIP-56 Reporting (kind 1984)

NIP-32 Labeling (kind 1985)

NIP-58 Badges (kind 8)

NIP-62 Request to Vanish (kind 62)

What the Solutions Have in Common

What Could Actually Work

NIP-85 (kind 30382) + embedded proof tag

Why false flags are not a real risk

The discovery problem

What Needs to Happen Next

Self-Hosting BigBrotr: From Bare Metal to Production in One Afternoon

The Hardware

Why ZFS?

The VM Architecture

PostgreSQL Tuning — It’s Mostly About RAM

Zero-Port API Exposure with Cloudflare Tunnel

Security Layers

The Production Deployment Folder

What It Looks Like Running

Lessons From the First Boot

Backups

What’s Next

Uncovering Exposed Private Keys Across the Nostr Network

Searching for nsec Strings

The Headline Number Is Noise

From 16,599 to 38

Who Leaked the Keys?

Authorship

Leak vectors weighted by social reach

How many leaked keys have social presence?

The Organic Leak Rate

Relay Spread

The 38 Accounts That Need to Know

Check If Your Key Is Exposed

What Clients and Relay Operators Can Do

Limitations

Methodology

BigBrotr vs Pensieve: Two Approaches to Indexing the Nostr Network

The Core Question

How They Fetch Events

BigBrotr: Systematic Crawling

Pensieve: Live Subscription

The Trade-off

Architecture

BigBrotr: Eight Independent Services, One Database

Pensieve: Pipeline with Archive as Source of Truth

Storage

BigBrotr: One Database, Full Relational Model

Pensieve: Five Storage Engines

Relay Management

BigBrotr: Deep Health Profiling

Pensieve: Coverage-Optimized Relay Rotation

Analytics and Data Access

BigBrotr: SQL + REST API + Nostr DVM

Pensieve: ClickHouse + REST API + Preview Pages

Network Support

Engineering and Operations

Monitoring

Deployment

Testing and CI/CD

NIP Support

Trade-offs and Limitations

Complementary, Not Competing

Building a Nostr Relay Monitor with BigBrotr

Everything, or Just What You Need

The Code

NIP-11: Relay Information

NIP-66: Six Concurrent Health Checks

RTT (Round-Trip Time)

SSL (Certificate Inspection)

DNS (Resolution)

Geo (Geolocation)

Net (Network/ASN)

NIP-85 (kind 30382) + embedded `proof` tag

`stream_events`: Zero Stress

`models/` — Pure Domain, Immutable, Fail-Fast

`core/` — Infrastructure and Lifecycle

Connection Pool (`pool.py`, 738 lines)

DB Facade (`brotr.py`, 964 lines)

Service Lifecycle (`base_service.py`, 418 lines)

Structured Logging (`logger.py`, 249 lines)

Prometheus Metrics (`metrics.py`, 209 lines)

`nips/` — Protocol Layer with Graceful Degradation

Declarative Parsing (`FieldSpec`)

`utils/` — Network Primitives

`services/` — Business Logic

`services/common/` — Shared Code