feat(api): expose version and watched-address diagnostics

Add /v1/version, include version and watched_addresses in /v1/status,
include watched_addresses and server_version in /v1/rescan/status, and
attach X-Neutrino-Version response headers for easier client diagnostics.

Changelog: Expose server version and watched-address diagnostics via API metadata endpoints and headers.

Author: m0wer

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `GET /v1/version` endpoint returning `{"version": "..."}` for lightweight version diagnostics.
+- Include `version` and `watched_addresses` fields in `GET /v1/status` responses.
+- Include `watched_addresses` and `server_version` in `GET /v1/rescan/status` responses.
+- Add `X-Neutrino-Version` response header on JSON API responses.
+
 ## [0.10.0] - 2026-04-06
 
 ### Added

neutrino_server/cmd/neutrinod/main.go

@@ -77,6 +77,7 @@ func main() {
 		DataDir:             *dataDir,
 		TorProxy:            *torProxy,
 		AddPeers:            *addPeers,
+		Version:             version,
 		MaxPeers:            8,
 		FilterCacheSize:     100 * 1024 * 1024,
 		PrefetchFilters:     *prefetchFilters,
@@ -103,7 +104,7 @@ func main() {
 	// Create API handler
 	apiLogger := backend.Logger("API")
 	apiLogger.SetLevel(level)
-	handler := api.NewHandler(node, apiLogger)
+	handler := api.NewHandler(node, apiLogger, version)
 
 	// Set up router
 	router := mux.NewRouter()

neutrino_server/internal/api/handler.go

@@ -36,15 +36,22 @@ type NodeInterface interface {
 
 // Handler provides REST API endpoints for the neutrino node.
 type Handler struct {
-	node   NodeInterface
-	logger btclog.Logger
+	node    NodeInterface
+	logger  btclog.Logger
+	version string
 }
 
 // NewHandler creates a new API handler.
-func NewHandler(node NodeInterface, logger btclog.Logger) *Handler {
+func NewHandler(node NodeInterface, logger btclog.Logger, version ...string) *Handler {
+	resolvedVersion := ""
+	if len(version) > 0 {
+		resolvedVersion = version[0]
+	}
+
 	return &Handler{
-		node:   node,
-		logger: logger,
+		node:    node,
+		logger:  logger,
+		version: resolvedVersion,
 	}
 }
 
@@ -55,6 +62,7 @@ func (h *Handler) RegisterRoutes(r *mux.Router) {
 
 	// Status
 	r.HandleFunc("/v1/status", h.handleGetStatus).Methods("GET")
+	r.HandleFunc("/v1/version", h.handleGetVersion).Methods("GET")
 
 	// Block queries
 	r.HandleFunc("/v1/block/{height}/header", h.handleGetBlockHeader).Methods("GET")
@@ -112,9 +120,21 @@ func (h *Handler) loggingMiddleware(next http.Handler) http.Handler {
 
 func (h *Handler) jsonResponse(w http.ResponseWriter, data any) {
 	w.Header().Set("Content-Type", "application/json")
+	if version := h.effectiveVersion(); version != "" {
+		w.Header().Set("X-Neutrino-Version", version)
+	}
 	json.NewEncoder(w).Encode(data)
 }
 
+func (h *Handler) effectiveVersion() string {
+	if h.version != "" {
+		return h.version
+	}
+
+	status := h.node.GetStatus()
+	return status.Version
+}
+
 func (h *Handler) errorResponse(w http.ResponseWriter, code int, message string) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(code)
@@ -124,9 +144,17 @@ func (h *Handler) errorResponse(w http.ResponseWriter, code int, message string)
 // Status endpoint
 func (h *Handler) handleGetStatus(w http.ResponseWriter, r *http.Request) {
 	status := h.node.GetStatus()
+	if status.Version == "" {
+		status.Version = h.effectiveVersion()
+	}
 	h.jsonResponse(w, status)
 }
 
+// Version endpoint.
+func (h *Handler) handleGetVersion(w http.ResponseWriter, r *http.Request) {
+	h.jsonResponse(w, map[string]any{"version": h.effectiveVersion()})
+}
+
 // Block header endpoint
 func (h *Handler) handleGetBlockHeader(w http.ResponseWriter, r *http.Request) {
 	vars := mux.Vars(r)
@@ -365,6 +393,7 @@ func (h *Handler) handleRescan(w http.ResponseWriter, r *http.Request) {
 
 // Rescan status endpoint
 func (h *Handler) handleGetRescanStatus(w http.ResponseWriter, r *http.Request) {
+	nodeStatus := h.node.GetStatus()
 	status := h.node.RescanStatus()
 	h.jsonResponse(w, map[string]any{
 		"in_progress":       status.InProgress,
@@ -373,6 +402,8 @@ func (h *Handler) handleGetRescanStatus(w http.ResponseWriter, r *http.Request)
 		"last_start_height": status.LastStartHeight,
 		"last_scanned_tip":  status.LastScannedTip,
 		"last_error":        status.LastError,
+		"watched_addresses": nodeStatus.WatchedAddresses,
+		"server_version":    h.effectiveVersion(),
 	})
 }
 

neutrino_server/internal/api/handler_test.go

@@ -21,10 +21,12 @@ type mockNode struct{}
 
 func (m *mockNode) GetStatus() neutrino.Status {
 	return neutrino.Status{
-		Synced:       true,
-		BlockHeight:  8543,
-		FilterHeight: 8543,
-		Peers:        1,
+		Synced:           true,
+		BlockHeight:      8543,
+		FilterHeight:     8543,
+		Peers:            1,
+		Version:          testVersion,
+		WatchedAddresses: 3,
 	}
 }
 
@@ -78,11 +80,13 @@ func (m *mockNode) RescanStatus() neutrino.RescanStatus {
 	return neutrino.RescanStatus{}
 }
 
+const testVersion = "v0.10.1-test"
+
 func TestHandleGetStatus(t *testing.T) {
 	backend := btclog.NewBackend(os.Stdout)
 	logger := backend.Logger("TEST")
 
-	handler := NewHandler(&mockNode{}, logger)
+	handler := NewHandler(&mockNode{}, logger, testVersion)
 
 	router := mux.NewRouter()
 	router.HandleFunc("/v1/status", handler.handleGetStatus).Methods("GET")
@@ -119,6 +123,53 @@ func TestHandleGetStatus(t *testing.T) {
 	if response.Peers != 1 {
 		t.Errorf("expected peers=1, got %v", response.Peers)
 	}
+
+	if response.Version != testVersion {
+		t.Errorf("expected version=%s, got %v", testVersion, response.Version)
+	}
+
+	if response.WatchedAddresses != 3 {
+		t.Errorf("expected watched_addresses=3, got %v", response.WatchedAddresses)
+	}
+
+	if got := rr.Header().Get("X-Neutrino-Version"); got != testVersion {
+		t.Errorf("expected X-Neutrino-Version=%s, got %v", testVersion, got)
+	}
+}
+
+func TestHandleGetVersion(t *testing.T) {
+	backend := btclog.NewBackend(os.Stdout)
+	logger := backend.Logger("TEST")
+
+	handler := NewHandler(&mockNode{}, logger, testVersion)
+
+	router := mux.NewRouter()
+	router.HandleFunc("/v1/version", handler.handleGetVersion).Methods("GET")
+
+	req, err := http.NewRequest("GET", "/v1/version", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	if status := rr.Code; status != http.StatusOK {
+		t.Errorf("handler returned wrong status code: got %v want %v", status, http.StatusOK)
+	}
+
+	var response map[string]any
+	if err := json.Unmarshal(rr.Body.Bytes(), &response); err != nil {
+		t.Fatalf("could not decode response: %v", err)
+	}
+
+	if response["version"] != testVersion {
+		t.Errorf("expected version=%s, got %v", testVersion, response["version"])
+	}
+
+	if got := rr.Header().Get("X-Neutrino-Version"); got != testVersion {
+		t.Errorf("expected X-Neutrino-Version=%s, got %v", testVersion, got)
+	}
 }
 
 func TestHandleBroadcastTransaction_InvalidJSON(t *testing.T) {
@@ -584,6 +635,12 @@ func TestHandleGetRescanStatus_NotInProgress(t *testing.T) {
 	if _, ok := response["last_scanned_tip"]; !ok {
 		t.Error("expected last_scanned_tip in response")
 	}
+	if watched, ok := response["watched_addresses"].(float64); !ok || int(watched) != 3 {
+		t.Errorf("expected watched_addresses=3, got %v", response["watched_addresses"])
+	}
+	if version, ok := response["server_version"].(string); !ok || version != testVersion {
+		t.Errorf("expected server_version=%s, got %v", testVersion, response["server_version"])
+	}
 }
 
 func TestLoggingMiddleware_Success(t *testing.T) {

neutrino_server/internal/neutrino/node.go

@@ -36,6 +36,7 @@ type Config struct {
 	DataDir             string
 	TorProxy            string
 	AddPeers            string
+	Version             string
 	MaxPeers            int
 	BanDuration         time.Duration
 	FilterCacheSize     int
@@ -51,6 +52,7 @@ type Config struct {
 // Node wraps a neutrino ChainService with additional functionality.
 type Node struct {
 	config       *Config
+	version      string
 	chainParams  *chaincfg.Params
 	chainService *neutrino.ChainService
 	rescanMgr    *RescanManager
@@ -89,10 +91,12 @@ type Transaction struct {
 
 // Status represents the current node status.
 type Status struct {
-	Synced       bool  `json:"synced"`
-	BlockHeight  int32 `json:"block_height"`
-	FilterHeight int32 `json:"filter_height"`
-	Peers        int   `json:"peers"`
+	Synced           bool   `json:"synced"`
+	BlockHeight      int32  `json:"block_height"`
+	FilterHeight     int32  `json:"filter_height"`
+	Peers            int    `json:"peers"`
+	Version          string `json:"version"`
+	WatchedAddresses int    `json:"watched_addresses"`
 }
 
 // NewNode creates a new neutrino node.
@@ -124,11 +128,15 @@ func NewNode(config *Config) (*Node, error) {
 
 	node := &Node{
 		config:       config,
+		version:      strings.TrimSpace(config.Version),
 		chainParams:  chainParams,
 		logger:       logger,
 		prefetchQuit: make(chan struct{}),
 		prefetchDone: make(chan struct{}),
 	}
+	if node.version == "" {
+		node.version = "dev"
+	}
 	node.prefetchLastHeight = config.PrefetchStart - 1
 
 	return node, nil
@@ -436,11 +444,18 @@ func (n *Node) GetStatus() Status {
 		peers = len(n.chainService.Peers())
 	}
 
+	watchedAddresses := 0
+	if n.rescanMgr != nil {
+		watchedAddresses = n.rescanMgr.WatchedAddressCount()
+	}
+
 	return Status{
-		Synced:       n.synced,
-		BlockHeight:  n.blockHeight,
-		FilterHeight: n.filterHeight,
-		Peers:        peers,
+		Synced:           n.synced,
+		BlockHeight:      n.blockHeight,
+		FilterHeight:     n.filterHeight,
+		Peers:            peers,
+		Version:          n.version,
+		WatchedAddresses: watchedAddresses,
 	}
 }
 

neutrino_server/internal/neutrino/node_test.go

@@ -196,6 +196,35 @@ func TestGetStatus(t *testing.T) {
 	if status.Peers != 0 {
 		t.Errorf("expected 0 peers, got %d", status.Peers)
 	}
+
+	if status.Version != "dev" {
+		t.Errorf("expected default version dev, got %q", status.Version)
+	}
+
+	if status.WatchedAddresses != 0 {
+		t.Errorf("expected watched address count 0, got %d", status.WatchedAddresses)
+	}
+}
+
+func TestGetStatusIncludesConfiguredVersion(t *testing.T) {
+	backend := btclog.NewBackend(os.Stdout)
+
+	node, err := NewNode(&Config{
+		Network:         "regtest",
+		DataDir:         "/tmp/test",
+		Version:         "v1.2.3-test",
+		FilterCacheSize: 4096,
+		Logger:          backend,
+		LogLevel:        "info",
+	})
+	if err != nil {
+		t.Fatalf("NewNode() failed: %v", err)
+	}
+
+	status := node.GetStatus()
+	if status.Version != "v1.2.3-test" {
+		t.Errorf("expected configured version, got %q", status.Version)
+	}
 }
 
 func TestComputePrefetchWorkerCount(t *testing.T) {

neutrino_server/internal/neutrino/rescan.go

@@ -199,6 +199,13 @@ func (r *RescanManager) IsRescanInProgress() bool {
 	return r.rescanInProgress.Load() > 0
 }
 
+// WatchedAddressCount returns the number of currently watched addresses.
+func (r *RescanManager) WatchedAddressCount() int {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	return len(r.watchedAddrs)
+}
+
 // GetRescanStatus returns the current detailed rescan status.
 func (r *RescanManager) GetRescanStatus() RescanStatus {
 	r.statusMu.RLock()

neutrino_server/internal/neutrino/rescan_test.go

@@ -111,6 +111,39 @@ func TestWatchAddress(t *testing.T) {
 	}
 }
 
+func TestWatchedAddressCount(t *testing.T) {
+	backend := btclog.NewBackend(nil)
+	logger := backend.Logger("TEST")
+
+	mgr := &RescanManager{
+		chainParams:  &chaincfg.MainNetParams,
+		logger:       logger,
+		watchedAddrs: make(map[string]btcutil.Address),
+		utxoSet:      make(map[string]UTXO),
+	}
+
+	if got := mgr.WatchedAddressCount(); got != 0 {
+		t.Fatalf("expected empty watched count=0, got %d", got)
+	}
+
+	if err := mgr.WatchAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"); err != nil {
+		t.Fatalf("failed to watch address: %v", err)
+	}
+
+	if got := mgr.WatchedAddressCount(); got != 1 {
+		t.Fatalf("expected watched count=1, got %d", got)
+	}
+
+	// Duplicate should not increase count.
+	if err := mgr.WatchAddress("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"); err != nil {
+		t.Fatalf("failed to watch duplicate address: %v", err)
+	}
+
+	if got := mgr.WatchedAddressCount(); got != 1 {
+		t.Fatalf("expected watched count to remain 1, got %d", got)
+	}
+}
+
 // TestAddUTXO tests adding UTXOs to the set.
 func TestAddUTXO(t *testing.T) {
 	backend := btclog.NewBackend(nil)