walletrpc: return the master key birthday from ListAccounts

cmd/commands/cmd_walletunlocker.go

@@ -11,6 +11,7 @@
 	"os"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/lightningnetwork/lnd/lncfg"
 	"github.com/lightningnetwork/lnd/lnrpc"
@@ -332,7 +333,9 @@
 		}
 		extendedRootKey = strings.TrimSpace(extendedRootKey)
 
-		extendedRootKeyBirthday, err = askBirthdayTimestamp()
+		// An extended master key carries no birthday, so there's nothing
+		// to offer as a default here.
+		extendedRootKeyBirthday, err = askBirthdayTimestamp(0)
 		if err != nil {
 			return err
 		}
@@ -939,7 +942,14 @@
 		return err
 	}
 
-	extendedRootKeyBirthday, err := askBirthdayTimestamp()
+	// A wallet exported by a recent enough lnd tells us the birthday of the
+	// master key its accounts were derived from, which is more accurate than
+	// anything the operator is likely to type in, so we offer it as the
+	// default. An older export leaves this at zero and the prompt behaves as
+	// it always did.
+	extendedRootKeyBirthday, err := askBirthdayTimestamp(
+		jsonAccts.MasterKeyBirthdayTimestamp,
+	)
 	if err != nil {
 		return err
 	}
@@ -1061,11 +1071,27 @@
 	}
 }
 
