Transport

This page describes how clients connect to the server at the network level, and how to choose the addresses it listens on.

The stack

Ricochet protocols (/sf-network/..., /ricochet/...)
    |
Yamux       stream multiplexing
    |
Noise       encryption and mutual authentication
    |
UDX         reliable transport over UDP: ordered streams, congestion and flow control
    |
UDP

UDX is the only transport. The host is built with libp2p.NoTransports plus the UDX transport, so it does not listen on TCP, QUIC, WebSockets or WebRTC. A client must speak UDX to connect. The Go client gets it from github.com/stephanfeb/go-libp2p-udx-transport; for other languages see UDX: Go, Dart, JS.

Each connection is secured with Noise. The handshake authenticates both ends by their Ed25519 identity keys, so the server knows which peer is on every connection, and every access check uses that peer ID. See Identity keys.

Yamux carries many streams over one connection, one per protocol exchange. The server tunes Yamux for mobile clients: a keepalive every 15 seconds and a 10-second write timeout, so a dead connection is detected within about 25 seconds. A connection accepts up to 512 concurrent inbound streams.

Listen addresses

The default is one address: every IPv4 interface, UDP port 55223.

/etc/ricochet/config.yaml

server:
  listen_addresses:
    - /ip4/0.0.0.0/udp/55223/udx

Listen addresses are multiaddrs. Some variations:

Address	Listens on
/ip4/0.0.0.0/udp/55223/udx	Every IPv4 interface (default)
/ip4/10.0.0.5/udp/55223/udx	One IPv4 interface
/ip6/::/udp/55223/udx	Every IPv6 interface; on Linux, IPv4 as well through the dual-stack socket

Note

On Linux, listing both /ip6/::/udp/55223/udx and /ip4/0.0.0.0/udp/55223/udx on the same port fails, because the IPv6 socket already claims both address families. List one.

To change only the port, use --port (or LISTEN_PORT on the .deb install). It rewrites the port in every listen address. The file’s server.port rewrites only the default address: once you set listen_addresses, put the port in them.

External addresses

The addresses the server advertises to peers (through libp2p’s Identify protocol) are its listen addresses as seen on its own interfaces, plus any you add:

/etc/ricochet/config.yaml

server:
  external_addresses:
    - /ip4/203.0.113.10/udp/55223/udx

Or --external-addrs /ip4/203.0.113.10/udp/55223/udx (comma-separated for more than one). Set this whenever the host’s own interfaces carry private addresses, which includes most cloud VMs. Without it, a client that reconnects after a dropped connection has only private addresses for the server and cannot reach it.

At startup the server logs advertising external addresses with the count it accepted, and host advertised addresses with the full list. An address that does not parse is skipped with invalid external address, skipping.

Firewall

Open the UDP listen port (55223 by default) inbound. Keep the ops port (TCP 9090) closed to the outside; it binds to loopback by default. See Health & readiness.

Relayed connections

With the relay service on (the default), the server also accepts Circuit Relay v2 reservations and relays connections between peers that cannot reach each other directly. Those relayed connections ride on UDX connections to the server. See NAT traversal & relay.

Check it works

# Which UDP sockets the process holds
sudo ss -ulpn | grep 55223

In the log, server started lists the listen addresses (field addrs), and registered protocols lists every protocol ID the host serves.

Troubleshooting

• Clients time out connecting: check that the UDP port is open end to end, including any cloud security group. A TCP port check tells you nothing here.
• Clients connect once, then cannot reconnect: the server advertises only private addresses. Set external_addresses.
• Startup fails binding the port: another process holds it, or you listed both an IPv6 wildcard and an IPv4 wildcard on the same port.