How Nostr Works — Events, Relays & Keys Explained (12-Min Read)

Introduction

Nostr is beautifully simple. While other decentralized protocols require blockchains, complex consensus mechanisms, or federated server networks, Nostr works with just three components: keys, events, and relays.

This guide explains how Nostr actually works under the hood - accessible enough for non-developers, but detailed enough for those who want to understand the architecture.

The Core Components

1. Cryptographic Keys (Identity)

Your identity on Nostr is a cryptographic key pair generated using the secp256k1 elliptic curve (the same used in Bitcoin).

Key Generation

When you create a Nostr identity, the process is:

1. Generate a private key - A random 256-bit number (32 bytes)
2. Derive the public key - Mathematically derived from the private key
3. Encode for human use - Convert to readable formats

Key Formats

Hexadecimal (Raw):

These examples are NIP-19’s published test key pair. Never use a published key for a real account.

Private: 67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa
Public:  7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e

Bech32 (User-Friendly):

Private (nsec): nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5
Public (npub):  npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg

The bech32 format is what you see in Nostr clients. It’s:

• Easier to read
• Includes error detection
• Has type prefixes (nsec for private, npub for public)

Cryptographic Properties

Public Key:

• Mathematically derived from private key
• Cannot be used to derive the private key (one-way function)
• Safe to share publicly
• Your permanent identity

Private Key:

• Must be kept secret
• Used to create digital signatures
• Proves you control the public key
• If lost, identity is unrecoverable

2. Events (The Data Structure)

Everything in Nostr is an event. A post, a like, a follow list, a profile update - all are events.

Event Structure

An event is a JSON object with this structure:

{
  "id": "event_identifier_hash",
  "pubkey": "author_public_key",
  "created_at": unix_timestamp,
  "kind": event_type_number,
  "tags": [["tag_name", "tag_value"]],
  "content": "the actual content",
  "sig": "cryptographic_signature"
}

Let’s break down each field:

Event Fields Explained

id (Event Identifier):

• SHA-256 hash of the event
• Uniquely identifies this event
• Calculated from: pubkey + created_at + kind + tags + content
• Example: a0b1c2d3e4f5...

pubkey (Author’s Public Key):

• The 32-byte public key of the event creator
• In hexadecimal format
• Tells everyone who created this event

created_at (Timestamp):

• Unix timestamp (seconds since 1970)
• When the event was created
• Example: 1705680000 (19 January 2024, 16:00 UTC)

kind (Event Type):

• Number indicating what type of event this is
• Defined in NIPs (Nostr Implementation Possibilities)
• Examples:
  • 0 = Profile metadata
  • 1 = Short text note (like a tweet)
  • 3 = Follow list (who you follow)
  • 4 = Encrypted direct message (deprecated NIP-04; current DMs use NIP-17: kind 14, sealed in kind 13 and gift-wrapped in kind 1059)
  • 7 = Reaction (like/emoji)

tags (Metadata):

• Array of arrays
• Provides additional context
• Examples:
  • ["e", "event_id"] - References another event
  • ["p", "pubkey"] - Mentions a user
  • ["t", "bitcoin"] - Hashtag
  • ["r", "url"] - References a URL (relay URLs go in r tags only inside a kind 10002 relay list)

content (The Actual Data):

• The message, profile info, or data
• Plain text for public posts
• Encrypted for DMs (NIP-17; the legacy NIP-04 is deprecated)
• JSON for structured data (profiles)

sig (Signature):

• Cryptographic signature of the event
• Created by signing the event ID with the private key
• Proves:
  • This event was created by the owner of the public key
  • The content hasn’t been modified
  • The event is authentic

Example Event (Short Note)

Here’s what a simple post looks like:

