@relay-federation/bridge 0.1.2 → 0.3.1

package/lib/actions.js

@@ -0,0 +1,373 @@
+/**
+ * Shared action logic for register, deregister, and fund.
+ * Used by both CLI (cli.js) and StatusServer (status-server.js).
+ *
+ * Each function accepts a pluggable logger: log(type, message, data?)
+ *   type: 'step' | 'done' | 'error'
+ */
+
+import { join } from 'node:path'
+
+/**
+ * Register this bridge on the relay mesh.
+ * Builds stake bond + registration tx, broadcasts via BSV P2P.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - Bridge config (wif, pubkeyHex, endpoint, meshId, capabilities, dataDir)
+ * @param {object} opts.store  - Open PersistentStore instance
+ * @param {function} opts.log  - Logger: (type, message, data?) => void
+ * @returns {object} { stakeTxid, registrationTxid }
+ */
+export async function runRegister ({ config, store, log }) {
+  log('step', `Pubkey:       ${config.pubkeyHex}`)
+  log('step', `Endpoint:     ${config.endpoint}`)
+  log('step', `Mesh:         ${config.meshId}`)
+  log('step', `Capabilities: ${config.capabilities.join(', ')}`)
+
+  const { buildRegistrationTx } = await import('../../registry/lib/registration.js')
+  const { BSVNodeClient } = await import('./bsv-node-client.js')
+
+  // Get UTXOs from local store
+  const localUtxos = await store.getUnspentUtxos()
+
+  if (!localUtxos.length) {
+    throw new Error('No UTXOs found. Fund your bridge first: relay-bridge fund <rawTxHex>')
+  }
+
+  // Map local UTXO format to what buildRegistrationTx expects
+  const utxos = []
+  for (const u of localUtxos) {
+    const rawHex = await store.getTx(u.txid)
+    if (!rawHex) {
+      log('step', `Warning: No source tx for UTXO ${u.txid}:${u.vout}, skipping`)
+      continue
+    }
+    utxos.push({ tx_hash: u.txid, tx_pos: u.vout, value: u.satoshis, rawHex })
+  }
+
+  if (!utxos.length) {
+    throw new Error('No usable UTXOs (missing source transactions).')
+  }
+
+  // Connect to BSV P2P node for broadcasting
+  log('step', 'Connecting to BSV network...')
+  const bsvNode = new BSVNodeClient()
+
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      bsvNode.disconnect()
+      reject(new Error('BSV node connection timeout (15s)'))
+    }, 15000)
+    bsvNode.on('handshake', () => { clearTimeout(timeout); resolve() })
+    bsvNode.on('error', (err) => { clearTimeout(timeout); reject(err) })
+    bsvNode.connect()
+  })
+
+  try {
+    // Step 1: Build and broadcast stake bond tx
+    const { buildStakeBondTx } = await import('../../registry/lib/stake-bond.js')
+    const { MIN_STAKE_SATS } = await import('@relay-federation/common/protocol')
+
+    log('step', `Building stake bond (${MIN_STAKE_SATS} sats)...`)
+    const stakeBond = await buildStakeBondTx({ wif: config.wif, utxos })
+
+    bsvNode.broadcastTx(stakeBond.txHex)
+    log('step', `Stake bond txid: ${stakeBond.txid}`)
+
+    // Brief wait for stake tx to propagate
+    await new Promise(r => setTimeout(r, 1000))
+
+    // Step 2: Build registration tx using real stake bond txid
+    const stakeTxid = new Uint8Array(Buffer.from(stakeBond.txid, 'hex'))
+
+    // Use the stake bond tx's change output (index 1) as funding for registration
+    const { Transaction } = await import('@bsv/sdk')
+    const stakeParsed = Transaction.fromHex(stakeBond.txHex)
+    const changeOutput = stakeParsed.outputs[1]
+    const regUtxos = []
+    if (changeOutput && changeOutput.satoshis > 0) {
+      regUtxos.push({
+        tx_hash: stakeBond.txid,
+        tx_pos: 1,
+        value: changeOutput.satoshis,
+        rawHex: stakeBond.txHex
+      })
+    }
+
+    if (!regUtxos.length) {
+      throw new Error('Stake bond consumed all funds. No UTXOs left for registration tx.')
+    }
+
+    const { txHex, txid } = await buildRegistrationTx({
+      wif: config.wif,
+      utxos: regUtxos,
+      endpoint: config.endpoint,
+      capabilities: config.capabilities,
+      versions: ['1.0'],
+      networkVersion: '1.0',
+      stakeTxid,
+      meshId: config.meshId
+    })
+
+    bsvNode.broadcastTx(txHex)
+    log('done', `Registration broadcast successful! txid: ${txid}`, { stakeTxid: stakeBond.txid, registrationTxid: txid })
+
+    // Brief wait for tx to propagate
+    await new Promise(r => setTimeout(r, 1000))
+
+    return { stakeTxid: stakeBond.txid, registrationTxid: txid }
+  } finally {
+    bsvNode.disconnect()
+  }
+}
+
+/**
+ * Deregister this bridge from the relay mesh.
+ * Builds deregistration tx, broadcasts via BSV P2P.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - Bridge config (wif, pubkeyHex)
+ * @param {object} opts.store  - Open PersistentStore instance
+ * @param {string} opts.reason - Deregistration reason (default: 'shutdown')
+ * @param {function} opts.log  - Logger
+ * @returns {object} { txid }
+ */
+export async function runDeregister ({ config, store, reason = 'shutdown', log }) {
+  log('step', `Pubkey: ${config.pubkeyHex}`)
+  log('step', `Reason: ${reason}`)
+
+  const { buildDeregistrationTx } = await import('../../registry/lib/registration.js')
+  const { BSVNodeClient } = await import('./bsv-node-client.js')
+
+  // Get UTXOs from local store
+  const localUtxos = await store.getUnspentUtxos()
+
+  if (!localUtxos.length) {
+    throw new Error('No UTXOs found. Fund your bridge first: relay-bridge fund <rawTxHex>')
+  }
+
+  // Map local UTXO format
+  const utxos = []
+  for (const u of localUtxos) {
+    const rawHex = await store.getTx(u.txid)
+    if (!rawHex) {
+      log('step', `Warning: No source tx for UTXO ${u.txid}:${u.vout}, skipping`)
+      continue
+    }
+    utxos.push({ tx_hash: u.txid, tx_pos: u.vout, value: u.satoshis, rawHex })
+  }
+
+  if (!utxos.length) {
+    throw new Error('No usable UTXOs (missing source transactions).')
+  }
+
+  // Build deregistration tx
+  const { txHex, txid } = await buildDeregistrationTx({
+    wif: config.wif,
+    utxos,
+    reason
+  })
+
+  // Broadcast via BSV P2P
+  log('step', 'Connecting to BSV network...')
+  const bsvNode = new BSVNodeClient()
+
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      bsvNode.disconnect()
+      reject(new Error('BSV node connection timeout (15s)'))
+    }, 15000)
+    bsvNode.on('handshake', () => { clearTimeout(timeout); resolve() })
+    bsvNode.on('error', (err) => { clearTimeout(timeout); reject(err) })
+    bsvNode.connect()
+  })
+
+  try {
+    bsvNode.broadcastTx(txHex)
+    log('done', `Deregistration broadcast successful! txid: ${txid}`, { txid })
+
+    await new Promise(r => setTimeout(r, 1000))
+    return { txid }
+  } finally {
+    bsvNode.disconnect()
+  }
+}
+
+/**
+ * Fund this bridge by storing a raw transaction's outputs.
+ * No BSV P2P needed — just parses the tx and stores matching UTXOs.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - Bridge config (pubkeyHex)
+ * @param {object} opts.store  - Open PersistentStore instance
+ * @param {string} opts.rawHex - Raw transaction hex
+ * @param {function} opts.log  - Logger
+ * @returns {object} { stored, balance }
+ */
+export async function runFund ({ config, store, rawHex, log }) {
+  const { pubkeyToHash160, checkTxForWatched } = await import('./output-parser.js')
+
+  const hash160 = pubkeyToHash160(config.pubkeyHex)
+  const result = checkTxForWatched(rawHex, new Set([hash160]))
+
+  if (result.matches.length === 0) {
+    throw new Error(`No outputs found paying to this bridge address. Bridge hash160: ${hash160}`)
+  }
+
+  log('step', `Found ${result.matches.length} output(s) for this bridge`)
+
+  for (const match of result.matches) {
+    await store.putUtxo({
+      txid: result.txid,
+      vout: match.vout,
+      satoshis: match.satoshis,
+      scriptHex: match.scriptHex,
+      address: config.pubkeyHex
+    })
+    log('step', `UTXO stored: ${result.txid}:${match.vout} (${match.satoshis} sat)`)
+  }
+
+  await store.putTx(result.txid, rawHex)
+  const balance = await store.getBalance()
+  log('done', `Total balance: ${balance} satoshis`, { stored: result.matches.length, balance })
+
+  return { stored: result.matches.length, balance }
+}
+
+/**
+ * Send BSV from this bridge's wallet to a destination address.
+ * Builds a P2PKH tx, broadcasts via BSV P2P.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - Bridge config (wif, pubkeyHex)
+ * @param {object} opts.store  - Open PersistentStore instance
+ * @param {string} opts.toAddress - Destination BSV address
+ * @param {number} opts.amount - Amount in satoshis to send
+ * @param {function} opts.log  - Logger
+ * @returns {object} { txid, sent, change }
+ */
+export async function runSend ({ config, store, toAddress, amount, log }) {
+  const { Transaction, P2PKH, PrivateKey, SatoshisPerKilobyte } = await import('@bsv/sdk')
+
+  if (!toAddress || typeof toAddress !== 'string') {
+    throw new Error('Destination address is required.')
+  }
+  if (!amount || amount < 546) {
+    throw new Error('Amount must be at least 546 satoshis (dust limit).')
+  }
+
+  // Get UTXOs from local store
+  const localUtxos = await store.getUnspentUtxos()
+  if (!localUtxos.length) {
+    throw new Error('No UTXOs available. Wallet is empty.')
+  }
+
+  // Map local UTXO format and gather enough to cover amount + fee
+  const utxos = []
+  let gathered = 0
+  for (const u of localUtxos) {
+    const rawHex = await store.getTx(u.txid)
+    if (!rawHex) continue
+    utxos.push({ tx_hash: u.txid, tx_pos: u.vout, value: u.satoshis, rawHex })
+    gathered += u.satoshis
+    if (gathered >= amount + 1000) break // rough fee estimate
+  }
+
+  if (gathered < amount + 546) {
+    throw new Error(`Insufficient funds. Have ${gathered} sats, need ${amount} + fee.`)
+  }
+
+  log('step', `Sending ${amount} sats to ${toAddress}`)
+
+  const privateKey = PrivateKey.fromWif(config.wif)
+  const selfAddress = privateKey.toPublicKey().toAddress()
+  const p2pkh = new P2PKH()
+  const selfLockingScript = p2pkh.lock(selfAddress)
+
+  const tx = new Transaction()
+
+  for (const utxo of utxos) {
+    const sourceTransaction = Transaction.fromHex(utxo.rawHex)
+    tx.addInput({
+      sourceTransaction,
+      sourceOutputIndex: utxo.tx_pos,
+      unlockingScriptTemplate: p2pkh.unlock(
+        privateKey,
+        'all',
+        false,
+        utxo.value,
+        selfLockingScript
+      )
+    })
+  }
+
+  // Output 0: payment to destination
+  tx.addOutput({
+    lockingScript: p2pkh.lock(toAddress),
+    satoshis: amount
+  })
+
+  // Output 1: change back to self
+  tx.addOutput({
+    lockingScript: p2pkh.lock(selfAddress),
+    change: true
+  })
+
+  await tx.fee(new SatoshisPerKilobyte(1000))
+  await tx.sign()
+
+  const txHex = tx.toHex()
+  const txid = tx.id('hex')
+
+  // Broadcast via BSV P2P
+  log('step', 'Connecting to BSV network...')
+  const { BSVNodeClient } = await import('./bsv-node-client.js')
+  const bsvNode = new BSVNodeClient()
+
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      bsvNode.disconnect()
+      reject(new Error('BSV node connection timeout (15s)'))
+    }, 15000)
+    bsvNode.on('handshake', () => { clearTimeout(timeout); resolve() })
+    bsvNode.on('error', (err) => { clearTimeout(timeout); reject(err) })
+    bsvNode.connect()
+  })
+
+  try {
+    bsvNode.broadcastTx(txHex)
+    log('step', `Broadcast txid: ${txid}`)
+
+    // Mark spent UTXOs in store
+    for (const utxo of utxos) {
+      await store.spendUtxo(utxo.tx_hash, utxo.tx_pos)
+    }
+
+    // Store the new tx and change UTXO
+    await store.putTx(txid, txHex)
+    const parsedTx = Transaction.fromHex(txHex)
+    const changeOutput = parsedTx.outputs[1]
+    if (changeOutput && changeOutput.satoshis > 0) {
+      const { pubkeyToHash160, checkTxForWatched } = await import('./output-parser.js')
+      const hash160 = pubkeyToHash160(config.pubkeyHex)
+      const result = checkTxForWatched(txHex, new Set([hash160]))
+      for (const match of result.matches) {
+        await store.putUtxo({
+          txid,
+          vout: match.vout,
+          satoshis: match.satoshis,
+          scriptHex: match.scriptHex,
+          address: config.pubkeyHex
+        })
+      }
+    }
+
+    await new Promise(r => setTimeout(r, 1000))
+    const balance = await store.getBalance()
+    log('done', `Sent ${amount} sats to ${toAddress}. Remaining balance: ${balance} sats`, { txid, sent: amount, balance })
+
+    return { txid, sent: amount, balance }
+  } finally {
+    bsvNode.disconnect()
+  }
+}

