[Deliverable] Waku as a Signal Network (WebRTC) PoC

[weboko]

Summary

This deliverable is a place holder to create a new @waku/rtc library for browser users.

Proposed API:

const waku = createLightNode();
const rtcConnection: RTCPeerConnection = createWakuRTC(waku, peerId, {
  iceServers: [
    {
      urls: [
        "stun:stun.l.google.com:19302",
        "stun:stun1.l.google.com:19302"
      ]
    },
    // TURN servers with authentication
    {
      urls: [
        "turn:turn.example.com:3478?transport=udp",
        "turn:turn.example.com:3478?transport=tcp"
      ],
      username: "username",
      credential: "password",
      credentialType: "password"
    }
  ]
});

Proposed library should adapt following protocol:
https://www.notion.so/Waku-Phone-Protocol-1ba8f96fb65c80cd862cf51fe2927450

Deliverables of this item:

• publish adapted spec;
• provide @waku/rtc library;

FURPS

Functionality

• Establishes a 1:1 RTCPeerConnection between two peers using Waku as the signaling layer.
• Uses browser WebRTC for ICE, STUN, and TURN handling.
• Offers a high-level API: connect, onIncommingRequest, accept.
• Encrypts SDP/CANDIDATE payloads within the signaling messages.
• Handles message exchange based on the provided proto spec (dial, ringing, answer, candidate, bye, etc.).

Usability

• Targeted at browser app developers, Waku consumers, and real-time application developers.
• Minimalistic design: the WebRTC connection configuration is passed from the outside.
• Designed for simplicity: single-entry connect() method with event-based inbound handling.

Reliability

• Ensures message delivery with UUID-based tracking and retry logic until ACK is received.
• Implements basic retry loop for signaling messages (e.g., DIAL, CANDIDATE).
• No connection health monitoring (e.g., ping-pong or keepalive) — left to application logic.

Performance

• No custom ICE handling — defers to WebRTC stack in the browser.
• Can parallelize signaling (e.g., sending offer + trickle ICE simultaneously).
• Optimized for quick call setup using Waku LightPush + Filter.

Supportability

• Unit tested and part of the js-waku suite of tools.
• Example app included to demonstrate connection lifecycle and event handling.
• Fully pluggable with LightNode, and supports LightPush, Filter, and optionally Store.
• Logs and error handling designed to integrate with developer debugging.

---

Owner: js-waku

Feature: Waku as a Signal Network

FURPS:

• F1. Establish direct connection to remote peer using their public key as identifier.

• U1. Developers can implement their own application-level discovery method.

• U2. Only remote peer's public key is needed to initiate connection.

• U3. Hook is provided for developer to filter inbound connection requests.

• R1. End-to-end reliability is implemented for the signaling conversation.

• R2. No provided reliability for established connections, left to the developer (e.g. keep alive).

• S1. Developers can use this protocol in web application, imported from npmjs.com.

• S2. Developers can use this protocol to initiate WebRTC connections.

• S3. Only 1:1 direct connections are supported.

• +1. Network observers cannot retrieve node connection details; forward secrecy is not included.

• +2. STUN and TURN servers may be required for WebRTC usage.

Checklist:

• Specs: link to specs and/or API definition
• Code: link to GitHub issues/PRs/Epic
• Dogfood: link to dogfooding session/artefact
• Docs: links to README.md or docs.waku.org (TBD)

[fryorcraken]

So if I understand correctly, this enables 2 users to:

• Have an identifier
• Use this identifier to call each other
• Initial setup is done over Waku
• But then, it's handed over to WebRTC

I think it's a fine use case for "Waku as signalling network". I'd be keen to frame it more like that, because we know it's a use of Waku the community want.

Also would be keen to understand the decentralization of this, what would be the next steps for this use case specifically (would be beyond signaling example)

1. Usage of random/decentralized STUN servers? STUN servers are very light in terms of resource demand, we could have wakunode2 provide this service out of the box and be discoverable (capability discovery)
2. Decentralized TURN servers: this is a resource intensive service, and would need to assume the existing of incentivization and adaptation to TURN.

Noting that you were able to have calls without TURN, which is interesting.

[weboko]

So if I understand correctly, this enables 2 users

yes, and to add to it, identifiers are libp2p peerIds, which is convenient for Waku (need to add to FURPS)

I think it's a fine use case for "Waku as signalling network"

exactly

the next steps for this use case

in terms of library:

• STUN / TURN servers can be provided by consumers for the first iteration;
• we need to learn more about many-to-many use case in WebRTC and implement (this draft proposes 1:1 connection);

in term of Waku having users of this library would allow us to:

• dogfood marketplace / incentivization once ready
• provide decentralized STUN / TURN by using previous point
• enable maybe decentralized(there is a lot of things actually afaik) many-to-many topology by leveraging previous points

In our case it worked because it seems it was enough to use default Google's stun:stun.l.google.com:19302 for NAT traversal and it seems our networks are UDP friendly.

TURN would've been needed if we were not lucky with such good network conditions.

[fryorcraken]

we need to learn more about many-to-many use case in WebRTC and implement (this draft proposes 1:1 connection

I'd be more keen to decentralize first before extending the functionality, so we build on the rright foundations.

dogfood marketplace / incentivization once ready

Do you mean with TURN? Or do you mean it would increase Waku usage in general?

[weboko]

I'd be more keen to decentralize first before extending

totally share it, we need to know how to make these work right

Do you mean with TURN? Or do you mean it would increase Waku usage in general?

I mean both, more usage for existing / new things, potential upsell to our revenue generation features

[chair28980]

@weboko I added the description/furps/checklist from https://github.com/waku-org/pm/blob/master/draft-roadmap/streamline_dev_ex_local_dev_rust.md

Can you please align the existing description with the diff, thank you!