Add some documentation on the exposed WASM API and WebRTC peer address format

Author: iostat

node/web/src/lib.rs

@@ -74,11 +74,57 @@ fn parse_bp_key(key: JsValue) -> Option<AccountSecretKey> {
     )
 }
 
+/// Starts a Mina node in a WASM environment and returns an RPC interface.
+///
+/// This is the main entry point for running a Mina node from JavaScript/WASM.
+/// It spawns the node in a separate thread, sets up all necessary components,
+/// and returns an RPC sender that can be used to communicate with the running
+/// node.
+///
+/// # Arguments
+///
+/// * `block_producer` - Block producer configuration as a JavaScript value.
+///   Can be one of:
+///   - `null`/`undefined`: No block production
+///   - `string`: Plain text secret key
+///   - `[encrypted_key, password]`: Array with encrypted key and password
+/// * `seed_nodes_urls` - Optional list of URLs to fetch peer lists from.
+///   Each URL should return newline-separated peer addresses. This is similar
+///   to the `--peer-list-url` flag in the native node, but allows multiple URLs
+///   to be supplied.
+/// * `seed_nodes_addresses` - Optional list of peer addresses to connect to
+///   directly, in [WebRTC Multiaddr-ish format](https://o1-labs.github.io/mina-rust/docs/developers/webrtc#address-format-differences)
+///   This is directly comparable to the `--peers` flag in the native node.
+/// * `genesis_config_url` - Optional URL to fetch genesis configuration from.
+///   Genesis config must be in bin_prot format. If not provided, uses the default
+///   devnet configuration.
+///
+/// # Returns
+///
+/// An `RpcSender` that can be used to send RPC commands to the running node.
+///
+/// # Panics
+///
+/// Panics if:
+/// - Block producer key parsing fails
+/// - Node setup or build fails
+/// - Genesis configuration cannot be fetched
+///
+/// # Example
+///
+/// ```javascript
+/// const rpc = await run(
+///   null,  // No block production
+///   ["https://bootnodes.minaprotocol.com/networks/devnet-webrtc.txt"],
+///   ["/PEER_ID/https/webrtc-peer-signaling.example.com/443"],
+///   null, // Use the default devnet configuration
+/// );
+/// ```
 #[wasm_bindgen]
 pub async fn run(
     block_producer: JsValue,
     seed_nodes_urls: Option<Vec<String>>,
-    seed_nodes_fixed: Option<Vec<String>>,
+    seed_nodes_addresses: Option<Vec<String>>,
     genesis_config_url: Option<String>,
 ) -> RpcSender {
     let block_producer = parse_bp_key(block_producer);
@@ -89,7 +135,7 @@ pub async fn run(
             let mut node = setup_node(
                 block_producer,
                 seed_nodes_urls,
-                seed_nodes_fixed,
+                seed_nodes_addresses,
                 genesis_config_url,
             )
             .await;
@@ -106,7 +152,7 @@ pub async fn run(
 async fn setup_node(
     block_producer: Option<AccountSecretKey>,
     seed_nodes_urls: Option<Vec<String>>,
-    seed_nodes_fixed: Option<Vec<String>>,
+    seed_nodes_addresses: Option<Vec<String>>,
     genesis_config_url: Option<String>,
 ) -> mina_node_common::Node<NodeService> {
     let block_verifier_index = BlockVerifier::make().await;
@@ -127,7 +173,8 @@ async fn setup_node(
         .work_verifier_index(work_verifier_index.clone());
 
     // TODO(binier): refactor
-    let mut all_raw_peers = seed_nodes_fixed.unwrap_or_default();
+    let mut all_raw_peers = seed_nodes_addresses.unwrap_or_default();
+
     if let Some(seed_nodes_urls) = seed_nodes_urls {
         for seed_nodes_url in seed_nodes_urls {
             let peers = ::node::core::http::get_bytes(&seed_nodes_url).await;

website/docs/developers/webrtc.md

@@ -181,6 +181,71 @@ The Web Node represents a significant advancement in blockchain accessibility,
 enabling truly decentralized participation without requiring users to install
 native applications or manage complex network configurations.
 
+## Address Format Differences
+
+The Mina Rust Node uses a custom Multiaddr-like format for WebRTC peer addresses
+that differs from normal Multiaddrs. These addresses are specifically designed
+to encode signaling server information rather than direct network addresses,
+reflecting the different connection model of WebRTC versus direct TCP/UDP
+connections.
+
+The address parsing logic is implemented in
+[`p2p/src/connection/outgoing/mod.rs`](https://github.com/o1-labs/mina-rust/blob/develop/p2p/src/connection/outgoing/mod.rs)
+through the `FromStr` implementation for `P2pConnectionOutgoingInitOpts`. The
+parser distinguishes between libp2p addresses (starting with `/ip` or `/dns`)
+and WebRTC addresses (all other formats).
+
+### WebRTC peer address format
+
+WebRTC peer addresses follow this structure:
+
+```
+/{peer_id}/{signaling_method}
+```
+
+Where `{peer_id}` is the base58-encoded peer ID and `{signaling_method}`
+specifies how to reach the signaling server.
+
+### Signaling method formats
+
+The signaling method component can take several forms:
+
+**HTTP signaling:**
+
+```
+/http/{host}/{port}
+```
+
+Example:
+`/12D3KooWRTzN7HfmjoUBHokyRZuKdyohVVSGqKBMF24ZC3tGK74R/http/localhost/8080`
+
+**HTTPS signaling:**
+
+```
+/https/{host}/{port}
+```
+
+Example:
+`/12D3KooWRTzN7HfmjoUBHokyRZuKdyohVVSGqKBMF24ZC3tGK74R/https/signal.example.com/443`
+
+**HTTPS proxy signaling:**
+
+```
+/https_proxy/{cluster_id}/{host}/{port}
+```
+
+Example:
+`/12D3KooWRTzN7HfmjoUBHokyRZuKdyohVVSGqKBMF24ZC3tGK74R/https_proxy/123/proxy.example.com/443`
+
+**P2P relay signaling:**
+
+```
+/p2p/{relay_peer_id}
+```
+
+Example:
+`/12D3KooWRTzN7HfmjoUBHokyRZuKdyohVVSGqKBMF24ZC3tGK74R/p2p/12D3KooWABC...`
+
 ## Future Considerations
 
 While the current OCaml implementation doesn't use WebRTC, the Rust

website/docs/node-operators/webnode/local-webnode-docker.md

@@ -54,8 +54,45 @@ update the port accordingly.
 The Dockerized WebNode can be configured with additional environment variables
 to customize behavior.
 
-| Environment Variable        | Required? | Description                                                            |
-| :-------------------------- | :-------: | :--------------------------------------------------------------------- |
-| `MINA_FRONTEND_ENVIRONMENT` |    Yes    | Must be set to `webnode` to run the frontend in webnode mode           |
-| `MINA_WEBNODE_SEED_URLS`    |    No     | A comma-separated list of http(s) URLs to fetch initial P2P Seeds from |
-| `MINA_WEBNODE_BOOTNODES`    |    No     | A comma-separated list of initial peers in WebRTC-Multiaddrish format  |
+### `MINA_FRONTEND_ENVIRONMENT`
+
+This is required to launch the frontend in general. To serve a webnode, it must
+be set to the value `webnode`.
+
+Example:
+
+```
+-e MINA_FRONTEND_ENVIRONMENT=webnode
+```
+
+### `MINA_WEBNODE_SEED_URLS`
+
+A comma-separated list of http(s) URLs to fetch initial P2P seeds from. This is
+similar to the `--peer-list-url` flag in the native node, but can take multiple
+comma-separated values to fetch peer lists from multiple sources. Each peer list
+file must contain peer addresses in
+[WebRTC-Multiaddrish format](../../developers/webrtc.md#address-format-differences),
+separated by a newline.
+
+Example:
+
+```
+-e MINA_WEBNODE_SEED_URLS=https://bootnodes.minaprotocol.com/networks/devnet-webrtc.txt
+-e MINA_WEBNODE_SEED_URLS=https://example.com/extra-peers.txt,https://bootnodes.minaprotocol.com/networks/devnet-webrtc.txt,
+```
+
+### `MINA_WEBNODE_BOOTNODES`
+
+A comma separated list of
+[WebRTC-Multiaddrish](../../developers/webrtc.md#address-format-differences)
+peer addresses, to attempt to connect to in conjunction to any downloaded from
+`MINA_WEBNODE_SEED_URLS`. This is akin to the `--peers` flag in the native node,
+but instead of specifying the flag multiple times, each peer is simply
+comma-separated
+
+Example:
+
+```
+-e MINA_WEBNODE_BOOTNODES=/peer_id1/https/signaling.example.com/443
+-e MINA_WEBNODE_BOOTNODES=/peer_id1/https/signaling.example.com/443,/peer_id2/p2p/peer_id1
+```