feat(mempool): add watched-only mempool tracker

Subscribe to peers, fetch announced txs, and track unconfirmed UTXOs and
spends for watched addresses. Surface them via /v1/utxos (height 0),
/v1/utxo spend overlay, /v1/tx, and /v1/status. Toggle with
MEMPOOL_ENABLED (default true). Bumps the neutrino fork to 0d5f911.

Author: m0wer

CHANGELOG.md

@@ -9,6 +9,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Watched-only mempool tracker (`MEMPOOL_ENABLED`).** The daemon now
+  subscribes to every connected peer's incoming P2P messages, fetches each
+  announced transaction, and records the ones that pay or spend a watched
+  address. Unconfirmed UTXOs are surfaced in the existing `/v1/utxos`
+  endpoint with `height: 0`, unconfirmed spends are overlaid on
+  `/v1/utxo/{txid}/{vout}` via new `mempool_*` fields, and watched mempool
+  txs can be fetched verbatim from a new `/v1/tx/{txid}` endpoint. Tracker
+  state is in-memory only; after each successful rescan pass it evicts
+  precisely the entries that just confirmed on-chain (rather than wiping
+  the whole view, which would drop still-unconfirmed entries because
+  mempool peers do not reliably re-announce already-acked txs). A 14-day
+  TTL sweeps stale entries; RBF replacements automatically evict the
+  prior entry.
+  - New config: `MEMPOOL_ENABLED` / `--mempool` (default: `true`) toggles
+    the tracker.
+  - New request flag: `include_mempool` on `/v1/utxos` (request body) and
+    on `/v1/utxo/{txid}/{vout}` (query string), default `true`. Set to
+    `false` to receive only the chain-only view.
+  - `/v1/status` gains `mempool_enabled` and (when enabled) a `mempool`
+    object reporting tracker counts (`entries`, `utxos`, `spends`,
+    `peers`).
+  - Privacy model: the daemon asks every peer for every announced tx
+    rather than only those matching a local heuristic, so peers cannot
+    learn which addresses the operator cares about. The bandwidth cost
+    is small because we only fetch the tx body once per inv (deduped by
+    txid across peers) and discard txs that don't touch a watched
+    script. Backed by a fork patch on `lightninglabs/neutrino` that
+    stops dropping `MSG_TX` advertisements when the local node hasn't
+    asked the peer to relay txs.
 - Add a production-ready `systemd` service example in README for running the
   `neutrinod` binary directly on Linux hosts (including Raspberry Pi), with a
   signet-oriented configuration example.
@@ -24,6 +53,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `windows-amd64` outputs.
 - README now documents a signet Docker run example using
   `LISTEN_ADDR=0.0.0.0:38334` and host port mapping `38334:38334`.
+- Bump the `lightninglabs/neutrino` fork to
+  `0d5f911` (`m0wer/neutrino`), which gates the relaxed `MSG_TX`
+  relay behaviour behind the new `Config.MempoolEnabled` flag instead
+  of unconditionally enabling it.
 
 ## [1.2.0] - 2026-04-30
 

README.md

@@ -112,6 +112,7 @@ Anyone can reproduce and verify a release locally with one command:
 | `CFILTER_CDN_URL` | | Override block-dn base URL for compact filter CDN downloads |
 | `AUTO_SYNC_WATCHED` | `true` | Continuously scan new blocks for watched addresses in the background, keeping the UTXO set up-to-date so `/v1/utxos` is instant. Reacts to block-connected notifications from the chain service in real time |
 | `AUTO_SYNC_INTERVAL_SEC` | `30` | Fallback poll interval (in seconds) used while waiting for initial header sync, and as a safety net if block-notification subscription is unavailable. Only used when `AUTO_SYNC_WATCHED=true` |
+| `MEMPOOL_ENABLED` | `true` | Enable the watched-only mempool tracker. The daemon subscribes to every connected peer's incoming `inv` messages, fetches each announced tx, and records the ones that pay or spend a watched address. Unconfirmed UTXOs are surfaced in `/v1/utxos` (with `height: 0`) and unconfirmed spends are overlaid on `/v1/utxo/{txid}/{vout}`. Disable with `MEMPOOL_ENABLED=false` to keep the chain-only behaviour |
 | `MAX_PEERS` | `8` | Maximum number of peers to connect to |
 | `NO_AUTH` | `false` | Disable TLS and token authentication (for development/regtest) |
 
@@ -128,6 +129,7 @@ Anyone can reproduce and verify a release locally with one command:
   --clearnet-initial-sync=true \
   --cfilter-cdn-auto=true \
   --maxpeers=8 \
