@relay-federation/bridge 0.3.14 → 0.3.15

package/cli.js

@@ -744,13 +744,10 @@ async function cmdStart () {
     }
   })
 
-  // Auto-detect incoming payments: request txs announced via INV
+  // Track txids announced via BSV P2P inv (lightweight, no full tx fetch)
   bsvNode.on('tx:inv', ({ txids }) => {
     for (const txid of txids) {
-      if (txRelay.seen.has(txid)) continue
-      bsvNode.getTx(txid, 10000).then(({ txid: id, rawHex }) => {
-        txRelay.broadcastTx(id, rawHex)
-      }).catch(() => {}) // ignore fetch failures
+      txRelay.trackTxid(txid)
     }
   })
 

package/dashboard/index.html

@@ -951,6 +951,7 @@
     <button onclick="setTab('inscriptions')">Inscriptions</button>
     <button onclick="setTab('tokens')">Tokens</button>
     <button onclick="setTab('apps')">Apps</button>
+    <button onclick="setTab('x402')">x402</button>
   </div>
   <div class="header-right">
     <div class="header-stats">
@@ -1100,9 +1101,11 @@ let activeTab = 'overview';
 let savedExplorerInput = '';
 let savedExplorerResult = '';
 let appsData = null;
+let x402Data = null;
 let latestPrice = null;
 let mempoolHistory = [];
 let peerCountHistory = [];