{
  "id": "6b4d8b6f613a1f31058c3f84c58a41edc097a0db0c2225b112c8c37aefda1240",
  "pubkey": "7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e",
  "created_at": 1705680000,
  "kind": 1,
  "tags": [
    ["t", "nostr"],
    ["t", "decentralization"]
  ],
  "content": "Just learned how Nostr works. Mind blown by the simplicity! 🤯",
  "sig": "<Schnorr signature of the id: 128 hex characters>"
}

This event is:

• A short text note (kind 1)
• Posted by someone with that public key
• Tagged with #nostr and #decentralization
• Signed to prove authenticity

3. Relays (The Distribution Network)

Relays are simple servers that:

• Accept events from clients
• Store events (temporarily or permanently)
• Send events to clients who request them

What Relays Do

Accept Events:

Client → Relay: "Here's a new event I created"
Relay: Checks signature, stores event, confirms receipt

Distribute Events:

Client → Relay: "Send me all events from these public keys"
Relay: Sends matching events as they arrive

That’s It!

Relays don’t:

• Create events (only clients do)
• Modify events (they’d break the signature)
• Have special authority
• Know your private key
• Control your identity

Relay Communication Protocol

Clients talk to relays using WebSockets with a simple JSON protocol.

Client Sends Event:

["EVENT", {event_object}]

Client Subscribes to Events:

["REQ", "subscription_id", {"kinds": [1], "authors": ["pubkey1", "pubkey2"]}]

Relay Sends Event:

["EVENT", "subscription_id", {event_object}]

Client Closes Subscription:

["CLOSE", "subscription_id"]

Simple, elegant, no bloat.

Relay Types

Public Free Relays:

• Open to everyone
• May have spam issues
• Good for reach
• Example: wss://relay.damus.io

Paid Relays:

• Require payment (usually Lightning)
• Better spam filtering
• More reliable
• Example: wss://nostr.wine

Private Relays:

• Invite-only or personal
• Full control over content
• Maximum privacy
• Run your own!

Specialized Relays:

• Not media: images and video live on HTTP file servers (Blossom), not on relays
• Search relays (indexed content)
• Community relays (specific topics)
• Archive relays (long-term storage)

4. Clients (The User Interface)

Clients are applications that:

• Manage your private key
• Create and sign events
• Connect to relays
• Display content
• Provide user interface

What Clients Do

Key Management:

• Generate new keys
• Store private key securely (or integrate with key managers)
• Sign events using the private key

Event Creation:

• Compose posts, reactions, profile updates
• Format as proper event JSON
• Calculate event ID (hash)
• Sign with private key

Relay Communication:

• Connect to multiple relays via WebSocket
• Subscribe to relevant events
• Publish your events
• Receive events in real-time

Content Display:

• Parse event JSON
• Verify signatures
• Render in user-friendly format
• Handle media, links, mentions

The Complete Flow: Publishing a Post

Let’s walk through what happens when you post “Hello Nostr!”

Step 1: Compose (In Client)

You type: “Hello Nostr!”

Your client creates an event structure:

{
  "pubkey": "your_public_key",
  "created_at": 1705680000,
  "kind": 1,
  "tags": [],
  "content": "Hello Nostr!"
}

Step 2: Create Event ID (In Client)

The client:

1. Serializes the event data in a specific format
2. Computes SHA-256 hash
3. This hash becomes the event id

{
  "id": "computed_hash_of_event",
  "pubkey": "your_public_key",
  "created_at": 1705680000,
  "kind": 1,
  "tags": [],
  "content": "Hello Nostr!"
}

Step 3: Sign Event (In Client)

The client:

1. Takes the event ID
2. Signs it using your private key (Schnorr signature)
3. Adds signature to event

{
  "id": "computed_hash",
  "pubkey": "your_public_key",
  "created_at": 1705680000,
  "kind": 1,
  "tags": [],
  "content": "Hello Nostr!",
  "sig": "cryptographic_signature_of_id"
}

Step 4: Publish to Relays (Client → Relays)

Your client sends this event to your write relays (your NIP-65 relay list) and to the read relays of anyone you tag:

