Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

llms.txt

The repository keeps an llms.txt at its root, published at rings.rs/llms.txt, following the llms.txt convention: a plain-text map of the project for coding agents. It says what Rings is, which document is authoritative for what, how the crates are layered, how each target is built and tested, and which conventions a change must keep. Point an agent at it before it builds on Rings or changes it.

The file is maintained with the code — where it and the code disagree, the code wins and the file is corrected in the same change. This is the current file:

# Rings Network

> Rings is a browser-native, structured peer-to-peer network. Browser tabs and native daemons join one Chord DHT overlay, address each other by DID, and exchange messages over direct WebRTC datachannels; application protocols are namespace-scoped pure state machines run by an interpreter shell. Rust workspace, AGPL-3.0-only (commercial licensing available), https://github.com/RingsNetwork/rings.

This file follows https://llmstxt.org/. It is for agents that evaluate Rings, build on it, or change it: which document is authoritative for what, how the crates are layered, how each target is built and tested, and which conventions a change must keep. Where this file and the code disagree, the code wins; correct this file in the same change.

## What Rings is

- Overlay (communication layer): a Chord DHT (successor list, finger table, stabilization) keyed by DID with `network_id` overlay isolation. It provides authenticated O(log N) routing, replicated CRDT and relay-inbox storage, and end-to-end ElGamal stream encryption after a peer handshake.
- Privacy layer: onion loops in `crates/node/src/onion`, client-sealed loops of fixed-width Sphinx cells over direct edges through pinned entry guards, with constant-rate link emission that substitutes real cells for cover, paid per-hop admission, fixed cell size classes, and route selection from the signed onion-relay and onion-exit directories. Each relay learns only its immediate predecessor and successor, while exits process payloads without learning the client identity. The layer contracts are defined in SECURITY.md under Layer Contracts.
- Transport: WebRTC datachannels, native and browser (web_sys), with STUN/ICE/SDP for NAT traversal. Data flows directly peer to peer; seed nodes assist initial bootstrap discovery.
- Identity: a DID derived from a public key. Signature schemes: secp256k1 (EIP-191, bip137), secp256r1 (P-256), ed25519, BLS; the browser console signs with WebCrypto P-256, MetaMask, or Phantom. DIDs pair short-lived session delegations with slot-isolated admission, with epoch-randomized ring placement (#780) and DRanking trust algebra (#748) on the 2.0 track. SECURITY.md is authoritative for security architecture claims.
- Protocol runtime: `Protocol::step` is pure (state, event -> state, effects); an `Interpret` shell performs the effects through a namespace-scoped capability. Built-in protocols: relay (TCP/UDP tunnels over the overlay) and echo. Applications register their own by namespace: `provider.register_protocol(..)` in Rust, `provider.on(namespace, initialState, handler)` in JavaScript.
- Targets: the native daemon (`rings` CLI with a JSON-RPC API over HTTP), the browser/Wasm node (npm `@ringsnetwork/rings-node`; the rings.rs frontend and its Chrome extension), and a C FFI (`crates/node/include/rings.h`).

## Status

- Shipped in 1.0: the Chord overlay with range-proved finger convergence and non-transitive reachability healing, native and browser nodes, wire-versioned framing (`WIRE_VERSION = 3`), the onion privacy layer with client-sealed Sphinx/AEZ Kleisli pipelines (#834, TCP/HTTPS exits, TUN gateway, onion WebView), group-committed replay protection, slot-isolated resource accounting, per-origin rate quotas, clock-bounded CRDT removal stability, chain-replicated relay custody, DRanking service-receipt evidence collection, a public seed (https://node.rings.rs), and the hosted console (https://rings.rs/#node).
- Roadmap: adaptive churn telemetry and tuning (#773-#779), followed by 2.0 epoch-randomized ring positions (#780) and DRanking decentralized trust ranking (#748). See ROADMAP.md.
- To evaluate Rings, read README.md, SECURITY.md, and ROADMAP.md, in that order.

## Documentation

- [Documentation book](https://rings.rs/docs/): the reference; source in `docs/src`, built with mdBook and published from master.
- [Guide](https://rings.rs/#guide): the abridged version: one card per runtime and the first commands; the book is authoritative.
- [README](https://github.com/RingsNetwork/rings/blob/master/README.md): overview, architecture table, examples, whitepaper citation.
- [SECURITY.md](https://github.com/RingsNetwork/rings/blob/master/SECURITY.md): security architecture, layer contracts, feature guarantees, deployment models, and vulnerability reporting.
- [ROADMAP.md](https://github.com/RingsNetwork/rings/blob/master/ROADMAP.md): shipped foundations and the network-layer and privacy-layer tracks.
- [Whitepaper](https://github.com/RingsNetwork/rings/blob/master/papers/rings.pdf): the unified protocol paper (`papers/rings.tex`), alongside the 2.0 DRanking paper (`papers/dranking.pdf`).
- [JSON-RPC API](https://rings.rs/docs/jsonrpc.html): every method of the node API with curl examples.
- [config.yaml](https://rings.rs/docs/advanced-topic/config.yaml.html): the complete generated node configuration, section by section.
- [Operate a Node from the CLI](https://rings.rs/docs/cli.html): every `rings` subcommand.
- [Embed via C FFI](https://rings.rs/docs/ffi.html): the C ABI, its lifecycle and ownership rules, and the Python, Swift, and Kotlin wrappers.
- [Browser Node and Extension](https://rings.rs/docs/browser-node.html): the hosted console, running the frontend locally, and packaging the extension.

## Source map

- `crates/core`: Chord DHT, swarm, DID and elliptic-curve identity, message types, DHT storage bounds. Protocol only: application registries and descriptors live in `node`.
- `crates/transport`: the WebRTC transports (`native-webrtc`, `web-sys-webrtc`) and the `dummy` transport that topology tests run on.
- `crates/node`: the node. Native daemon and CLI (`bin/rings.rs`, `src/native`), browser provider (`src/provider/browser`), FFI provider (`src/provider/ffi.rs`, feature `ffi`), extension runtime and built-in protocols (`src/extension`), the privacy layer: onion loops, constant-rate link emission, paid admission, exit registry (`src/onion`), JSON-RPC handlers (`src/rpc_impl.rs`), seeds, peer quotas, registries.
- `crates/rpc`: RPC types and the JSON-RPC client. Its protos are plain data mirrors of node types.
- `crates/codec`: the serde wire codec. `crates/derive`: proc macros, including `wasm_export`.
- `crates/measure`: pure local peer credit and reliability algorithms. `crates/network-policy`: the public-network admission policy for egress targets. `crates/gateway`: the native TUN gateway that carries selected TCP destinations over onion loops (vendored netlink under `vendor/`). `crates/webview`: onion-backed WebView gateway primitives. `crates/turn`: the stateless signature-authenticated TURN server (`rings-turn`) for Symmetric NAT / CGNAT traversal using `DelegateeKey` or direct DID signatures as TURN passwords.
- `frontend/`: the Yew/Wasm web app and Chrome MV3 extension, its own Cargo workspace; TypeScript glue in `extension-assets/` and `scripts/` is compiled from source.
- `examples/`: `mailbox` (SMTP in, IMAP out, through a DNS relay or a mail gateway, and the mail gateway `rings-mail-gateway`), `native` and `relay` (workspace members), `dweb` (its own Yew workspace), `ffi` (Python, Swift, Kotlin wrappers and tests), `proof-demo`.
- `docs/`: the mdBook (`book.toml`, `src/`, `theme/`). `papers/`: the whitepaper and formal companion papers.

## Build and test

- Toolchain: `rust-toolchain.toml` pins the stable compiler (`cargo +<pin> install --locked rings-node`); a pin bump updates README.md, `crates/node/README.md`, `docs/src/install-a-native-node.md`, and `frontend/src/guide.rs`; formatting uses nightly rustfmt (`cargo +nightly fmt`). TOML is formatted with taplo; spelling is checked with typos.
- Native: `cargo build`; `cargo test --release --all --all-targets`; install the CLI with `cargo install --path crates/node`, then `rings init` and `rings run`.
- Wasm: `cargo clippy -p rings-node --features browser --no-default-features --target wasm32-unknown-unknown`; the npm package is built by `wasm-pack build crates/node --release --scope ringsnetwork -t web --no-default-features --features browser_default` (`npm run wasm_pack`); browser tests use wasm-bindgen-test in headless Chrome.
- Frontend (from `frontend/`): `cargo check --target wasm32-unknown-unknown`; `cargo clippy --target wasm32-unknown-unknown --all-targets -- -D warnings`; `cargo test --release --target wasm32-unknown-unknown`; `trunk serve --release true` to run it. Extension: `npm ci --ignore-scripts && npm run package:frontend-extension` from the root.
- FFI: `cargo build -p rings-node --features ffi`; `RINGS_FFI_REQUIRE_LIBRARY=1 pytest examples/ffi/tests`.
- Docs: `mdbook build docs`; `mdbook serve docs` to preview.
- Decode-boundary smoke: set `RINGS_DECODE_BOUNDARY_SEED` and `RINGS_DECODE_BOUNDARY_CASES`, then run the `decode_boundary` test filters for `rings-core`, `rings-transport`, and `rings-node`.
- Gates a change must pass (`.github/workflows/qaci.yml`): clippy with `-D warnings` on the native, wasm, and ffi feature sets; `cargo +nightly fmt --check`; rustdoc with `-D warnings`; `taplo format --check`; typos; cargo-deny; Miri on core invariants; the native, wasm, frontend, dweb, gateway, and generated decode-boundary test suites; the docs build.

## Conventions

- Layering: `core` is protocol only; application registries and descriptors live in `node`; `rpc` protos are plain DTO mirrors. Check every new type's vocabulary against the crate it lands in.
- Pure core, imperative shell: keep state transitions pure and explicit, represent effects as data, and confine IO to the interpreter that runs them.
- Lints are declared in the workspace `[lints]`: `unwrap_used`, `expect_used`, `panic`, `todo`, `unimplemented`, and `indexing_slicing` are denied on production paths. Fix the underlying structure (a struct for many arguments, `Box` for a large enum variant) rather than suppressing lints.
- Imports: one item per `use` line, no glob imports. Prefer method forms (`deref()`, `as_ref()`, `as_slice()`, `clone()`) to `&` and `*` in expressions.
- Tests are deterministic: wait for a concrete event (a generation counter, a channel message, a state predicate) and run topology tests on the `dummy` transport.
- Comments and docs explain why, not what. When a behaviour or boundary changes, update every comment and document that states it in the same commit.
- Commit messages, pull requests, and reviews are written in English. The workspace version in `Cargo.toml` is bumped with user-visible changes.
- License: AGPL-3.0-only for every crate, the frontend, and the npm package (`LICENSE`, the `license` fields, `deny.toml`). Derived works and network services built on Rings publish their source under the AGPL; a commercial license is available from Rings Network on request.

## Optional

- [crates.io: rings-node](https://crates.io/crates/rings-node), [docs.rs](https://docs.rs/rings-node), [npm: @ringsnetwork/rings-node](https://www.npmjs.com/package/@ringsnetwork/rings-node).
- [Releases](https://github.com/RingsNetwork/rings/releases): prebuilt `rings` for macOS (x86_64, aarch64) and Linux (x86_64 musl, aarch64 gnu), and the wasm package; one-line installer at `install.sh` (https://rings.rs/install.sh) and static service templates under `contrib/`.
- Public seed node: https://node.rings.rs. Its external handshake (`nodeDid`, `answerOffer`) is public; status and control methods use its Bearer token.
- Official X (Twitter) account: https://x.com/RingsNetworkio.