+let rssHistory = [];
 
 function openCardOverlay(type) {
   const b = bridgeData.get(selectedBridge);
@@ -1196,7 +1199,8 @@ function renderCardExpanded(type, b, op) {
       html += '<div class="panel-row"><span class="label">Mesh Bridges</span><span class="value">' + b.peers.connected + ' connected</span></div>';
       html += '<div style="font-size:11px;color:var(--text-dim);margin:16px 0 12px;text-transform:uppercase;letter-spacing:1px">Transactions</div>';
       html += '<div class="panel-row"><span class="label">Mempool</span><span class="value">' + b.txs.mempool + ' txs</span></div>';
-      html += '<div class="panel-row"><span class="label">Seen</span><span class="value">' + b.txs.seen + ' txs</span></div>';
+      html += '<div class="panel-row"><span class="label">Network Seen</span><span class="value">' + (b.txs.known || 0).toLocaleString() + ' txids</span></div>';
+      html += '<div class="panel-row"><span class="label">Relayed</span><span class="value">' + b.txs.seen + ' txs</span></div>';
       // Mempool sparkline (last 20 polls)
       if (mempoolHistory.length > 1) {
         html += '<div style="margin-top:12px"><div style="font-size:11px;color:var(--text-dim);margin-bottom:6px">Mempool History (last ' + mempoolHistory.length + ' polls)</div>';
@@ -1280,6 +1284,40 @@ function renderCardExpanded(type, b, op) {
       html += '<p style="margin-bottom:8px">More BSV bonded + longer held unspent = higher BND score. Minimum: 0.01 BSV.</p>';
       html += '</div></div>';
       break;
+    case 'system':
+      if (!b.system) return '';
+      var sysMem = b.system;
+      var sysMemPct = Math.round(sysMem.usedMemMB / sysMem.totalMemMB * 100);
+      var sysMemClr = sysMemPct > 85 ? 'var(--accent-red)' : sysMemPct > 70 ? 'var(--accent-yellow)' : 'var(--accent-green)';
+      html += '<h2>System</h2>';
+      // RAM hero
+      html += '<div style="text-align:center;padding:20px 0 16px">';
+      html += '<div style="font-size:32px;font-weight:700;color:' + sysMemClr + ';letter-spacing:-1px">' + sysMemPct + '%</div>';
+      html += '<div style="font-size:14px;color:var(--text-muted);margin-top:4px">RAM Usage</div>';
+      html += '</div>';
+      // RAM bar
+      html += '<div style="margin:0 0 20px"><div style="height:8px;background:var(--border);border-radius:4px;overflow:hidden"><div style="height:100%;width:' + sysMemPct + '%;background:' + sysMemClr + ';border-radius:4px;transition:width 0.5s"></div></div>';
+      html += '<div style="display:flex;justify-content:space-between;font-size:11px;margin-top:4px;color:var(--text-dim)"><span>Used: ' + sysMem.usedMemMB + ' MB</span><span>Free: ' + sysMem.freeMemMB + ' MB</span><span>Total: ' + sysMem.totalMemMB + ' MB</span></div></div>';
+      // Process
+      html += '<div style="font-size:11px;color:var(--text-dim);margin-bottom:12px;text-transform:uppercase;letter-spacing:1px">Process</div>';
+      html += '<div class="panel-row"><span class="label">RSS</span><span class="value">' + sysMem.processRssMB + ' MB</span></div>';
+      html += '<div class="panel-row"><span class="label">Node.js</span><span class="value">' + sysMem.nodeVersion + '</span></div>';
+      // CPU
+      html += '<div style="font-size:11px;color:var(--text-dim);margin:16px 0 12px;text-transform:uppercase;letter-spacing:1px">CPU</div>';
+      html += '<div class="panel-row"><span class="label">Cores</span><span class="value">' + sysMem.cpuCount + '</span></div>';
+      html += '<div class="panel-row"><span class="label">Load (1m)</span><span class="value">' + sysMem.loadAvg[0] + '</span></div>';
+      html += '<div class="panel-row"><span class="label">Load (5m)</span><span class="value">' + sysMem.loadAvg[1] + '</span></div>';
+      html += '<div class="panel-row"><span class="label">Load (15m)</span><span class="value">' + sysMem.loadAvg[2] + '</span></div>';
+      // OS
+      html += '<div style="font-size:11px;color:var(--text-dim);margin:16px 0 12px;text-transform:uppercase;letter-spacing:1px">Host</div>';
+      html += '<div class="panel-row"><span class="label">Platform</span><span class="value">' + sysMem.platform + ' / ' + sysMem.arch + '</span></div>';
+      html += '<div class="panel-row"><span class="label">OS Uptime</span><span class="value">' + fmtUptime(sysMem.osUptime) + '</span></div>';
+      // RSS sparkline
+      if (rssHistory && rssHistory.length > 1) {
+        html += '<div style="font-size:11px;color:var(--text-dim);margin:16px 0 12px;text-transform:uppercase;letter-spacing:1px">Process RSS (last ' + rssHistory.length + ' polls)</div>';
+        html += renderSparkline(rssHistory, 'rgba(210,153,34,0.7)');
+      }
+      break;
     default: return '';
   }
   return html;
@@ -1311,6 +1349,7 @@ function renderSparkline(data, color) {
   return svg + '</svg>';
 }
 function scoreColor(v) { return v >= 0.7 ? 'green' : v >= 0.4 ? 'yellow' : 'red'; }
+function fmtAge(ts) { var s = Math.floor((Date.now() - ts) / 1000); if (s < 60) return s + 's ago'; if (s < 3600) return Math.floor(s / 60) + 'm ago'; if (s < 86400) return Math.floor(s / 3600) + 'h ago'; return Math.floor(s / 86400) + 'd ago'; }
 function fmtSats(n) { return n === null || n === undefined ? '-' : n.toLocaleString(); }
 function fmtHeight(n) { return n > 0 ? n.toLocaleString() : '-'; }
 function isOperator(url) { return !!operatorTokens[url]; }
@@ -1390,7 +1429,11 @@ async function discoverBridges() {
 }
 
 // ── Poll ───────────────────────────────────────────
+let polling = false;
 async function pollAll() {
+  if (polling) return;
+  polling = true;
+  try {
   if (!discoveryDone) await discoverBridges();
   const results = await Promise.all(BRIDGES.map(fetchBridge));
   const mempools = await Promise.all(BRIDGES.map(fetchMempool));
@@ -1405,12 +1448,14 @@ async function pollAll() {
   const sel = bridgeData.get(selectedBridge);
   if (sel && sel.txs) { mempoolHistory.push(sel.txs.mempool); if (mempoolHistory.length > 20) mempoolHistory.shift(); }
   if (sel && sel.peers) { peerCountHistory.push(sel.peers.connected); if (peerCountHistory.length > 20) peerCountHistory.shift(); }
+  if (sel && sel.system) { rssHistory.push(sel.system.processRssMB); if (rssHistory.length > 20) rssHistory.shift(); }
   // Fetch price from self (same-origin, always works)
   fetch('/price', { signal: AbortSignal.timeout(5000) })
     .then(r => r.ok ? r.json() : null).then(d => { if (d) { latestPrice = d; const el = document.querySelector('.stats-hero .stat-card:last-child .stat-value'); if (el) el.textContent = '$' + d.usd.toFixed(2); } }).catch(() => {});
   renderHeader();
   renderBridgeRail();
   renderActiveTab(true);
+  } finally { polling = false; }
 }
 
 // ── Header stats ───────────────────────────────────
@@ -1464,17 +1509,18 @@ function setTab(tab) {
   if (activeTab === 'overview' && tab !== 'overview') destroyMeshMap3D();
   activeTab = tab;
   const buttons = document.querySelectorAll('#headerTabs button');
-  const tabs = ['overview', 'mempool', 'explorer', 'inscriptions', 'tokens', 'apps'];
+  const tabs = ['overview', 'mempool', 'explorer', 'inscriptions', 'tokens', 'apps', 'x402'];
   buttons.forEach((btn, i) => btn.classList.toggle('active', tabs[i] === tab));
   renderActiveTab();
   if (tab === 'apps') setTimeout(fetchAppsData, 50);
   if (tab === 'tokens') setTimeout(fetchTokens, 50);
+  if (tab === 'x402') setTimeout(fetchX402Data, 50);
 }
 
 function renderActiveTab(fromPoll) {
   const el = document.getElementById('tabContent');
   // Skip apps/explorer re-render during poll (preserves state)
-  if (fromPoll && (activeTab === 'apps' || activeTab === 'explorer' || activeTab === 'inscriptions' || activeTab === 'tokens')) return;
+  if (fromPoll && (activeTab === 'apps' || activeTab === 'explorer' || activeTab === 'inscriptions' || activeTab === 'tokens' || activeTab === 'x402')) return;
   // On poll, if overview tab has active 3D scene, just update data — don't rebuild DOM
   if (fromPoll && activeTab === 'overview' && mesh3d) {
     updateMeshMap3D();
@@ -1490,6 +1536,7 @@ function renderActiveTab(fromPoll) {
     case 'inscriptions': html = renderInscriptionsTab(); break;
     case 'tokens': html = renderTokensTab(); break;
     case 'apps': html = renderAppsTab(); break;
+    case 'x402': html = renderX402Tab(); break;
     default: html = renderOverviewTab();
   }
   // Only update DOM if content actually changed (prevents flash)
@@ -1637,6 +1684,18 @@ function renderOverviewTab() {
   }
   html += '</div>';
 
+  // System card
+  if (b.system) {
+    var memPct = Math.round(b.system.usedMemMB / b.system.totalMemMB * 100);
+    var memColor = memPct > 85 ? 'red' : memPct > 70 ? 'yellow' : 'green';
+    html += '<div class="detail-card glass" onclick="openCardOverlay(\'system\')"><h3>System <span style="font-size:9px;color:var(--text-dim);font-weight:400;text-transform:none;letter-spacing:0">— click to expand</span></h3>';
+    html += '<div class="panel-row"><span class="label">RAM</span><span class="value ' + memColor + '">' + b.system.usedMemMB + ' / ' + b.system.totalMemMB + ' MB (' + memPct + '%)</span></div>';
+    html += '<div class="panel-row"><span class="label">Process RSS</span><span class="value">' + b.system.processRssMB + ' MB</span></div>';
+    html += '<div class="panel-row"><span class="label">CPU Load</span><span class="value">' + b.system.loadAvg[0] + ' / ' + b.system.loadAvg[1] + ' / ' + b.system.loadAvg[2] + '</span></div>';
+    html += '<div class="panel-row"><span class="label">OS Uptime</span><span class="value">' + fmtUptime(b.system.osUptime) + '</span></div>';
+    html += '</div>';
+  }
+
   html += '</div>'; // cards-grid
 
   return html;
@@ -1649,6 +1708,14 @@ function renderMempoolTab() {
 
   let html = '<div class="tab-title">Mempool <span class="count">' + (b._mempool ? b._mempool.count : 0) + ' transactions</span></div>';
 
+  const known = b.txs ? b.txs.known || 0 : 0;
+  if (known > 0) {
+    html += '<div class="glass" style="padding:16px;margin-bottom:12px;display:flex;gap:24px;align-items:center">';
+    html += '<div><span class="label">Network Txids Seen</span><div style="font-size:1.5em;font-weight:700;color:var(--accent)">' + known.toLocaleString() + '</div></div>';
+    html += '<div style="color:var(--text-dim);font-size:0.85em">Transactions observed via P2P (10 min window)</div>';
+    html += '</div>';
+  }
+
   if (!b._mempool || b._mempool.txs.length === 0) {
     html += '<div class="glass" style="padding:40px;text-align:center"><div style="color:var(--text-dim)">No transactions in mempool</div></div>';
     return html;
@@ -2519,8 +2586,8 @@ function showAuthModal(bridgeUrl) {
   openModal('<h2>Operator Login</h2><div style="margin-bottom:12px;font-size:13px;color:var(--text-secondary)">' + bName + ' &mdash; ' + bIp + '</div><div class="form-group"><label>statusSecret (from bridge config.json)</label><input type="password" id="authInput" value="' + existing + '" placeholder="64-char hex token"></div><div class="modal-actions"><button class="btn" onclick="closeModal()">Cancel</button><button class="btn primary" onclick="saveAuth(\'' + bridgeUrl + '\')">Login</button></div>');
   setTimeout(() => document.getElementById('authInput').focus(), 100);
 }
-function saveAuth(bridgeUrl) { const t = document.getElementById('authInput').value.trim(); if (!t) delete operatorTokens[bridgeUrl]; else operatorTokens[bridgeUrl] = t; localStorage.setItem('relay_operator_tokens', JSON.stringify(operatorTokens)); closeModal(); pollAll(); }
-function logoutOperator(bridgeUrl) { delete operatorTokens[bridgeUrl]; localStorage.setItem('relay_operator_tokens', JSON.stringify(operatorTokens)); pollAll(); }
+async function saveAuth(bridgeUrl) { const t = document.getElementById('authInput').value.trim(); if (!t) delete operatorTokens[bridgeUrl]; else operatorTokens[bridgeUrl] = t; localStorage.setItem('relay_operator_tokens', JSON.stringify(operatorTokens)); closeModal(); destroyMeshMap3D(); const bridge = BRIDGES.find(b => b.url === bridgeUrl); if (bridge) { const data = await fetchBridge(bridge); bridgeData.set(data._name, data); } renderActiveTab(false); }
+async function logoutOperator(bridgeUrl) { delete operatorTokens[bridgeUrl]; localStorage.setItem('relay_operator_tokens', JSON.stringify(operatorTokens)); destroyMeshMap3D(); const bridge = BRIDGES.find(b => b.url === bridgeUrl); if (bridge) { const data = await fetchBridge(bridge); bridgeData.set(data._name, data); } renderActiveTab(false); }
 
 function showRegisterModal(bridgeUrl) {
   openModal('<h2>Register Bridge</h2><div class="warning">This will broadcast a stake bond + registration transaction to the BSV network. Ensure your bridge wallet is funded.</div><div class="modal-actions"><button class="btn" onclick="closeModal()">Cancel</button><button class="btn primary" id="regBtn" onclick="doRegister(\'' + bridgeUrl + '\')">Register</button></div><div id="jobLog" class="job-log" style="display:none"></div>');
@@ -2968,6 +3035,175 @@ async function fetchAppsData() {
   }
 }
 
+// ── x402 tab ──────────────────────────────────────
+function renderX402Tab() {
+  let html = '<div style="margin-bottom:10px"><span style="font-size:15px;font-weight:600;color:var(--text-primary)">x402 Payment Gate</span>';
+  html += '<span style="font-size:11px;color:var(--text-muted);margin-left:10px">Free reads, paid writes</span></div>';
+
+  if (!x402Data) {
+    html += '<div class="glass" style="padding:20px;color:var(--text-muted)">Loading...</div>';
+    return html;
+  }
+
+  // Status row
+  var statusClr = x402Data.enabled ? 'var(--accent-green)' : 'var(--text-dim)';
+  var statusTxt = x402Data.enabled ? 'ENABLED' : 'DISABLED';
+  html += '<div class="glass" style="padding:10px 16px;margin-bottom:8px;display:flex;align-items:center;gap:10px">';
+  html += '<div style="width:8px;height:8px;border-radius:50%;background:' + statusClr + '"></div>';
+  html += '<span style="font-size:13px;font-weight:600;color:' + statusClr + '">' + statusTxt + '</span>';
+  if (x402Data.payTo) {
+    html += '<span style="margin-left:auto;font-family:monospace;font-size:11px;color:var(--text-muted)">' + escapeHtml(x402Data.payTo) + '</span>';
+  }
+  html += '</div>';
+
+  // Revenue card
+  if (x402Data.revenue) {
+    var rev = x402Data.revenue;
+    html += '<div class="glass" style="padding:12px 16px;margin-bottom:8px">';
+    html += '<div style="font-size:11px;color:var(--text-dim);text-transform:uppercase;letter-spacing:1px;margin-bottom:8px">Revenue</div>';
+    html += '<div style="display:flex;align-items:baseline;gap:16px;margin-bottom:8px">';
+    html += '<div><span style="font-size:22px;font-weight:700;color:var(--accent-green)">' + Number(rev.totalSatsEarned).toLocaleString() + '</span><span style="font-size:11px;color:var(--text-muted);margin-left:6px">total sats</span></div>';
+    html += '<div style="font-size:12px;color:var(--text-dim)">' + Number(rev.todaySats).toLocaleString() + ' today</div>';
+    html += '<div style="font-size:12px;color:var(--text-dim)">' + Number(rev.weekSats).toLocaleString() + ' this week</div>';
+    html += '</div>';
+    html += '<div class="panel-row"><span class="label">Receipts</span><span class="value">' + rev.totalReceipts + '</span></div>';
+    html += '<div class="panel-row"><span class="label">Pending</span><span class="value">' + rev.pendingClaims + '</span></div>';
+    html += '</div>';
+  }
+
+  // Pricing table
+  if (x402Data.endpoints && x402Data.endpoints.length > 0) {
+    html += '<div class="glass" style="padding:16px;margin-bottom:12px">';
+    html += '<div style="font-size:11px;color:var(--text-dim);text-transform:uppercase;letter-spacing:1px;margin-bottom:12px">Pricing</div>';
+    for (var i = 0; i < x402Data.endpoints.length; i++) {
+      var ep = x402Data.endpoints[i];
+      html += '<div class="panel-row"><span class="label" style="font-family:monospace;font-size:11px">' + escapeHtml(ep.method) + ' ' + escapeHtml(ep.path) + '</span><span class="value" style="color:var(--accent-green)">' + ep.satoshis.toLocaleString() + ' sats</span></div>';
+    }
+    html += '</div>';
+  }
+
+  // Recent receipts (operator only)
+  if (x402Data.recentReceipts && x402Data.recentReceipts.length > 0) {
+    html += '<div class="glass" style="padding:16px;margin-bottom:12px">';
+    html += '<div style="font-size:11px;color:var(--text-dim);text-transform:uppercase;letter-spacing:1px;margin-bottom:12px">Recent Receipts</div>';
+    for (var j = 0; j < x402Data.recentReceipts.length; j++) {
+      var rx = x402Data.recentReceipts[j];
+      var age = rx.createdAt ? fmtAge(rx.createdAt) : '?';
+      html += '<div style="display:flex;justify-content:space-between;align-items:center;padding:6px 0;border-bottom:1px solid var(--border);font-size:11px">';
+      html += '<span style="font-family:monospace;color:var(--text-muted)">' + escapeHtml(rx.txid.slice(0, 12)) + '...</span>';
+      html += '<span style="color:var(--text-dim)">' + escapeHtml(rx.endpoint) + '</span>';
+      html += '<span style="color:var(--accent-green)">' + Number(rx.satoshisPaid).toLocaleString() + ' sats</span>';
+      html += '<span style="color:var(--text-dim)">' + age + '</span>';
+      html += '</div>';
+    }
+    html += '</div>';
+  }
+
+  // Settings panel (operator only)
+  var b = bridgeData.get(selectedBridge);
+  if (b && isOperator(b._url)) {
+    html += '<div class="glass" style="padding:12px 16px;margin-bottom:8px">';
+    html += '<div style="font-size:11px;color:var(--text-dim);text-transform:uppercase;letter-spacing:1px;margin-bottom:8px">Settings</div>';
+
+    // Enable/disable checkbox
+    html += '<div style="display:flex;align-items:center;gap:8px;margin-bottom:8px">';
+    html += '<input type="checkbox" id="x402Enabled"' + (x402Data.enabled ? ' checked' : '') + ' style="cursor:pointer">';
+    html += '<label for="x402Enabled" class="label" style="cursor:pointer">Enable Payment Gate</label>';
+    html += '</div>';
+
+    // PayTo address
+    html += '<div style="margin-bottom:8px">';
+    html += '<div class="label" style="margin-bottom:4px">Pay To Address</div>';
+    html += '<input type="text" id="x402PayTo" value="' + escapeHtml(x402Data.payTo || '') + '" placeholder="1YourBSVAddress..." style="width:100%;padding:6px 8px;background:var(--bg-secondary);border:1px solid var(--border);border-radius:4px;color:var(--text-primary);font-family:monospace;font-size:11px;box-sizing:border-box">';
+    html += '</div>';
+
+    // Endpoint pricing
+    html += '<div class="label" style="margin-bottom:8px">Endpoint Pricing (satoshis)</div>';
+    var epList = x402Data.endpoints || [];
+    html += '<div id="x402Endpoints">';
+    for (var k = 0; k < epList.length; k++) {
+      html += '<div style="display:flex;gap:8px;margin-bottom:6px;align-items:center">';
+      html += '<input type="text" value="' + escapeHtml(epList[k].method + ':' + epList[k].path) + '" class="x402-ep-key" style="flex:2;padding:4px 6px;background:var(--bg-secondary);border:1px solid var(--border);border-radius:4px;color:var(--text-primary);font-family:monospace;font-size:11px">';
+      html += '<input type="number" value="' + epList[k].satoshis + '" class="x402-ep-val" style="flex:1;padding:4px 6px;background:var(--bg-secondary);border:1px solid var(--border);border-radius:4px;color:var(--text-primary);font-family:monospace;font-size:11px">';
+      html += '<button onclick="removeX402Endpoint(this)" style="background:none;border:none;color:var(--accent-red);cursor:pointer;font-size:14px">×</button>';
+      html += '</div>';
+    }
+    html += '</div>';
+    html += '<button class="btn" style="font-size:11px;padding:4px 12px;margin-bottom:12px" onclick="addX402Endpoint()">+ Add Endpoint</button>';
+
+    // Save button
+    html += '<div style="margin-top:8px;text-align:right">';
+    html += '<button class="btn primary" style="font-size:12px;padding:6px 20px" onclick="saveX402Settings()">Save Settings</button>';
+    html += '</div>';
+    html += '</div>';
+  }
+
+  // Discovery endpoint hint
+  html += '<div class="glass" style="padding:12px;font-size:11px;color:var(--text-dim)">';
+  html += 'Discovery: <span style="font-family:monospace;color:var(--text-muted)">GET /.well-known/x402</span>';
+  html += '</div>';
+
+  return html;
+}
+
+async function fetchX402Data() {
+  var b = bridgeData.get(selectedBridge);
+  if (!b) return;
+  try {
+    var r = await fetch(b._url + '/x402' + getAuthParam(b._url), { signal: AbortSignal.timeout(10000) });
+    if (!r.ok) { x402Data = { enabled: false, endpoints: [] }; if (activeTab === 'x402') { var el = document.getElementById('tabContent'); if (el) el.innerHTML = renderX402Tab(); } return; }
+    x402Data = await r.json();
+    if (activeTab === 'x402') {
+      var el = document.getElementById('tabContent');
+      if (el) el.innerHTML = renderX402Tab();
+    }
+  } catch (e) {
+    x402Data = { enabled: false, endpoints: [] };
+    if (activeTab === 'x402') {
+      var el = document.getElementById('tabContent');
+      if (el) el.innerHTML = '<div class="glass" style="padding:20px;color:var(--accent-red)">' + escapeHtml(e.message) + '</div>';
+    }
+  }
+}
+
+
+function addX402Endpoint() {
+  var container = document.getElementById('x402Endpoints');
+  if (!container) return;
+  var div = document.createElement('div');
+  div.style.cssText = 'display:flex;gap:8px;margin-bottom:6px;align-items:center';
+  div.innerHTML = '<input type="text" value="POST:/api/broadcast" class="x402-ep-key" style="flex:2;padding:4px 6px;background:var(--bg-secondary);border:1px solid var(--border);border-radius:4px;color:var(--text-primary);font-family:monospace;font-size:11px">' +
+    '<input type="number" value="1000" class="x402-ep-val" style="flex:1;padding:4px 6px;background:var(--bg-secondary);border:1px solid var(--border);border-radius:4px;color:var(--text-primary);font-family:monospace;font-size:11px">' +
+    '<button onclick="removeX402Endpoint(this)" style="background:none;border:none;color:var(--accent-red);cursor:pointer;font-size:14px">\u00d7</button>';
+  container.appendChild(div);
+}
+
+function removeX402Endpoint(btn) { btn.parentElement.remove(); }
+
+async function saveX402Settings() {
+  var b = bridgeData.get(selectedBridge);
+  if (!b) return;
+  var enabled = document.getElementById('x402Enabled')?.checked || false;
+  var payTo = document.getElementById('x402PayTo').value.trim();
+  var keys = document.querySelectorAll('.x402-ep-key');
+  var vals = document.querySelectorAll('.x402-ep-val');
+  var endpoints = {};
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i].value.trim();
+    var v = parseInt(vals[i].value, 10);
+    if (k && !isNaN(v)) endpoints[k] = v;
+  }
+  try {
+    var r = await fetch(b._url + '/x402' + getAuthParam(b._url), {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ enabled: enabled, payTo: payTo, endpoints: endpoints })
+    });
+    if (r.ok) { fetchX402Data(); }
+    else { var err = await r.json().catch(function() { return {}; }); alert(err.error || 'Save failed'); }
+  } catch (e) { alert(e.message); }
+}
+
 // ── Log viewer ─────────────────────────────────────
 function openLogViewer(bridgeUrl) {
   document.getElementById('logViewerBody').innerHTML = '';

package/lib/bsv-node-client.js

@@ -145,6 +145,21 @@ export class BSVNodeClient extends EventEmitter {
     return Promise.reject(new Error('not connected to BSV node'))
   }
 
+  /**
+   * Fetch a transaction from a specific peer (the one that announced it via inv).
+   * Falls back to any connected peer if the target peer is unavailable.
+   * @param {import('./bsv-peer.js').BSVPeer} peer
+   * @param {string} txid
+   * @param {number} [timeoutMs=5000]
+   * @returns {Promise<{ txid, rawHex }>}
+   */
+  getTxFromPeer (peer, txid, timeoutMs = 5000) {
+    if (peer && peer._handshakeComplete) {
+      return peer.getTx(txid, timeoutMs)
+    }
+    return this.getTx(txid, timeoutMs)
+  }
+
   /**
    * Trigger header sync on connected peers.
    */

package/lib/bsv-peer.js

@@ -593,7 +593,7 @@ export class BSVPeer extends EventEmitter {
     }
 
     if (txids.length > 0) {
-      this.emit('tx:inv', { txids })
+      this.emit('tx:inv', { txids, peer: this })
     }
   }
 
@@ -723,7 +723,7 @@ export class BSVPeer extends EventEmitter {
     offset += writeVarInt(payload, offset, userAgentBuf.length)
     userAgentBuf.copy(payload, offset); offset += userAgentBuf.length
     payload.writeInt32LE(this._bestHeight, offset); offset += 4
-    payload[offset] = 0; offset += 1
+    payload[offset] = 1; offset += 1
 
     this._sendMessage('version', payload.subarray(0, offset))
   }

package/lib/persistent-store.js

@@ -43,6 +43,7 @@ export class PersistentStore extends EventEmitter {
     this._content = null
     this._tokens = null
     this._sessions = null
+    this._paymentReceipts = null
     this._contentDir = join(dataDir, 'content')
   }
 
@@ -63,6 +64,7 @@ export class PersistentStore extends EventEmitter {
     this._content = this.db.sublevel('content', { valueEncoding: 'json' })
     this._tokens = this.db.sublevel('tokens', { valueEncoding: 'json' })
     this._sessions = this.db.sublevel('sessions', { valueEncoding: 'json' })
+    this._paymentReceipts = this.db.sublevel('payment_receipts', { valueEncoding: 'json' })
     await mkdir(this._contentDir, { recursive: true })
     this.emit('open')
   }
@@ -801,6 +803,76 @@ export class PersistentStore extends EventEmitter {
     for await (const _ of this._inscriptions.keys()) count++
     return count
   }
+
+  // ── x402 Payment Receipts ──────────────────────────────
+
+  /**
+   * Atomic claim — put-if-absent. Returns { ok: true } if claimed,
+   * { ok: false } if txid already exists (replay blocked).
+   */
+  async claimTxid (txid, { routeKey, price, createdAt }) {
+    const key = `u!${txid}`
+    try {
+      await this._paymentReceipts.put(key,
+        { status: 'claimed', routeKey, price, createdAt },
+        { ifNotExists: true })
+      return { ok: true }
+    } catch (err) {
+      if (err.code !== 'LEVEL_KEY_EXISTS' && err?.cause?.code !== 'LEVEL_KEY_EXISTS')
+        console.error(`[x402] unexpected claimTxid error for ${txid}:`, err.message)
+      return { ok: false }
+    }
+  }
+
+  /**
+   * Release a claim (verification failed). Only deletes if status is 'claimed'.
+   * Never deletes receipts — finalized payments are permanent.
+   */
+  async releaseClaim (txid) {
+    const key = `u!${txid}`
+    try {
+      const val = await this._paymentReceipts.get(key)
+      if (val && val.status === 'claimed') await this._paymentReceipts.del(key)
+    } catch {}
+  }
+
+  /**
+   * Promote claim to permanent receipt. Overwrites in-place — key is
+   * NEVER deleted after this, blocking replay permanently.
+   */
+  async finalizePayment (txid, receipt) {
+    await this._paymentReceipts.put(`u!${txid}`, { ...receipt, status: 'receipt' })
+  }
+
+  /**
+   * Startup sweep — delete stale claims older than maxAgeMs (default 5 min).
+   * Only touches status === 'claimed' keys. Receipts are untouched.
+   */
+  async cleanupStaleClaims (maxAgeMs = 300000) {
+    const now = Date.now()
+    for await (const [key, val] of this._paymentReceipts.iterator({ gte: 'u!', lt: 'u~' })) {
+      if (val.status !== 'claimed') continue
+      if (!val.createdAt || (now - val.createdAt) > maxAgeMs)
+        await this._paymentReceipts.del(key)
+    }
+  }
+
+  /**
+   * Prune old receipts — chunked batch deletes for receipts older than N months.
+   */
+  async pruneOldReceipts (monthsToKeep = 6) {
+    const cutoffMs = Date.now() - (monthsToKeep * 30 * 24 * 60 * 60 * 1000)
+    const CHUNK = 500
+    let ops = []
+    for await (const [key, val] of this._paymentReceipts.iterator({ gte: 'u!', lt: 'u~' })) {
+      if (val.status !== 'receipt') continue
+      if (val.createdAt && val.createdAt < cutoffMs) {
+        ops.push({ type: 'del', key })
+        if (ops.length >= CHUNK) { await this._paymentReceipts.batch(ops); ops = [] }
+      }
+    }
+    if (ops.length > 0) await this._paymentReceipts.batch(ops)
+  }
 }
 
 /** Double SHA-256 (Bitcoin standard) */

package/lib/status-server.js

@@ -1,12 +1,15 @@
+import os from 'node:os'
 import { createServer } from 'node:http'
 import { createHash } from 'node:crypto'
-import { readFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import https from 'node:https'
 import { parseTx } from './output-parser.js'
 import { scanAddress } from './address-scanner.js'
 import { handlePostData, handleGetTopics, handleGetData } from './data-endpoints.js'
+import { createPaymentGate } from './x402-middleware.js'
+import { handleWellKnownX402 } from './x402-endpoints.js'
 
 /**
  * StatusServer — public-facing HTTP server exposing bridge status and APIs.
@@ -82,6 +85,44 @@ export class StatusServer {
         try { this._appBridgeDomains.add(new URL(app.url).hostname) } catch {}
       }
     }
+
+    // x402 payment gate
+    this._paymentGate = null
+    if (this._config.x402?.enabled && this._config.x402?.payTo && this._store) {
+      try {
+        const fetchTx = async (txid, opts) => {
+          // Check mempool first
+          if (this._txRelay?.mempool.has(txid)) {
+            const raw = this._txRelay.mempool.get(txid)
+            const p = parseTx(raw)
+            return { txid: p.txid, vout: p.outputs.map(o => ({ satoshis: o.satoshis, scriptPubKey: { hex: o.scriptHex } })) }
+          }
+          // Try BSV P2P
+          if (this._bsvNodeClient) {
+            try {
+              const { rawHex } = await this._bsvNodeClient.getTx(txid, 5000)
+              const p = parseTx(rawHex)
+              return { txid: p.txid, vout: p.outputs.map(o => ({ satoshis: o.satoshis, scriptPubKey: { hex: o.scriptHex } })) }
+            } catch {}
+          }
+          // WoC fallback
+          const resp = await fetch(
+            `https://api.whatsonchain.com/v1/bsv/main/tx/${txid}`,
+            { signal: opts?.signal || AbortSignal.timeout(5000) }
+          )
+          if (!resp.ok) {
+            const err = new Error(`WoC ${resp.status}`)
+            err.httpStatus = resp.status
+            throw err
+          }
+          return await resp.json()
+        }
+        this._paymentGate = createPaymentGate(this._config, this._store, fetchTx)
+        this._store.cleanupStaleClaims().catch(() => {})
+      } catch (err) {
+        console.error('[x402] Failed to create payment gate:', err.message)
+      }
+    }
   }
 
   /**
@@ -138,12 +179,25 @@ export class StatusServer {
       },
       txs: {
         mempool: this._txRelay ? this._txRelay.mempool.size : 0,
+        known: this._txRelay ? this._txRelay.knownTxids.size : 0,
         seen: this._txRelay ? this._txRelay.seen.size : 0
       },
       bsvNode: {
         connected: this._bsvNodeClient ? this._bsvNodeClient.connectedCount > 0 : false,
         peers: this._bsvNodeClient ? this._bsvNodeClient.connectedCount : 0,
         height: this._bsvNodeClient ? this._bsvNodeClient.bestHeight : null
+      },
+      system: {
+        totalMemMB: Math.round(os.totalmem() / 1048576),
+        freeMemMB: Math.round(os.freemem() / 1048576),
+        usedMemMB: Math.round((os.totalmem() - os.freemem()) / 1048576),
+        processRssMB: Math.round(process.memoryUsage.rss() / 1048576),
+        cpuCount: os.cpus().length,
+        loadAvg: os.loadavg().map(v => Math.round(v * 100) / 100),
+        platform: os.platform(),
+        arch: os.arch(),
+        nodeVersion: process.version,
+        osUptime: Math.floor(os.uptime())
       }
     }
 
@@ -335,7 +389,7 @@ export class StatusServer {
       this._server = createServer((req, res) => {
         // CORS headers for federation dashboard
         res.setHeader('Access-Control-Allow-Origin', '*')
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, OPTIONS')
         res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
 
         if (req.method === 'OPTIONS') {
@@ -390,6 +444,23 @@ export class StatusServer {
       }
     }
 
+    // GET /.well-known/x402 — pricing discovery (always free)
+    if (req.method === 'GET' && path === '/.well-known/x402') {
+      handleWellKnownX402(this._config, PKG_VERSION, res)
+      return
+    }
+
+    // x402 payment gate — authenticated (operator) requests bypass
+    if (this._paymentGate && !authenticated) {
+      const result = await this._paymentGate(req.method, path, req)
+      if (!result.ok) {
+        res.writeHead(result.status, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify(result.body))
+        return
+      }
+      if (result.receipt) req._x402Receipt = result.receipt
+    }
+
     // GET /status — public or operator status
     if (req.method === 'GET' && path === '/status') {
       const status = await this.getStatus({ authenticated })
@@ -430,6 +501,24 @@ export class StatusServer {
       return
     }
 
+    // GET /mempool/known/:txid — fast check if txid was seen on the BSV network
+    const knownMatch = path.match(/^\/mempool\/known\/([0-9a-f]{64})$/)
+    if (req.method === 'GET' && knownMatch) {
+      const txid = knownMatch[1]
+      if (this._txRelay && this._txRelay.mempool.has(txid)) {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ known: true, source: 'mempool' }))
+      } else if (this._txRelay && this._txRelay.knownTxids.has(txid)) {
+        const firstSeen = this._txRelay.knownTxids.get(txid)
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ known: true, source: 'inv', firstSeen }))
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ known: false }))
+      }
+      return
+    }
+
     // GET /discover — public list of all known bridges in the mesh
     if (req.method === 'GET' && path === '/discover') {
       const bridges = []
@@ -1111,6 +1200,147 @@ export class StatusServer {
       return
     }
 
+    // GET /x402 — payment gate stats (operator-only details when authenticated)
+    if (req.method === 'GET' && path === '/x402') {
+      const x402Config = this._config.x402 || {}
+      const enabled = !!(x402Config.enabled && x402Config.payTo)
+      const result = {
+        enabled,
+        payTo: x402Config.payTo || '',
+        endpoints: []
+      }
+
+      // Build pricing table
+      if (x402Config.endpoints) {
+        for (const [key, satoshis] of Object.entries(x402Config.endpoints)) {
+          const colonIdx = key.indexOf(':')
+          if (colonIdx === -1) continue
+          result.endpoints.push({
+            method: key.slice(0, colonIdx),
+            path: key.slice(colonIdx + 1),
+            satoshis
+          })
+        }
+      }
+
+      // Read receipts from LevelDB if store is available
+      if (this._store && this._store._paymentReceipts) {
+        let totalReceipts = 0
+        let totalSatsEarned = 0n
+        let pendingClaims = 0
+        const recentReceipts = []
+        const now = Date.now()
+        const oneDayAgo = now - 86400000
+        const oneWeekAgo = now - 604800000
+        let todaySats = 0n
+        let weekSats = 0n
+
+        try {
+          for await (const [key, val] of this._store._paymentReceipts.iterator({ gte: 'u!', lt: 'u~' })) {
+            if (val.status === 'receipt') {
+              totalReceipts++
+              const paid = BigInt(val.satoshisPaid || val.satoshisRequired || '0')
+              totalSatsEarned += paid
+              if (val.createdAt && val.createdAt > oneDayAgo) todaySats += paid
+              if (val.createdAt && val.createdAt > oneWeekAgo) weekSats += paid
+              if (recentReceipts.length < 20) {
+                recentReceipts.push({
+                  txid: val.txid || key.slice(2),
+                  satoshisPaid: (val.satoshisPaid || val.satoshisRequired || '0'),
+                  endpoint: val.endpointKey || val.endpoint || '',
+                  createdAt: val.createdAt || null
+                })
+              }
+            } else if (val.status === 'claimed') {
+              pendingClaims++
+            }
+          }
+        } catch {}
+
+        result.revenue = {
+          totalReceipts,
+          totalSatsEarned: totalSatsEarned.toString(),
+          todaySats: todaySats.toString(),
+          weekSats: weekSats.toString(),
+          pendingClaims
+        }
+        if (authenticated) {
+          result.recentReceipts = recentReceipts.reverse()
+        }
+      }
+
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify(result))
+      return
+    }
+
+    // PATCH /x402 — update x402 settings (operator-only)
+    if (req.method === 'PATCH' && path === '/x402') {
+      if (!authenticated) {
+        res.writeHead(401, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'unauthorized' }))
+        return
+      }
+
+      try {
+        const chunks = []
+        for await (const chunk of req) chunks.push(chunk)
+        const body = JSON.parse(Buffer.concat(chunks).toString())
+
+        // Update in-memory config
+        if (!this._config.x402) this._config.x402 = {}
+        if (body.enabled !== undefined) this._config.x402.enabled = !!body.enabled
+        if (body.payTo !== undefined) this._config.x402.payTo = String(body.payTo)
+        if (body.endpoints !== undefined && typeof body.endpoints === 'object') {
+          // Validate all prices are non-negative safe integers
+          for (const [key, price] of Object.entries(body.endpoints)) {
+            if (!Number.isSafeInteger(price) || price < 0) {
+              res.writeHead(400, { 'Content-Type': 'application/json' })
+              res.end(JSON.stringify({ error: `Invalid price for ${key}: must be a non-negative integer` }))
+              return
+            }
+          }
+          this._config.x402.endpoints = body.endpoints
+        }
+
+        // Write config to disk
+        const configDir = this._config.dataDir ? dirname(this._config.dataDir) : join(os.homedir(), '.relay-bridge')
+        const configPath = join(configDir, 'config.json')
+        writeFileSync(configPath, JSON.stringify(this._config, null, 2))
+
+        // Recreate payment gate with new settings
+        if (this._config.x402.enabled && this._config.x402.payTo && this._store) {
+          try {
+            const fetchTx = async (txid, opts) => {
+              const resp = await fetch(
+                `https://api.whatsonchain.com/v1/bsv/main/tx/${txid}`,
+                { signal: opts?.signal || AbortSignal.timeout(5000) }
+              )
+              if (!resp.ok) {
+                const err = new Error(`WoC ${resp.status}`)
+                err.httpStatus = resp.status
+                throw err
+              }
+              return await resp.json()
+            }
+            this._paymentGate = createPaymentGate(this._config, this._store, fetchTx)
+          } catch (err) {
+            console.error('[x402] Failed to recreate payment gate:', err.message)
+            this._paymentGate = null
+          }
+        } else {
+          this._paymentGate = null
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: true, x402: this._config.x402 }))
+      } catch (err) {
+        res.writeHead(400, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: err.message }))
+      }
+      return
+    }
+
     // GET /health — MCP/CLI compatibility
     if (req.method === 'GET' && path === '/health') {
       const status = await this.getStatus()

package/lib/tx-relay.js

@@ -32,6 +32,11 @@ export class TxRelay extends EventEmitter {
     this.seen = new Set()
     this._maxMempool = opts.maxMempool || 1000
 
+    /** @type {Map<string, number>} txid → timestamp first seen via BSV P2P inv */
+    this.knownTxids = new Map()
+    this._knownTxidMax = opts.maxKnownTxids || 50000
+    this._knownTxidTtlMs = opts.knownTxidTtlMs || 600000 // 10 min
+
     this.peerManager.on('peer:message', ({ pubkeyHex, message }) => {
       this._handleMessage(pubkeyHex, message)
     })
@@ -60,6 +65,30 @@ export class TxRelay extends EventEmitter {
     return this.mempool.get(txid) || null
   }
 
+  /**
+   * Record a txid as "seen on the BSV network" without storing the full tx.
+   * @param {string} txid
+   */
+  trackTxid (txid) {
+    if (this.knownTxids.has(txid)) return
+    this.knownTxids.set(txid, Date.now())
+    if (this.knownTxids.size > this._knownTxidMax) {
+      const now = Date.now()
+      for (const [id, ts] of this.knownTxids) {
+        if (now - ts > this._knownTxidTtlMs) this.knownTxids.delete(id)
+      }
+    }
+  }
+
+  /**
+   * Check if we've seen a txid on the network (inv or mempool).
+   * @param {string} txid
+   * @returns {boolean}
+   */
+  hasSeen (txid) {
+    return this.seen.has(txid) || this.knownTxids.has(txid)
+  }
+
   /** @private */
   _storeTx (txid, rawHex) {
     if (this.mempool.size >= this._maxMempool) {

package/lib/x402-endpoints.js

@@ -0,0 +1,46 @@
+/**
+ * x402-endpoints.js — Discovery endpoint for x402 payment middleware.
+ *
+ * GET /.well-known/x402 — returns pricing info, free endpoints, payTo address.
+ */
+
+/**
+ * Handle GET /.well-known/x402 — pricing discovery.
+ *
+ * @param {object} config — bridge config with x402 section
+ * @param {string} version — bridge version string
+ * @param {import('node:http').ServerResponse} res
+ */
+export function handleWellKnownX402 (config, version, res) {
+  const pricingMap = config.x402?.endpoints || {}
+  const endpoints = []
+  for (const [key, satoshis] of Object.entries(pricingMap)) {
+    const colonIdx = key.indexOf(':')
+    if (colonIdx === -1) continue
+    const method = key.slice(0, colonIdx)
+    const path = key.slice(colonIdx + 1)
+    endpoints.push({ method, path, satoshis })
+  }
+
+  res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' })
+  res.end(JSON.stringify({
+    x402Version: '1',
+    bridge: 'relay-federation',
+    version,
+    payTo: config.x402?.payTo || '',
+    enabled: !!(config.x402?.enabled && config.x402?.payTo),
+    endpoints,
+    freeEndpoints: [
+      '/health',
+      '/.well-known/x402',
+      '/status',
+      '/api/address/*/unspent',
+      '/api/address/*/history',
+      '/api/address/*/balance',
+      '/api/tx/*/hex',
+      '/api/tx/*',
+      '/api/sessions/*',
+      '/api/sessions/index'
+    ]
+  }))
+}

package/lib/x402-middleware.js

@@ -0,0 +1,348 @@
+/**
+ * x402-middleware.js — HTTP 402 payment gate for relay federation bridges.
+ *
+ * Free reads, paid writes. Operator auth bypasses payment.
+ * Design reviewed by Codex over 8 rounds (27+ security mitigations).
+ *
+ * Usage:
+ *   const gate = createPaymentGate(config, store, fetchTx)
+ *   const result = await gate(method, path, req)
+ *   if (!result.ok) { res.writeHead(result.status, ...); res.end(...); return }
+ */
+
+import { addressToHash160 } from './output-parser.js'
+
+const MAX_CONCURRENT = 50
+const FETCH_TIMEOUT_MS = 5000
+const TXID_RE = /^[0-9a-f]{64}$/i
+const NEG_CACHE_MAX = 10000
+
+// ── Helpers ──────────────────────────────────────────────
+
+/**
+ * Convert BSV decimal string to satoshis as BigInt. No floats.
+ * @param {string|number} value — e.g. '0.00001000'
+ * @returns {bigint}
+ */
+function bsvToSats (value) {
+  const s = String(value)
+  if (!/^\d+(\.\d{1,8})?$/.test(s)) throw new Error('bad_value')
+  const [whole, frac = ''] = s.split('.')
+  const fracPadded = (frac + '00000000').slice(0, 8)
+  return BigInt(whole) * 100000000n + BigInt(fracPadded)
+}
+
+/**
+ * Extract hash160 from a P2PKH locking script hex.
+ * Returns null if not P2PKH.
+ * @param {string} hex — locking script hex
+ * @returns {string|null} 40-char hash160 hex or null
+ */
+function extractP2PKH (hex) {
+  if (typeof hex !== 'string') return null
+  if (hex.length === 50 && hex.startsWith('76a914') && hex.endsWith('88ac')) {
+    return hex.slice(6, 46)
+  }
+  return null
+}
+
+/**
+ * Get satoshis from a vout entry. Prefers integer fields over BSV decimals.
+ * @param {object} v — vout entry from tx JSON
+ * @returns {bigint}
+ */
+function getVoutSats (v) {
+  // Prefer integer satoshi fields (no float conversion needed)
+  if (v.valueSat !== undefined && v.valueSat !== null) return BigInt(v.valueSat)
+  if (v.satoshis !== undefined && v.satoshis !== null) return BigInt(v.satoshis)
+  // Fallback to BSV decimal
+  if (v.value !== undefined && v.value !== null) return bsvToSats(v.value)
+  return 0n
+}
+
+/**
+ * Find P2PKH outputs paying the expected address. Sums all matching outputs.
+ * @param {object} txJson — { vout: [{ value, scriptPubKey: { hex } }] }
+ * @param {string} expectedHash160 — 40-char hex
+ * @param {bigint} minSats — minimum required payment
+ * @returns {{ ok: true, totalPaid: bigint, matched: Array } | null}
+ */
+function findPaymentOutput (txJson, expectedHash160, minSats) {
+  let totalPaid = 0n
+  const matched = []
+  for (let i = 0; i < txJson.vout.length; i++) {
+    const v = txJson.vout[i]
+    const hash160 = extractP2PKH(v.scriptPubKey?.hex || '')
+    if (!hash160) continue
+    if (hash160 !== expectedHash160) continue
+    const sats = getVoutSats(v)
+    totalPaid += sats
+    matched.push({ vout: i, sats: sats.toString() })
+  }
+  if (totalPaid >= minSats) return { ok: true, totalPaid, matched }
+  return null
+}
+
+/**
+ * Normalize a URL path: collapse double slashes, strip trailing slash,
+ * decode segments, reject smuggled slashes.
+ * Returns '/' for root path (never returns empty string).
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizePath (raw) {
+  const collapsed = raw.replace(/\/+/g, '/').replace(/\/$/, '')
+  if (!collapsed) return '/'
+  const segments = collapsed.split('/')
+  const decoded = segments.map(seg => {
+    try {
+      const d = decodeURIComponent(seg)
+      if (d.includes('/')) throw new Error('smuggled_slash')
+      return d
+    } catch { return seg }
+  })
+  return decoded.join('/') || '/'
+}
+
+/**
+ * Build a route table from config endpoint keys and match against a path.
+ * Supports parameterized patterns like /inscription/:txid/:vout/content.
+ * @param {string} method — uppercased HTTP method
+ * @param {string} path — normalized path
+ * @param {Array} routes — pre-built route table
+ * @returns {string|null} — matched route key or null
+ */
+function matchRoute (method, path, routes) {
+  for (const route of routes) {
+    if (route.method !== method) continue
+    const routeParts = route.parts
+    const pathParts = path.split('/')
+    if (routeParts.length !== pathParts.length) continue
+    const match = routeParts.every((part, i) =>
+      part.startsWith(':') || part === pathParts[i]
+    )
+    if (match) return route.key
+  }
+  return null
+}
+
+/**
+ * Wrap fetchTx with an AbortController timeout.
+ * @param {function} fetchTx — async function(txid) → txJson
+ * @param {string} txid
+ * @param {number} timeoutMs
+ * @returns {Promise<object>}
+ */
+async function fetchTxWithTimeout (fetchTx, txid, timeoutMs) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetchTx(txid, { signal: controller.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// ── Payment Gate Factory ─────────────────────────────────
+
+/**
+ * Create the x402 payment gate.
+ *
+ * @param {object} config — bridge config with x402 section
+ * @param {object} store — PersistentStore instance (has claimTxid, releaseClaim, etc.)
+ * @param {function} fetchTx — async function(txid, opts?) → { txid, vout: [...] }
+ *   Must throw with { httpStatus } property to distinguish 404 vs upstream failure.
+ * @returns {function} async checkPayment(method, rawPath, req) → result
+ */
+export function createPaymentGate (config, store, fetchTx) {
+  const pricingMap = config.x402?.endpoints || {}
+  const payTo = config.x402?.payTo || ''
+  const enabled = !!(config.x402?.enabled && payTo)
+
+  const _pending = new Map() // txid → { promise, routeKey, price }
+  const _negCache = new Map() // txid → { expiry, reason, status }
+
+  // Build route table from config keys (once at startup)
+  const routes = []
+  let expectedHash160 = null
+
+  if (enabled) {
+    // Validate payTo — P2PKH only, fail fast
+    expectedHash160 = addressToHash160(payTo)
+
+    for (const [key, price] of Object.entries(pricingMap)) {
+      if (!Number.isSafeInteger(price) || price < 0) {
+        throw new Error(`[x402] Invalid price for ${key}: must be a non-negative integer`)
+      }
+      const colonIdx = key.indexOf(':')
+      if (colonIdx === -1) {
+        throw new Error(`[x402] Invalid endpoint key ${key}: must be METHOD:/path`)
+      }
+      const method = key.slice(0, colonIdx).toUpperCase()
+      const pattern = key.slice(colonIdx + 1)
+      if (!pattern.startsWith('/')) {
+        throw new Error(`[x402] Invalid endpoint pattern ${pattern}: must start with /`)
+      }
+      routes.push({ method, pattern, parts: pattern.split('/'), key })
+    }
+
+    console.log(`[x402] Payment gate enabled: payTo=${payTo}, ${routes.length} paid endpoints`)
+  }
+
+  // ── Negative cache ──
+
+  function isNegativelyCached (txid) {
+    const entry = _negCache.get(txid)
+    if (!entry) return null
+    if (Date.now() > entry.expiry) { _negCache.delete(txid); return null }
+    return entry
+  }
+
+  function cacheNegative (txid, reason, ttlMs, status) {
+    const ttl = ttlMs || (reason === 'tx_not_found' ? 8000 : 60000)
+    _negCache.set(txid, { expiry: Date.now() + ttl, reason, status: status || 402 })
+    if (_negCache.size > NEG_CACHE_MAX) {
+      const now = Date.now()
+      // First pass: evict expired
+      for (const [k, v] of _negCache) {
+        if (now > v.expiry) _negCache.delete(k)
+      }
+      // Second pass: FIFO trim if still oversized
+      if (_negCache.size > NEG_CACHE_MAX) {
+        const excess = _negCache.size - NEG_CACHE_MAX
+        let removed = 0
+        for (const k of _negCache.keys()) {
+          if (removed >= excess) break
+          _negCache.delete(k)
+          removed++
+        }
+      }
+    }
+  }
+
+  // ── The gate function ──
+
+  return async function checkPayment (method, rawPath, req) {
+    if (!enabled) return { ok: true }
+
+    method = method.toUpperCase()
+    const path = normalizePath(rawPath)
+    if (!path.startsWith('/')) return { ok: true }
+
+    const routeKey = matchRoute(method, path, routes)
+    if (!routeKey) return { ok: true }
+    const price = pricingMap[routeKey] || 0
+    if (price === 0) return { ok: true }
+
+    // Normalize proof header (handle array, empty, whitespace)
+    let proofRaw = req.headers['x-402-proof']
+    if (Array.isArray(proofRaw)) proofRaw = proofRaw[0]
+    if (!proofRaw || !proofRaw.trim()) {
+      return {
+        ok: false, status: 402,
+        body: {
+          x402Version: '1', scheme: 'bsv-direct', error: 'payment_required',
+          endpoint: routeKey, satoshis: price,
+          accepts: [{ scheme: 'bsv-direct', network: 'mainnet', satoshis: price, payTo }]
+        }
+      }
+    }
+
+    // Parse proof: accept <txid> or <txid>:<commit> (v2 stub)
+    const proofStr = proofRaw.trim().toLowerCase().slice(0, 256)
+    const txid = proofStr.split(':')[0]
+
+    if (!TXID_RE.test(txid)) {
+      return { ok: false, status: 400, body: { error: 'invalid_txid_format' } }
+    }
+
+    // Two-tier negative cache
+    const cached = isNegativelyCached(txid)
+    if (cached) {
+      return { ok: false, status: cached.status, body: { error: cached.reason } }
+    }
+
+    // Cross-endpoint protection
+    if (_pending.has(txid)) {
+      const inflight = _pending.get(txid)
+      if (inflight.routeKey !== routeKey || inflight.price !== price) {
+        return { ok: false, status: 402, body: { error: 'already_used' } }
+      }
+      return await inflight.promise
+    }
+
+    // Cap concurrent verifications
+    if (_pending.size >= MAX_CONCURRENT) {
+      return { ok: false, status: 503, body: { error: 'too_many_verifications' } }
+    }
+
+    const verifyPromise = (async () => {
+      // Atomic claim in LevelDB — put-if-absent (u!{txid} key)
+      const claim = await store.claimTxid(txid, { routeKey, price, createdAt: Date.now() })
+      if (!claim.ok) {
+        return { ok: false, status: 402, body: { error: 'already_used' } }
+      }
+
+      try {
+        // Fetch tx with timeout — distinguish 404 vs upstream failure
+        let txJson
+        try {
+          txJson = await fetchTxWithTimeout(fetchTx, txid, FETCH_TIMEOUT_MS)
+        } catch (err) {
+          await store.releaseClaim(txid)
+          // 404 = tx genuinely not found (short cache)
+          // Anything else = upstream outage (don't punish user, very short cache)
+          if (err.httpStatus === 404) {
+            cacheNegative(txid, 'tx_not_found', 8000, 402)
+            return { ok: false, status: 402, body: { error: 'tx_not_found' } }
+          }
+          cacheNegative(txid, 'upstream_unavailable', 3000, 503)
+          return { ok: false, status: 503, body: { error: 'upstream_unavailable' } }
+        }
+
+        // Sanity checks
+        const returnedId = txJson?.txid || txJson?.hash
+        if (!returnedId || returnedId !== txid || !Array.isArray(txJson.vout) ||
+            txJson.vout.length > 1000) {
+          await store.releaseClaim(txid)
+          cacheNegative(txid, 'invalid_payment', 60000, 402)
+          return { ok: false, status: 402, body: { error: 'invalid_payment' } }
+        }
+
+        // Find P2PKH outputs paying our address
+        const payment = findPaymentOutput(txJson, expectedHash160, BigInt(price))
+        if (!payment) {
+          await store.releaseClaim(txid)
+          cacheNegative(txid, 'insufficient_payment', 60000, 402)
+          return { ok: false, status: 402, body: { error: 'insufficient_payment' } }
+        }
+
+        // Promote claim to permanent receipt
+        const receipt = {
+          txid,
+          satoshisRequired: String(price),
+          satoshisPaid: payment.totalPaid.toString(),
+          matchedVouts: payment.matched.map(m => m.vout),
+          endpointKey: routeKey,
+          createdAt: Date.now(),
+          confirmed: false,
+          confirmedHeight: null
+        }
+        await store.finalizePayment(txid, receipt)
+        return { ok: true, receipt }
+      } catch (err) {
+        // Safety net: release claim on ANY unexpected error (bad BigInt, store throw, etc.)
+        await store.releaseClaim(txid).catch(() => {})
+        console.error(`[x402] unexpected verify error for ${txid}:`, err)
+        return { ok: false, status: 500, body: { error: 'internal_error' } }
+      }
+    })()
+
+    _pending.set(txid, { promise: verifyPromise, routeKey, price })
+    try {
+      return await verifyPromise
+    } finally {
+      _pending.delete(txid)
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relay-federation/bridge",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "description": "Bridge server — WebSocket peering, header sync, tx relay, CLI",
   "type": "module",
   "bin": {