db: add scan horizon extension helpers

yyforyongyu · yyforyongyu · commit b70bd9eba71e · 2026-06-13T18:20:22.000+08:00
Add ExtendScanHorizon and its validateHorizon, deriveHorizonRange, and
deriveNextValidChild helpers, mirroring the legacy ScopedKeyManager
extend-addresses semantics: derive and persist every valid child through
the horizon index, skip HD-invalid children, and advance the branch
next-index monotonically.
diff --git a/wallet/internal/db/scan_batch_common.go b/wallet/internal/db/scan_batch_common.go
@@ -2,6 +2,10 @@ package db
 
 import (
 	"context"
+	"errors"
+	"fmt"
+
+	"github.com/btcsuite/btcd/btcutil/hdkeychain"
 )
 
 // externalBranch and internalBranch are the BIP44 branch numbers the horizon
@@ -73,3 +77,150 @@ type ScanHorizonOps interface {
 	AdvanceNextIndex(ctx context.Context, accountID int64, branch uint32,
 		nextIndex uint32) error
 }
+
+// ExtendScanHorizon ensures every valid child through horizon.Index is derived
+// and persisted on the requested branch, mirroring the legacy
+// ScopedKeyManager.ExtendAddresses semantics used by the kvdb backend:
+//
+//   - Derivation starts from the branch's current next-index and runs through
+//     horizon.Index inclusive.
+//   - When horizon.Index is already below the current next-index the call is a
+//     no-op, so replaying a horizon never inserts duplicate rows.
+//   - HD-invalid child indices are skipped (the next-index simply advances)
+//     instead of failing, so the SQL path matches the kvdb invalid-child skip.
+//   - After derivation the branch next-index advances to one past the last
+//     derived child, leaving the same terminal counter the legacy path would.
+func ExtendScanHorizon(ctx context.Context, ops ScanHorizonOps,
+	deriveFn AddressDerivationFunc, horizon ScanHorizon) error {
+
+	branch, err := validateHorizon(deriveFn, horizon)
+	if err != nil {
+		return err
+	}
+
+	account, err := ops.GetHorizonAccount(ctx, horizon)
+	if err != nil {
+		return fmt.Errorf("extend horizon: %w", err)
+	}
+
+	addrType, nextIndex := account.branchState(branch)
+
+	// Nothing to do when the scan did not advance past the persisted tip.
+	if horizon.Index < nextIndex {
+		return nil
+	}
+
+	nextIndex, err = deriveHorizonRange(
+		ctx, ops, deriveFn, account, horizon, branch, addrType, nextIndex,
+	)
+	if err != nil {
+		return err
+	}
+
+	// Persist the advanced next-index so subsequent address allocation and
+	// horizon replays resume past the derived range.
+	err = ops.AdvanceNextIndex(ctx, account.AccountID, branch, nextIndex)
+	if err != nil {
+		return fmt.Errorf("extend horizon: advance next index: %w", err)
+	}
+
+	return nil
+}
+
+// validateHorizon checks the derivation callback and horizon bounds, returning
+// the validated branch number.
+func validateHorizon(deriveFn AddressDerivationFunc,
+	horizon ScanHorizon) (uint32, error) {
+
+	if deriveFn == nil {
+		return 0, fmt.Errorf("extend horizon: %w",
+			errNilAddressDerivationFunc)
+	}
+
+	// Recovery only ever reports the external or internal branch; reject
+	// anything else up front so an unexpected branch cannot silently derive
+	// against the wrong next-index column.
+	branch := horizon.Branch
+	if branch != externalBranch && branch != internalBranch {
+		return 0, fmt.Errorf("extend horizon: %w: branch %d",
+			ErrInvalidParam, branch)
+	}
+
+	// kvdb caps a single extension at MaxAddressesPerAccount; mirror the bound
+	// so both backends reject the same out-of-range horizon.
+	if horizon.Index > MaxAddressIndex {
+		return 0, fmt.Errorf("extend horizon: %w",
+			ErrMaxAddressIndexReached)
+	}
+
+	return branch, nil
+}
+
+// deriveHorizonRange derives and persists one valid child per index from
+// nextIndex through horizon.Index inclusive and returns the advanced next
+// index. It mirrors the nested loop in the legacy extendAddresses: each outer
+// step finds the next valid child, skipping HD-invalid indices even past
+// horizon.Index, so the terminal next index matches the address manager.
+func deriveHorizonRange(ctx context.Context, ops ScanHorizonOps,
+	deriveFn AddressDerivationFunc, account *HorizonAccount,
+	horizon ScanHorizon, branch uint32, addrType AddressType,
+	nextIndex uint32) (uint32, error) {
+
+	for nextIndex <= horizon.Index {
+		next, err := deriveNextValidChild(
+			ctx, ops, deriveFn, account, horizon.Scope, branch, addrType,
+			nextIndex,
+		)
+		if err != nil {
+			return 0, err
+		}
+
+		nextIndex = next
+	}
+
+	return nextIndex, nil
+}
+
+// deriveNextValidChild derives and persists the first valid child at or after
+// startIndex, returning the index immediately past the persisted child.
+// HD-invalid children are skipped without persisting a row, exactly like the
+// inner loop of the legacy extendAddresses.
+func deriveNextValidChild(ctx context.Context, ops ScanHorizonOps,
+	deriveFn AddressDerivationFunc, account *HorizonAccount, scope KeyScope,
+	branch uint32, addrType AddressType, startIndex uint32) (uint32, error) {
+
+	for index := startIndex; ; index++ {
+		derived, err := deriveFn(ctx, AddressDerivationParams{
+			Scope:                scope,
+			DerivedAccountNumber: &account.AccountNumber,
+			Branch:               branch,
+			Index:                index,
+			AddrType:             addrType,
+			AccountPubKey:        account.AccountPubKey,
+		})
+		if errors.Is(err, hdkeychain.ErrInvalidChild) {
+			continue
+		}
+
+		if err != nil {
+			return 0, fmt.Errorf("extend horizon: derive index %d: %w",
+				index, err)
+		}
+
+		if derived == nil {
+			return 0, fmt.Errorf("extend horizon: derive index %d: %w",
+				index, errNilDerivedAddressData)
+		}
+
+		err = ops.InsertDerivedAddress(
+			ctx, account.AccountID, addrType, branch, index,
+			derived.ScriptPubKey, derived.PubKey,
+		)
+		if err != nil {
+			return 0, fmt.Errorf("extend horizon: insert index %d: %w",
+				index, err)
+		}
+
+		return index + 1, nil
+	}
+}
diff --git a/wallet/internal/db/scan_batch_common_test.go b/wallet/internal/db/scan_batch_common_test.go
@@ -0,0 +1,181 @@
+package db
+
+import (
+	"context"
+	"testing"
+
+	"github.com/btcsuite/btcd/btcutil/hdkeychain"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeHorizonOps is a minimal ScanHorizonOps used by the ExtendScanHorizon
+// tests. It records the inserted child indices and the final advanced
+// next-index so each scenario can assert the exact derivation work performed.
+type fakeHorizonOps struct {
+	account *HorizonAccount
+
+	inserted    []uint32
+	advancedTo  uint32
+	advanceCall bool
+}
+
+// GetHorizonAccount returns the preconfigured account.
+func (o *fakeHorizonOps) GetHorizonAccount(_ context.Context,
+	_ ScanHorizon) (*HorizonAccount, error) {
+
+	return o.account, nil
+}
+
+// InsertDerivedAddress records the child index that was derived and persisted.
+func (o *fakeHorizonOps) InsertDerivedAddress(_ context.Context, _ int64,
+	_ AddressType, _ uint32, index uint32, _ []byte, _ []byte) error {
+
+	o.inserted = append(o.inserted, index)
+
+	return nil
+}
+
+// AdvanceNextIndex records the advanced next-index value.
+func (o *fakeHorizonOps) AdvanceNextIndex(_ context.Context, _ int64,
+	_ uint32, nextIndex uint32) error {
+
+	o.advanceCall = true
+	o.advancedTo = nextIndex
+
+	return nil
+}
+
+// validChildDeriveFunc returns a derivation callback that always derives a
+// valid address, recording nothing of the input.
+func validChildDeriveFunc() AddressDerivationFunc {
+	return func(_ context.Context,
+		_ AddressDerivationParams) (*DerivedAddressData, error) {
+
+		return &DerivedAddressData{
+			ScriptPubKey: []byte{0x00, 0x14},
+			PubKey:       []byte{0x02},
+		}, nil
+	}
+}
+
+// TestExtendScanHorizonNoOpBelowNextIndex verifies that ExtendScanHorizon does
+// nothing when the discovered index is below the branch's current next index,
+// so replaying an already-covered horizon never re-derives or advances.
+func TestExtendScanHorizonNoOpBelowNextIndex(t *testing.T) {
+	t.Parallel()
+
+	ops := &fakeHorizonOps{
+		account: &HorizonAccount{
+			AccountID:         7,
+			NextExternalIndex: 5,
+		},
+	}
+
+	// The horizon index is below the persisted next-external index, so the
+	// call must be a no-op.
+	err := ExtendScanHorizon(t.Context(), ops, validChildDeriveFunc(),
+		ScanHorizon{Branch: externalBranch, Index: 3})
+	require.NoError(t, err)
+
+	require.Empty(t, ops.inserted)
+	require.False(t, ops.advanceCall)
+}
+
+// TestExtendScanHorizonRejectsInvalidBranch verifies that a branch other than
+// external or internal is rejected with ErrInvalidParam before any account
+// load or derivation.
+func TestExtendScanHorizonRejectsInvalidBranch(t *testing.T) {
+	t.Parallel()
+
+	ops := &fakeHorizonOps{account: &HorizonAccount{AccountID: 7}}
+
+	err := ExtendScanHorizon(t.Context(), ops, validChildDeriveFunc(),
+		ScanHorizon{Branch: 2, Index: 1})
+	require.ErrorIs(t, err, ErrInvalidParam)
+
+	require.Empty(t, ops.inserted)
+	require.False(t, ops.advanceCall)
+}
+
+// TestExtendScanHorizonRejectsMaxIndex verifies that a horizon index above
+// MaxAddressIndex is rejected with ErrMaxAddressIndexReached, matching the
+// legacy address manager's per-account child bound.
+func TestExtendScanHorizonRejectsMaxIndex(t *testing.T) {
+	t.Parallel()
+
+	ops := &fakeHorizonOps{account: &HorizonAccount{AccountID: 7}}
+
+	err := ExtendScanHorizon(t.Context(), ops, validChildDeriveFunc(),
+		ScanHorizon{Branch: externalBranch, Index: MaxAddressIndex + 1})
+	require.ErrorIs(t, err, ErrMaxAddressIndexReached)
+
+	require.Empty(t, ops.inserted)
+	require.False(t, ops.advanceCall)
+}
+
+// TestExtendScanHorizonSkipsInvalidChild verifies that an HD-invalid child
+// index is skipped without persisting a row while derivation advances to the
+// next valid child, mirroring the legacy extendAddresses inner loop.
+func TestExtendScanHorizonSkipsInvalidChild(t *testing.T) {
+	t.Parallel()
+
+	ops := &fakeHorizonOps{
+		account: &HorizonAccount{
+			AccountID:         7,
+			NextExternalIndex: 0,
+		},
+	}
+
+	// Index 1 derives an ErrInvalidChild, so it must be skipped: only indices
+	// 0 and 2 are persisted while the loop still reaches horizon index 2.
+	deriveFn := func(_ context.Context,
+		params AddressDerivationParams) (*DerivedAddressData, error) {
+
+		if params.Index == 1 {
+			return nil, hdkeychain.ErrInvalidChild
+		}
+
+		return &DerivedAddressData{
+			ScriptPubKey: []byte{0x00, 0x14},
+			PubKey:       []byte{0x02},
+		}, nil
+	}
+
+	err := ExtendScanHorizon(t.Context(), ops, deriveFn,
+		ScanHorizon{Branch: externalBranch, Index: 2})
+	require.NoError(t, err)
+
+	// Index 1 was skipped; indices 0 and 2 were persisted.
+	require.Equal(t, []uint32{0, 2}, ops.inserted)
+
+	// The next index advanced past the last derived child.
+	require.True(t, ops.advanceCall)
+	require.Equal(t, uint32(3), ops.advancedTo)
+}
+
+// TestExtendScanHorizonAdvancesAfterInserts verifies that, after deriving the
+// full range, ExtendScanHorizon persists every child and advances the branch
+// next-index to one past the last derived child.
+func TestExtendScanHorizonAdvancesAfterInserts(t *testing.T) {
+	t.Parallel()
+
+	ops := &fakeHorizonOps{
+		account: &HorizonAccount{
+			AccountID:         7,
+			NextInternalIndex: 1,
+			AddrSchema: ScopeAddrSchema{
+				InternalAddrType: WitnessPubKey,
+				ExternalAddrType: WitnessPubKey,
+			},
+		},
+	}
+
+	// Extend the internal branch from its next index 1 through index 3.
+	err := ExtendScanHorizon(t.Context(), ops, validChildDeriveFunc(),
+		ScanHorizon{Branch: internalBranch, Index: 3})
+	require.NoError(t, err)
+
+	require.Equal(t, []uint32{1, 2, 3}, ops.inserted)
+	require.True(t, ops.advanceCall)
+	require.Equal(t, uint32(4), ops.advancedTo)
+}
