Rings Network

Rings Network

rings-node cargo docs GitHub Sponsor

A peer-to-peer network for the sovereign age.

Rings is a structured peer-to-peer network that runs natively and in the browser. Browser tabs and native daemons join a unified Chord DHT overlay, address each other by DIDs, and communicate over direct WebRTC datachannels with no application server in the data path.

Why Rings

Try it

Status

Active public overlay at the seed node.rings.rs, with deterministic wire-versioned framing ("RINGS\0" ‖ wire_version, WIRE_VERSION = 4) across every frame and handshake. 1.0 stabilizes WIRE_VERSION = 4 and the public runtime contracts across 1.0.x, while 2.0 extends the overlay with epoch-randomized ring placement (#780) and decentralized trust ranking (DRanking). See UPGRADING.md, ROADMAP.md, and SECURITY.md.

Where Rings fits

✅ supported · ❌ not provided. Qualifications are listed below the table.

Network Browser P2P Structured P2P Privacy layer E2E encryption
Rings ✅ ✅ Chord ✅ Separate layer ✅¹
libp2p ✅ ✅ Kademlia² ❌ ✅³
aMule / Kad ❌ ✅ Kademlia ❌ ❌⁴
Nostr ❌ ❌ ❌ ✅⁵
Nym mixnet ❌ ❌ ✅ Full mixnet path ✅⁶
Tor ❌ ❌ Relay network ✅ Onion circuits ✅⁷
I2P ❌ ✅ netDb² ✅ Tunnel network ✅⁶
WebTorrent (browser) ✅ ❌ ❌ ✅³

Browser P2P means the browser itself connects as a peer; a browser UI or gateway client does not qualify. Structured P2P includes DHT-based discovery; it does not imply that application traffic is routed through the DHT. Privacy means network metadata protection, separate from payload encryption.

  1. Rings authenticates every overlay message by DID signature and provides E2E ElGamal stream encryption after a peer handshake.
  2. libp2p offers an optional Kademlia DHT. I2P uses a Kademlia-based netDb for discovery; messages travel through tunnels.
  3. Encrypted peer connections: libp2p includes circuit-relayed connections; browser WebTorrent uses WebRTC/DTLS.
  4. aMule protocol obfuscation is transport-level only. This row covers Kad; eD2k uses indexing servers.
  5. Nostr supports encrypted direct messages, such as NIP-44 payloads, alongside public signed events.
  6. Between Nym clients or I2P destinations; traffic to external services uses application-layer TLS/HTTPS.
  7. Tor provides end-to-end encryption for onion services and pairs with HTTPS for external websites.

Primary sources

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│  Applications   dWeb · relay/tunnel · your own app                     │
├──────────────────────────────────────────────────────────────────────┤
│  Protocols      built-ins: relay (tcp/udp tunnels), echo —             │  node::extension::protocols
│  (namespaced)   plus any user Protocol, addressed by namespace         │
├──────────────────────────────────────────────────────────────────────┤
│  Extension      pure `Protocol::step` → `Effect` → `Interpret` shell   │  node::extension::ext
│  runtime        over a namespace-scoped `Scope` (send / self-inject)   │
├──────────────────────────────────────────────────────────────────────┤
│  Privacy        onion loops: Sphinx cells over direct edges,           │  crates/node/src/onion
│  (loops)        constant-rate cover, paid admission, exit registry     │
├──────────────────────────────────────────────────────────────────────┤
│  Overlay        Chord DHT: successor / finger tables, stabilization,   │  crates/core
│  (routing +     DID addressing, message relay, network_id isolation,   │
│  encryption)    E2E ElGamal to a DID after its handshake               │
├──────────────────────────────────────────────────────────────────────┤
│  Transport      direct WebRTC datachannels (native + browser/web_sys), │  crates/transport
│                 STUN / ICE / SDP NAT traversal                         │
├──────────────────────────────────────────────────────────────────────┤
│  Identity       DID + secp256k1 / secp256r1 / ed25519 / BLS / bip137   │  crates/core::ecc
└──────────────────────────────────────────────────────────────────────┘

The overlay layer provides authenticated DID routing and E2E stream encryption, while the privacy layer provides anonymous Sphinx onion circuits (layer contracts). Connections are established peer-to-peer over WebRTC with optional TURN relay support (crates/turn / rings-turn provides a stateless signature-authenticated TURN server for Symmetric NAT and strict firewall environments with no user/password database). Supporting crates: rpc (JSON-RPC), measure (local peer credit), gateway (TUN over onion), webview (onion browsing), network-policy (exit egress policy), codec, and derive.

Build on Rings

A protocol is a pure state machine registered under a namespace; its interpreter shell performs the IO.

provider.register_protocol(Echo, EchoShell)?;
provider.set_backend()?;

// Built-in relay: tunnel a local socket to a peer's service, no server.
let relay = RelayHandle::install(&provider.extensions())?;
relay.register_tcp_service("web".into(), "127.0.0.1:8080".parse()?).await?; // server side
relay.open_tcp_tunnel(local_addr, peer_did, "web".into()).await?;            // client side

In the browser, a protocol can be a JS handler: provider.on(namespace, initialState, handler). Proof systems fit the same boundary: Rings routes and authenticates the envelopes, and the protocol's shell runs the prover.

Example Shows
native A native node with a custom protocol
relay TCP and UDP tunnels to a peer's service
mailbox SMTP/IMAP mailbox and mail gateway over Rings
dweb A decentralized web app (Yew)
ffi Driving a node over the C FFI

Installation

curl -fsSL https://rings.rs/install.sh | sh

The installer detects macOS (aarch64, x86_64) or Linux (x86_64 static musl, aarch64 gnu), downloads the matching release archive, verifies its SHA-256 checksum, and installs rings to /usr/local/bin (when writable) or ~/.local/bin. Re-run the same command to upgrade in place, or pass --version vX.Y.Z (curl -fsSL https://rings.rs/install.sh | sh -s -- --version v1.0.0-pre.6) to pin a release.

Running persistently

Static systemd (Linux user unit) and launchd (macOS LaunchAgent) service definitions live under contrib/.

Documentation

rings.rs/docs The book: operating nodes, browser and FFI runtimes, protocol internals
UPGRADING.md 1.0 frozen contracts and upgrade checklist
SECURITY.md Security architecture, layer contracts, and vulnerability reporting
ROADMAP.md Milestones and tracks
llms.txt Project map for AI agents
frontend Source of rings.rs and the browser extension
@RingsNetworkio Announcements

Whitepaper

To cite Rings:

@misc{rings-network,
  author = {Ryan J. Kung},
  title = {Rings: A peer-to-peer network for sovereign age},
  year = {2023},
  month = feb,
  url = {https://github.com/RingsNetwork/rings/blob/master/papers/rings.pdf},
  note = {Repository-owned whitepaper and LaTeX source: https://github.com/RingsNetwork/rings/tree/master/papers}
}

Contributing

See CONTRIBUTING.md.

License

Rings is released under the GNU Affero General Public License, version 3.0 only (AGPL-3.0-only). Works derived from it must be released under the same license, and the AGPL's network clause extends that obligation to services that offer Rings over a network: a product or hosted service built on Rings must publish its source.

A commercial license for use outside the AGPL's terms is available from Rings Network on request. The Rings Network name, logo, and the hosted rings.rs service are not covered by the software license.