From 7335771c572759ff32902223586af5d1de55d384 Mon Sep 17 00:00:00 2001
From: Clawd <ai@clawd.bot>
Date: Fri, 20 Feb 2026 19:33:56 -0800
Subject: docs: rewrite README with honest disclaimers

---
 README.md | 41 +++++++++++++++--------------------------
 1 file changed, 15 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 8d42710..77eea61 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # nostr
 
-A minimal Go library for the [Nostr protocol](https://github.com/nostr-protocol/nostr).
+A zero-dependency Go library for the [Nostr protocol](https://github.com/nostr-protocol/nostr).
 
 ```bash
 go get code.northwest.io/nostr
@@ -8,43 +8,32 @@ go get code.northwest.io/nostr
 
 ## Why This Library?
 
-**Zero dependencies.**
+You probably shouldn't use it.
 
-Other Nostr libraries pull in 30+ dependencies. This one has none. The secp256k1 cryptography is implemented in pure Go, embedded in the library.
+This library rolls its own secp256k1 cryptography in pure Go. No CGO, no external dependencies, no nothing. I built it to see if it was possible to implement Nostr with truly zero dependencies. It is. But that doesn't mean it's a good idea.
 
-```
-require (nothing)
-```
+**What you get:**
+- Zero external dependencies
+- Fully auditable pure-Go crypto
+- Passes all BIP-340 test vectors
+- Works fine for normal Nostr usage
+
+**What you're giving up:**
+- Constant-time operations (timing attacks are theoretically possible)
+- Performance (~10x slower than btcec)
+- Battle-tested crypto code
 
-No external crypto libraries, no WebSocket libraries, no logging frameworks, no kitchen sink. Just the core protocol.
+If you're building something serious, use a library backed by btcec. If you're hacking on a side project or just want to read the code, welcome.
 
 ## What's Included
 
 - **Keys** — Generate, parse, sign, verify (hex and bech32/npub/nsec)
 - **Events** — Create, serialize, sign NIP-01 events  
 - **Filters** — Build and match subscription filters
-- **Relay** — WebSocket pub/sub (stdlib `net/http` only)
+- **Relay** — WebSocket pub/sub (stdlib only)
 - **Tags** — Parse and build event tags
 - **Envelopes** — Protocol message parsing
 
-## What's Not Included
-
-This is a minimal core library. It implements NIP-01 and the basics. It doesn't implement every NIP, handle connection pooling, or manage relay discovery. Build that yourself, or don't.
-
-## Cryptography
-
-This library uses an internal pure-Go implementation of secp256k1 and BIP-340 Schnorr signatures.
-
-**Tradeoffs:**
-
-- ✅ Zero dependencies, fully auditable
-- ✅ Passes all BIP-340 test vectors
-- ✅ Interoperable with btcec/bitcoin implementations
-- ⚠️ **Not constant-time** — uses Go's `math/big`, which has variable-time operations
-- ⚠️ ~10x slower than btcec (still fast enough for typical Nostr usage)
-
-For applications signing thousands of events per second or with strict timing-attack threat models, consider a library backed by btcec or libsecp256k1.
-
 ## Usage
 
 ```go
-- 
cgit v1.2.3