feat: Add block_height to UTXOSpendReport and test JSON serialization

Author: m0wer

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add block_height to UTXOSpendReport for more efficient scans.
+
 ## [0.6.1] - 2026-01-09
 
 ### Fixed

neutrino_server/internal/neutrino/node.go

@@ -374,6 +374,7 @@ type UTXOSpendReport struct {
 	Unspent      bool   `json:"unspent"`
 	Value        int64  `json:"value,omitempty"`
 	ScriptPubKey string `json:"scriptpubkey,omitempty"`
+	BlockHeight  uint32 `json:"block_height,omitempty"`
 
 	// If the output has been spent, these fields are populated
 	SpendingTxID   string `json:"spending_txid,omitempty"`
@@ -524,6 +525,7 @@ func (n *Node) GetUTXO(txid string, vout uint32, address string, startHeight int
 		txOut := foundTx.TxOut[vout]
 		report.Value = txOut.Value
 		report.ScriptPubKey = fmt.Sprintf("%x", txOut.PkScript)
+		report.BlockHeight = uint32(foundHeight)
 	} else {
 		// UTXO has been spent
 		report.Unspent = false

neutrino_server/internal/neutrino/node_test.go

@@ -1,6 +1,7 @@
 package neutrino
 
 import (
+	"encoding/json"
 	"os"
 	"testing"
 	"time"
@@ -196,3 +197,81 @@ func TestGetStatus(t *testing.T) {
 		t.Errorf("expected 0 peers, got %d", status.Peers)
 	}
 }
+
+func TestUTXOSpendReportJSON(t *testing.T) {
+	tests := []struct {
+		name     string
+		report   UTXOSpendReport
+		wantKeys []string // JSON keys that must be present
+		noKeys   []string // JSON keys that must NOT be present (omitempty)
+	}{
+		{
+			name: "unspent with block_height",
+			report: UTXOSpendReport{
+				Unspent:      true,
+				Value:        100000,
+				ScriptPubKey: "00140000000000000000000000000000000000000000",
+				BlockHeight:  295000,
+			},
+			wantKeys: []string{"unspent", "value", "scriptpubkey", "block_height"},
+			noKeys:   []string{"spending_txid", "spending_input", "spending_height"},
+		},
+		{
+			name: "unspent without block_height (omitempty)",
+			report: UTXOSpendReport{
+				Unspent:      true,
+				Value:        50000,
+				ScriptPubKey: "00140000000000000000000000000000000000000000",
+				BlockHeight:  0,
+			},
+			wantKeys: []string{"unspent", "value", "scriptpubkey"},
+			noKeys:   []string{"block_height"},
+		},
+		{
+			name: "spent UTXO",
+			report: UTXOSpendReport{
+				Unspent:        false,
+				SpendingTxID:   "abcd1234",
+				SpendingInput:  0,
+				SpendingHeight: 295001,
+			},
+			wantKeys: []string{"unspent", "spending_txid", "spending_height"},
+			noKeys:   []string{"value", "scriptpubkey", "block_height"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			data, err := json.Marshal(tt.report)
+			if err != nil {
+				t.Fatalf("json.Marshal() error: %v", err)
+			}
+
+			var parsed map[string]interface{}
+			if err := json.Unmarshal(data, &parsed); err != nil {
+				t.Fatalf("json.Unmarshal() error: %v", err)
+			}
+
+			for _, key := range tt.wantKeys {
+				if _, ok := parsed[key]; !ok {
+					t.Errorf("expected key %q in JSON, got: %s", key, string(data))
+				}
+			}
+
+			for _, key := range tt.noKeys {
+				if _, ok := parsed[key]; ok {
+					t.Errorf("unexpected key %q in JSON (omitempty), got: %s", key, string(data))
+				}
+			}
+
+			// Verify block_height value when present
+			if tt.report.BlockHeight > 0 {
+				if bh, ok := parsed["block_height"].(float64); !ok {
+					t.Errorf("block_height is not a number: %v", parsed["block_height"])
+				} else if uint32(bh) != tt.report.BlockHeight {
+					t.Errorf("block_height = %v, want %d", bh, tt.report.BlockHeight)
+				}
+			}
+		})
+	}
+}