Client → Relay 1: ["EVENT", {event}]
Client → Relay 2: ["EVENT", {event}]
Client → Relay 3: ["EVENT", {event}]

Step 5: Relay Verification (At Each Relay)

Each relay:

1. Receives the event
2. Verifies the signature matches the pubkey
3. Checks the ID hash is correct
4. Stores the event
5. Confirms receipt to your client

Relay → Client: ["OK", "event_id", true, ""]

Step 6: Distribution (Relay → Other Clients)

When someone following you connects to a relay:

Their Client → Relay: "Send me events from [your_pubkey]"
Relay → Their Client: ["EVENT", "subscription_id", {your_event}]

Their client:

1. Receives your event
2. Verifies the signature (proves you created it)
3. Displays “Hello Nostr!” in their feed

Done! Decentralized publishing complete.

Why This Design is Brilliant

1. No Central Authority

• No company controls your identity (it’s a key pair)
• No platform can ban you (they don’t control your keys)
• No algorithm manipulates your feed (client decides what to show)
• No single point of failure (many relays)

2. Extreme Simplicity

• Events are just JSON objects
• Relays are simple servers (can be built in a weekend)
• No complex consensus (no blockchain needed)
• No cryptocurrency required (though Lightning integrates nicely)

3. Censorship Resistance

• If one relay bans you, use another
• If all relays ban you, run your own
• Your identity persists (keys don’t depend on relays)
• Content can be replicated across unlimited relays

4. Portability

• Same identity works in all clients
• Switch clients anytime
• No data lock-in
• True user ownership

5. Scalability

• More users = more relays naturally emerge
• No global state to synchronize
• Clients only fetch what they need
• Relays can specialize (media, text, communities)

Advanced Concepts

Event Kinds (Types of Content)

The kind field enables different types of content:

Basic Kinds:

• 0 - Profile metadata (name, bio, picture)
• 1 - Short text note
• 3 - Follow list
• 4 - Encrypted DM (deprecated NIP-04; use NIP-17: kind 14, sealed in kind 13 and gift-wrapped in kind 1059)
• 5 - Event deletion request
• 7 - Reaction (like, emoji)

Advanced Kinds:

• 30023 - Long-form article
• 30078 - Application-specific data
• 1984 - Report/flag content
• 10002 - Relay list (NIP-65)
• 40 - Channel creation (NIP-28, now marked unrecommended; groups use NIP-29)
• 41 - Channel metadata (NIP-28, unrecommended)
• 42 - Channel message (NIP-28, unrecommended)

NIPs define new kinds as the protocol evolves.

Replaceable Events

Some event kinds are “replaceable” - newer events replace older ones.

Example: Profile metadata (kind 0)

• You post a profile update
• If you post another profile update later
• Relays should keep only the newest one
• Saves storage, ensures up-to-date info

Ephemeral Events

Some events are temporary (kinds 20000-29999):

• Not stored by relays
• Only distributed to active subscribers
• Useful for real-time data (typing indicators, presence)

Addressable Events

Events that can be replaced but are identified by additional parameters beyond just pubkey and kind.

Example: Blog posts (kind 30023)

• Each post has a unique identifier in tags
• Can be updated by publishing a newer version
• Relays keep the latest version of each unique post

Filters and Queries

Clients use filters to request specific events from relays:

{
  "kinds": [1, 7],
  "authors": ["pubkey1"],
  "#t": ["bitcoin"],
  "since": 1705680000,
  "limit": 50
}

• kinds: only text notes and reactions
• authors: from specific authors
• #t: with specific tags
• since: created at or after this timestamp
• limit: at most 50 events

Relays return matching events.

Security Model

What’s Secure

Authenticity:

• Signatures prove events are genuine
• Can’t forge events (would need private key)
• Can’t modify events (would break signature)

Identity Ownership:

• Only you control your private key
• Only you can create events as you
• No platform can impersonate you

What’s Not Secure

