Add mesh.html — browser↔browser block propagation (PoC)

Open in two tabs: they become Bitcoin peers over a direct WebRTC data channel
(meeting in a room on a JSS pod, no server in the data path), then relay a block
inv → getdata → block, validating it (PoW + merkle). New, additive; nothing
existing touched.
- peer-mesh.js: MeshPeer — joins a room, offerer/answerer by join order,
  non-trickle ICE; speaks real Bitcoin messages over the channel.
- test-mesh.mjs: node-side proof — two peers relay block #26000, validated
  (29 txs, correct hash), no server in the path.
- mesh's own room (distinct from the bridge's room).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Melvin Carvalho

mesh.html

@@ -0,0 +1,140 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>bitcoin-kernel/browser-node — mesh: browser↔browser block propagation</title>
+<style>
+  :root { --bg:#fff; --fg:#16181d; --mut:#5b6470; --bd:#e6e8eb; --pan:#fafbfc; --ac:#e8830c; --ac2:#0969da; --good:#1a7f37; --bad:#cf222e; --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; color-scheme:light; }
+  body { background:var(--bg); color:var(--fg); font:14px/1.5 var(--mono); max-width:760px; margin:24px auto; padding:0 16px; }
+  h1 { font-size:18px; } a { color:var(--ac2); }
+  button { background:var(--pan); color:var(--fg); border:1px solid var(--bd); border-radius:6px; padding:9px 16px; cursor:pointer; font:inherit; }
+  button:hover { background:#f0f2f4; border-color:var(--ac); } button:disabled { opacity:.45; cursor:default; }
+  .grid { display:grid; grid-template-columns:repeat(3,1fr); gap:10px; margin:14px 0; }
+  .card { border:1px solid var(--bd); border-radius:8px; padding:10px 12px; background:var(--pan); }
+  .card .k { color:var(--mut); font-size:12px; text-transform:uppercase; letter-spacing:.04em; }
+  .card .v { font-size:20px; color:var(--fg); margin-top:3px; }
+  .card .s { color:var(--mut); font-size:12px; }
+  #log { background:var(--pan); border:1px solid var(--bd); border-radius:6px; padding:12px; height:200px; overflow:auto; white-space:pre-wrap; margin-top:12px; }
+  .ok{color:var(--good)} .warn{color:var(--ac)} .err{color:var(--bad)} .dim{color:var(--mut)}
+  .dot{ display:inline-block; width:9px; height:9px; border-radius:50%; background:var(--mut); margin-right:6px; vertical-align:middle; }
+  .dot.live{ background:var(--good); animation:pulse 2s ease-in-out infinite; }
+  @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:.35} }
+</style>
+</head>
+<body>
+<h1>bitcoin-kernel / browser-node — mesh <span class="dim">(block propagation · PoC)</span></h1>
+<p class="dim"><b>Open this page in two tabs</b> (or send the link to a friend). The two tabs become Bitcoin peers to each other
+over <b>WebRTC — no server in the data path</b> — meeting in a room on a signaling server. Then one tab <b>relays a block</b> to
+the other: it announces it (<code>inv</code>), the other requests it (<code>getdata</code>), receives the block, and
+<b>validates it</b> (proof-of-work + merkle root). That's block propagation, in a browser mesh.
+<a href="node.html">the node</a> · <a href="how-it-works.html">how it works</a></p>
+
+<p>
+  <button id="connect">▶ Connect to the mesh</button>
+  <button id="share" disabled>📤 Relay block #26,000 to the peer</button>
+  <span id="status" class="dim">idle</span>
+</p>
+
+<div class="grid">
+  <div class="card"><div class="k"><span class="dot" id="dot"></span>mesh</div><div class="v" id="mesh">—</div><div class="s" id="role">browser ↔ browser</div></div>
+  <div class="card"><div class="k">blocks relayed</div><div class="v" id="relayed">0</div><div class="s">inv → getdata → block</div></div>
+  <div class="card"><div class="k">last block validated</div><div class="v" id="last">—</div><div class="s" id="lasthash">PoW + merkle</div></div>
+</div>
+<div id="log"></div>
+
+<p class="dim" style="margin-top:14px; border-top:1px solid var(--bd); padding-top:10px">
+PoC scope: the relayed block is a bundled sample (<code>data/block-26000.hex</code>), validated for structure + proof-of-work
+(no UTXO set, so not full-consensus). Next steps: source the block live from the network (via the bridge), relay across more
+than two peers, and stream the full chain. Default room <code>c0ffeebabe123456</code>; override with
+<code>?room=&lt;hex&gt;</code> and the signaling server with <code>?signal=wss://your.pod/.webrtc</code>.</p>
+
+<script type="module">
+import { Codec } from './engine/codec/codec.js';
+import { P2pEngine } from './engine/codec/p2p.js';
+import { BlockEngine } from './engine/codec/blocks.js';
+import { MeshPeer } from './peer-mesh.js';
+
+const $ = (id) => document.getElementById(id);
+const log = (m, c='') => { const t = new Date().toISOString().slice(11,19); $('log').innerHTML += `<span class="dim">${t}</span> <span class="${c}">${m}</span>\n`; $('log').scrollTop = $('log').scrollHeight; };
+const fmt = (n) => Number(n).toLocaleString();
+const setStatus = (m, c='') => $('status').innerHTML = `<span class="${c}">${m}</span>`;
+const MSG_BLOCK = 2;
+
+const q = new URLSearchParams(location.search);
+const signalUrl = q.get('signal') || 'wss://melvincarvalho.com/.webrtc';
+const room = q.get('room') || 'c0ffeebabe123456';   // mesh's own room (distinct from the bridge's room)
+
+let codec, p2p, be, peer = null;
+const have = new Map();      // blockHash -> hex (blocks we can serve)
+let relayed = 0;
+
+async function loadEngine() {
+  const jl = (n) => fetch(`./engine/schema/${n}.jsonld`).then(r => r.json());
+  const [core, proof, p2pS, chain, validate, script] = await Promise.all(['core','proof','p2p','chain','validate','script'].map(jl));
+  codec = new Codec(core, proof, p2pS);
+  p2p = P2pEngine.fromSchemas(codec, p2pS, chain, 'btc:testnet4');
+  be = BlockEngine.fromSchemas(codec, chain, validate, script, 'btc:testnet4');
+}
+
+// Handle a Bitcoin message arriving from the mesh peer.
+function onMessage(msg) {
+  if (msg.command === 'inv') {
+    for (const it of msg.payload?.items ?? []) {
+      if (!have.has(it.hash)) { log(`← inv: peer has block ${it.hash.slice(0,16)}… → requesting (getdata)`); peer.send('getdata', { items: [{ type: MSG_BLOCK, hash: it.hash }] }); }
+    }
+  } else if (msg.command === 'getdata') {
+    for (const it of msg.payload?.items ?? []) {
+      const hex = have.get(it.hash);
+      if (hex) { log(`← getdata for ${it.hash.slice(0,16)}… → sending the block`); peer.send('block', hex); }
+    }
+  } else if (msg.command === 'block') {
+    const block = msg.payload;
+    const hash = codec.blockHash(block.header);
+    const failed = be.validateBlockStructure(block).results.filter(r => r.ok === false).map(r => r.rule);
+    if (failed.length) { log(`← block ${hash.slice(0,16)}… ✗ INVALID: ${failed.join(', ')}`, 'err'); return; }
+    const reHex = Array.from(codec.encode('Block', block), (b) => b.toString(16).padStart(2, '0')).join('');
+    have.set(hash, reHex);   // now we hold it too — could relay onward (mesh)
+    relayed++; $('relayed').textContent = fmt(relayed);
+    $('last').textContent = '#26,000'; $('lasthash').textContent = hash.slice(0, 22) + '…';
+    log(`✅ received + validated block ${hash.slice(0,16)}… (${block.transactions.length} txs, PoW + merkle ✓) — from a browser peer, no server`, 'ok');
+  }
+}
+
+$('connect').onclick = async () => {
+  $('connect').disabled = true;
+  try {
+    setStatus('loading engine…', 'warn');
+    if (!be) await loadEngine();
+    setStatus(`joining the mesh room ${room.slice(0,10)}…`, 'warn');
+    log(`connecting to the mesh (signaling ${signalUrl})…`);
+    peer = new MeshPeer(p2p, codec, { log, onMessage, onOpen: (role) => {
+      $('dot').classList.add('live'); $('mesh').textContent = 'connected';
+      $('role').textContent = `you are the ${role}`;
+      $('share').disabled = false;
+      setStatus('● connected to a peer — relay a block', 'ok');
+      log(`mesh connected (you are the ${role}) — a direct browser↔browser channel, no server in the path`, 'ok');
+    } });
+    await peer.connect(signalUrl, { room });
+  } catch (e) {
+    setStatus('mesh error: ' + e.message, 'err');
+    log('mesh: ' + e.message + ' — is the page open in a second tab? (one tab waits for the other)', 'err');
+    $('connect').disabled = false;
+  }
+};
+
+$('share').onclick = async () => {
+  try {
+    const hex = (await (await fetch('./data/block-26000.hex')).text()).trim();
+    const block = codec.decode('Block', hex);
+    const hash = codec.blockHash(block.header);
+    have.set(hash, hex);
+    log(`announcing block #26,000 ${hash.slice(0,16)}… to the peer (inv)`, 'ok');
+    peer.send('inv', { items: [{ type: MSG_BLOCK, hash }] });
+  } catch (e) { log('share failed: ' + e.message, 'err'); }
+};
+
+log(`idle — press ▶ Connect, then open this page in a second tab. Room ${room.slice(0,10)}… via ${signalUrl}.`, 'dim');
+</script>
+</body>
+</html>

