1 files changed, 99 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f3d961a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,99 @@
+# nostr-grpc
+
+A high-performance Nostr relay with gRPC and WebSocket support.
+
+## Features
+
+- **gRPC-first**: Binary protobuf storage with gRPC API
+- **SQLite storage**: WAL mode, optimized indexes
+- **Event validation**: Signature and ID verification
+- **Nostr compatible**: NIP-01 compliant
+
+## Quick Start
+
+### Build
+
+```bash
+make build          # Build relay
+make build-client   # Build test client
+make build-all      # Build both
+```
+
+### Run the Relay
+
+```bash
+./bin/relay
+# or with custom settings:
+./bin/relay -grpc-addr :50051 -db relay.db
+```
+
+The relay will start listening on `:50051` (gRPC).
+
+### Test with Client
+
+```bash
+# In another terminal:
+./bin/testclient
+
+# Output:
+# Generated key: npub1...
+# Publishing event...
+# ✓ Event published successfully: abc123...
+# Querying events...
+# Found 1 events
+#   - abc123...: Hello from gRPC client!
+```
+
+## gRPC API
+
+See [proto/nostr/v1/nostr.proto](proto/nostr/v1/nostr.proto) for the full API.
+
+### Available RPCs
+
+- `PublishEvent` - Publish a single event (with validation)
+- `PublishBatch` - Publish multiple events
+- `QueryEvents` - Query events with filters (paginated)
+- `CountEvents` - Count events matching filters
+- `Subscribe` - Stream events (not implemented yet)
+- `Unsubscribe` - Close subscription (not implemented yet)
+
+## Current Status
+
+**Phase 1: Core Relay**
+- ✅ SQLite storage with binary-first design
+- ✅ Event validation (ID, signature)
+- ✅ gRPC publish/query API
+- ⏳ Subscribe/streaming (in progress)
+- ⏳ WebSocket server (planned)
+
+## Development
+
+```bash
+make proto          # Regenerate protobuf code
+make test           # Run tests
+make proto-lint     # Lint proto files
+```
+
+## Architecture
+
+```
+┌─────────────────┐
+│   gRPC Client   │
+└────────┬────────┘
+         │ pb.Event
+         ▼
+┌─────────────────┐
+│  gRPC Handler   │  ← validates using nostr.Event
+│  (convert.go)   │  ← generates canonical JSON
+└────────┬────────┘
+         │ pb.Event + canonicalJSON
+         ▼
+┌─────────────────┐
+│ Storage Layer   │  ← protobuf + compressed JSON
+│   (SQLite)      │  ← query by filter
+└─────────────────┘
+```
+
+## License
+
+MIT