@relay-federation/bridge 0.1.0

package/lib/score-actions.js

@@ -0,0 +1,135 @@
+import { EventEmitter } from 'node:events'
+
+const DEFAULT_DISCONNECT_THRESHOLD = 0.3
+const DEFAULT_BLACKLIST_THRESHOLD = 0.1
+const DEFAULT_BLACKLIST_DURATION_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+/**
+ * Score-based automatic actions.
+ *
+ * Listens to PeerScorer 'score:update' events and takes action:
+ * - score < 0.3 → auto-disconnect peer
+ * - score < 0.1 → blacklist peer for 24 hours
+ *
+ * Emits:
+ *   'peer:disconnected' — { pubkeyHex, score, reason }
+ *   'peer:blacklisted'  — { pubkeyHex, score, expiresAt }
+ */
+export class ScoreActions extends EventEmitter {
+  /**
+   * @param {import('./peer-scorer.js').PeerScorer} scorer
+   * @param {import('./peer-manager.js').PeerManager} peerManager
+   * @param {object} [opts]
+   * @param {number} [opts.disconnectThreshold=0.3]
+   * @param {number} [opts.blacklistThreshold=0.1]
+   * @param {number} [opts.blacklistDurationMs=86400000] — 24 hours
+   */
+  constructor (scorer, peerManager, opts = {}) {
+    super()
+    this.scorer = scorer
+    this.peerManager = peerManager
+    this._disconnectThreshold = opts.disconnectThreshold ?? DEFAULT_DISCONNECT_THRESHOLD
+    this._blacklistThreshold = opts.blacklistThreshold ?? DEFAULT_BLACKLIST_THRESHOLD
+    this._blacklistDurationMs = opts.blacklistDurationMs ?? DEFAULT_BLACKLIST_DURATION_MS
+    this._blacklist = new Map() // pubkeyHex → expiresAt (timestamp)
+
+    this.scorer.on('score:update', ({ pubkeyHex, score }) => {
+      this._evaluate(pubkeyHex, score)
+    })
+  }
+
+  /**
+   * Evaluate a peer's score and take action if below thresholds.
+   * @param {string} pubkeyHex
+   * @param {number} score
+   */
+  _evaluate (pubkeyHex, score) {
+    if (score < this._blacklistThreshold) {
+      this._blacklistPeer(pubkeyHex, score)
+    } else if (score < this._disconnectThreshold) {
+      this._disconnectPeer(pubkeyHex, score)
+    }
+  }
+
+  /**
+   * Disconnect a low-scoring peer.
+   * @param {string} pubkeyHex
+   * @param {number} score
+   */
+  _disconnectPeer (pubkeyHex, score) {
+    this.peerManager.disconnectPeer(pubkeyHex)
+    this.emit('peer:disconnected', {
+      pubkeyHex,
+      score,
+      reason: 'low_score'
+    })
+  }
+
+  /**
+   * Blacklist a peer — disconnect and prevent reconnection for the blacklist duration.
+   * @param {string} pubkeyHex
+   * @param {number} score
+   */
+  _blacklistPeer (pubkeyHex, score) {
+    const expiresAt = Date.now() + this._blacklistDurationMs
+
+    this._blacklist.set(pubkeyHex, expiresAt)
+    this.peerManager.disconnectPeer(pubkeyHex)
+
+    this.emit('peer:blacklisted', {
+      pubkeyHex,
+      score,
+      expiresAt
+    })
+  }
+
+  /**
+   * Check if a peer is currently blacklisted.
+   * Automatically cleans up expired entries.
+   *
+   * @param {string} pubkeyHex
+   * @returns {boolean}
+   */
+  isBlacklisted (pubkeyHex) {
+    if (!this._blacklist.has(pubkeyHex)) return false
+
+    const expiresAt = this._blacklist.get(pubkeyHex)
+    if (Date.now() >= expiresAt) {
+      this._blacklist.delete(pubkeyHex)
+      return false
+    }
+
+    return true
+  }
+
+  /**
+   * Get the blacklist expiry timestamp for a peer, or null.
+   * @param {string} pubkeyHex
+   * @returns {number|null}
+   */
+  getBlacklistExpiry (pubkeyHex) {
+    if (!this.isBlacklisted(pubkeyHex)) return null
+    return this._blacklist.get(pubkeyHex)
+  }
+
+  /**
+   * Get all currently blacklisted peers.
+   * @returns {Map<string, number>} pubkeyHex → expiresAt
+   */
+  getBlacklist () {
+    // Clean up expired entries
+    const now = Date.now()
+    for (const [pubkey, expiresAt] of this._blacklist) {
+      if (now >= expiresAt) this._blacklist.delete(pubkey)
+    }
+    return new Map(this._blacklist)
+  }
+
+  /**
+   * Manually remove a peer from the blacklist.
+   * @param {string} pubkeyHex
+   */
+  unblacklist (pubkeyHex) {
+    this._blacklist.delete(pubkeyHex)
+  }
+}

