NIP-95: Hybrid Peer-to-Peer Relay Protocol

[lucianocasalunga]

NIP-95: Hybrid Peer-to-Peer Relay Protocol

Summary

This NIP proposes a hybrid P2P extension for Nostr relays, inspired by Spotify's P2P music distribution model.

Key concepts:

• Relay acts as Seed Node (authoritative source + peer coordinator)
• Stable clients become Super Peers (cache and share recent events via WebRTC)
• Other clients are Casual Peers (consume from Super Peers with relay fallback)

Benefits

• 30-50% reduction in relay load (recent events served via P2P)
• Improved decentralization (clients contribute to the network)
• Resilience: if relay goes down, peers continue sharing cached events
• Fully backwards compatible with existing relays and clients

New Message Types

• PEER_REGISTER — Register as potential Super Peer
• PEER_REQUEST — Request events with P2P preference
• PEER_OFFER — Relay offers list of peers with cached events
• PEER_PROMOTED / PEER_DEMOTED — Peer status changes

Reference Implementation

• Relay: Nexus Relay (in development)
• Client Library: nostr-p2p.js (planned)

Status

draft — Seeking community feedback before implementation.

---

Proposed by LiberNet Infrastructure (Israel/Brazil)

[arthurfranca]

I asked myself "what's the incentive to become a super peer to store and serve recent events in contrast to spinning up a 'super relay' that stores and serves recent events?"

I've noticed some differences:

1. Super peers get to be recommended by seed relays to casual peers (users). (But not a real difference because a seed relay could instead recommend "super relays" to users).
2. Super peers can run from a basement on a browser tab. But it can't connect to as much users as a "super relay" could. But if seed relays are keeping track of the available p2p connections of each super peer, it's ok.
3. Peers using WebRTC won't be able to hide their IPs by using Tor afaik

I like the possibility of running a node on a browser tab though not sure if p2p is the way to go.

However, the model of recommending stable, near and well behaving entities for fetching recent events from looks promising in that there's no need to use outbox model to figure out the right places to go. Follows feed and communication in general could be sped up dramatically.

But for that to work, seed relays would have to sync events between each other or clients would need to blast events to all of them when publishing. And I don't think seed relays need to store all events forever, this is too much to ask. For old events, fallbacking to usual outbox model seems better.

[lucianocasalunga]

Response to @kaiisfree's review

Thank you for the thorough and constructive review. Addressing each point:

1. Selective omission attacks

You're right — omission is the subtler vector. In the current Nexus implementation, P2P is additive, not substitutive. The client receives events from both the relay and peers simultaneously (smart routing). If a peer omits events, the relay fills the gap automatically. The peer complements the relay, never replaces it.

That said, your spot-check idea is valuable. We can add to the spec: clients SHOULD periodically compare random samples between P2P-served and relay-served result sets to detect systematic omission, and demote inconsistent peers.

Regarding Sybil: promotion criteria are the minimum bar. In practice, reputation is built through verified contribution — events served via P2P, reported to the relay. An attacker would need to spend real bandwidth serving legitimate events to build reputation, which limits the attack incentive.

2. Incentive gap for Super Peer participation

Three layers of incentive, from simple to economic:

1. Priority access — Super Peers get more generous rate limits from the relay (already supported in the implementation)
2. Persistent reputation — tied to the Nostr pubkey, survives reconnections and restarts. High reputation = more trust in the network
3. Sat rewards — after 1 month as a stable Super Peer, unlock automatic zaps via NIP-57. The relay can allocate a portion of received donations to top-contributing peers

Spotify's model worked by forcing P2P through the client. In Nostr, the path is making Super Peer status advantageous, not mandatory. Even with few Super Peers, load reduction is significant — our test with a single Super Peer (a headless Node.js client on a separate server) already served real events via P2P.

3. Hard promotion boundaries vs. smooth transition

Valid point. The current Nexus implementation already uses a continuous scoring system (reputation 0-100) with hysteresis: promotion at ≥50, demotion at <30. This prevents thrashing at the boundary. The spec will be updated to recommend a composite score rather than individual hard cuts.

4. "Blind relay mode" is self-defeating

Fully agree. Proxying WebRTC through the relay recreates the client-server model with extra complexity. In the current version, we removed this option — P2P is either opt-in direct or disabled. For users who need privacy, the correct path is not participating as a peer and using the relay normally. We'll update the spec to remove the "blind relay mode" mention.

5. Peer reputation is under-specified

The current Nexus implementation has a working model:

• Accumulation: +1 per verified event served, +2 bonus every 5 events. Starting baseline: 70
• Decay: peers above 70 with no contribution decay -0.5 per heartbeat cycle
• Demotion: reputation < 30
• Rehabilitation: yes, any peer can recover by actively serving events
• Persistence: tied to Nostr publicKey in Redis, survives server restarts

We'll detail this in the spec. Your work on reputation attestation (PR #2285) is interesting — cross-relay reputation would be a natural evolution of this system.

---

Update: As of April 3, 2026, the Nexus Relay has achieved its first successful P2P event transfer via WebRTC. A browser client connected to a headless Super Peer through the relay's signaling, established a WebRTC data channel using external TURN servers, and received a Schnorr-verified Nostr event — all in ~778ms. The P2P layer is no longer theoretical.

[lucianocasalunga]

Response to @arthurfranca

Great questions. Point by point:

Super Peer vs "Super Relay": The fundamental difference is barrier to entry. A relay needs a server, domain, SSL, 24/7 maintenance. A Super Peer is a browser tab or a desktop app running in background — zero infrastructure, zero cost. This democratizes network participation. Today Nostr has ~800 relays; with P2P, potentially thousands of peers can help distribute events.

You're right that a seed relay could recommend "super relays" instead — but that's just relay federation, which requires every participant to run server infrastructure. P2P lets any user contribute with hardware they already have.

WebRTC and IP/Tor: Correct, WebRTC exposes IP. P2P participation is opt-in — users who need privacy simply don't activate it. The relay continues working normally without P2P. This isn't different from using a Nostr client that connects directly to relays (IP is also exposed without Tor).

Sync between seed relays: Agreed this is needed at scale. NIP-95 doesn't require "forever" storage — Super Peers cache only recent events (24h TTL in the implementation). For older events, the fallback is the relay/outbox model as you suggested. The two complement each other perfectly.

"Not sure if P2P is the way to go": We just proved it works. Our Nexus Relay has a permanent Super Peer (CloudMor, a headless Node.js client on a separate server) that served the first Nostr event via WebRTC P2P yesterday. Signaling via relay, ICE via external TURN servers, direct data channel. It works, it's fast (~778ms from offer to connect), and the event is Schnorr-verified at the destination.

The model of "recommending stable, nearby, well-behaving entities for fetching recent events" that you mentioned is exactly what we do — the relay knows the peers, knows which events each one has cached, and directs the client to the most suitable peer (PEER_OFFER). It's essentially a decentralized CDN native to Nostr.

Your insight about speeding up follows feeds and communication by recommending nearby entities is spot-on — that's exactly the use case where P2P shines, and it doesn't conflict with the outbox model for historical data.