Skip to main content

subrelay: The SUBFROST Relay

subrelay is a critical component of the SUBFROST networking stack. It acts as a rendezvous point, a traffic relay, and a name registrar for the subp2p network. By providing these essential services, subrelay enables peers to connect to each other reliably, even when they are behind restrictive firewalls or NATs.

WebTransport and Censorship Resistance​

subrelay is designed to be highly accessible and resistant to censorship. It achieves this by using WebTransport as its primary transport protocol. WebTransport is a modern, QUIC-based protocol that is designed to be used in web browsers and can be easily proxied by standard web servers and CDNs.

This has a significant advantage: a subrelay server can be deployed behind a service like Cloudflare. By doing so, the relay's IP address is hidden, and its traffic is blended with normal web traffic, making it much more difficult for censors to block.

To connect to a subrelay that is behind a CDN, a peer simply needs to know its DNS address. The subp2p networking layer will automatically resolve the DNS address and establish a secure WebTransport connection to the relay.

For example, a subrelay might have the following multiaddress:

/dns4/p2p.subfrost.io/udp/8443/quic-v1/webtransport

In this address, p2p.subfrost.io is a DNS name that can be pointed to a Cloudflare endpoint, which then forwards the traffic to the actual subrelay server.

Circuit Relaying​

When two peers are unable to establish a direct connection (e.g., because they are both behind NATs), they can use a subrelay to communicate. This is known as circuit relaying.

Here's how it works:

  1. A peer that wants to be reachable via a relay establishes a reservation with the subrelay.
  2. The subrelay provides the peer with a special /p2p-circuit address.
  3. The peer can then share this circuit address with other peers.
  4. When another peer wants to connect, it dials the circuit address. The subrelay will then forward the traffic between the two peers.

This mechanism allows for seamless communication between any two peers on the subp2p network, regardless of their network conditions.

Name Registration and Discovery​

In addition to its relaying capabilities, subrelay also provides a simple name registration and discovery service. This allows peers to register human-readable names (e.g., my-service.rail) and associate them with their PeerId.

Other peers can then resolve these names to get the PeerId and establish a connection. This provides a user-friendly alternative to sharing long, cryptic PeerIds.

The name registration service is built on top of the request_response protocol in libp2p. A peer can send a RegisterName request to the subrelay, and the relay will store the mapping in its local memory. When another peer sends a ResolveName request, the relay will look up the name and return the corresponding PeerId.

subrelay in SUBFROST​

The subfrost-cli can be used to run a subrelay server. This is useful for creating a private SUBFROST network or for providing a relay for the public network.

Running a subrelay Server​

Here is an example of how to run a subrelay server:

subfrost-cli relay --listen /ip4/0.0.0.0/udp/8443/quic-v1/webtransport

This command will start a subrelay server that listens on port 8443 for WebTransport connections. You can then connect to this relay by using its multiaddress.