package/lib/status-server.js

@@ -0,0 +1,115 @@
+import { createServer } from 'node:http'
+
+/**
+ * StatusServer — localhost-only HTTP server exposing bridge status.
+ *
+ * Started by `relay-bridge start`, queried by `relay-bridge status`.
+ * Binds to 127.0.0.1 only — not accessible from outside the machine.
+ *
+ * Endpoints:
+ *   GET /status — JSON object with bridge state
+ */
+export class StatusServer {
+  /**
+   * @param {object} opts
+   * @param {number} [opts.port=9333] — HTTP port for status endpoint
+   * @param {import('./peer-manager.js').PeerManager} [opts.peerManager]
+   * @param {import('./header-relay.js').HeaderRelay} [opts.headerRelay]
+   * @param {import('./tx-relay.js').TxRelay} [opts.txRelay]
+   * @param {object} [opts.config] — Bridge config (pubkeyHex, endpoint, meshId)
+   */
+  constructor (opts = {}) {
+    this._port = opts.port || 9333
+    this._peerManager = opts.peerManager || null
+    this._headerRelay = opts.headerRelay || null
+    this._txRelay = opts.txRelay || null
+    this._config = opts.config || {}
+    this._startedAt = Date.now()
+    this._server = null
+  }
+
+  /**
+   * Build the status object from current bridge state.
+   * @returns {object}
+   */
+  getStatus () {
+    const peers = []
+    if (this._peerManager) {
+      for (const [pubkeyHex, conn] of this._peerManager.peers) {
+        peers.push({
+          pubkeyHex,
+          endpoint: conn.endpoint,
+          connected: !!conn.connected
+        })
+      }
+    }
+
+    return {
+      bridge: {
+        pubkeyHex: this._config.pubkeyHex || null,
+        endpoint: this._config.endpoint || null,
+        meshId: this._config.meshId || null,
+        uptimeSeconds: Math.floor((Date.now() - this._startedAt) / 1000)
+      },
+      peers: {
+        connected: this._peerManager ? this._peerManager.connectedCount() : 0,
+        max: this._peerManager ? this._peerManager.maxPeers : 0,
+        list: peers
+      },
+      headers: {
+        bestHeight: this._headerRelay ? this._headerRelay.bestHeight : -1,
+        bestHash: this._headerRelay ? this._headerRelay.bestHash : null,
+        count: this._headerRelay ? this._headerRelay.headers.size : 0
+      },
+      txs: {
+        mempool: this._txRelay ? this._txRelay.mempool.size : 0,
+        seen: this._txRelay ? this._txRelay.seen.size : 0
+      }
+    }
+  }
+
+  /**
+   * Start the HTTP server on localhost.
+   * @returns {Promise<void>}
+   */
+  start () {
+    return new Promise((resolve, reject) => {
+      this._server = createServer((req, res) => {
+        if (req.method === 'GET' && req.url === '/status') {
+          const status = this.getStatus()
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify(status))
+        } else {
+          res.writeHead(404)
+          res.end('Not Found')
+        }
+      })
+
+      this._server.listen(this._port, '127.0.0.1', () => resolve())
+      this._server.on('error', reject)
+    })
+  }
+
+  /**
+   * Stop the HTTP server.
+   * @returns {Promise<void>}
+   */
+  stop () {
+    return new Promise((resolve) => {
+      if (this._server) {
+        this._server.close(() => resolve())
+        this._server = null
+      } else {
+        resolve()
+      }
+    })
+  }
+
+  /**
+   * Get the port this server is configured to use.
+   * @returns {number}
+   */
+  get port () {
+    return this._port
+  }
+}

package/lib/tx-relay.js

