@relay-federation/bridge 0.1.0

package/cli.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+
+import { join } from 'node:path'
+import { initConfig, loadConfig, configExists, defaultConfigDir } from './lib/config.js'
+import { PeerManager } from './lib/peer-manager.js'
+import { HeaderRelay } from './lib/header-relay.js'
+import { TxRelay } from './lib/tx-relay.js'
+import { StatusServer } from './lib/status-server.js'
+import { fetchUtxos, broadcastTx } from '@relay-federation/common/network'
+
+const command = process.argv[2]
+
+switch (command) {
+  case 'init':
+    await cmdInit()
+    break
+  case 'register':
+    await cmdRegister()
+    break
+  case 'start':
+    await cmdStart()
+    break
+  case 'status':
+    await cmdStatus()
+    break
+  case 'deregister':
+    await cmdDeregister()
+    break
+  default:
+    console.log('relay-bridge — Federated SPV relay mesh bridge\n')
+    console.log('Commands:')
+    console.log('  init        Generate bridge identity and config')
+    console.log('  register    Register this bridge on-chain')
+    console.log('  start       Start the bridge server')
+    console.log('  status      Show running bridge status')
+    console.log('  deregister  Deregister this bridge from the mesh')
+    console.log('')
+    console.log('Usage: relay-bridge <command> [options]')
+    process.exit(command ? 1 : 0)
+}
+
+async function cmdInit () {
+  const dir = defaultConfigDir()
+
+  if (await configExists(dir)) {
+    console.log(`Config already exists at ${dir}/config.json`)
+    console.log('To re-initialize, delete the existing config first.')
+    process.exit(1)
+  }
+
+  const config = await initConfig(dir)
+
+  console.log('Bridge initialized!\n')
+  console.log(`  Config: ${dir}/config.json`)
+  console.log(`  Pubkey: ${config.pubkeyHex}`)
+  console.log('')
+  console.log('Next steps:')
+  console.log('  1. Edit config.json — set your WSS endpoint and API key')
+  console.log('  2. Fund your bridge address with BSV')
+  console.log('  3. Run: relay-bridge register')
+}
+
+async function cmdRegister () {
+  const dir = defaultConfigDir()
+
+  if (!(await configExists(dir))) {
+    console.log('No config found. Run: relay-bridge init')
+    process.exit(1)
+  }
+
+  const config = await loadConfig(dir)
+
+  if (config.endpoint === 'wss://your-bridge.example.com:8333') {
+    console.log('Error: Update your endpoint in config.json before registering.')
+    process.exit(1)
+  }
+
+  console.log('Registration details:\n')
+  console.log(`  Pubkey:       ${config.pubkeyHex}`)
+  console.log(`  Endpoint:     ${config.endpoint}`)
+  console.log(`  Mesh:         ${config.meshId}`)
+  console.log(`  Capabilities: ${config.capabilities.join(', ')}`)
+  console.log(`  SPV Endpoint: ${config.spvEndpoint}`)
+  console.log('')
+  console.log('On-chain registration requires:')
+  console.log('  - Funded wallet (stake bond + tx fees)')
+  console.log('  - Valid API key for SPV bridge access')
+  console.log('')
+  console.log('Broadcast support coming in Phase 2.')
+}
+
+async function cmdStart () {
+  const dir = defaultConfigDir()
+
+  if (!(await configExists(dir))) {
+    console.log('No config found. Run: relay-bridge init')
+    process.exit(1)
+  }
+
+  const config = await loadConfig(dir)
+  const peerArg = process.argv[3] // optional: ws://host:port
+
+  const peerManager = new PeerManager({ maxPeers: config.maxPeers })
+  const headerRelay = new HeaderRelay(peerManager)
+  const txRelay = new TxRelay(peerManager)
+
+  // Start server
+  await peerManager.startServer({ port: config.port, host: '0.0.0.0' })
+  console.log(`Bridge listening on port ${config.port}`)
+  console.log(`  Pubkey: ${config.pubkeyHex}`)
+  console.log(`  Mesh:   ${config.meshId}`)
+
+  if (peerArg) {
+    // Manual peer connection
+    console.log(`Connecting to peer: ${peerArg}`)
+    const conn = peerManager.connectToPeer({
+      pubkeyHex: 'manual_peer',
+      endpoint: peerArg
+    })
+    if (conn) {
+      conn.on('open', () => {
+        conn.send({
+          type: 'hello',
+          pubkey: config.pubkeyHex,
+          endpoint: config.endpoint
+        })
+      })
+    }
+  } else if (config.apiKey) {
+    // Scan chain for peers
+    console.log('Scanning chain for peers...')
+    try {
+      const { scanRegistry } = await import('../registry/lib/scanner.js')
+      const { buildPeerList, excludeSelf } = await import('../registry/lib/discovery.js')
+      const { savePeerCache, loadPeerCache } = await import('../registry/lib/peer-cache.js')
+
+      const cachePath = join(dir, 'cache', 'peers.json')
+      let peers = await loadPeerCache(cachePath)
+
+      if (!peers) {
+        const entries = await scanRegistry({
+          spvEndpoint: config.spvEndpoint,
+          apiKey: config.apiKey
+        })
+        peers = buildPeerList(entries)
+        peers = excludeSelf(peers, config.pubkeyHex)
+        await savePeerCache(peers, cachePath)
+      }
+
+      console.log(`Found ${peers.length} peers`)
+      for (const peer of peers) {
+        const conn = peerManager.connectToPeer(peer)
+        if (conn) {
+          conn.on('open', () => {
+            conn.send({
+              type: 'hello',
+              pubkey: config.pubkeyHex,
+              endpoint: config.endpoint
+            })
+          })
+        }
+      }
+    } catch (err) {
+      console.log(`Peer scan failed: ${err.message}`)
+      console.log('Start with manual peer: relay-bridge start ws://peer:port')
+    }
+  } else {
+    console.log('No peer specified and no API key configured.')
+    console.log('Usage: relay-bridge start ws://peer:port')
+  }
+
+  // Start status server (localhost only)
+  const statusPort = config.statusPort || 9333
+  const statusServer = new StatusServer({
+    port: statusPort,
+    peerManager,
+    headerRelay,
+    txRelay,
+    config
+  })
+  await statusServer.start()
+  console.log(`  Status: http://127.0.0.1:${statusPort}/status`)
+
+  // Log events
+  peerManager.on('peer:connect', ({ pubkeyHex }) => {
+    console.log(`Peer connected: ${pubkeyHex}`)
+  })
+
+  peerManager.on('peer:disconnect', ({ pubkeyHex }) => {
+    console.log(`Peer disconnected: ${pubkeyHex}`)
+  })
+
+  headerRelay.on('header:sync', ({ pubkeyHex, added, bestHeight }) => {
+    console.log(`Synced ${added} headers from ${pubkeyHex} (height: ${bestHeight})`)
+  })
+
+  txRelay.on('tx:new', ({ txid }) => {
+    console.log(`New tx: ${txid}`)
+  })
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.log('\nShutting down...')
+    await statusServer.stop()
+    await peerManager.shutdown()
+    process.exit(0)
+  }
+
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+}
+
+async function cmdStatus () {
+  const dir = defaultConfigDir()
+
+  if (!(await configExists(dir))) {
+    console.log('No config found. Run: relay-bridge init')
+    process.exit(1)
+  }
+
+  const config = await loadConfig(dir)
+  const statusPort = config.statusPort || 9333
+
+  let status
+  try {
+    const res = await fetch(`http://127.0.0.1:${statusPort}/status`)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    status = await res.json()
+  } catch {
+    console.log('Bridge is not running.')
+    console.log(`  (expected status server on port ${statusPort})`)
+    console.log('  Start it with: relay-bridge start')
+    process.exit(1)
+  }
+
+  console.log('Bridge Status\n')
+
+  // Bridge identity
+  console.log('  Bridge')
+  console.log(`    Pubkey:   ${status.bridge.pubkeyHex}`)
+  console.log(`    Endpoint: ${status.bridge.endpoint}`)
+  console.log(`    Mesh:     ${status.bridge.meshId}`)
+  console.log(`    Uptime:   ${formatUptime(status.bridge.uptimeSeconds)}`)
+
+  // Peers
+  console.log('')
+  console.log(`  Peers (${status.peers.connected}/${status.peers.max})`)
+  if (status.peers.list.length === 0) {
+    console.log('    (no peers)')
+  } else {
+    for (const peer of status.peers.list) {
+      const tag = peer.connected ? 'connected' : 'disconnected'
+      console.log(`    ${peer.pubkeyHex.slice(0, 16)}... ${peer.endpoint} (${tag})`)
+    }
+  }
+
+  // Headers
+  console.log('')
+  console.log('  Headers')
+  console.log(`    Best Height: ${status.headers.bestHeight}`)
+  console.log(`    Best Hash:   ${status.headers.bestHash || '(none)'}`)
+  console.log(`    Stored:      ${status.headers.count}`)
+
+  // Transactions
+  console.log('')
+  console.log('  Transactions')
+  console.log(`    Mempool: ${status.txs.mempool}`)
+  console.log(`    Seen:    ${status.txs.seen}`)
+}
+
+async function cmdDeregister () {
+  const dir = defaultConfigDir()
+
+  if (!(await configExists(dir))) {
+    console.log('No config found. Run: relay-bridge init')
+    process.exit(1)
+  }
+
+  const config = await loadConfig(dir)
+
+  if (!config.apiKey) {
+    console.log('Error: API key required for deregistration (broadcasts via SPV bridge).')
+    console.log('Set "apiKey" in config.json.')
+    process.exit(1)
+  }
+
+  const reason = process.argv[3] || 'shutdown'
+
+  console.log('Deregistration details:\n')
+  console.log(`  Pubkey: ${config.pubkeyHex}`)
+  console.log(`  Reason: ${reason}`)
+  console.log(`  SPV:    ${config.spvEndpoint}`)
+  console.log('')
+
+  try {
+    const { buildDeregistrationTx } = await import('../registry/lib/registration.js')
+
+    // Fetch UTXOs from SPV bridge
+    const utxos = await fetchUtxos(config.spvEndpoint, config.apiKey, config.pubkeyHex)
+
+    if (!utxos.length) {
+      console.log('Error: No UTXOs found. Wallet needs funding for tx fees.')
+      process.exit(1)
+    }
+
+    // Build deregistration tx
+    const { txHex, txid } = await buildDeregistrationTx({
+      wif: config.wif,
+      utxos,
+      reason
+    })
+
+    // Broadcast via SPV bridge
+    await broadcastTx(config.spvEndpoint, config.apiKey, txHex)
+
+    console.log('Deregistration broadcast successful!')
+    console.log(`  txid: ${txid}`)
+    console.log('')
+    console.log('Your bridge will be removed from peer lists on next scan cycle.')
+  } catch (err) {
+    console.log(`Deregistration failed: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+function formatUptime (seconds) {
+  const days = Math.floor(seconds / 86400)
+  const hours = Math.floor((seconds % 86400) / 3600)
+  const minutes = Math.floor((seconds % 3600) / 60)
+  const secs = seconds % 60
+
+  if (days > 0) return `${days}d ${hours}h ${minutes}m`
+  if (hours > 0) return `${hours}h ${minutes}m ${secs}s`
+  if (minutes > 0) return `${minutes}m ${secs}s`
+  return `${secs}s`
+}

package/lib/anchor-manager.js

@@ -0,0 +1,158 @@
+import { EventEmitter } from 'node:events'
+
+const DEFAULT_MIN_ANCHORS = 2
+const DEFAULT_RECONNECT_INTERVAL_MS = 30000 // 30 seconds
+const DEFAULT_LOW_SCORE_THRESHOLD = 0.3
+
+/**
+ * AnchorManager — ensures minimum connections to well-known anchor bridges.
+ *
+ * Anchors are hardcoded in config. This manager:
+ * - Ensures at least N anchor connections are maintained
+ * - Auto-reconnects to anchors on disconnect
+ * - Allows dropping low-scoring anchors (with warning)
+ * - Does NOT make anchors immune to scoring
+ *
+ * Emits:
+ *   'anchor:connect'    — { pubkeyHex, endpoint }
+ *   'anchor:disconnect' — { pubkeyHex, endpoint }
+ *   'anchor:low_score'  — { pubkeyHex, score } — warning, anchor scoring below threshold
+ */
+export class AnchorManager extends EventEmitter {
+  /**
+   * @param {import('./peer-manager.js').PeerManager} peerManager
+   * @param {object} [opts]
+   * @param {Array<{ pubkeyHex: string, endpoint: string }>} [opts.anchors=[]] — anchor bridge list
+   * @param {number} [opts.minAnchors=2] — minimum anchor connections to maintain
+   * @param {number} [opts.reconnectIntervalMs=30000] — how often to check anchor connections
+   * @param {number} [opts.lowScoreThreshold=0.3] — score below which to warn about anchor
+   */
+  constructor (peerManager, opts = {}) {
+    super()
+    this.peerManager = peerManager
+    this._anchors = opts.anchors || []
+    this._minAnchors = opts.minAnchors ?? DEFAULT_MIN_ANCHORS
+    this._reconnectIntervalMs = opts.reconnectIntervalMs ?? DEFAULT_RECONNECT_INTERVAL_MS
+    this._lowScoreThreshold = opts.lowScoreThreshold ?? DEFAULT_LOW_SCORE_THRESHOLD
+    this._reconnectTimer = null
+    this._anchorSet = new Set(this._anchors.map(a => a.pubkeyHex))
+
+    // Listen for disconnects to track anchor status
+    this.peerManager.on('peer:disconnect', ({ pubkeyHex, endpoint }) => {
+      if (this._anchorSet.has(pubkeyHex)) {
+        this.emit('anchor:disconnect', { pubkeyHex, endpoint })
+      }
+    })
+
+    this.peerManager.on('peer:connect', ({ pubkeyHex, endpoint }) => {
+      if (this._anchorSet.has(pubkeyHex)) {
+        this.emit('anchor:connect', { pubkeyHex, endpoint })
+      }
+    })
+  }
+
+  /**
+   * Check if a pubkey is an anchor bridge.
+   * @param {string} pubkeyHex
+   * @returns {boolean}
+   */
+  isAnchor (pubkeyHex) {
+    return this._anchorSet.has(pubkeyHex)
+  }
+
+  /**
+   * Get the list of configured anchor bridges.
+   * @returns {Array<{ pubkeyHex: string, endpoint: string }>}
+   */
+  getAnchors () {
+    return [...this._anchors]
+  }
+
+  /**
+   * Get count of currently connected anchor bridges.
+   * @returns {number}
+   */
+  connectedAnchorCount () {
+    let count = 0
+    for (const anchor of this._anchors) {
+      const conn = this.peerManager.peers.get(anchor.pubkeyHex)
+      if (conn && conn.connected) count++
+    }
+    return count
+  }
+
+  /**
+   * Connect to all configured anchors that we're not already connected to.
+   * Respects maxPeers — if at capacity, still tries anchors (they're priority).
+   *
+   * @returns {number} Number of new connections initiated
+   */
+  ensureConnections () {
+    let initiated = 0
+
+    for (const anchor of this._anchors) {
+      const existing = this.peerManager.peers.get(anchor.pubkeyHex)
+      if (existing && existing.connected) continue
+
+      // If we have a disconnected connection object, remove it first
+      if (existing && !existing.connected) {
+        this.peerManager.peers.delete(anchor.pubkeyHex)
+      }
+
+      const conn = this.peerManager.connectToPeer(anchor)
+      if (conn) initiated++
+    }
+
+    return initiated
+  }
+
+  /**
+   * Start periodic anchor connection monitoring.
+   * Checks every reconnectIntervalMs and reconnects to missing anchors.
+   */
+  startMonitoring () {
+    if (this._reconnectTimer) return
+
+    this._reconnectTimer = setInterval(() => {
+      const connected = this.connectedAnchorCount()
+      if (connected < this._minAnchors) {
+        this.ensureConnections()
+      }
+    }, this._reconnectIntervalMs)
+
+    // Don't prevent process exit
+    if (this._reconnectTimer.unref) {
+      this._reconnectTimer.unref()
+    }
+  }
+
+  /**
+   * Stop periodic monitoring.
+   */
+  stopMonitoring () {
+    if (this._reconnectTimer) {
+      clearInterval(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+  }
+
+  /**
+   * Check anchor scores and emit warnings for low-scoring anchors.
+   *
+   * @param {import('./peer-scorer.js').PeerScorer} scorer
+   * @returns {Array<{ pubkeyHex: string, score: number }>} Low-scoring anchors
+   */
+  checkAnchorScores (scorer) {
+    const lowScoring = []
+
+    for (const anchor of this._anchors) {
+      const score = scorer.getScore(anchor.pubkeyHex)
+      if (score < this._lowScoreThreshold) {
+        lowScoring.push({ pubkeyHex: anchor.pubkeyHex, score })
+        this.emit('anchor:low_score', { pubkeyHex: anchor.pubkeyHex, score })
+      }
+    }
+
+    return lowScoring
+  }
+}

package/lib/config.js

@@ -0,0 +1,69 @@
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { PrivateKey } from '@bsv/sdk'
+
+const DEFAULT_DIR = join(homedir(), '.relay-bridge')
+const CONFIG_FILE = 'config.json'
+
+/**
+ * Get the default config directory path.
+ * @returns {string}
+ */
+export function defaultConfigDir () {
+  return DEFAULT_DIR
+}
+
+/**
+ * Initialize a new bridge config with a fresh key pair.
+ *
+ * @param {string} [dir] — Config directory (default: ~/.relay-bridge)
+ * @returns {Promise<object>} The generated config
+ */
+export async function initConfig (dir = DEFAULT_DIR) {
+  const privKey = PrivateKey.fromRandom()
+
+  const config = {
+    wif: privKey.toWif(),
+    pubkeyHex: privKey.toPublicKey().toString(),
+    endpoint: 'wss://your-bridge.example.com:8333',
+    meshId: 'indelible',
+    capabilities: ['tx_relay', 'header_sync', 'broadcast', 'address_history'],
+    spvEndpoint: 'https://relay.indelible.one',
+    apiKey: '',
+    port: 8333,
+    statusPort: 9333,
+    maxPeers: 20
+  }
+
+  await mkdir(dir, { recursive: true })
+  await writeFile(join(dir, CONFIG_FILE), JSON.stringify(config, null, 2))
+
+  return config
+}
+
+/**
+ * Load an existing bridge config.
+ *
+ * @param {string} [dir] — Config directory (default: ~/.relay-bridge)
+ * @returns {Promise<object>}
+ */
+export async function loadConfig (dir = DEFAULT_DIR) {
+  const raw = await readFile(join(dir, CONFIG_FILE), 'utf8')
+  return JSON.parse(raw)
+}
+
+/**
+ * Check if a config file exists.
+ *
+ * @param {string} [dir] — Config directory (default: ~/.relay-bridge)
+ * @returns {Promise<boolean>}
+ */
+export async function configExists (dir = DEFAULT_DIR) {
+  try {
+    await access(join(dir, CONFIG_FILE))
+    return true
+  } catch {
+    return false
+  }
+}