Repository navigation
v0.34.0
Rings 0.34.0: a network-wide upgrade
Rings 0.34.0 is out. It is a total network-wide cutover: a 0.34 node and a 0.33 node cannot
exchange messages at all. Every node (native, browser, FFI embedders and the public seed) must
move to 0.34.0. Rings negotiates no protocol versions before 1.0, so a mixed network is not
supported.
- Release and binaries: https://github.com/RingsNetwork/rings/releases/tag/v0.34.0
- Full list of changes: CHANGELOG, RingsNetwork/rings#988
- Configuration reference: https://rings.rs/docs/advanced-topic/config.yaml.html
The public seed node.rings.rs moves to 0.34.0 with this release. After that, a 0.33 node can no
longer bootstrap from it.
Why 0.33 and 0.34 do not interoperate
| Layer | Change |
|---|---|
| Every payload frame | The relay carrier records the connect-signalling path (#947). |
| Link control | Delegation references become leases. LinkControl tags change (#908). |
| Onion | Sphinx-header loops replace per-layer envelopes (#834). |
| TCP relay | Data frames are sequenced, and UDP has its own datagram frame (#939). |
What's new
- Onion circuits are client-sealed loops (#834). A route is
guard → relay → exit → relay → guardand returns to the client.- Relays are stateless: no circuit ids, return tables, per-edge AEAD or exit reply signatures.
- The header is a fixed-size Sphinx header of 14 uniform layers (#840). The carry is AEZ, from
the new in-repo craterings-aez(#836). Replies are deniable. - Every received cell is admitted and charged before any ECDH (#841).
- Every link emits at a constant rate while active and sends cover traffic while idle (#880).
- Sessions over loops.
tcpandhttpssessions are flow-controlled by reply blocks: an exit pauses its target
instead of dropping bytes.- Keep-alives observe a dead link on either segment at both endpoints within
2V(#975). - Credit frames carry the forward high-water mark, so a lost last frame is detected (#981).
- A retired link, a dropped message or a full inbound lane fails every session riding it, at
both endpoints (#963, #964, #966, #969, #971).
- Loss is detected end to end (#939). The TCP relay and E2E streams no longer pass on a stream
with a silent gap. A gap resets the stream, and the local socket gets an RST. A clean FIN now
means every byte arrived. - Delegation references are bounded, renewable leases (#908). No frame is held for a repair
round trip, so no frame is released out of order and lost as stale. - Connection establishment (#945, #946, #947, #953, #954, #960).
- A simultaneous open always ends with exactly one edge.
- No legitimate message is refused as
MonotonicTimeRegressed. - A browser ICE gathering ends when its connection is closed locally.
- DHT.
- Gateway. It names the cause of every captured-flow reset and degraded status (#950).
- Dependencies.
rustls0.23.46, for RUSTSEC-2026-0346..0349 (#956).- YAML is read and written with
serde-saphyr, replacing the unmaintainedserde_yaml
(RUSTSEC-2024-0449). Configuration documents are unchanged.
Upgrading a native node from 0.33
-
Stop the node and back up
~/.rings. -
Clear the DHT data store. This is the
data_storagepath of the configuration (by default
~/.rings/data), or thedatadirectory underrings run --storage-pathwhen that flag
overrides it.- The stored message codec changed, so relay-inbox messages held by 0.33 can never be
delivered by 0.34. - Data topics and onion registrations repopulate on their next writes and heartbeats.
- Messages held for offline peers at the upgrade are lost.
- The stored message codec changed, so relay-inbox messages held by 0.33 can never be
-
Install the 0.34.0 binary.
-
Edit
config.yaml:onion_exit_policy: allowed_targets: ["*:443"] denied_targets: [] - max_circuits: 0 - max_streams_per_circuit: 0 + max_sessions: 0 max_bytes_per_minute: 0 -onion_http_proxy_service: tcp -onion_http_proxy_hop_count: 0 -onion_http_proxy_allow_short_paths: false gateway: # ... - onion_service: tcp - onion_hop_count: 0 - onion_allow_short_paths: false
- Route length is no longer configurable. It is fixed by the loop shape.
- The
ONION_HTTP_PROXY_SERVICEenvironment variable is removed. onion_exit_servicesaccepts onlytcpandhttps; any other name is rejected.httpsis one request/response fetch.- Every tunnel uses
tcp: HTTP CONNECT, SOCKS and captured gateway flows. - For TLS-only egress, register
tcpwith the allowed target*:443.
- Exit targets accept
*:<port>. - Role prerequisites:
- A relay (
advertise_onion_relay: true) requiresadvertise_presence: true. - An exit (
advertise_onion_exit: true) requiresadvertise_onion_relay: true.
- A relay (
- A browser exit may offer only
https. - Known gaps in 0.34.0, tracked in #989:
crates/node/README.mdandcrates/gateway/README.mdstill show
gateway.onion_service, which 0.34.0 rejects. Follow the configuration reference instead.- A leftover
max_circuitsormax_streams_per_circuitnext tomax_sessionsis ignored
rather than rejected. Delete both keys.
-
Start the node.
Onion routes need enough relays. A route needs four distinct live relays besides the client,
and one of them must register the exit service. With fewer, route selection fails instead of
shortening the path.
Upgrading from a release older than 0.33? Apply each release's notes in the CHANGELOG in turn.
For developers and embedders
- JSON-RPC
answerOfferandrings connect answermay return a counter-offer. To complete the
connection, answer it with the caller'sanswerOffer, then return that answer with the peer's
acceptAnswer.Swarm::answer_offerreturnsOfferReply<MessagePayload, MessagePayload>. - E2E streams.
E2eStreamDecryptor::newtakes the creation time.decrypt_nexttakes the frame's arrival time.- The new
check(now_ms)reports a stalled stream asError::E2eStreamStalled. Processor::check_e2e_streampolls a stream with the node's clock.
- Relay effects.
RelayEffect::Writegainsseq,Shutdowngainssent, and
SendDatagramis new. - Core links.
ConnectionStateChangeandPeerRetiredcarry the link generation.- New:
PeerLink,admitted_links(),connection_registry_capacity()and the
generation-exactdisconnect_link.
- New errors.
- A refused single-attempt write:
Err(SingleAttemptRefused { refusal }). - A cancelled application send:
Err(OutboundTransferCancelled), never reported as sent. Error::DelegationExpiresWithinMargin.Error::SerdeYamlErrorwraps a boxedserde_saphyr::Error.
- A refused single-attempt write:
ProcessorBuilder::onion_idle_floormay only lower the idle floor.
What's next
- #843 stays open until the ≥ 1 MB/s onion throughput benchmark is re-measured on 0.34.0.
- #834 (Onion Kleisli pipelines) continues with its later phases.
Questions and reports: GitHub issues or dev@rings.rs.