-func askBirthdayTimestamp() (uint64, error) {
+// askBirthdayTimestamp prompts for the wallet's birthday as a unix timestamp in
+// seconds. The given default is what an empty answer resolves to, which lets a
+// caller that already knows the birthday offer it up for confirmation, instead
+// of making the user dig it out by hand.
+func askBirthdayTimestamp(defaultTimestamp uint64) (uint64, error) {
+	// Spell a non-zero default out as a date as well. An empty answer
+	// accepts it, and it decides where the rescan starts, so the operator
+	// should be able to sanity check it without converting a bare unix
+	// timestamp in their head.
+	defaultHint := fmt.Sprintf("%d", defaultTimestamp)
+	if defaultTimestamp != 0 {
+		birthday := time.Unix(int64(defaultTimestamp), 0).UTC()
+		defaultHint = fmt.Sprintf("%d, which is %s", defaultTimestamp,
+			birthday.Format(time.RFC3339))
+	}
+
 	for {
 		fmt.Println()
-		fmt.Printf("Input an optional wallet birthday unix timestamp " +
-			"of first block to start scanning from (default 0): ")
+		fmt.Printf("Input an optional wallet birthday unix timestamp "+
+			"of first block to start scanning from (default %s): ",
+			defaultHint)
 
 		reader := bufio.NewReader(os.Stdin)
 		answer, err := reader.ReadString('\n')
@@ -1078,7 +1104,7 @@
 		answer = strings.TrimSpace(answer)
 
 		if len(answer) == 0 {
-			return 0, nil
+			return defaultTimestamp, nil
 		}
 
 		birthdayTimestamp, err := strconv.ParseUint(answer, 10, 64)

docs/release-notes/release-notes-0.22.0.md

@@ -90,8 +90,22 @@
 
 ## RPC Updates
 
+* [`walletrpc.ListAccounts` now also returns the birthday of the wallet's master
+  key](https://github.com/lightningnetwork/lnd/pull/10993) in the new
+  `master_key_birthday_timestamp` field. The accounts themselves are extended
+  public keys, which say nothing about when they were created, so a watch-only
+  wallet importing them had no birthday to work with and had to rescan the chain
+  from lnd's default of 2017-08-24. On mainnet that's hundreds of thousands of
+  blocks and several hours, even for a node with no history at all.
+
 ## lncli Updates
 
+* [`createwatchonly` now offers the birthday from the accounts
+  file](https://github.com/lightningnetwork/lnd/pull/10993) as the default for
+  its birthday prompt, so an accounts file exported by a recent enough lnd
+  carries the right value through without the operator having to know it. An
+  older file leaves the field unset and the prompt behaves as before.
+
 ## Breaking Changes
 
 ## Performance Improvements
@@ -159,3 +173,4 @@
 * Boris Nagaev
 * Erick Cestari
 * Jared Tobin
+* Olaoluwa Osuntokun

lnrpc/walletrpc/walletkit.proto

@@ -585,6 +585,17 @@ message ListAccountsRequest {
 
 message ListAccountsResponse {
     repeated Account accounts = 1;
+
+    /*
+    The birthday of the wallet's master key, expressed in seconds since the unix
+    epoch. This is the earliest time any of the wallet's keys could have been
+    used, so it is where a rescan of the chain has to start. The accounts above
+    are extended public keys, which carry no notion of when they were created,
+    so this value needs to be transported alongside them when importing them
+    into a watch-only wallet. It corresponds to the
+    WatchOnly.master_key_birthday_timestamp field of the InitWallet request.
+    */
+    uint64 master_key_birthday_timestamp = 2;
 }
 
 message RequiredReserveRequest {

lnrpc/walletrpc/walletkit.swagger.json

@@ -1882,6 +1882,11 @@
             "type": "object",
             "$ref": "#/definitions/walletrpcAccount"
           }
+        },
+        "master_key_birthday_timestamp": {
+          "type": "string",
+          "format": "uint64",
+          "description": "The birthday of the wallet's master key, expressed in seconds since the unix\nepoch. This is the earliest time any of the wallet's keys could have been\nused, so it is where a rescan of the chain has to start. The accounts above\nare extended public keys, which carry no notion of when they were created,\nso this value needs to be transported alongside them when importing them\ninto a watch-only wallet. It corresponds to the\nWatchOnly.master_key_birthday_timestamp field of the InitWallet request."
         }
       }
     },

lnrpc/walletrpc/walletkit_server.go

@@ -2689,7 +2689,28 @@ func (w *WalletKit) ListAccounts(ctx context.Context,
 		rpcAccounts = append(rpcAccounts, rpcAccount)
 	}
 
-	return &ListAccountsResponse{Accounts: rpcAccounts}, nil
+	// The accounts above are extended public keys, which say nothing about
+	// when they were created. We return the wallet's birthday along with
+	// them so that a watch-only wallet importing this response doesn't have
+	// to rescan the chain from lnd's default birthday.
+	//
+	// A wallet that somehow has no birthday at all reports zero rather than
+	// the nonsense a uint64 cast of a pre-epoch time would produce, since
+	// zero is what the InitWallet request already reads as "unknown".
+	//
+	// The comparison has to stay a positivity check and not become an
+	// IsZero one: a non-zero time before 1970 has a negative Unix value,
+	// which is exactly what the cast below would turn into a timestamp
+	// somewhere past the year 292 billion.
+	var birthdayTimestamp uint64
+	if birthday := w.cfg.Wallet.Birthday(); birthday.Unix() > 0 {
+		birthdayTimestamp = uint64(birthday.Unix())
+	}
+
+	return &ListAccountsResponse{
+		Accounts:                   rpcAccounts,
+		MasterKeyBirthdayTimestamp: birthdayTimestamp,
+	}, nil
 }
 
 // RequiredReserve returns the minimum amount of satoshis that should be

lnrpc/walletrpc/walletkit_server_test.go

@@ -5,13 +5,16 @@
 
 import (
 	"bytes"
+	"context"
 	"fmt"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/btcec/v2/schnorr"
 	"github.com/btcsuite/btcd/btcutil/v2"
+	"github.com/btcsuite/btcd/chaincfg/v2"
 	"github.com/btcsuite/btcd/chainhash/v2"
 	"github.com/btcsuite/btcd/psbt/v2"
 	"github.com/btcsuite/btcd/txscript/v2"
@@ -720,3 +723,55 @@
 		})
 	}
 }