package/lib/address-scanner.js

@@ -0,0 +1,169 @@
+import { parseTx } from './output-parser.js'
+
+const WOC_BASE = 'https://api.whatsonchain.com/v1/bsv/main'
+const BATCH_SIZE = 5          // concurrent fetches per batch
+const BATCH_DELAY_MS = 400    // pause between batches (~12 req/s burst, ~5/400ms avg)
+const PROGRESS_INTERVAL = 10  // emit progress every N txs (or on inscription find)
+
+/**
+ * AddressScanner — fetches all txids for an address from WhatsOnChain,
+ * retrieves raw tx hex, parses each one, and indexes any inscriptions
+ * found into the persistent store.
+ *
+ * Uses batched parallel fetching for speed while respecting WoC rate limits.
+ * Emits progress callbacks so callers can stream status to clients.
+ */
+
+/**
+ * Scan an address for inscriptions.
+ * @param {string} address — BSV address to scan
+ * @param {import('./persistent-store.js').PersistentStore} store — persistent store instance
+ * @param {function} [onProgress] — called with { phase, current, total, txid, found } on each step
+ * @returns {Promise<{ address: string, txsScanned: number, inscriptionsFound: number, errors: number }>}
+ */
+export async function scanAddress (address, store, onProgress = () => {}) {
+  // Phase 1: Fetch tx history from WhatsOnChain
+  onProgress({ phase: 'discovery', current: 0, total: 0, message: 'Fetching transaction history...' })
+
+  const historyUrl = `${WOC_BASE}/address/${address}/history`
+  const histRes = await fetchWithRetry(historyUrl)
+  if (!histRes.ok) {
+    throw new Error(`WhatsOnChain returned ${histRes.status} for address history`)
+  }
+  const history = await histRes.json()
+
+  if (!Array.isArray(history) || history.length === 0) {
+    onProgress({ phase: 'done', current: 0, total: 0, message: 'No transactions found for this address' })
+    return { address, txsScanned: 0, inscriptionsFound: 0, errors: 0 }
+  }
+
+  const txids = history.map(h => h.tx_hash)
+  onProgress({ phase: 'scanning', current: 0, total: txids.length, message: `Found ${txids.length} transactions. Scanning...` })
+
+  // Phase 2: Check cache — split into cached vs uncached
+  const uncached = []
+  const cached = []
+  for (const txid of txids) {
+    const rawHex = await store.getTx(txid)
+    if (rawHex) {
+      cached.push({ txid, rawHex })
+    } else {
+      uncached.push(txid)
+    }
+  }
+
+  onProgress({
+    phase: 'scanning',
+    current: cached.length,
+    total: txids.length,
+    message: `${cached.length} cached, ${uncached.length} to fetch from network...`
+  })
+
+  let inscriptionsFound = 0
+  let errors = 0
+  let processed = 0
+
+  // Phase 3: Process cached txs instantly (no network, no delay)
+  for (const { txid, rawHex } of cached) {
+    const found = await parseTxAndIndex(txid, rawHex, store)
+    inscriptionsFound += found
+    processed++
+    if (found > 0 || processed % PROGRESS_INTERVAL === 0) {
+      onProgress({ phase: 'scanning', current: processed, total: txids.length, txid, found })
+    }
+  }
+
+  // Phase 4: Fetch uncached txs in parallel batches
+  for (let i = 0; i < uncached.length; i += BATCH_SIZE) {
+    const batch = uncached.slice(i, i + BATCH_SIZE)
+
+    // Fetch batch concurrently
+    const results = await Promise.allSettled(
+      batch.map(txid => fetchTxHex(txid))
+    )
+
+    // Process batch results
+    for (let j = 0; j < results.length; j++) {
+      const txid = batch[j]
+      const result = results[j]
+      processed++
+
+      if (result.status === 'rejected' || result.value === null) {
+        errors++
+        if (processed % PROGRESS_INTERVAL === 0) {
+          onProgress({ phase: 'scanning', current: processed, total: txids.length, txid, error: result.reason?.message || 'fetch failed' })
+        }
+        continue
+      }
+
+      const rawHex = result.value
+      await store.putTx(txid, rawHex)
+      const found = await parseTxAndIndex(txid, rawHex, store)
+      inscriptionsFound += found
+
+      if (found > 0 || processed % PROGRESS_INTERVAL === 0) {
+        onProgress({ phase: 'scanning', current: processed, total: txids.length, txid, found })
+      }
+    }
+
+    // Rate limit between batches (only if more batches remain)
+    if (i + BATCH_SIZE < uncached.length) {
+      await sleep(BATCH_DELAY_MS)
+    }
+  }
+
+  // Final progress
+  onProgress({
+    phase: 'done',
+    current: txids.length,
+    total: txids.length,
+    message: `Scan complete. ${inscriptionsFound} inscriptions found in ${txids.length} transactions (${cached.length} cached, ${uncached.length} fetched).`
+  })
+
+  return { address, txsScanned: txids.length, inscriptionsFound, errors }
+}
+
+/** Fetch raw tx hex from WhatsOnChain. Returns hex string or null on error. */
+async function fetchTxHex (txid) {
+  const res = await fetchWithRetry(`${WOC_BASE}/tx/${txid}/hex`)
+  if (!res.ok) return null
+  return res.text()
+}
+
+/** Parse a tx and index any inscriptions. Returns count of inscriptions found. */
+async function parseTxAndIndex (txid, rawHex, store) {
+  const parsed = parseTx(rawHex)
+  let count = 0
+  for (const output of parsed.outputs) {
+    if (output.type === 'ordinal' && output.parsed) {
+      await store.putInscription({
+        txid,
+        vout: output.vout,
+        contentType: output.parsed.contentType || null,
+        contentSize: output.parsed.content ? output.parsed.content.length / 2 : 0,
+        content: output.parsed.content || null,
+        isBsv20: output.parsed.isBsv20 || false,
+        bsv20: output.parsed.bsv20 || null,
+        timestamp: Date.now(),
+        address: output.hash160 || null
+      })
+      count++
+    }
+  }
+  return count
+}
+
+function sleep (ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function fetchWithRetry (url, maxAttempts = 3) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const res = await fetch(url)
+    if (res.status === 429 && attempt < maxAttempts) {
+      await sleep(1000 * Math.pow(2, attempt - 1))
+      continue
+    }
+    return res
+  }
+}