peer-mesh.js

@@ -0,0 +1,90 @@
+// MeshPeer: a browser-to-browser Bitcoin peer. Two tabs join the same room on a
+// signaling server (a JSS pod's /.webrtc) and connect DIRECTLY over a WebRTC data
+// channel — no server in the data path — then speak real Bitcoin p2p messages
+// (inv / getdata / block). This is the propagation transport: a tab can relay a
+// block to another tab. Role is decided by join order: the peer already in the
+// room answers; a later joiner offers (so two tabs pair up deterministically).
+//
+// Non-trickle ICE (room signaling has no candidate relay): gather candidates into
+// the SDP before sending. Mirrors the proven node-side relay (rtc-signaling.mjs).
+export class MeshPeer {
+  constructor(engine, codec, { onOpen, onMessage, log } = {}) {
+    this.engine = engine; this.codec = codec;
+    this.onOpen = onOpen; this.onMessage = onMessage; this.log = log || (() => {});
+    this.buf = new Uint8Array(0);
+    this.dc = null; this.pc = null; this.ws = null; this.role = null;
+  }
+
+  connect(signalUrl, { room = 'b17c0192abad1deacafe', iceServers = [{ urls: 'stun:stun.l.google.com:19302' }], timeout = 25000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const ws = this.ws = new WebSocket(signalUrl);
+      const offerId = 'o' + Math.random().toString(36).slice(2);
+      let settled = false, announceTimer = null, offerSdp = null;
+      const stop = () => { clearTimeout(to); clearInterval(announceTimer); };
+      const to = setTimeout(() => { if (!settled) { settled = true; stop(); reject(new Error('mesh connect timeout')); } }, timeout);
+
+      const setupDC = (dc) => {
+        this.dc = dc; dc.binaryType = 'arraybuffer';
+        dc.onopen = () => { if (settled) return; settled = true; stop(); this.onOpen?.(this.role); resolve(this); };
+        dc.onmessage = (ev) => this.#onData(new Uint8Array(ev.data));
+        dc.onclose = () => this.log('mesh peer disconnected', 'warn');
+      };
+
+      // Later joiner → offerer: create the channel + offer, announce it.
+      const becomeOfferer = async () => {
+        this.role = 'offerer';
+        const pc = this.pc = new RTCPeerConnection({ iceServers });
+        setupDC(pc.createDataChannel('mesh'));
+        await pc.setLocalDescription(await pc.createOffer());
+        await iceComplete(pc);
+        offerSdp = pc.localDescription.sdp;
+        const announce = () => { if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'announce', resource: room, offers: [{ sdp: offerSdp, offer_id: offerId }] })); };
+        announce(); announceTimer = setInterval(announce, 2500);
+      };
+
+      // Already in the room → answerer: answer an incoming offer.
+      const answerOffer = async (m) => {
+        this.role = 'answerer';
+        const pc = this.pc = new RTCPeerConnection({ iceServers });
+        pc.ondatachannel = (ev) => setupDC(ev.channel);
+        await pc.setRemoteDescription({ type: 'offer', sdp: m.sdp });
+        await pc.setLocalDescription(await pc.createAnswer());
+        await iceComplete(pc);
+        ws.send(JSON.stringify({ type: 'answer', resource: room, to: m.from, offer_id: m.offer_id, sdp: pc.localDescription.sdp }));
+      };
+
+      ws.onopen = () => ws.send(JSON.stringify({ type: 'announce', resource: room, offers: [] }));  // join, learn who's here
+      ws.onmessage = async (ev) => {
+        let m; try { m = JSON.parse(ev.data); } catch { return; }
+        if (m.type === 'resource-peers' && this.role === null) {
+          if (m.count > 0) becomeOfferer().catch((e) => { if (!settled) { settled = true; stop(); reject(e); } });
+          else { this.role = 'waiting'; this.log('in the room — waiting for a peer to join (open this page in another tab)…'); }
+        } else if (m.type === 'offer' && m.resource === room && this.role === 'waiting') {
+          answerOffer(m).catch((e) => this.log('answer failed: ' + e.message, 'warn'));
+        } else if (m.type === 'answer' && m.resource === room && m.offer_id === offerId && this.role === 'offerer' && this.pc && !this.pc.currentRemoteDescription) {
+          try { await this.pc.setRemoteDescription({ type: 'answer', sdp: m.sdp }); } catch {}
+        }
+      };
+      ws.onerror = () => { if (!settled) { settled = true; stop(); reject(new Error('signaling error')); } };
+    });
+  }
+
+  send(command, payload) { if (this.dc?.readyState === 'open') this.dc.send(this.engine.encodeMessage(command, payload)); }
+  close() { try { this.dc?.close(); } catch {} try { this.pc?.close(); } catch {} try { this.ws?.close(); } catch {} }
+
+  #onData(chunk) {
+    const merged = new Uint8Array(this.buf.length + chunk.length);
+    merged.set(this.buf); merged.set(chunk, this.buf.length);
+    const { messages, consumed } = this.engine.decodeStream(merged);
+    this.buf = merged.slice(consumed);
+    for (const msg of messages) this.onMessage?.(msg);
+  }
+}
+
+function iceComplete(pc) {
+  return new Promise((res) => {
+    if (pc.iceGatheringState === 'complete') return res();
+    const c = () => { if (pc.iceGatheringState === 'complete') { pc.removeEventListener('icegatheringstatechange', c); res(); } };
+    pc.addEventListener('icegatheringstatechange', c);
+  });
+}