+  --mempool=true \
   --no-auth        # Disable TLS + auth (dev/regtest only)
   # --reset-auth   # Regenerate TLS cert and auth token, then exit
 ```
@@ -238,10 +240,19 @@ Response:
   "synced": true,
   "block_height": 820000,
   "filter_height": 820000,
-  "peers": 8
+  "peers": 8,
+  "mempool_enabled": true,
+  "mempool": {
+    "entries": 4,
+    "utxos": 3,
+    "spends": 1,
+    "peers": 8
+  }
 }
 ```
 
+The `mempool` object is omitted when `MEMPOOL_ENABLED=false`. `entries` counts watched mempool txs, `utxos` counts unconfirmed outputs paying watched addresses, `spends` counts unconfirmed spends of watched outpoints, and `peers` reflects how many connected peers the tracker is subscribed to.
+
 ### Block Header
 
 Get block header by height:
@@ -305,10 +316,15 @@ curl -X POST http://localhost:8334/v1/rescan \
     "addresses": ["12cbQLTFMXRnSzktFkuoG3eHoMeFtpTu3S"]
   }'
 
-# Then query UTXOs
+# Then query UTXOs (mempool entries are included by default)
 curl -X POST http://localhost:8334/v1/utxos \
   -H "Content-Type: application/json" \
   -d '{"addresses": ["12cbQLTFMXRnSzktFkuoG3eHoMeFtpTu3S"]}'
+
+# Suppress unconfirmed mempool entries
+curl -X POST http://localhost:8334/v1/utxos \
+  -H "Content-Type: application/json" \
+  -d '{"addresses": ["12cbQLTFMXRnSzktFkuoG3eHoMeFtpTu3S"], "include_mempool": false}'
 ```
 
 > **Note:** When `AUTO_SYNC_WATCHED=true` (the default), the daemon
@@ -318,6 +334,13 @@ curl -X POST http://localhost:8334/v1/utxos \
 > without requiring another `/v1/rescan` — the daemon stays caught up
 > in real time and also re-syncs on every restart.
 
+> **Mempool:** When `MEMPOOL_ENABLED=true` (the default), unconfirmed
+> outputs paying a watched address are returned in the same `utxos`
+> array with `height: 0`. Set `include_mempool: false` in the request
+> body to opt out and receive only confirmed UTXOs. If the same outpoint
+> appears in both sets (e.g., the mempool tracker has not yet evicted a
+> just-confirmed tx), the confirmed entry wins.
+
 Response:
 ```json
 {
@@ -329,6 +352,14 @@ Response:
       "address": "12cbQLTFMXRnSzktFkuoG3eHoMeFtpTu3S",
       "scriptpubkey": "410411db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a6909a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f656b412a3ac",
       "height": 9
+    },
+    {
+      "txid": "ea44e97271691990157559d0bdd9959e02790c34db6c006d779e82fa5aee708e",
+      "vout": 1,
+      "value": 12345,
+      "address": "12cbQLTFMXRnSzktFkuoG3eHoMeFtpTu3S",
+      "scriptpubkey": "76a914...",
+      "height": 0
     }
   ]
 }
