Skip to content

v0.34.0

Choose a tag to compare

@github-actions github-actions released this 20 Oct 16:33
· 16 commits to master since this release
1407066

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.

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 → guard and 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 crate rings-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.
    • tcp and https sessions 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.
    • User storage sends re-route from fresh topology after a refusal (#859, #862).
    • A node reads its own writes, whichever owner a lookup reaches (#948, #982).
  • Gateway. It names the cause of every captured-flow reset and degraded status (#950).
  • Dependencies.
    • rustls 0.23.46, for RUSTSEC-2026-0346..0349 (#956).
    • YAML is read and written with serde-saphyr, replacing the unmaintained serde_yaml
      (RUSTSEC-2024-0449). Configuration documents are unchanged.

Upgrading a native node from 0.33

  1. Stop the node and back up ~/.rings.

  2. Clear the DHT data store. This is the data_storage path of the configuration (by default
    ~/.rings/data), or the data directory under rings run --storage-path when 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.
  3. Install the 0.34.0 binary.

  4. 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_SERVICE environment variable is removed.
    • onion_exit_services accepts only tcp and https; any other name is rejected.
      • https is one request/response fetch.
      • Every tunnel uses tcp: HTTP CONNECT, SOCKS and captured gateway flows.
      • For TLS-only egress, register tcp with the allowed target *:443.
    • Exit targets accept *:<port>.
    • Role prerequisites:
      • A relay (advertise_onion_relay: true) requires advertise_presence: true.
      • An exit (advertise_onion_exit: true) requires advertise_onion_relay: true.
    • A browser exit may offer only https.
    • Known gaps in 0.34.0, tracked in #989:
      • crates/node/README.md and crates/gateway/README.md still show
        gateway.onion_service, which 0.34.0 rejects. Follow the configuration reference instead.
      • A leftover max_circuits or max_streams_per_circuit next to max_sessions is ignored
        rather than rejected. Delete both keys.
  5. 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 answerOffer and rings connect answer may return a counter-offer. To complete the
    connection, answer it with the caller's answerOffer, then return that answer with the peer's
    acceptAnswer. Swarm::answer_offer returns OfferReply<MessagePayload, MessagePayload>.
  • E2E streams.
    • E2eStreamDecryptor::new takes the creation time.
    • decrypt_next takes the frame's arrival time.
    • The new check(now_ms) reports a stalled stream as Error::E2eStreamStalled.
    • Processor::check_e2e_stream polls a stream with the node's clock.
  • Relay effects. RelayEffect::Write gains seq, Shutdown gains sent, and
    SendDatagram is new.
  • Core links.
    • ConnectionStateChange and PeerRetired carry the link generation.
    • New: PeerLink, admitted_links(), connection_registry_capacity() and the
      generation-exact disconnect_link.
  • New errors.
    • A refused single-attempt write: Err(SingleAttemptRefused { refusal }).
    • A cancelled application send: Err(OutboundTransferCancelled), never reported as sent.
    • Error::DelegationExpiresWithinMargin.
    • Error::SerdeYamlError wraps a boxed serde_saphyr::Error.
  • ProcessorBuilder::onion_idle_floor may 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.


0.34.0 - 2026-10-20