test-mesh.mjs

@@ -0,0 +1,53 @@
+// De-risk the mesh relay: two peers join the same room (no bridge, no server in
+// the path) and relay a Bitcoin block between them over a direct WebRTC data
+// channel. Proves the browser↔browser propagation transport that mesh.html uses
+// (here both ends are node-datachannel; the browser mirrors it with RTCPeerConnection).
+import { readFile } from 'node:fs/promises';
+import nodeDataChannel from 'node-datachannel';
+import { Codec } from './engine/codec/codec.js';
+import { P2pEngine } from './engine/codec/p2p.js';
+import { startSignaling } from './signaling-stub.mjs';
+import { connectAsOfferer, connectAsAnswerer } from './rtc-signaling.mjs';
+
+const D = new URL('./', import.meta.url);
+const jl = async (n) => JSON.parse(await readFile(new URL(`engine/schema/${n}.jsonld`, D), 'utf8'));
+const PORT = 9095, ROOM = 'b17c0192abad1deacafe';
+const SIGNAL = `ws://localhost:${PORT}/.webrtc`;
+
+const codec = new Codec(await jl('core'), await jl('proof'), await jl('p2p'));
+const p2p = P2pEngine.fromSchemas(codec, await jl('p2p'), await jl('chain'), 'btc:testnet4');
+const blockHex = (await readFile(new URL('data/block-26000.hex', D), 'utf8')).trim();
+const expectHash = codec.blockHash(codec.decode('Block', blockHex).header);
+const log = (m) => console.log(m);
+
+const sig = startSignaling(PORT, { log });
+let done = false;
+const end = (c) => { if (done) return; done = true; try { sig.close(); } catch {} try { nodeDataChannel.cleanup(); } catch {} setImmediate(() => process.exit(c)); };
+const to = setTimeout(() => { console.log('\n❌ timeout'); end(1); }, 30000);
+
+log(`\nrelaying block #26000 peer→peer in room ${ROOM} (no server in the data path)…`);
+
+// Peer A = the source: answerer. When a peer connects, it serves the block.
+connectAsAnswerer({ signalUrl: SIGNAL, room: ROOM, log, onChannel: (dc) => {
+  dc.onMessage((m) => { if ((Buffer.isBuffer(m) ? m.toString() : String(m)) === 'getdata') serve(dc); });
+  dc.onOpen(() => { log('  A: peer connected → announcing it has block #26000 (inv)'); dc.sendMessage('inv:26000'); });
+} });
+function serve(dc) { log('  A: got getdata → sending the block over WebRTC'); dc.sendMessageBinary(Buffer.from(p2p.encodeMessage('block', blockHex))); }
+
+// Peer B = the receiver: offerer. Asks for the block, validates what arrives.
+const B = await connectAsOfferer({ signalUrl: SIGNAL, room: ROOM, log });
+let buf = Buffer.alloc(0);
+B.dc.onMessage((m) => {
+  if (typeof m === 'string' || (!Buffer.isBuffer(m) && !(m instanceof Uint8Array))) {
+    if (String(m).startsWith('inv:')) { log('  B: received inv → requesting the block (getdata)'); B.dc.sendMessage('getdata'); }
+    return;
+  }
+  buf = Buffer.concat([buf, Buffer.isBuffer(m) ? m : Buffer.from(m)]);
+  const { messages, consumed } = p2p.decodeStream(new Uint8Array(buf)); buf = buf.subarray(consumed);
+  for (const msg of messages) if (msg.command === 'block') {
+    const h = codec.blockHash(msg.payload.header);
+    clearTimeout(to);
+    if (h === expectHash) { log(`\n✅ B received + validated block #26000 from peer A over WebRTC — ${h.slice(0, 16)}… (${msg.payload.transactions.length} txs)`); log('   browser↔browser block propagation works.'); end(0); }
+    else { log('\n❌ hash mismatch'); end(1); }
+  }
+});