Privacy:

• All posts are public by default
• Relays can see who you follow
• Timing analysis possible
• IP addresses visible to relays (use Tor/VPN)

Deletion:

• Events may persist on relays
• Deletion (kind 5) is a request, not a guarantee
• Treat all posts as permanent

DM Encryption (NIP-17):

• Modern DMs use NIP-44 encryption inside NIP-59 gift wraps, which hides the sender, the real timestamp and the content; the recipient stays visible to the relay
• The legacy NIP-04 encrypts only the message body and leaks metadata to every relay it passes; treat it as deprecated
• Still not as secure as Signal/WhatsApp (no forward secrecy)
• Use dedicated secure messaging for sensitive comms

Comparison to Other Protocols

Nostr vs ActivityPub (Mastodon)

Nostr:

• Identity: Cryptographic keys (portable)
• Servers: Relays (simple, dumb)
• Accounts: No accounts, just keys
• Migration: Seamless (same keys everywhere)

ActivityPub:

• Identity: username@server (tied to server)
• Servers: Complex, federated
• Accounts: Traditional server accounts
• Migration: Difficult, data loss

Nostr vs AT Protocol (Bluesky)

Nostr:

• Architecture: Simple (keys + relays)
• Identity: Self-sovereign keys
• Infrastructure: Anyone can run relay
• Complexity: Very low

AT Protocol:

• Architecture: Complex (DIDs, PDSs, Relays, AppViews)
• Identity: DIDs (more complex)
• Infrastructure: More centralization
• Complexity: Higher

Nostr vs Blockchain Social

Nostr:

• Data: Stored on relays
• Cost: Free (or cheap paid relays)
• Speed: Instant
• Scalability: Excellent

Blockchain Social:

• Data: On blockchain
• Cost: Transaction fees
• Speed: Block time delays
• Scalability: Limited by chain

Performance Considerations

Network Efficiency

Multi-Relay Strategy:

• Connect to 5-10 relays
• Balance redundancy and bandwidth
• Use closer relays for speed

Selective Subscriptions:

• Don’t subscribe to everything
• Filter by follows, topics, time
• Close subscriptions when done

Caching:

• Clients cache events locally
• Reduces relay queries
• Faster user experience

Relay Optimization

Indexing:

• Relays index events by kind, author, tags
• Fast queries
• Minimal computational overhead

Storage:

• Ephemeral events not stored
• Replaceable events save space
• Specialized relays (text-only, no media)

Future Developments

Already Available

Several improvements once listed here as future work already exist:

• Proof-of-work requirements (NIP-13)
• Paid relays
• Better DM encryption (NIP-44)
• Private relays
• Relay discovery (NIP-65 relay lists, NIP-66 relay monitoring)
• Decentralized marketplaces (NIP-99)
• Identity verification (NIP-05)

Coming Improvements

Better Spam Filtering:

• Web of trust
• Reputation systems

Enhanced Privacy:

• Tor integration standard
• Anonymous posting options

Scaling Solutions:

• Specialized relay types
• Content delivery networks
• Optimized event formats

New Use Cases:

• Social graphs for apps
• Reputation systems
• DAO coordination

Conclusion

Nostr works through elegant simplicity:

Keys provide identity ownership Events structure all data Relays distribute content Clients create user experiences

No blockchain, no tokens, no complex consensus - just cryptography, simple servers, and open standards.

This simplicity is Nostr’s superpower. It’s easy to:

• Understand the protocol
• Build clients and relays
• Add new features (NIPs)
• Scale infrastructure
• Resist censorship

The architecture isn’t perfect, but it’s good enough - and that’s revolutionary.

---

Explore Further:

• NIPs Directory - Protocol specifications
• Client Directory - Try different implementations
• Relay Directory - Find relays to connect to
• For Developers - Build on Nostr

Ready to Get Started?

• Getting Started Guide - Join Nostr today
• Security Best Practices - Protect your identity