summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorClawd <ai@clawd.bot>2026-02-20 19:33:56 -0800
committerClawd <ai@clawd.bot>2026-02-20 19:33:56 -0800
commit7335771c572759ff32902223586af5d1de55d384 (patch)
treeaf2761b7cd5ed0a1f49a19c71bc2ad9a4ed4c744 /README.md
parent2ff3bff2cc178e2dcd7c0536a016b2d2800a55af (diff)
docs: rewrite README with honest disclaimers
Diffstat (limited to 'README.md')
-rw-r--r--README.md41
1 files 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 @@
1# nostr 1# nostr
2 2
3A minimal Go library for the [Nostr protocol](https://github.com/nostr-protocol/nostr). 3A zero-dependency Go library for the [Nostr protocol](https://github.com/nostr-protocol/nostr).
4 4
5```bash 5```bash
6go get code.northwest.io/nostr 6go get code.northwest.io/nostr
@@ -8,43 +8,32 @@ go get code.northwest.io/nostr
8 8
9## Why This Library? 9## Why This Library?
10 10
11**Zero dependencies.** 11You probably shouldn't use it.
12 12
13Other Nostr libraries pull in 30+ dependencies. This one has none. The secp256k1 cryptography is implemented in pure Go, embedded in the library. 13This 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.
14 14
15``` 15**What you get:**
16require (nothing) 16- Zero external dependencies
17``` 17- Fully auditable pure-Go crypto
18- Passes all BIP-340 test vectors
19- Works fine for normal Nostr usage
20
21**What you're giving up:**
22- Constant-time operations (timing attacks are theoretically possible)
23- Performance (~10x slower than btcec)
24- Battle-tested crypto code
18 25
19No external crypto libraries, no WebSocket libraries, no logging frameworks, no kitchen sink. Just the core protocol. 26If 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.
20 27
21## What's Included 28## What's Included
22 29
23- **Keys** — Generate, parse, sign, verify (hex and bech32/npub/nsec) 30- **Keys** — Generate, parse, sign, verify (hex and bech32/npub/nsec)
24- **Events** — Create, serialize, sign NIP-01 events 31- **Events** — Create, serialize, sign NIP-01 events
25- **Filters** — Build and match subscription filters 32- **Filters** — Build and match subscription filters
26- **Relay** — WebSocket pub/sub (stdlib `net/http` only) 33- **Relay** — WebSocket pub/sub (stdlib only)
27- **Tags** — Parse and build event tags 34- **Tags** — Parse and build event tags
28- **Envelopes** — Protocol message parsing 35- **Envelopes** — Protocol message parsing
29 36
30## What's Not Included
31
32This 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.
33
34## Cryptography
35
36This library uses an internal pure-Go implementation of secp256k1 and BIP-340 Schnorr signatures.
37
38**Tradeoffs:**
39
40- ✅ Zero dependencies, fully auditable
41- ✅ Passes all BIP-340 test vectors
42- ✅ Interoperable with btcec/bitcoin implementations
43- ⚠️ **Not constant-time** — uses Go's `math/big`, which has variable-time operations
44- ⚠️ ~10x slower than btcec (still fast enough for typical Nostr usage)
45
46For applications signing thousands of events per second or with strict timing-attack threat models, consider a library backed by btcec or libsecp256k1.
47
48## Usage 37## Usage
49 38
50```go 39```go