package/lib/address-watcher.js

@@ -0,0 +1,161 @@
+import { EventEmitter } from 'node:events'
+import { checkTxForWatched, pubkeyToHash160 } from './output-parser.js'
+
+/**
+ * AddressWatcher — monitors transactions for outputs to watched addresses.
+ *
+ * Listens to TxRelay's 'tx:new' events, parses each transaction, and
+ * checks outputs against a set of watched hash160s. When a match is
+ * found, it:
+ *   1. Stores the UTXO in PersistentStore
+ *   2. Checks inputs for spent UTXOs and marks them
+ *   3. Records the watched-address match
+ *   4. Emits events for upstream consumers
+ *
+ * This replaces the HTTP-based address queries (fetchUtxos,
+ * fetchAddressHistory) with pure local P2P-based tracking.
+ *
+ * Events:
+ *   'utxo:received'  — { txid, vout, satoshis, address, hash160 }
+ *   'utxo:spent'     — { txid, vout, spentByTxid }
+ *   'tx:watched'     — { txid, address, direction, matches }
+ */
+export class AddressWatcher extends EventEmitter {
+  /**
+   * @param {import('./tx-relay.js').TxRelay} txRelay
+   * @param {import('./persistent-store.js').PersistentStore} store
+   */
+  constructor (txRelay, store) {
+    super()
+    this.txRelay = txRelay
+    this.store = store
+    /** @type {Map<string, string>} hash160 → address (human-readable) */
+    this._watched = new Map()
+    /** @type {Set<string>} hash160s for fast lookup */
+    this._hash160Set = new Set()
+
+    this.txRelay.on('tx:new', ({ txid, rawHex }) => {
+      this._processTx(txid, rawHex).catch(err => {
+        this.emit('error', err)
+      })
+    })
+  }
+
+  /**
+   * Watch an address by its compressed public key hex.
+   * @param {string} pubkeyHex — 33-byte compressed public key
+   * @param {string} [label] — optional human-readable label
+   */
+  watchPubkey (pubkeyHex, label) {
+    const hash160 = pubkeyToHash160(pubkeyHex)
+    this._watched.set(hash160, label || pubkeyHex)
+    this._hash160Set.add(hash160)
+  }
+
+  /**
+   * Watch an address by its hash160 directly.
+   * @param {string} hash160 — 20-byte hash160 as hex
+   * @param {string} [label] — optional human-readable label
+   */
+  watchHash160 (hash160, label) {
+    this._watched.set(hash160, label || hash160)
+    this._hash160Set.add(hash160)
+  }
+
+  /**
+   * Stop watching an address.
+   * @param {string} hash160
+   */
+  unwatch (hash160) {
+    this._watched.delete(hash160)
+    this._hash160Set.delete(hash160)
+  }
+
+  /**
+   * Get all watched hash160s.
+   * @returns {Array<{ hash160: string, label: string }>}
+   */
+  getWatched () {
+    const result = []
+    for (const [hash160, label] of this._watched) {
+      result.push({ hash160, label })
+    }
+    return result
+  }
+
+  /**
+   * Manually process a raw transaction (e.g., from fund command).
+   * @param {string} rawHex
+   */
+  async processTxManual (rawHex) {
+    const { checkTxForWatched: check } = await import('./output-parser.js')
+    const result = check(rawHex, this._hash160Set)
+    await this._handleResult(result, rawHex)
+  }
+
+  /** @private */
+  async _processTx (txid, rawHex) {
+    if (this._hash160Set.size === 0) return
+
+    const result = checkTxForWatched(rawHex, this._hash160Set)
+    await this._handleResult(result, rawHex)
+  }
+
+  /** @private */
+  async _handleResult (result, rawHex) {
+    // Check inputs — are any of our UTXOs being spent?
+    for (const spend of result.spends) {
+      const utxoKey = `${spend.prevTxid}:${spend.prevVout}`
+      // Check if this input spends one of our tracked UTXOs
+      const existing = await this.store._utxos.get(utxoKey)
+      if (existing !== undefined && !existing.spent) {
+        await this.store.spendUtxo(spend.prevTxid, spend.prevVout)
+        this.emit('utxo:spent', {
+          txid: spend.prevTxid,
+          vout: spend.prevVout,
+          spentByTxid: result.txid
+        })
+      }
+    }
+
+    // Check outputs — any paying to our watched addresses?
+    if (result.matches.length > 0) {
+      // Store the raw tx for future reference
+      await this.store.putTx(result.txid, rawHex)
+
+      for (const match of result.matches) {
+        const address = this._watched.get(match.hash160) || match.hash160
+
+        // Store as UTXO
+        await this.store.putUtxo({
+          txid: result.txid,
+          vout: match.vout,
+          satoshis: match.satoshis,
+          scriptHex: match.scriptHex,
+          address
+        })
+
+        // Record watched-address match
+        await this.store.putWatchedTx({
+          txid: result.txid,
+          address,
+          direction: 'in',
+          timestamp: Date.now()
+        })
+
+        this.emit('utxo:received', {
+          txid: result.txid,
+          vout: match.vout,
+          satoshis: match.satoshis,
+          address,
+          hash160: match.hash160
+        })
+      }
+
+      this.emit('tx:watched', {
+        txid: result.txid,
+        matches: result.matches.length
+      })
+    }
+  }
+}