@@ -364,12 +395,50 @@ Response for spent UTXO:
 }
 ```
 
+Response for an on-chain unspent UTXO that has an unconfirmed spend in the
+mempool (when `MEMPOOL_ENABLED=true`, default):
+```json
+{
+  "unspent": true,
+  "value": 11516,
+  "scriptpubkey": "001481f291ca5498ec941b014fff4719201ba68939d5",
+  "mempool_spending_txid": "ccccdddd...",
+  "mempool_spending_input": 0,
+  "mempool_spend_first_seen": 1714501234
+}
+```
+
+Append `?include_mempool=false` to suppress the mempool overlay and receive
+only the on-chain status. A confirmed spend always takes precedence over
+any tracked mempool spend.
+
 **Important Notes**:
 - The `address` parameter is **required**. Compact block filters (BIP158) work by matching on scripts, not transaction IDs. Without the address, filter matching cannot work correctly.
 - Specifying a `start_height` parameter is **highly recommended** for performance. Set it to the block height where the UTXO was created (or slightly before). Without it, the scan could take a very long time as it scans from the provided height to the current chain tip.
 - The `start_height` means "start scanning FROM this height going FORWARD to the chain tip", not backwards.
 - Performance scales with the scan range: scanning 1 block takes ~0.01s, scanning 100 blocks takes ~0.5s, scanning 10,000+ blocks can take minutes.
 
+### Get Transaction (mempool only)
+
+Fetch a serialized transaction by txid. With `MEMPOOL_ENABLED=true` (default)
+the daemon returns the watched mempool tx if it has been observed; for any
+other txid it responds with `501 Not Implemented` because compact block
+filters do not allow looking up arbitrary historical transactions without a
+full block download.
+
+```bash
+curl http://localhost:8334/v1/tx/<txid>
+```
+
+Response when the tx is in the watched mempool:
+```json
+{
+  "txid": "ccccdddd...",
+  "hex": "0200000001...",
+  "mempool": true
+}
+```
+
 ### Rescan
 
 Trigger a blockchain rescan from a specific height:

neutrino_server/cmd/neutrinod/main.go

@@ -46,6 +46,7 @@ func main() {
 	cfilterCDNURL := flag.String("cfilter-cdn-url", getEnv("CFILTER_CDN_URL", ""), "Override block-dn base URL for compact filter CDN downloads")
 	autoSyncWatched := flag.Bool("auto-sync-watched", getEnvBool("AUTO_SYNC_WATCHED", true), "Continuously scan new blocks for watched addresses in the background, keeping the UTXO set up-to-date so /v1/utxos is instant")
 	autoSyncIntervalSec := flag.Int("auto-sync-interval", getEnvInt("AUTO_SYNC_INTERVAL_SEC", 30), "Seconds between auto-sync polling passes for new blocks (only used when --auto-sync-watched is enabled)")
+	mempoolEnabled := flag.Bool("mempool", getEnvBool("MEMPOOL_ENABLED", true), "Enable watched-only mempool tracking: relay tx invs from peers and track unconfirmed transactions matching watched addresses")
 	noAuth := flag.Bool("no-auth", getEnvBool("NO_AUTH", false), "Disable TLS and token authentication (for development/regtest)")
 	resetAuth := flag.Bool("reset-auth", false, "Regenerate TLS cert and auth token, clear watched addresses, then exit")
 	showVersion := flag.Bool("version", false, "Show version and exit")
@@ -131,6 +132,7 @@ func main() {
 		CFilterCDNURL:       *cfilterCDNURL,
 		AutoSyncWatched:     *autoSyncWatched,
 		AutoSyncInterval:    time.Duration(*autoSyncIntervalSec) * time.Second,
+		MempoolEnabled:      *mempoolEnabled,
 		Logger:              backend,
 		LogLevel:            *logLevel,
 	}

neutrino_server/go.mod

@@ -14,7 +14,7 @@ require (
 	golang.org/x/net v0.48.0
 )
 
-replace github.com/lightninglabs/neutrino => github.com/m0wer/neutrino v0.0.0-20260409110914-c1b598b97446
+replace github.com/lightninglabs/neutrino => github.com/m0wer/neutrino v0.0.0-20260522161657-0d5f911e647c
 
 require (
 	github.com/aead/siphash v1.0.1 // indirect

neutrino_server/go.sum

@@ -91,8 +91,8 @@ github.com/lightningnetwork/lnd/queue v1.0.1 h1:jzJKcTy3Nj5lQrooJ3aaw9Lau3I0IwvQ
 github.com/lightningnetwork/lnd/queue v1.0.1/go.mod h1:vaQwexir73flPW43Mrm7JOgJHmcEFBWWSl9HlyASoms=
 github.com/lightningnetwork/lnd/ticker v1.0.0 h1:S1b60TEGoTtCe2A0yeB+ecoj/kkS4qpwh6l+AkQEZwU=
 github.com/lightningnetwork/lnd/ticker v1.0.0/go.mod h1:iaLXJiVgI1sPANIF2qYYUJXjoksPNvGNYowB8aRbpX0=
-github.com/m0wer/neutrino v0.0.0-20260409110914-c1b598b97446 h1:c6MpEEzMXuQaIZw+GkvrqcyQG5QceDEUEKBBkA9xU5A=
-github.com/m0wer/neutrino v0.0.0-20260409110914-c1b598b97446/go.mod h1:fNjnbuSPw4lRsVAzvjC1JG7IE7rqae/mbek2tNkN/Dw=
+github.com/m0wer/neutrino v0.0.0-20260522161657-0d5f911e647c h1:DEv0lannTrzm70LLj/svu0EgBlb2JN359QB9wMs/ayI=
+github.com/m0wer/neutrino v0.0.0-20260522161657-0d5f911e647c/go.mod h1:tcwCgRTGWcaua0L/xzdwllW8eslHDbux4XkiYsivvHE=
 github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
 github.com/onsi/ginkgo v1.7.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=

neutrino_server/internal/api/handler.go

@@ -32,6 +32,12 @@ type NodeInterface interface {
 	Rescan(startHeight int32, addresses []string) error
 	IsRescanInProgress() bool
 	RescanStatus() neutrino.RescanStatus
+
+	// Mempool — return zero values when the tracker is disabled.
+	GetMempoolUTXOs(addresses []string) []neutrino.MempoolUTXO
+	GetMempoolSpend(txid string, vout uint32) (neutrino.MempoolSpend, bool)
+	GetMempoolTx(txid string) (*wire.MsgTx, bool)
+	MempoolStats() neutrino.MempoolStats
 }
 
 // Handler provides REST API endpoints for the neutrino node.
@@ -210,10 +216,25 @@ func (h *Handler) handleGetTransaction(w http.ResponseWriter, r *http.Request) {
 	vars := mux.Vars(r)
 	txid := vars["txid"]
 
-	// Neutrino doesn't store full transactions by default
-	// This would require fetching from a peer or having received it
+	// Mempool tracker holds the full tx for every watched unconfirmed
+	// entry; serve those without needing a block download.
+	if tx, ok := h.node.GetMempoolTx(txid); ok {
+		var buf bytes.Buffer
+		if err := tx.Serialize(&buf); err != nil {
+			h.errorResponse(w, http.StatusInternalServerError, "failed to serialize transaction")
+			return
+		}
+		h.jsonResponse(w, map[string]any{
+			"txid":    txid,
+			"hex":     hex.EncodeToString(buf.Bytes()),
+			"mempool": true,
+		})
+		return
+	}
+
+	// Confirmed-tx lookup is unimplemented — neutrino doesn't store full
+	// blocks/txs by default.
 	h.errorResponse(w, http.StatusNotImplemented, "transaction lookup requires full block download")
-	_ = txid
 }
 
 // Broadcast transaction endpoint
@@ -255,7 +276,8 @@ func (h *Handler) handleBroadcastTransaction(w http.ResponseWriter, r *http.Requ
 // UTXOs endpoint
 func (h *Handler) handleGetUTXOs(w http.ResponseWriter, r *http.Request) {
 	var req struct {
-		Addresses []string `json:"addresses"`
+		Addresses      []string `json:"addresses"`
+		IncludeMempool *bool    `json:"include_mempool,omitempty"`
 	}
 
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
@@ -269,11 +291,47 @@ func (h *Handler) handleGetUTXOs(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// include_mempool defaults to true; clients opt out by sending false.
+	includeMempool := true
+	if req.IncludeMempool != nil {
+		includeMempool = *req.IncludeMempool
+	}
+
+	if includeMempool {
+		mempoolUTXOs := h.node.GetMempoolUTXOs(req.Addresses)
+		// Drop confirmed UTXOs that the mempool tracker hasn't yet
+		// evicted post-confirmation: a (txid,vout) appearing in both
+		// sets is the confirmed copy. Keying on "txid:vout" preserves
+		// the confirmed entry (Height>=1) over the mempool sentinel.
+		seen := make(map[string]struct{}, len(utxos))
+		for _, u := range utxos {
+			seen[utxoKey(u.TxID, u.Vout)] = struct{}{}
+		}
+		for _, mu := range mempoolUTXOs {
+			if _, ok := seen[utxoKey(mu.TxID, mu.Vout)]; ok {
+				continue
+			}
+			utxos = append(utxos, neutrino.UTXO{
+				TxID:         mu.TxID,
+				Vout:         mu.Vout,
+				Value:        mu.Value,
+				Address:      mu.Address,
+				ScriptPubKey: mu.ScriptPubKey,
+				Height:       0, // mempool sentinel
+			})
+		}
+	}
+
 	h.jsonResponse(w, map[string]any{
 		"utxos": utxos,
 	})
 }
 
+// utxoKey builds the dedup key used when merging confirmed and mempool UTXOs.
+func utxoKey(txid string, vout uint32) string {
+	return txid + ":" + strconv.FormatUint(uint64(vout), 10)
+}
+
 // UTXO lookup endpoint
 func (h *Handler) handleGetUTXO(w http.ResponseWriter, r *http.Request) {
 	vars := mux.Vars(r)
@@ -317,6 +375,32 @@ func (h *Handler) handleGetUTXO(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// include_mempool defaults to true; clients opt out with ?include_mempool=false.
+	includeMempool := true
+	if v := r.URL.Query().Get("include_mempool"); v != "" {
+		if parsed, perr := strconv.ParseBool(v); perr == nil {
+			includeMempool = parsed
+		}
+	}
+
+	// If the UTXO is reported unspent on-chain but a mempool spend exists,
+	// surface it via dedicated mempool fields without overwriting confirmed
+	// state. Confirmed-spend wins over mempool-spend.
+	if includeMempool && report.Unspent {
+		if spend, ok := h.node.GetMempoolSpend(txid, uint32(vout)); ok {
+			h.jsonResponse(w, map[string]any{
+				"unspent":                  report.Unspent,
+				"value":                    report.Value,
+				"scriptpubkey":             report.ScriptPubKey,
+				"block_height":             report.BlockHeight,
+				"mempool_spending_txid":    spend.SpendingTxID,
+				"mempool_spending_input":   spend.InputIndex,
+				"mempool_spend_first_seen": spend.FirstSeen,
+			})
+			return
+		}
+	}
+
 	h.jsonResponse(w, report)
 }