@relay-federation/bridge 0.1.0

package/lib/data-validator.js

@@ -0,0 +1,205 @@
+import { EventEmitter } from 'node:events'
+import { createHash } from 'node:crypto'
+
+// BSV block header is 80 bytes.
+// Timestamp bounds: reject headers more than 2 hours in the future.
+const MAX_FUTURE_SECONDS = 2 * 60 * 60
+
+/**
+ * Validate a block header.
+ *
+ * Checks:
+ * - Has required fields (height, hash, prevHash)
+ * - Hash is a 64-char hex string
+ * - prevHash is a 64-char hex string
+ *
+ * Note: Full PoW validation requires raw 80-byte header data, which our
+ * HeaderRelay doesn't carry (it uses {height, hash, prevHash} objects).
+ * We validate format and chain linkage here; PoW validation is deferred
+ * to when raw headers are available.
+ *
+ * @param {object} header — { height, hash, prevHash }
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function validateHeader (header) {
+  if (!header || typeof header !== 'object') {
+    return { valid: false, reason: 'not_an_object' }
+  }
+
+  if (typeof header.height !== 'number' || header.height < 0) {
+    return { valid: false, reason: 'invalid_height' }
+  }
+
+  if (typeof header.hash !== 'string' || !/^[0-9a-f]{64}$/i.test(header.hash)) {
+    return { valid: false, reason: 'invalid_hash' }
+  }
+
+  if (typeof header.prevHash !== 'string' || !/^[0-9a-f]{64}$/i.test(header.prevHash)) {
+    return { valid: false, reason: 'invalid_prevHash' }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Validate a transaction.
+ *
+ * Checks:
+ * - txid is a valid 64-char hex string
+ * - rawHex is a non-empty hex string
+ * - rawHex has minimum tx size (at least 10 bytes = 20 hex chars)
+ *
+ * @param {string} txid
+ * @param {string} rawHex
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function validateTx (txid, rawHex) {
+  if (typeof txid !== 'string' || !/^[0-9a-f]{64}$/i.test(txid)) {
+    return { valid: false, reason: 'invalid_txid' }
+  }
+
+  if (typeof rawHex !== 'string' || rawHex.length < 20) {
+    return { valid: false, reason: 'invalid_raw_hex' }
+  }
+
+  if (!/^[0-9a-f]+$/i.test(rawHex)) {
+    return { valid: false, reason: 'not_hex' }
+  }
+
+  // Verify txid matches hash of raw tx
+  const hash1 = createHash('sha256').update(Buffer.from(rawHex, 'hex')).digest()
+  const hash2 = createHash('sha256').update(hash1).digest()
+  const computedTxid = hash2.reverse().toString('hex')
+
+  if (computedTxid !== txid.toLowerCase()) {
+    return { valid: false, reason: 'txid_mismatch' }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Validate header chain linkage.
+ *
+ * Checks that each header's prevHash matches the previous header's hash.
+ *
+ * @param {Array<{ height: number, hash: string, prevHash: string }>} headers — sorted by height ascending
+ * @returns {{ valid: boolean, reason?: string, invalidAt?: number }}
+ */
+export function validateHeaderChain (headers) {
+  if (!Array.isArray(headers) || headers.length === 0) {
+    return { valid: true } // empty chain is valid
+  }
+
+  for (let i = 0; i < headers.length; i++) {
+    const check = validateHeader(headers[i])
+    if (!check.valid) {
+      return { valid: false, reason: `header[${i}]: ${check.reason}`, invalidAt: i }
+    }
+  }
+
+  for (let i = 1; i < headers.length; i++) {
+    if (headers[i].prevHash !== headers[i - 1].hash) {
+      return {
+        valid: false,
+        reason: `chain_break at height ${headers[i].height}: prevHash doesn't match previous hash`,
+        invalidAt: i
+      }
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * DataValidator — hooks into PeerManager events and reports
+ * data accuracy to PeerScorer.
+ *
+ * Listens for peer:message events, validates headers and txs,
+ * and calls scorer.recordGoodData/recordBadData.
+ *
+ * Emits:
+ *   'validation:fail' — { pubkeyHex, type, reason }
+ */
+export class DataValidator extends EventEmitter {
+  /**
+   * @param {import('./peer-manager.js').PeerManager} peerManager
+   * @param {import('./peer-scorer.js').PeerScorer} scorer
+   */
+  constructor (peerManager, scorer) {
+    super()
+    this.peerManager = peerManager
+    this.scorer = scorer
+
+    this.peerManager.on('peer:message', ({ pubkeyHex, message }) => {
+      this._onMessage(pubkeyHex, message)
+    })
+  }
+
+  _onMessage (pubkeyHex, message) {
+    switch (message.type) {
+      case 'headers':
+        this._validateHeaders(pubkeyHex, message)
+        break
+      case 'tx':
+        this._validateTx(pubkeyHex, message)
+        break
+      case 'header_announce':
+        this._validateHeaderAnnounce(pubkeyHex, message)
+        break
+    }
+  }
+
+  _validateHeaders (pubkeyHex, msg) {
+    if (!Array.isArray(msg.headers) || msg.headers.length === 0) {
+      this.scorer.recordBadData(pubkeyHex)
+      this.emit('validation:fail', { pubkeyHex, type: 'headers', reason: 'empty_or_missing' })
+      return
+    }
+
+    const chainCheck = validateHeaderChain(msg.headers)
+    if (!chainCheck.valid) {
+      this.scorer.recordBadData(pubkeyHex)
+      this.emit('validation:fail', { pubkeyHex, type: 'headers', reason: chainCheck.reason })
+      return
+    }
+
+    // Each valid header counts as a good data point
+    for (let i = 0; i < msg.headers.length; i++) {
+      this.scorer.recordGoodData(pubkeyHex)
+    }
+  }
+
+  _validateTx (pubkeyHex, msg) {
+    if (!msg.txid || !msg.rawHex) {
+      this.scorer.recordBadData(pubkeyHex)
+      this.emit('validation:fail', { pubkeyHex, type: 'tx', reason: 'missing_fields' })
+      return
+    }
+
+    const check = validateTx(msg.txid, msg.rawHex)
+    if (!check.valid) {
+      this.scorer.recordBadData(pubkeyHex)
+      this.emit('validation:fail', { pubkeyHex, type: 'tx', reason: check.reason })
+      return
+    }
+
+    this.scorer.recordGoodData(pubkeyHex)
+  }
+
+  _validateHeaderAnnounce (pubkeyHex, msg) {
+    if (typeof msg.height !== 'number' || msg.height < 0) {
+      this.scorer.recordBadData(pubkeyHex)
+      this.emit('validation:fail', { pubkeyHex, type: 'header_announce', reason: 'invalid_height' })
+      return
+    }
+
+    if (typeof msg.hash !== 'string' || !/^[0-9a-f]{64}$/i.test(msg.hash)) {
+      this.scorer.recordBadData(pubkeyHex)
+      this.emit('validation:fail', { pubkeyHex, type: 'header_announce', reason: 'invalid_hash' })
+      return
+    }
+
+    this.scorer.recordGoodData(pubkeyHex)
+  }
+}

package/lib/handshake.js

@@ -0,0 +1,165 @@
+import { randomBytes } from 'node:crypto'
+import { PrivateKey } from '@bsv/sdk'
+import { signHash, verifyHash } from '@relay-federation/common/crypto'
+import { SUPPORTED_VERSIONS, HANDSHAKE_TIMEOUT_MS } from '@relay-federation/common/protocol'
+
+/**
+ * Create a cryptographic handshake helper.
+ *
+ * Protocol (2 round-trips):
+ *   1. Initiator → Responder: { type: "hello", pubkey, nonce, versions, endpoint }
+ *   2. Responder → Initiator: { type: "challenge_response", pubkey, nonce, signature, selected_version }
+ *   3. Initiator → Responder: { type: "verify", signature }
+ *   (Responder verifies → connection established)
+ *
+ * @param {object} opts
+ * @param {string} opts.wif — Our WIF private key
+ * @param {string} opts.pubkeyHex — Our compressed pubkey hex
+ * @param {string} opts.endpoint — Our advertised WSS endpoint
+ * @param {string[]} [opts.versions] — Supported protocol versions
+ * @returns {object} Handshake helper with methods
+ */
+export function createHandshake (opts) {
+  const privKey = PrivateKey.fromWif(opts.wif)
+  const ourPubkeyHex = opts.pubkeyHex
+  const ourEndpoint = opts.endpoint
+  const ourVersions = opts.versions || SUPPORTED_VERSIONS
+
+  return {
+    /**
+     * Build the initial hello message (initiator side).
+     * @returns {{ message: object, nonce: string }}
+     */
+    createHello () {
+      const nonce = randomBytes(32).toString('hex')
+      return {
+        message: {
+          type: 'hello',
+          pubkey: ourPubkeyHex,
+          nonce,
+          versions: ourVersions,
+          endpoint: ourEndpoint
+        },
+        nonce
+      }
+    },
+
+    /**
+     * Handle an incoming hello and produce a challenge_response (responder side).
+     *
+     * @param {object} hello — The received hello message
+     * @param {Set<string>|null} [registeredPubkeys] — Set of registered pubkeys (if null, skip registry check)
+     * @returns {{ message: object, nonce: string, peerPubkey: string, selectedVersion: string } | { error: string }}
+     */
+    handleHello (hello, registeredPubkeys = null) {
+      if (!hello || hello.type !== 'hello' || !hello.pubkey || !hello.nonce || !hello.endpoint) {
+        return { error: 'invalid_hello' }
+      }
+
+      if (!Array.isArray(hello.versions) || hello.versions.length === 0) {
+        return { error: 'missing_versions' }
+      }
+
+      // Check registry
+      if (registeredPubkeys && !registeredPubkeys.has(hello.pubkey)) {
+        return { error: 'not_registered' }
+      }
+
+      // Version negotiation — select highest mutual version
+      const mutual = hello.versions.filter(v => ourVersions.includes(v))
+      if (mutual.length === 0) {
+        return { error: 'version_mismatch', supported: ourVersions }
+      }
+      const selectedVersion = mutual.sort().pop() // highest mutual version
+
+      // Sign the initiator's nonce to prove our identity
+      const signature = signHash(hello.nonce, privKey)
+      const responderNonce = randomBytes(32).toString('hex')
+
+      return {
+        message: {
+          type: 'challenge_response',
+          pubkey: ourPubkeyHex,
+          nonce: responderNonce,
+          signature,
+          selected_version: selectedVersion
+        },
+        nonce: responderNonce,
+        peerPubkey: hello.pubkey,
+        selectedVersion
+      }
+    },
+
+    /**
+     * Verify the challenge_response and produce the verify message (initiator side).
+     *
+     * @param {object} response — The received challenge_response message
+     * @param {string} ourNonce — The nonce we sent in hello
+     * @param {Set<string>|null} [registeredPubkeys] — Set of registered pubkeys
+     * @returns {{ message: object, peerPubkey: string, selectedVersion: string } | { error: string }}
+     */
+    handleChallengeResponse (response, ourNonce, registeredPubkeys = null) {
+      if (!response || response.type !== 'challenge_response' || !response.pubkey || !response.nonce || !response.signature) {
+        return { error: 'invalid_challenge_response' }
+      }
+
+      if (!response.selected_version) {
+        return { error: 'missing_version' }
+      }
+
+      // Check registry
+      if (registeredPubkeys && !registeredPubkeys.has(response.pubkey)) {
+        return { error: 'not_registered' }
+      }
+
+      // Verify responder signed our nonce
+      try {
+        const valid = verifyHash(ourNonce, response.signature, response.pubkey)
+        if (!valid) {
+          return { error: 'invalid_signature' }
+        }
+      } catch {
+        return { error: 'invalid_signature' }
+      }
+
+      // Sign responder's nonce
+      const signature = signHash(response.nonce, privKey)
+
+      return {
+        message: {
+          type: 'verify',
+          signature
+        },
+        peerPubkey: response.pubkey,
+        selectedVersion: response.selected_version
+      }
+    },
+
+    /**
+     * Verify the verify message (responder side — final step).
+     *
+     * @param {object} verify — The received verify message
+     * @param {string} ourNonce — The nonce we sent in challenge_response
+     * @param {string} peerPubkeyHex — The initiator's pubkey from hello
+     * @returns {{ success: true } | { error: string }}
+     */
+    handleVerify (verify, ourNonce, peerPubkeyHex) {
+      if (!verify || verify.type !== 'verify' || !verify.signature) {
+        return { error: 'invalid_verify' }
+      }
+
+      try {
+        const valid = verifyHash(ourNonce, verify.signature, peerPubkeyHex)
+        if (!valid) {
+          return { error: 'invalid_signature' }
+        }
+      } catch {
+        return { error: 'invalid_signature' }
+      }
+
+      return { success: true }
+    }
+  }
+}
+
+export { SUPPORTED_VERSIONS, HANDSHAKE_TIMEOUT_MS }

package/lib/header-relay.js

@@ -0,0 +1,184 @@
+import { EventEmitter } from 'node:events'
+
+/**
+ * HeaderRelay — syncs block headers between peers.
+ *
+ * Uses the PeerManager's message infrastructure to:
+ * - Announce our best header to new peers (triggered by hello handshake)
+ * - Request missing headers from peers that are ahead
+ * - Respond to header requests from peers that are behind
+ * - Re-announce to all peers after syncing new headers
+ *
+ * Message types:
+ *   header_announce — { type, height, hash }
+ *   header_request  — { type, fromHeight }
+ *   headers         — { type, headers: [{ height, hash, prevHash }] }
+ *
+ * Events:
+ *   'header:sync'   — { pubkeyHex, added, bestHeight }
+ *   'header:behind' — { pubkeyHex, theirHeight, ourHeight }
+ */
+export class HeaderRelay extends EventEmitter {
+  /**
+   * @param {import('./peer-manager.js').PeerManager} peerManager
+   * @param {object} [opts]
+   * @param {number} [opts.maxBatch=500] — Max headers per response
+   */
+  constructor (peerManager, opts = {}) {
+    super()
+    this.peerManager = peerManager
+    /** @type {Map<number, { height: number, hash: string, prevHash: string }>} */
+    this.headers = new Map()
+    this.bestHeight = -1
+    this.bestHash = null
+    this._maxBatch = opts.maxBatch || 500
+
+    this.peerManager.on('peer:message', ({ pubkeyHex, message }) => {
+      this._handleMessage(pubkeyHex, message)
+    })
+  }
+
+  /**
+   * Add a single header to the local store.
+   * @returns {boolean} true if added, false if duplicate or invalid
+   */
+  addHeader (header) {
+    if (this.headers.has(header.height)) return false
+
+    // Validate prevHash chain if we have the previous header
+    if (header.height > 0 && this.headers.has(header.height - 1)) {
+      const prev = this.headers.get(header.height - 1)
+      if (prev.hash !== header.prevHash) return false
+    }
+
+    this.headers.set(header.height, header)
+    if (header.height > this.bestHeight) {
+      this.bestHeight = header.height
+      this.bestHash = header.hash
+    }
+    return true
+  }
+
+  /**
+   * Add multiple headers (sorts by height first).
+   * @returns {number} count of headers added
+   */
+  addHeaders (headers) {
+    let added = 0
+    const sorted = [...headers].sort((a, b) => a.height - b.height)
+    for (const h of sorted) {
+      if (this.addHeader(h)) added++
+    }
+    return added
+  }
+
+  /** Get the best (highest) header, or null. */
+  getBestHeader () {
+    if (this.bestHeight < 0) return null
+    return this.headers.get(this.bestHeight)
+  }
+
+  /** Get header at a specific height, or null. */
+  getHeader (height) {
+    return this.headers.get(height) || null
+  }
+
+  /**
+   * Announce our best header to all connected peers.
+   * @returns {number} peers notified
+   */
+  announceToAll () {
+    return this.peerManager.broadcast({
+      type: 'header_announce',
+      height: this.bestHeight,
+      hash: this.bestHash
+    })
+  }
+
+  /** @private */
+  _announceToPeer (pubkeyHex) {
+    const conn = this.peerManager.peers.get(pubkeyHex)
+    if (conn) {
+      conn.send({
+        type: 'header_announce',
+        height: this.bestHeight,
+        hash: this.bestHash
+      })
+    }
+  }
+
+  /** @private */
+  _handleMessage (pubkeyHex, message) {
+    switch (message.type) {
+      case 'hello':
+        // Inbound peer completed handshake — announce our best header
+        this._announceToPeer(pubkeyHex)
+        break
+      case 'header_announce':
+        this._onHeaderAnnounce(pubkeyHex, message)
+        break
+      case 'header_request':
+        this._onHeaderRequest(pubkeyHex, message)
+        break
+      case 'headers':
+        this._onHeaders(pubkeyHex, message)
+        break
+    }
+  }
+
+  /** @private */
+  _onHeaderAnnounce (pubkeyHex, msg) {
+    if (msg.height > this.bestHeight) {
+      // We're behind — request missing headers
+      const conn = this.peerManager.peers.get(pubkeyHex)
+      if (conn) {
+        conn.send({
+          type: 'header_request',
+          fromHeight: this.bestHeight + 1
+        })
+      }
+      this.emit('header:behind', {
+        pubkeyHex,
+        theirHeight: msg.height,
+        ourHeight: this.bestHeight
+      })
+    } else if (msg.height < this.bestHeight) {
+      // We're ahead — announce back so they can sync from us
+      this._announceToPeer(pubkeyHex)
+    }
+  }
+
+  /** @private */
+  _onHeaderRequest (pubkeyHex, msg) {
+    const headers = []
+    for (let h = msg.fromHeight; h <= this.bestHeight && headers.length < this._maxBatch; h++) {
+      const header = this.headers.get(h)
+      if (header) headers.push(header)
+    }
+    if (headers.length > 0) {
+      const conn = this.peerManager.peers.get(pubkeyHex)
+      if (conn) {
+        conn.send({ type: 'headers', headers })
+      }
+    }
+  }
+
+  /** @private */
+  _onHeaders (pubkeyHex, msg) {
+    if (!Array.isArray(msg.headers)) return
+    const added = this.addHeaders(msg.headers)
+    if (added > 0) {
+      this.emit('header:sync', {
+        pubkeyHex,
+        added,
+        bestHeight: this.bestHeight
+      })
+      // Re-announce to all peers except the source
+      this.peerManager.broadcast({
+        type: 'header_announce',
+        height: this.bestHeight,
+        hash: this.bestHash
+      }, pubkeyHex)
+    }
+  }
+}

package/lib/peer-connection.js

@@ -0,0 +1,114 @@
+import WebSocket from 'ws'
+import { EventEmitter } from 'node:events'
+
+/**
+ * PeerConnection — wraps a WebSocket connection to a single peer.
+ *
+ * JSON message framing: all messages are JSON objects with a `type` field.
+ * Supports both outbound (we connect to them) and inbound (they connect to us).
+ *
+ * Events:
+ *   'message'  — { type, ...payload } parsed JSON message
+ *   'open'     — connection established
+ *   'close'    — connection closed
+ *   'error'    — connection error
+ */
+export class PeerConnection extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.endpoint - WSS endpoint of the peer
+   * @param {string} opts.pubkeyHex - Peer's compressed pubkey (hex)
+   * @param {WebSocket} [opts.socket] - Existing socket (for inbound connections)
+   */
+  constructor (opts) {
+    super()
+    this.endpoint = opts.endpoint
+    this.pubkeyHex = opts.pubkeyHex
+    this.ws = opts.socket || null
+    this.connected = false
+    this._reconnectTimer = null
+    this._reconnectDelay = 5000
+    this._maxReconnectDelay = 60000
+    this._shouldReconnect = !opts.socket // only auto-reconnect outbound
+    this._destroyed = false
+
+    if (opts.socket) {
+      this._attachListeners(opts.socket)
+      this.connected = opts.socket.readyState === WebSocket.OPEN
+    }
+  }
+
+  /** Connect to the peer (outbound only). */
+  connect () {
+    if (this._destroyed) return
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) return
+
+    try {
+      this.ws = new WebSocket(this.endpoint)
+      this._attachListeners(this.ws)
+    } catch (err) {
+      this.emit('error', err)
+      this._scheduleReconnect()
+    }
+  }
+
+  /** Send a JSON message to the peer. */
+  send (msg) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return false
+    }
+    this.ws.send(JSON.stringify(msg))
+    return true
+  }
+
+  /** Close the connection permanently (no reconnect). */
+  destroy () {
+    this._destroyed = true
+    this._shouldReconnect = false
+    clearTimeout(this._reconnectTimer)
+    if (this.ws) {
+      this.ws.close()
+      this.ws = null
+    }
+    this.connected = false
+  }
+
+  _attachListeners (ws) {
+    ws.on('open', () => {
+      this.connected = true
+      this._reconnectDelay = 5000 // reset backoff on success
+      this.emit('open')
+    })
+
+    ws.on('message', (data) => {
+      try {
+        const msg = JSON.parse(data.toString())
+        if (msg && typeof msg.type === 'string') {
+          this.emit('message', msg)
+        }
+      } catch (err) {
+        // Ignore non-JSON messages
+      }
+    })
+
+    ws.on('close', () => {
+      this.connected = false
+      this.emit('close')
+      this._scheduleReconnect()
+    })
+
+    ws.on('error', (err) => {
+      this.emit('error', err)
+    })
+  }
+
+  _scheduleReconnect () {
+    if (!this._shouldReconnect || this._destroyed) return
+    clearTimeout(this._reconnectTimer)
+    this._reconnectTimer = setTimeout(() => {
+      this.connect()
+    }, this._reconnectDelay)
+    // Exponential backoff, capped
+    this._reconnectDelay = Math.min(this._reconnectDelay * 2, this._maxReconnectDelay)
+  }
+}