How the web node works
Relays connect browsers to the network
A browser can only use WebRTC. It can't open a TCP connection or speak libp2p, so it can't connect to an OCaml node. The native node speaks both. It uses libp2p with other nodes and WebRTC with browsers. Blocks pass from the Mina network to a relay, and then on to the browser.
A relay is any native node that browsers can reach. It needs three things:
- its signaling endpoint, over HTTPS for a public page:
--webrtc-signal-port - its WebRTC UDP ports open:
--webrtc-udp-ports - a public address, or
--webrtc-nat-ipbehind a 1:1 NAT
The web node's page lists its relays and dials each one. Its Peers page shows each relay, connected or not. Run a relay sets one up.
How a connection starts
- The browser sends a WebRTC offer to the relay's signaling endpoint over HTTPS, and gets an answer back. The offer and the answer describe each side's network addresses.
- The two sides then talk directly over WebRTC.
Two kinds of server help a connection start:
- STUN
- Lets the browser learn its own public address. The STUN server sees the browser's IP address. No data passes through it.
- TURN
- Carries the traffic when a network blocks the direct route, as some offices, VPNs, and carriers do. A relay's TURN server forwards only to that relay.
Most connections need no TURN, because each relay has a public address. The Peers page shows whether each relay's route is direct or goes through TURN.
How it syncs
- Over that connection, the web node downloads the staking ledgers and the recent blocks.
- It checks the best tip's proof itself, and fetches the blocks behind the tip by hash.
- It then follows new blocks as they are gossiped, and checks each one's proof.
A relay can stall the web node, but can't feed it a fake chain.
With several relays, the web node times each relay's answers and sends most of its requests to the nearest one. The staged ledger, one download of about 35 MiB, goes to the nearest relay too. A farther relay gets one request at a time, so it is ready to take over if the nearest one stops.
The saved chain
The web node saves its ledgers and recent blocks in the browser's storage. After a reload, it restores the chain from that copy, then catches up from its relays.
The node saves the chain shortly after it reaches Synced. A reload before that starts the sync again.
The Overview and Start-up pages show what a reload does with the saved chain. The node decides it with the same rules it applies when it restores.
- Not saved yet
- No chain is saved. A reload starts the sync again.
- Saved at #N
- A reload restores the chain up to block N. If a saved file fails the node's checks, the node syncs again instead.
- Saved, but a reload syncs again
- The saved chain can't be restored. The Start-up page gives the reason, such as a saved tip more than 1,160 slots old. The node reuses the saved ledgers, syncs, and saves a new chain.
- Checking
- The node is restoring the saved chain.
- Not known
- The node couldn't read what it needs to decide. The Start-up page gives the reason.
One tab per browser uses the saved chain. A second tab of the same browser runs a second node without it, which uses as much memory again. Close one of the tabs to stop its node.
The reset on the Start-up page deletes the saved chain and syncs again.
Why bootstrap blocks show Not checked
On the Blocks page, the blocks from the bootstrap show Not checked. The node fetched them by hash, back from a best tip whose proof it checked. It did not check each of those blocks' own proofs.
Each block that arrives after the bootstrap has its own proof checked.
One role per tab
A web node runs the SNARK worker or the block producer, not both. Choosing one role stops the other.
The reason is the block's deadline. A SNARK proof can't be stopped for a block proof. If the tab were proving SNARK work when it won a slot, the block proof would wait, and the block could miss its slot.
A native node can run both roles. It stops taking new worker jobs before a known won slot, as Start the worker with flags describes for --snarker-block-first-lead.
Your key
The Key page makes a key in the browser, from its random number generator, or imports one. The key stays in the tab's memory, and the page never sends it anywhere. The web node signs payments in the tab, in its WebAssembly, and sends them to the network through its relays.
To keep a key in the browser, save it with a passphrase. The page derives an AES-256-GCM key from the passphrase with PBKDF2-SHA-256 (600,000 iterations), and stores only the encrypted key, in this browser's storage. Anyone with the device and the passphrase can use the key.
Where SNARK worker fees go
The SNARK worker page fills in the key held or saved in the tab as the fee recipient. You can enter any other public key instead. A new key has no account on chain, so its fee must be at least 1 MINA. A key with an account can ask any fee. Choose the fee recipient has the details.
Sharing with other browsers
Sharing lets other visitors' web nodes sync from yours. It is off by default. Turn it on or off on the Peers page, and this browser keeps the choice. Either way, the node restarts, and a key or role that the tab holds carries over.
With sharing on, the web node behaves as follows:
- The page still dials only its relays. It asks them to introduce it to other browsers that turned sharing on.
- It connects to at most 4 browsers, and helps at most 2 of them sync at once.
- A browser it meets can't point it at a private address on your network. That browser can name public addresses, and your browser tries those.
- A relay introduces only pages that turned sharing on. Each relay permits at most 6 introductions per peer key per hour, 12 per IPv4 address or IPv6 /64 per hour, and 120 in total per hour.
What sharing costs you
- The browsers you connect to see your public IP address: IPv4, and IPv6 if you have it. An introduction exchanges WebRTC offers, and the offers hold each browser's addresses.
- Anyone who runs a modified page with sharing on sees it too. Such a page can keep asking for introductions, and record each address it gets, as fast as the relays' limits allow.
- The relay can't read the offers, because they are encrypted. The relay does see which browsers it introduced to each other.
- Sharing uses your upload. Each tab that you help sync takes up to about 130 MiB. Each connected browser then takes tens of MiB an hour, in each direction.
To stop, turn the switch off on the Peers page. The node restarts without sharing, and drops its browser connections.
With --webrtc-sharing-relay, a relay introduces only browsers that turned sharing on. 0.21.0 removes --webrtc-signaling-relay. Use --webrtc-sharing-relay instead. A relay without --webrtc-sharing-relay introduces no one, and sharing then finds no browsers.
Who sees your address
Each relay you connect to sees your IP address. So do the STUN and TURN servers that the page uses, and the hosts that its files come from. With sharing on, so do the browsers you connect to. On minaweb.org, the STUN and TURN servers run on the relays' hosts.
To use your own relay instead, run the web node yourself and point its --relay option at your own node.