+
+// TestListAccountsBirthday makes sure ListAccounts reports the birthday of the
+// wallet's master key. The exported accounts are extended public keys, which
+// carry no creation time of their own, so this timestamp is the only thing that
+// lets an importing watch-only wallet start its rescan at the right height
+// instead of at lnd's default birthday.
+func TestListAccountsBirthday(t *testing.T) {
+	t.Parallel()
+
+	birthday := time.Unix(1719792000, 0)
+
+	testCases := []struct {
+		name     string
+		birthday time.Time
+		expected uint64
+	}{{
+		name:     "birthday is reported in unix seconds",
+		birthday: birthday,
+		expected: uint64(birthday.Unix()),
+	}, {
+		// A wallet without a birthday must report zero, which is what
+		// InitWallet already reads as "unknown". Casting a pre-epoch
+		// time to uint64 would instead produce a nonsense timestamp
+		// somewhere in the year 292 billion.
+		name:     "wallet without a birthday reports zero",
+		birthday: time.Time{},
+		expected: 0,
+	}}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(tt *testing.T) {
+			tt.Parallel()
+
+			rpcServer, _, err := New(&Config{
+				Wallet: &mock.WalletController{
+					WalletBirthday: tc.birthday,
+				},
+				ChainParams: &chaincfg.RegressionNetParams,
+			})
+			require.NoError(tt, err)
+
+			resp, err := rpcServer.ListAccounts(
+				context.Background(), &ListAccountsRequest{},
+			)
+			require.NoError(tt, err)
+			require.Equal(
+				tt, tc.expected,
+				resp.MasterKeyBirthdayTimestamp,
+			)
+		})
+	}
+}

lntest/mock/walletcontroller.go

@@ -34,6 +34,7 @@ type WalletController struct {
 	PublishedTransactions chan *wire.MsgTx
 	index                 uint32
 	Utxos                 []*lnwallet.Utxo
+	WalletBirthday        time.Time
 }
 
 // A compile time check to ensure this mocked WalletController implements the
@@ -285,6 +286,12 @@ func (w *WalletController) GetRecoveryInfo() (bool, float64, error) {
 	return true, float64(1), nil
 }
 
+// Birthday returns the mock wallet's birthday, which is the zero time unless a
+// test set one explicitly.
+func (w *WalletController) Birthday() time.Time {
+	return w.WalletBirthday
+}
+
 // Start currently does nothing.
 func (w *WalletController) Start() error {
 	return nil

lnwallet/btcwallet/btcwallet.go

@@ -1883,6 +1883,14 @@ func (b *BtcWallet) GetRecoveryInfo() (bool, float64, error) {
 	return isRecoveryMode, progress, nil
 }
 
+// Birthday returns the birthday of the wallet's master key, meaning the
+// earliest time at which any of its keys could have been used.
+//
+// This is a part of the WalletController interface.
+func (b *BtcWallet) Birthday() time.Time {
+	return b.wallet.AddrManager().Birthday()
+}
+
 // FetchTx attempts to fetch a transaction in the wallet's database identified
 // by the passed transaction hash. If the transaction can't be found, then a
 // nil pointer is returned.

lnwallet/interface.go

@@ -550,6 +550,12 @@ type WalletController interface {
 	// recovery progress made so far.
 	GetRecoveryInfo() (bool, float64, error)
 
+	// Birthday returns the birthday of the wallet's master key, meaning the
+	// earliest time at which any of its keys could have been used. Blocks
+	// before that point cannot contain any of the wallet's outputs, so this
+	// is where a rescan of the chain starts.
+	Birthday() time.Time
+
 	// Start initializes the wallet, making any necessary connections,
 	// starting up required goroutines etc.
 	Start() error

lnwallet/mock.go

@@ -40,6 +40,7 @@ type mockWalletController struct {
 	PublishedTransactions chan *wire.MsgTx
 	index                 uint32
 	Utxos                 []*Utxo
+	walletBirthday        time.Time
 }
 
 // A compile time check to ensure that mockWalletController implements the
@@ -301,6 +302,12 @@ func (w *mockWalletController) GetRecoveryInfo() (bool, float64, error) {
 	return true, float64(1), nil
 }
 
+// Birthday returns the mock wallet's birthday, which is the zero time unless a
+// test set one explicitly.
+func (w *mockWalletController) Birthday() time.Time {
+	return w.walletBirthday
+}
+
 // Start currently does nothing.
 func (w *mockWalletController) Start() error {
 	return nil