# Nostr Library Benchmarks

This directory contains comprehensive benchmarks comparing three popular Go Nostr libraries:

- **NWIO** (`code.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 are in a separate module (`benchmarks/comparison/`) to avoid polluting the main module dependencies with competitor libraries.

### Quick Start

Run all comparison benchmarks:
```bash
cd benchmarks/comparison
go test -bench=. -benchmem -benchtime=1s
```

### Specific Benchmark Groups

Event unmarshaling:
```bash
cd benchmarks/comparison
go test -bench=BenchmarkEventUnmarshal -benchmem
```

Event signing:
```bash
cd benchmarks/comparison
go test -bench=BenchmarkEventSign -benchmem
```

Event verification:
```bash
cd benchmarks/comparison
go test -bench=BenchmarkEventVerify -benchmem
```

Filter matching:
```bash
cd benchmarks/comparison
go test -bench=BenchmarkFilterMatch -benchmem
```

### Compare Single Library

NWIO only:
```bash
cd benchmarks/comparison
go test -bench='.*_NWIO' -benchmem
```

NBD only:
```bash
cd benchmarks/comparison
go test -bench='.*_NBD' -benchmem
```

Fiat only:
```bash
cd benchmarks/comparison
go test -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
cd benchmarks/comparison
go test -bench=. -benchmem -count=10 > results.txt
benchstat results.txt
```

Compare two specific libraries:
```bash
cd benchmarks/comparison
go test -bench='.*_NWIO' -benchmem -count=10 > nwio.txt
go test -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