feat: add library comparison benchmarks with build tag isolation

Add comprehensive benchmarks comparing NWIO against nbd-wtf/go-nostr and
fiatjaf.com/nostr across event operations, signing, verification, and filtering.

Use build tag 'benchcmp' to prevent competitor libraries from polluting module
dependencies - they're only downloaded when explicitly running comparison tests.

1 files changed, 129 insertions, 0 deletions

diff --git a/BENCHMARKS.md b/BENCHMARKS.md
new file mode 100644
index 0000000..14a861c
--- /dev/null
+++ b/BENCHMARKS.md
@@ -0,0 +1,129 @@
+# Nostr Library Benchmarks
+
+This directory contains comprehensive benchmarks comparing three popular Go Nostr libraries:
+
+- **NWIO** (`northwest.io/nostr`) - This library
+- **NBD** (`github.com/nbd-wtf/go-nostr`) - Popular community library
+- **Fiat** (`fiatjaf.com/nostr`) - Original implementation by Fiatjaf
+
+## Benchmark Categories
+
+### Event Operations
+- **Unmarshal**: Parsing JSON into Event struct
+- **Marshal**: Serializing Event struct to JSON
+- **Serialize**: Canonical serialization for ID computation
+- **ComputeID**: Computing event ID hash
+- **Sign**: Signing events with private key
+- **Verify**: Verifying event signatures
+
+### Key Operations
+- **GenerateKey**: Generating new private keys
+
+### Filter Operations
+- **FilterMatch**: Simple filter matching (kind, author)
+- **FilterMatchComplex**: Complex filter matching (with tags, prefix matching)
+
+## Running Benchmarks
+
+**Important**: The comparison benchmarks require the `benchcmp` build tag to avoid polluting the module dependencies with competitor libraries.
+
+### Quick Start
+
+Run all benchmarks (automatically handles dependencies):
+```bash
+./run_benchmarks.sh
+```
+
+Or manually:
+```bash
+# First, get the comparison dependencies
+go get -tags=benchcmp -t ./...
+
+# Then run the benchmarks
+go test -tags=benchcmp -bench=. -benchmem -benchtime=1s
+```
+
+### Specific Benchmark Groups
+
+Event unmarshaling:
+```bash
+go test -tags=benchcmp -bench=BenchmarkEventUnmarshal -benchmem
+```
+
+Event signing:
+```bash
+go test -tags=benchcmp -bench=BenchmarkEventSign -benchmem
+```
+
+Event verification:
+```bash
+go test -tags=benchcmp -bench=BenchmarkEventVerify -benchmem
+```
+
+Filter matching:
+```bash
+go test -tags=benchcmp -bench=BenchmarkFilterMatch -benchmem
+```
+
+### Compare Single Library
+
+NWIO only:
+```bash
+go test -tags=benchcmp -bench='.*_NWIO' -benchmem
+```
+
+NBD only:
+```bash
+go test -tags=benchcmp -bench='.*_NBD' -benchmem
+```
+
+Fiat only:
+```bash
+go test -tags=benchcmp -bench='.*_Fiat' -benchmem
+```
+
+## Analyzing Results
+
+Use `benchstat` for statistical analysis:
+
+```bash
+# Install benchstat
+go install golang.org/x/perf/cmd/benchstat@latest
+
+# Run benchmarks multiple times and compare
+go test -tags=benchcmp -bench=. -benchmem -count=10 > results.txt
+benchstat results.txt
+```
+
+Compare two specific libraries:
+```bash
+go test -tags=benchcmp -bench='.*_NWIO' -benchmem -count=10 > nwio.txt
+go test -tags=benchcmp -bench='.*_NBD' -benchmem -count=10 > nbd.txt
+benchstat nwio.txt nbd.txt
+```
+
+## Understanding the Output
+
+Example output:
+```
+BenchmarkEventSign_NWIO-24    50000    35421 ns/op    1024 B/op    12 allocs/op
+```
+
+- `50000`: Number of iterations
+- `35421 ns/op`: Nanoseconds per operation (lower is better)
+- `1024 B/op`: Bytes allocated per operation (lower is better)
+- `12 allocs/op`: Memory allocations per operation (lower is better)
+
+## Performance Tips
+
+1. **Event Unmarshaling**: Critical for relay implementations
+2. **Event Signing**: Important for client implementations
+3. **Event Verification**: Critical for all implementations
+4. **Filter Matching**: Important for relay implementations with many subscriptions
+
+## Notes
+
+- All benchmarks use realistic event data
+- Benchmarks run with default Go test timeout
+- Results may vary based on hardware and system load
+- Use `-benchtime=5s` for more stable results on noisy systems