@@ -0,0 +1,117 @@
+import { EventEmitter } from 'node:events'
+
+/**
+ * TxRelay — relays transactions between peers.
+ *
+ * Uses the INV/GETDATA pattern (like Bitcoin P2P):
+ * 1. Peer announces a txid via tx_announce
+ * 2. If we haven't seen it, we request the full tx via tx_request
+ * 3. Peer responds with the raw tx hex via tx message
+ * 4. We store it and re-announce to other peers
+ *
+ * Message types:
+ *   tx_announce — { type, txid }
+ *   tx_request  — { type, txid }
+ *   tx          — { type, txid, rawHex }
+ *
+ * Events:
+ *   'tx:new' — { txid, rawHex } — new transaction received or submitted
+ */
+export class TxRelay extends EventEmitter {
+  /**
+   * @param {import('./peer-manager.js').PeerManager} peerManager
+   * @param {object} [opts]
+   * @param {number} [opts.maxMempool=1000] — Max txs in local mempool
+   */
+  constructor (peerManager, opts = {}) {
+    super()
+    this.peerManager = peerManager
+    /** @type {Map<string, string>} txid → rawHex */
+    this.mempool = new Map()
+    /** @type {Set<string>} txids we've already seen (dedup) */
+    this.seen = new Set()
+    this._maxMempool = opts.maxMempool || 1000
+
+    this.peerManager.on('peer:message', ({ pubkeyHex, message }) => {
+      this._handleMessage(pubkeyHex, message)
+    })
+  }
+
+  /**
+   * Submit a new tx for relay to all peers.
+   * @param {string} txid
+   * @param {string} rawHex
+   * @returns {number} Number of peers the announce was sent to
+   */
+  broadcastTx (txid, rawHex) {
+    if (this.seen.has(txid)) return 0
+    this.seen.add(txid)
+    this._storeTx(txid, rawHex)
+    this.emit('tx:new', { txid, rawHex })
+    return this.peerManager.broadcast({ type: 'tx_announce', txid })
+  }
+
+  /**
+   * Get a tx from the local mempool.
+   * @param {string} txid
+   * @returns {string|null} rawHex or null
+   */
+  getTx (txid) {
+    return this.mempool.get(txid) || null
+  }
+
+  /** @private */
+  _storeTx (txid, rawHex) {
+    if (this.mempool.size >= this._maxMempool) {
+      const oldest = this.mempool.keys().next().value
+      this.mempool.delete(oldest)
+    }
+    this.mempool.set(txid, rawHex)
+  }
+
+  /** @private */
+  _handleMessage (pubkeyHex, message) {
+    switch (message.type) {
+      case 'tx_announce':
+        this._onTxAnnounce(pubkeyHex, message)
+        break
+      case 'tx_request':
+        this._onTxRequest(pubkeyHex, message)
+        break
+      case 'tx':
+        this._onTx(pubkeyHex, message)
+        break
+    }
+  }
+
+  /** @private */
+  _onTxAnnounce (pubkeyHex, msg) {
+    if (this.seen.has(msg.txid)) return
+    this.seen.add(msg.txid)
+    const conn = this.peerManager.peers.get(pubkeyHex)
+    if (conn) {
+      conn.send({ type: 'tx_request', txid: msg.txid })
+    }
+  }
+
+  /** @private */
+  _onTxRequest (pubkeyHex, msg) {
+    const rawHex = this.mempool.get(msg.txid)
+    if (rawHex) {
+      const conn = this.peerManager.peers.get(pubkeyHex)
+      if (conn) {
+        conn.send({ type: 'tx', txid: msg.txid, rawHex })
+      }
+    }
+  }
+
+  /** @private */
+  _onTx (pubkeyHex, msg) {
+    if (!msg.txid || !msg.rawHex) return
+    if (this.mempool.has(msg.txid)) return
+    this._storeTx(msg.txid, msg.rawHex)
+    this.emit('tx:new', { txid: msg.txid, rawHex: msg.rawHex })
+    // Re-announce to all peers except the source
+    this.peerManager.broadcast({ type: 'tx_announce', txid: msg.txid }, pubkeyHex)
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@relay-federation/bridge",
+  "version": "0.1.0",
+  "description": "Bridge server — WebSocket peering, header sync, tx relay, CLI",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "relay-bridge": "./cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@bsv/sdk": "^1.10.1",
+    "@relay-federation/common": "^0.1.0",
+    "ws": "^8.19.0"
+  },
+  "license": "MIT",
+  "author": "zcooL",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zcoolz/relay-federation",
+    "directory": "packages/bridge"
+  },
+  "keywords": ["bsv", "spv", "relay", "bridge", "federation", "bitcoin", "mesh"],
+  "engines": { "node": ">=18" },
+  "files": ["index.js", "cli.js", "lib/"]
+}