diff --git a/docs/release-notes/release-notes-0.21.0.md b/docs/release-notes/release-notes-0.21.0.md index c24e65eba3a..3b117cc8aca 100644 --- a/docs/release-notes/release-notes-0.21.0.md +++ b/docs/release-notes/release-notes-0.21.0.md @@ -208,6 +208,17 @@ the database. Deletion requires the target cutoff timestamp to be at least 1 hour in the past, preventing accidental removal of recent data. +* [A new `DeriveAndStoreKey` RPC was added to + `walletrpc`](https://github.com/lightningnetwork/lnd/pull/11095). It derives an + arbitrary key like `DeriveKey` does, but also records the key in the wallet, so + the wallet is able to map the public key back to its key locator later on. That + mapping is required to sign with a key, which means keys meant for signing can + now be derived at an arbitrary index instead of only through `DeriveNextKey` + ([#8698](https://github.com/lightningnetwork/lnd/issues/8698)). Recording a key + also advances the key family's derivation index past it, which lets an external + consumer of a key family restore that index after the wallet was recovered from + seed. + * The `WaitingCloseChannel` response in `PendingChannels` now includes two new fields via [#10509](https://github.com/lightningnetwork/lnd/pull/10509): `blocks_til_close_confirmed`, showing the remaining confirmations until a diff --git a/itest/list_on_test.go b/itest/list_on_test.go index fd236c25a19..5a5471aa232 100644 --- a/itest/list_on_test.go +++ b/itest/list_on_test.go @@ -511,6 +511,10 @@ var allTestCases = []*lntest.TestCase{ Name: "derive shared key", TestFunc: testDeriveSharedKey, }, + { + Name: "derive and store key", + TestFunc: testDeriveAndStoreKey, + }, { Name: "sign output raw", TestFunc: testSignOutputRaw, diff --git a/itest/lnd_remote_signer_test.go b/itest/lnd_remote_signer_test.go index 6982cf20f17..eb4278649fd 100644 --- a/itest/lnd_remote_signer_test.go +++ b/itest/lnd_remote_signer_test.go @@ -116,6 +116,10 @@ var remoteSignerTestCases = []*lntest.TestCase{ Name: "sign output raw", TestFunc: testRemoteSignerSignOutputRaw, }, + { + Name: "derive and store key", + TestFunc: testRemoteSignerDeriveAndStoreKey, + }, { Name: "sign output raw outbound", TestFunc: testRemoteSignerSignOutputRawOutbound, @@ -660,6 +664,21 @@ func testRemoteSignerSignOutputRawOutbound(ht *lntest.HarnessTest) { executeRemoteSignerTestCase(ht, signOutputRawTestCase(true)) } +func deriveAndStoreKeyTestCase(isOutbound bool) remoteSignerTestCase { + return remoteSignerTestCase{ + sendCoins: true, + isOutbound: isOutbound, + fn: func(tt *lntest.HarnessTest, wo, carol *node.HarnessNode) { + runDeriveAndStoreKey(tt, wo) + runDeriveAndStoreKeySigning(tt, wo) + }, + } +} + +func testRemoteSignerDeriveAndStoreKey(ht *lntest.HarnessTest) { + executeRemoteSignerTestCase(ht, deriveAndStoreKeyTestCase(false)) +} + func signVerifyMsgTestCase(isOutbound bool) remoteSignerTestCase { return remoteSignerTestCase{ sendCoins: true, diff --git a/itest/lnd_signer_test.go b/itest/lnd_signer_test.go index 9ef7ddeb79c..224fd329938 100644 --- a/itest/lnd_signer_test.go +++ b/itest/lnd_signer_test.go @@ -3,6 +3,8 @@ package itest import ( "bytes" "crypto/sha256" + "fmt" + "strings" "github.com/btcsuite/btcd/address/v2" "github.com/btcsuite/btcd/btcec/v2" @@ -19,6 +21,242 @@ import ( "github.com/stretchr/testify/require" ) +// testDeriveAndStoreKey checks that the DeriveAndStoreKey endpoint records the +// keys it derives in the wallet, which advances the key family's derivation +// index past them, and that it refuses to derive an unbounded number of keys. +func testDeriveAndStoreKey(ht *lntest.HarnessTest) { + alice := ht.NewNode("Alice", nil) + + runDeriveAndStoreKey(ht, alice) +} + +// runDeriveAndStoreKey checks that the DeriveAndStoreKey endpoint records the +// keys it derives in the wallet of the given node, which advances the key +// family's derivation index past them, and that it refuses to derive an +// unbounded number of keys. +func runDeriveAndStoreKey(ht *lntest.HarnessTest, hn *node.HarnessNode) { + // We use a key family of our own so that no other subsystem interferes + // with the derivation indexes we assert on below. The indexes are + // asserted relative to where the family starts out, since a watch-only + // wallet may already have addresses for it. + const testCustomKeyFamily = 55 + + startIndex := externalKeyCount(ht, hn, testCustomKeyFamily) + targetIndex := startIndex + 5 + + // Deriving a key without storing it must neither touch the family's + // derivation index nor make the key known to the wallet. + keyLoc := &signrpc.KeyLocator{ + KeyFamily: testCustomKeyFamily, + KeyIndex: int32(targetIndex), + } + unstoredDesc := hn.RPC.DeriveKey(keyLoc) + require.Equal( + ht, startIndex, externalKeyCount(ht, hn, testCustomKeyFamily), + ) + assertKeyKnown(ht, hn, unstoredDesc, false) + + // Storing the very same key returns the very same key, but now fills in + // every index up to it, so the family's next index moves past it. + storedDesc := hn.RPC.DeriveAndStoreKey(keyLoc) + require.Equal(ht, unstoredDesc.RawKeyBytes, storedDesc.RawKeyBytes) + require.Equal( + ht, targetIndex+1, + externalKeyCount(ht, hn, testCustomKeyFamily), + ) + + // And the wallet now knows the key, which is what allows it to sign + // with it later on. + assertKeyKnown(ht, hn, storedDesc, true) + + // Moving the index also means the indexes we just consumed are not + // handed out again. + nextDesc := hn.RPC.DeriveNextKey(&walletrpc.KeyReq{ + KeyFamily: testCustomKeyFamily, + }) + require.EqualValues(ht, targetIndex+1, nextDesc.KeyLoc.KeyIndex) + + // Storing a key at an index the family already advanced past leaves the + // index alone, it is never rewound. + hn.RPC.DeriveAndStoreKey(&signrpc.KeyLocator{ + KeyFamily: testCustomKeyFamily, + KeyIndex: int32(startIndex), + }) + require.Equal( + ht, targetIndex+2, + externalKeyCount(ht, hn, testCustomKeyFamily), + ) + + // An index that is too far ahead is refused outright instead of + // deriving an unbounded number of keys, and leaves the family alone. + err := hn.RPC.DeriveAndStoreKeyErr(&signrpc.KeyLocator{ + KeyFamily: testCustomKeyFamily, + KeyIndex: int32(targetIndex) + 2 + + keychain.MaxKeyIndexExtension, + }) + require.ErrorContains(ht, err, "key index extension too large") + require.Equal( + ht, targetIndex+2, + externalKeyCount(ht, hn, testCustomKeyFamily), + ) + + // Neither a negative family nor a negative index can be mapped to the + // unsigned values the wallet uses, so both are rejected. + err = hn.RPC.DeriveAndStoreKeyErr(&signrpc.KeyLocator{ + KeyFamily: -1, + KeyIndex: 0, + }) + require.ErrorContains(ht, err, "key family must not be negative") + + // The families lnd itself derives from cannot be advanced externally. + err = hn.RPC.DeriveAndStoreKeyErr(&signrpc.KeyLocator{ + KeyFamily: int32(keychain.KeyFamilyNodeKey), + KeyIndex: 1, + }) + require.ErrorContains(ht, err, "reserved by lnd") + + err = hn.RPC.DeriveAndStoreKeyErr(&signrpc.KeyLocator{ + KeyFamily: testCustomKeyFamily, + KeyIndex: -1, + }) + require.ErrorContains(ht, err, "key index must not be negative") +} + +// runDeriveAndStoreKeySigning checks that a key derived at an arbitrary index +// can only be signed with if it was stored in the wallet. Resolving a key +// locator from a public key alone requires the wallet to know the key's +// address, which is only the case for a stored key. +// +// NOTE: This is only meaningful against a watch-only node driving a remote +// signer, since a node with a local wallet falls back to scanning a range of +// key indexes when it is given a public key without a key locator. +func runDeriveAndStoreKeySigning(ht *lntest.HarnessTest, + hn *node.HarnessNode) { + + const ( + testCustomKeyFamily = 56 + targetIndex = 7 + ) + + keyLoc := &signrpc.KeyLocator{ + KeyFamily: testCustomKeyFamily, + KeyIndex: targetIndex, + } + + // A key that is only derived, but not stored, cannot be signed with + // when it is referenced by its public key, since the wallet has no + // address to map it back to a key locator with. + unstoredDesc := hn.RPC.DeriveKey(keyLoc) + unstoredPubKey, err := btcec.ParsePubKey(unstoredDesc.RawKeyBytes) + require.NoError(ht, err) + + targetAddr, err := address.NewAddressWitnessPubKeyHash( + address.Hash160(unstoredPubKey.SerializeCompressed()), + harnessNetParams, + ) + require.NoError(ht, err) + + targetScript, err := txscript.PayToAddrScript(targetAddr) + require.NoError(ht, err) + + // The transaction we ask to sign never makes it to the chain, the key + // cannot even be resolved. + tx := wire.NewMsgTx(2) + tx.TxIn = []*wire.TxIn{{ + PreviousOutPoint: wire.OutPoint{ + Hash: chainhash.Hash{1}, + Index: 0, + }, + }} + tx.TxOut = []*wire.TxOut{{ + PkScript: targetScript, + Value: 799_800, + }} + + var buf bytes.Buffer + require.NoError(ht, tx.Serialize(&buf)) + + err = hn.RPC.SignOutputRawErr(&signrpc.SignReq{ + RawTxBytes: buf.Bytes(), + SignDescs: []*signrpc.SignDescriptor{{ + Output: &signrpc.TxOut{ + PkScript: targetScript, + Value: 800_000, + }, + InputIndex: 0, + KeyDesc: &signrpc.KeyDescriptor{ + RawKeyBytes: unstoredDesc.RawKeyBytes, + }, + Sighash: uint32(txscript.SigHashAll), + WitnessScript: targetScript, + }}, + }) + require.ErrorContains(ht, err, "error fetching address info") + + // Storing the key makes it known to the wallet, so the very same + // reference by public key now resolves and produces a valid signature. + storedDesc := hn.RPC.DeriveAndStoreKey(keyLoc) + require.Equal(ht, unstoredDesc.RawKeyBytes, storedDesc.RawKeyBytes) + + assertSignOutputRaw( + ht, hn, unstoredPubKey, &signrpc.KeyDescriptor{ + RawKeyBytes: storedDesc.RawKeyBytes, + }, txscript.SigHashAll, + ) +} + +// externalKeyCount returns the number of external keys the given node's wallet +// has derived for the given key family, which is also the index the next key +// derived for that family will have. +func externalKeyCount(ht *lntest.HarnessTest, hn *node.HarnessNode, + keyFam keychain.KeyFamily) uint32 { + + accounts := hn.RPC.ListAccounts(&walletrpc.ListAccountsRequest{}) + + // The accounts of our key families are the ones under the BIP-0043 + // purpose lnd uses, with the family as the last path element. + purpose := fmt.Sprintf("/%d'/", keychain.BIP0043Purpose) + suffix := fmt.Sprintf("/%d'", keyFam) + for _, account := range accounts.Accounts { + path := account.DerivationPath + if !strings.Contains(path, purpose) { + continue + } + + if strings.HasSuffix(path, suffix) { + return account.ExternalKeyCount + } + } + + return 0 +} + +// assertKeyKnown asserts whether the given node's wallet has a record of the +// given key, which it needs in order to map the key back to its key locator. +// +// NOTE: For keys in lnd's own key scope, ListAddresses reports the public key +// itself instead of an address, since those keys are not used as addresses. +func assertKeyKnown(ht *lntest.HarnessTest, hn *node.HarnessNode, + desc *signrpc.KeyDescriptor, known bool) { + + resp := hn.RPC.ListAddresses(&walletrpc.ListAddressesRequest{ + ShowCustomAccounts: true, + }) + + var found bool + for _, account := range resp.AccountWithAddresses { + for _, walletAddr := range account.Addresses { + if bytes.Equal(walletAddr.PublicKey, desc.RawKeyBytes) { + found = true + } + } + } + + require.Equalf( + ht, known, found, "key %x known to wallet", desc.RawKeyBytes, + ) +} + // testDeriveSharedKey checks the ECDH performed by the endpoint // DeriveSharedKey. It creates an ephemeral private key, performing an ECDH with // the node's pubkey and a customized public key to check the validity of the diff --git a/keychain/btcwallet.go b/keychain/btcwallet.go index 41167f3c4ea..20e62e96248 100644 --- a/keychain/btcwallet.go +++ b/keychain/btcwallet.go @@ -253,6 +253,98 @@ func (b *BtcWalletKeyRing) DeriveKey(keyLoc KeyLocator) (KeyDescriptor, error) { return keyDesc, nil } +// DeriveAndStoreKey attempts to derive an arbitrary key specified by the passed +// KeyLocator, and also records that key (along with every key in the family +// preceding it) in the wallet's address manager. +// +// NOTE: This is part of the keychain.KeyRing interface. +func (b *BtcWalletKeyRing) DeriveAndStoreKey( + keyLoc KeyLocator) (KeyDescriptor, error) { + + var keyDesc KeyDescriptor + + db := b.wallet.Database() + err := walletdb.Update(db, func(tx walletdb.ReadWriteTx) error { + addrmgrNs := tx.ReadWriteBucket(waddrmgrNamespaceKey) + + scope, err := b.keyScope() + if err != nil { + return err + } + + // If the account doesn't exist, then we may need to create it + // for the first time in order to derive the keys that we + // require. We skip this if we're using a remote signer in which + // case we _need_ to create all accounts when creating the + // wallet, so it must exist now. + if !b.wallet.AddrManager().WatchOnly() { + err = b.createAccountIfNotExists( + addrmgrNs, keyLoc.Family, scope, + ) + if err != nil { + return err + } + } + + // Every index between the family's current next index and the + // requested one is derived and persisted, so we bound the + // amount of work (and the number of address records) a single + // call can cause. + props, err := scope.AccountProperties( + addrmgrNs, uint32(keyLoc.Family), + ) + if err != nil { + return err + } + + nextIndex := props.ExternalKeyCount + if keyLoc.Index >= nextIndex && + keyLoc.Index-nextIndex >= MaxKeyIndexExtension { + + return fmt.Errorf("%w: extending key family %d from "+ + "index %d to index %d requires deriving %d "+ + "keys, maximum is %d", ErrKeyExtensionTooLarge, + keyLoc.Family, nextIndex, keyLoc.Index, + keyLoc.Index-nextIndex+1, MaxKeyIndexExtension) + } + + // This is a no-op if the family has already advanced past the + // requested index, so the family's index is never rewound. + err = scope.ExtendExternalAddresses( + addrmgrNs, uint32(keyLoc.Family), keyLoc.Index, + ) + if err != nil { + return err + } + + path := waddrmgr.DerivationPath{ + InternalAccount: uint32(keyLoc.Family), + Branch: 0, + Index: keyLoc.Index, + } + addr, err := scope.DeriveFromKeyPath(addrmgrNs, path) + if err != nil { + return err + } + + pubKeyAddr, ok := addr.(waddrmgr.ManagedPubKeyAddress) + if !ok { + return fmt.Errorf("address is not a managed pubkey " + + "addr") + } + + keyDesc.KeyLocator = keyLoc + keyDesc.PubKey = pubKeyAddr.PubKey() + + return nil + }) + if err != nil { + return keyDesc, err + } + + return keyDesc, nil +} + // DerivePrivKey attempts to derive the private key that corresponds to the // passed key descriptor. // diff --git a/keychain/derivation.go b/keychain/derivation.go index 2b1c43444eb..7c63525c801 100644 --- a/keychain/derivation.go +++ b/keychain/derivation.go @@ -1,6 +1,7 @@ package keychain import ( + "errors" "fmt" "github.com/btcsuite/btcd/btcec/v2" @@ -33,8 +34,19 @@ const ( // // NOTE: BRICK SQUUUUUAD. BIP0043Purpose = 1017 + + // MaxKeyIndexExtension is the maximum number of keys a single + // DeriveAndStoreKey call is allowed to derive and persist. Since that + // method fills in every index between a family's current next index and + // the requested one, this bounds both the work and the number of + // address records a single call can cause. + MaxKeyIndexExtension = 25_000 ) +// ErrKeyExtensionTooLarge is returned when a DeriveAndStoreKey call would need +// to derive more than MaxKeyIndexExtension keys to reach the requested index. +var ErrKeyExtensionTooLarge = errors.New("key index extension too large") + // IsKnownVersion returns true if the given version is one of the known // derivation scheme versions as defined by this package. func IsKnownVersion(internalVersion uint8) bool { @@ -196,7 +208,30 @@ type KeyRing interface { // passed KeyLocator. This may be used in several recovery scenarios, // or when manually rotating something like our current default node // key. + // + // NOTE: The derived key is not recorded in the wallet, so the wallet + // cannot map the resulting public key back to its KeyLocator later on. + // Callers that intend to sign with the key must use DeriveAndStoreKey + // instead. DeriveKey(keyLoc KeyLocator) (KeyDescriptor, error) + + // DeriveAndStoreKey attempts to derive an arbitrary key specified by + // the passed KeyLocator, and also records that key in the wallet. This + // is the variant of DeriveKey that must be used for a key the wallet is + // later expected to sign with, since signing requires the wallet to be + // able to look the key's KeyLocator back up. + // + // Recording a key implies recording every key in the family that + // precedes it, so on return the family's next index is guaranteed to be + // above the requested one, and any key at or below it will not be + // handed out by DeriveNextKey again. The call is monotonic and + // idempotent: an index the family has already advanced past leaves the + // wallet untouched, and the family's index is never rewound. + // + // An error wrapping ErrKeyExtensionTooLarge is returned if reaching the + // requested index would require deriving more than + // MaxKeyIndexExtension keys. + DeriveAndStoreKey(keyLoc KeyLocator) (KeyDescriptor, error) } // SecretKeyRing is a ring similar to the regular KeyRing interface, but it is diff --git a/keychain/interface_test.go b/keychain/interface_test.go index 5d66b975146..4b026c2b474 100644 --- a/keychain/interface_test.go +++ b/keychain/interface_test.go @@ -6,6 +6,7 @@ import ( "testing" "time" + "github.com/btcsuite/btcd/address/v2" "github.com/btcsuite/btcd/btcec/v2" "github.com/btcsuite/btcd/chaincfg/v2" "github.com/btcsuite/btcd/chainhash/v2" @@ -220,6 +221,139 @@ func TestKeyRingDerivation(t *testing.T) { } } +// nextFamilyIndex returns the index that the next key derived for the given +// family will have, as recorded by the wallet. +func nextFamilyIndex(t *testing.T, w *wallet.Wallet, coinType uint32, + keyFam KeyFamily) uint32 { + + t.Helper() + + props, err := w.AccountProperties(waddrmgr.KeyScope{ + Purpose: BIP0043Purpose, + Coin: coinType, + }, uint32(keyFam)) + require.NoError(t, err) + + return props.ExternalKeyCount +} + +// assertKnownToWallet asserts whether the wallet is able to map the given key +// back to the address it belongs to, which is a prerequisite for the wallet +// being able to sign with that key. +func assertKnownToWallet(t *testing.T, w *wallet.Wallet, desc KeyDescriptor, + known bool) { + + t.Helper() + + addr, err := address.NewAddressWitnessPubKeyHash( + address.Hash160(desc.PubKey.SerializeCompressed()), + &chaincfg.SimNetParams, + ) + require.NoError(t, err) + + managedAddr, err := w.AddressInfo(addr) + if !known { + require.Error(t, err) + + return + } + + require.NoError(t, err) + + pubKeyAddr, ok := managedAddr.(waddrmgr.ManagedPubKeyAddress) + require.True(t, ok) + + _, path, ok := pubKeyAddr.DerivationInfo() + require.True(t, ok) + require.Equal(t, uint32(desc.Family), path.InternalAccount) + require.Equal(t, desc.Index, path.Index) +} + +// TestDeriveAndStoreKey tests that DeriveAndStoreKey records the derived key in +// the wallet, advances the key family's derivation index past it, and bounds +// the number of keys a single call derives. +func TestDeriveAndStoreKey(t *testing.T) { + t.Parallel() + + const ( + coinType = CoinTypeBitcoin + keyFam = KeyFamilyNodeKey + ) + + baseWallet, err := createTestBtcWallet(t, coinType) + require.NoError(t, err) + + keyRing := NewBtcWalletKeyRing(baseWallet, coinType) + + // Storing a key derives and records every key in the family up to and + // including the requested index, so the family's next index moves past + // it. + desc, err := keyRing.DeriveAndStoreKey(KeyLocator{ + Family: keyFam, + Index: 5, + }) + require.NoError(t, err) + assertEqualKeyLocator(t, KeyLocator{ + Family: keyFam, + Index: 5, + }, desc.KeyLocator) + require.EqualValues( + t, 6, nextFamilyIndex(t, baseWallet, coinType, keyFam), + ) + + // Which means that the indexes we just consumed are not handed out + // again. This is the property that lets a caller restore a key family's + // index after the wallet was recovered from seed. + nextDesc, err := keyRing.DeriveNextKey(keyFam) + require.NoError(t, err) + require.EqualValues(t, 6, nextDesc.Index) + + // The key itself must be the very same one that the plain DeriveKey + // method returns. + plainDesc, err := keyRing.DeriveKey(KeyLocator{ + Family: keyFam, + Index: 5, + }) + require.NoError(t, err) + require.True(t, plainDesc.PubKey.IsEqual(desc.PubKey)) + + // But unlike DeriveKey, the wallet is now able to map the key back to + // its address, and therefore to its key locator, which it needs in + // order to sign with the key. + assertKnownToWallet(t, baseWallet, desc, true) + + unstoredDesc, err := keyRing.DeriveKey(KeyLocator{ + Family: keyFam, + Index: 50, + }) + require.NoError(t, err) + assertKnownToWallet(t, baseWallet, unstoredDesc, false) + + // Storing a key at an index the family has already advanced past leaves + // the wallet untouched, the index is never rewound. + earlierDesc, err := keyRing.DeriveAndStoreKey(KeyLocator{ + Family: keyFam, + Index: 2, + }) + require.NoError(t, err) + require.EqualValues(t, 2, earlierDesc.Index) + require.EqualValues( + t, 7, nextFamilyIndex(t, baseWallet, coinType, keyFam), + ) + + // An index that is too far ahead of the family's next index is refused + // outright instead of deriving an unbounded number of keys, and the + // family is left untouched. + _, err = keyRing.DeriveAndStoreKey(KeyLocator{ + Family: keyFam, + Index: 7 + MaxKeyIndexExtension, + }) + require.ErrorIs(t, err, ErrKeyExtensionTooLarge) + require.EqualValues( + t, 7, nextFamilyIndex(t, baseWallet, coinType, keyFam), + ) +} + // secretKeyRingConstructor is a function signature that's used as a generic // constructor for various implementations of the SecretKeyRing interface. A // string naming the returned interface, and the SecretKeyRing interface itself diff --git a/lnencrypt/test_utils.go b/lnencrypt/test_utils.go index 1dd381eb383..c4d44164829 100644 --- a/lnencrypt/test_utils.go +++ b/lnencrypt/test_utils.go @@ -38,3 +38,9 @@ func (m *MockKeyRing) DeriveKey( PubKey: pub, }, nil } + +func (m *MockKeyRing) DeriveAndStoreKey( + keyLoc keychain.KeyLocator) (keychain.KeyDescriptor, error) { + + return m.DeriveKey(keyLoc) +} diff --git a/lnrpc/walletrpc/walletkit.pb.go b/lnrpc/walletrpc/walletkit.pb.go index 5e6df7a9838..c284cd47c8b 100644 --- a/lnrpc/walletrpc/walletkit.pb.go +++ b/lnrpc/walletrpc/walletkit.pb.go @@ -5381,7 +5381,7 @@ const file_walletrpc_walletkit_proto_rawDesc = "" + "\x1fTAPROOT_COMMITMENT_REVOKE_FINAL\x10**V\n" + "\x11ChangeAddressType\x12#\n" + "\x1fCHANGE_ADDRESS_TYPE_UNSPECIFIED\x10\x00\x12\x1c\n" + - "\x18CHANGE_ADDRESS_TYPE_P2TR\x10\x012\x81\x13\n" + + "\x18CHANGE_ADDRESS_TYPE_P2TR\x10\x012\xc3\x13\n" + "\tWalletKit\x12L\n" + "\vListUnspent\x12\x1d.walletrpc.ListUnspentRequest\x1a\x1e.walletrpc.ListUnspentResponse\x12L\n" + "\vLeaseOutput\x12\x1d.walletrpc.LeaseOutputRequest\x1a\x1e.walletrpc.LeaseOutputResponse\x12R\n" + @@ -5389,7 +5389,8 @@ const file_walletrpc_walletkit_proto_rawDesc = "" + "\n" + "ListLeases\x12\x1c.walletrpc.ListLeasesRequest\x1a\x1d.walletrpc.ListLeasesResponse\x12:\n" + "\rDeriveNextKey\x12\x11.walletrpc.KeyReq\x1a\x16.signrpc.KeyDescriptor\x128\n" + - "\tDeriveKey\x12\x13.signrpc.KeyLocator\x1a\x16.signrpc.KeyDescriptor\x12;\n" + + "\tDeriveKey\x12\x13.signrpc.KeyLocator\x1a\x16.signrpc.KeyDescriptor\x12@\n" + + "\x11DeriveAndStoreKey\x12\x13.signrpc.KeyLocator\x1a\x16.signrpc.KeyDescriptor\x12;\n" + "\bNextAddr\x12\x16.walletrpc.AddrRequest\x1a\x17.walletrpc.AddrResponse\x12F\n" + "\x0eGetTransaction\x12 .walletrpc.GetTransactionRequest\x1a\x12.lnrpc.Transaction\x12O\n" + "\fListAccounts\x12\x1e.walletrpc.ListAccountsRequest\x1a\x1f.walletrpc.ListAccountsResponse\x12U\n" + @@ -5559,62 +5560,64 @@ var file_walletrpc_walletkit_proto_depIdxs = []int32{ 67, // 42: walletrpc.WalletKit.ListLeases:input_type -> walletrpc.ListLeasesRequest 9, // 43: walletrpc.WalletKit.DeriveNextKey:input_type -> walletrpc.KeyReq 78, // 44: walletrpc.WalletKit.DeriveKey:input_type -> signrpc.KeyLocator - 10, // 45: walletrpc.WalletKit.NextAddr:input_type -> walletrpc.AddrRequest - 23, // 46: walletrpc.WalletKit.GetTransaction:input_type -> walletrpc.GetTransactionRequest - 15, // 47: walletrpc.WalletKit.ListAccounts:input_type -> walletrpc.ListAccountsRequest - 17, // 48: walletrpc.WalletKit.XCreateAccount:input_type -> walletrpc.XCreateAccountRequest - 19, // 49: walletrpc.WalletKit.RequiredReserve:input_type -> walletrpc.RequiredReserveRequest - 21, // 50: walletrpc.WalletKit.ListAddresses:input_type -> walletrpc.ListAddressesRequest - 24, // 51: walletrpc.WalletKit.SignMessageWithAddr:input_type -> walletrpc.SignMessageWithAddrRequest - 26, // 52: walletrpc.WalletKit.VerifyMessageWithAddr:input_type -> walletrpc.VerifyMessageWithAddrRequest - 28, // 53: walletrpc.WalletKit.ImportAccount:input_type -> walletrpc.ImportAccountRequest - 30, // 54: walletrpc.WalletKit.ImportPublicKey:input_type -> walletrpc.ImportPublicKeyRequest - 32, // 55: walletrpc.WalletKit.ImportTapscript:input_type -> walletrpc.ImportTapscriptRequest - 37, // 56: walletrpc.WalletKit.PublishTransaction:input_type -> walletrpc.Transaction - 39, // 57: walletrpc.WalletKit.SubmitPackage:input_type -> walletrpc.SubmitPackageRequest - 23, // 58: walletrpc.WalletKit.RemoveTransaction:input_type -> walletrpc.GetTransactionRequest - 43, // 59: walletrpc.WalletKit.SendOutputs:input_type -> walletrpc.SendOutputsRequest - 45, // 60: walletrpc.WalletKit.EstimateFee:input_type -> walletrpc.EstimateFeeRequest - 48, // 61: walletrpc.WalletKit.PendingSweeps:input_type -> walletrpc.PendingSweepsRequest - 50, // 62: walletrpc.WalletKit.BumpFee:input_type -> walletrpc.BumpFeeRequest - 52, // 63: walletrpc.WalletKit.BumpForceCloseFee:input_type -> walletrpc.BumpForceCloseFeeRequest - 54, // 64: walletrpc.WalletKit.ListSweeps:input_type -> walletrpc.ListSweepsRequest - 56, // 65: walletrpc.WalletKit.LabelTransaction:input_type -> walletrpc.LabelTransactionRequest - 58, // 66: walletrpc.WalletKit.FundPsbt:input_type -> walletrpc.FundPsbtRequest - 63, // 67: walletrpc.WalletKit.SignPsbt:input_type -> walletrpc.SignPsbtRequest - 65, // 68: walletrpc.WalletKit.FinalizePsbt:input_type -> walletrpc.FinalizePsbtRequest - 4, // 69: walletrpc.WalletKit.ListUnspent:output_type -> walletrpc.ListUnspentResponse - 6, // 70: walletrpc.WalletKit.LeaseOutput:output_type -> walletrpc.LeaseOutputResponse - 8, // 71: walletrpc.WalletKit.ReleaseOutput:output_type -> walletrpc.ReleaseOutputResponse - 68, // 72: walletrpc.WalletKit.ListLeases:output_type -> walletrpc.ListLeasesResponse - 79, // 73: walletrpc.WalletKit.DeriveNextKey:output_type -> signrpc.KeyDescriptor - 79, // 74: walletrpc.WalletKit.DeriveKey:output_type -> signrpc.KeyDescriptor - 11, // 75: walletrpc.WalletKit.NextAddr:output_type -> walletrpc.AddrResponse - 80, // 76: walletrpc.WalletKit.GetTransaction:output_type -> lnrpc.Transaction - 16, // 77: walletrpc.WalletKit.ListAccounts:output_type -> walletrpc.ListAccountsResponse - 18, // 78: walletrpc.WalletKit.XCreateAccount:output_type -> walletrpc.XCreateAccountResponse - 20, // 79: walletrpc.WalletKit.RequiredReserve:output_type -> walletrpc.RequiredReserveResponse - 22, // 80: walletrpc.WalletKit.ListAddresses:output_type -> walletrpc.ListAddressesResponse - 25, // 81: walletrpc.WalletKit.SignMessageWithAddr:output_type -> walletrpc.SignMessageWithAddrResponse - 27, // 82: walletrpc.WalletKit.VerifyMessageWithAddr:output_type -> walletrpc.VerifyMessageWithAddrResponse - 29, // 83: walletrpc.WalletKit.ImportAccount:output_type -> walletrpc.ImportAccountResponse - 31, // 84: walletrpc.WalletKit.ImportPublicKey:output_type -> walletrpc.ImportPublicKeyResponse - 36, // 85: walletrpc.WalletKit.ImportTapscript:output_type -> walletrpc.ImportTapscriptResponse - 38, // 86: walletrpc.WalletKit.PublishTransaction:output_type -> walletrpc.PublishResponse - 41, // 87: walletrpc.WalletKit.SubmitPackage:output_type -> walletrpc.SubmitPackageResponse - 42, // 88: walletrpc.WalletKit.RemoveTransaction:output_type -> walletrpc.RemoveTransactionResponse - 44, // 89: walletrpc.WalletKit.SendOutputs:output_type -> walletrpc.SendOutputsResponse - 46, // 90: walletrpc.WalletKit.EstimateFee:output_type -> walletrpc.EstimateFeeResponse - 49, // 91: walletrpc.WalletKit.PendingSweeps:output_type -> walletrpc.PendingSweepsResponse - 51, // 92: walletrpc.WalletKit.BumpFee:output_type -> walletrpc.BumpFeeResponse - 53, // 93: walletrpc.WalletKit.BumpForceCloseFee:output_type -> walletrpc.BumpForceCloseFeeResponse - 55, // 94: walletrpc.WalletKit.ListSweeps:output_type -> walletrpc.ListSweepsResponse - 57, // 95: walletrpc.WalletKit.LabelTransaction:output_type -> walletrpc.LabelTransactionResponse - 59, // 96: walletrpc.WalletKit.FundPsbt:output_type -> walletrpc.FundPsbtResponse - 64, // 97: walletrpc.WalletKit.SignPsbt:output_type -> walletrpc.SignPsbtResponse - 66, // 98: walletrpc.WalletKit.FinalizePsbt:output_type -> walletrpc.FinalizePsbtResponse - 69, // [69:99] is the sub-list for method output_type - 39, // [39:69] is the sub-list for method input_type + 78, // 45: walletrpc.WalletKit.DeriveAndStoreKey:input_type -> signrpc.KeyLocator + 10, // 46: walletrpc.WalletKit.NextAddr:input_type -> walletrpc.AddrRequest + 23, // 47: walletrpc.WalletKit.GetTransaction:input_type -> walletrpc.GetTransactionRequest + 15, // 48: walletrpc.WalletKit.ListAccounts:input_type -> walletrpc.ListAccountsRequest + 17, // 49: walletrpc.WalletKit.XCreateAccount:input_type -> walletrpc.XCreateAccountRequest + 19, // 50: walletrpc.WalletKit.RequiredReserve:input_type -> walletrpc.RequiredReserveRequest + 21, // 51: walletrpc.WalletKit.ListAddresses:input_type -> walletrpc.ListAddressesRequest + 24, // 52: walletrpc.WalletKit.SignMessageWithAddr:input_type -> walletrpc.SignMessageWithAddrRequest + 26, // 53: walletrpc.WalletKit.VerifyMessageWithAddr:input_type -> walletrpc.VerifyMessageWithAddrRequest + 28, // 54: walletrpc.WalletKit.ImportAccount:input_type -> walletrpc.ImportAccountRequest + 30, // 55: walletrpc.WalletKit.ImportPublicKey:input_type -> walletrpc.ImportPublicKeyRequest + 32, // 56: walletrpc.WalletKit.ImportTapscript:input_type -> walletrpc.ImportTapscriptRequest + 37, // 57: walletrpc.WalletKit.PublishTransaction:input_type -> walletrpc.Transaction + 39, // 58: walletrpc.WalletKit.SubmitPackage:input_type -> walletrpc.SubmitPackageRequest + 23, // 59: walletrpc.WalletKit.RemoveTransaction:input_type -> walletrpc.GetTransactionRequest + 43, // 60: walletrpc.WalletKit.SendOutputs:input_type -> walletrpc.SendOutputsRequest + 45, // 61: walletrpc.WalletKit.EstimateFee:input_type -> walletrpc.EstimateFeeRequest + 48, // 62: walletrpc.WalletKit.PendingSweeps:input_type -> walletrpc.PendingSweepsRequest + 50, // 63: walletrpc.WalletKit.BumpFee:input_type -> walletrpc.BumpFeeRequest + 52, // 64: walletrpc.WalletKit.BumpForceCloseFee:input_type -> walletrpc.BumpForceCloseFeeRequest + 54, // 65: walletrpc.WalletKit.ListSweeps:input_type -> walletrpc.ListSweepsRequest + 56, // 66: walletrpc.WalletKit.LabelTransaction:input_type -> walletrpc.LabelTransactionRequest + 58, // 67: walletrpc.WalletKit.FundPsbt:input_type -> walletrpc.FundPsbtRequest + 63, // 68: walletrpc.WalletKit.SignPsbt:input_type -> walletrpc.SignPsbtRequest + 65, // 69: walletrpc.WalletKit.FinalizePsbt:input_type -> walletrpc.FinalizePsbtRequest + 4, // 70: walletrpc.WalletKit.ListUnspent:output_type -> walletrpc.ListUnspentResponse + 6, // 71: walletrpc.WalletKit.LeaseOutput:output_type -> walletrpc.LeaseOutputResponse + 8, // 72: walletrpc.WalletKit.ReleaseOutput:output_type -> walletrpc.ReleaseOutputResponse + 68, // 73: walletrpc.WalletKit.ListLeases:output_type -> walletrpc.ListLeasesResponse + 79, // 74: walletrpc.WalletKit.DeriveNextKey:output_type -> signrpc.KeyDescriptor + 79, // 75: walletrpc.WalletKit.DeriveKey:output_type -> signrpc.KeyDescriptor + 79, // 76: walletrpc.WalletKit.DeriveAndStoreKey:output_type -> signrpc.KeyDescriptor + 11, // 77: walletrpc.WalletKit.NextAddr:output_type -> walletrpc.AddrResponse + 80, // 78: walletrpc.WalletKit.GetTransaction:output_type -> lnrpc.Transaction + 16, // 79: walletrpc.WalletKit.ListAccounts:output_type -> walletrpc.ListAccountsResponse + 18, // 80: walletrpc.WalletKit.XCreateAccount:output_type -> walletrpc.XCreateAccountResponse + 20, // 81: walletrpc.WalletKit.RequiredReserve:output_type -> walletrpc.RequiredReserveResponse + 22, // 82: walletrpc.WalletKit.ListAddresses:output_type -> walletrpc.ListAddressesResponse + 25, // 83: walletrpc.WalletKit.SignMessageWithAddr:output_type -> walletrpc.SignMessageWithAddrResponse + 27, // 84: walletrpc.WalletKit.VerifyMessageWithAddr:output_type -> walletrpc.VerifyMessageWithAddrResponse + 29, // 85: walletrpc.WalletKit.ImportAccount:output_type -> walletrpc.ImportAccountResponse + 31, // 86: walletrpc.WalletKit.ImportPublicKey:output_type -> walletrpc.ImportPublicKeyResponse + 36, // 87: walletrpc.WalletKit.ImportTapscript:output_type -> walletrpc.ImportTapscriptResponse + 38, // 88: walletrpc.WalletKit.PublishTransaction:output_type -> walletrpc.PublishResponse + 41, // 89: walletrpc.WalletKit.SubmitPackage:output_type -> walletrpc.SubmitPackageResponse + 42, // 90: walletrpc.WalletKit.RemoveTransaction:output_type -> walletrpc.RemoveTransactionResponse + 44, // 91: walletrpc.WalletKit.SendOutputs:output_type -> walletrpc.SendOutputsResponse + 46, // 92: walletrpc.WalletKit.EstimateFee:output_type -> walletrpc.EstimateFeeResponse + 49, // 93: walletrpc.WalletKit.PendingSweeps:output_type -> walletrpc.PendingSweepsResponse + 51, // 94: walletrpc.WalletKit.BumpFee:output_type -> walletrpc.BumpFeeResponse + 53, // 95: walletrpc.WalletKit.BumpForceCloseFee:output_type -> walletrpc.BumpForceCloseFeeResponse + 55, // 96: walletrpc.WalletKit.ListSweeps:output_type -> walletrpc.ListSweepsResponse + 57, // 97: walletrpc.WalletKit.LabelTransaction:output_type -> walletrpc.LabelTransactionResponse + 59, // 98: walletrpc.WalletKit.FundPsbt:output_type -> walletrpc.FundPsbtResponse + 64, // 99: walletrpc.WalletKit.SignPsbt:output_type -> walletrpc.SignPsbtResponse + 66, // 100: walletrpc.WalletKit.FinalizePsbt:output_type -> walletrpc.FinalizePsbtResponse + 70, // [70:101] is the sub-list for method output_type + 39, // [39:70] is the sub-list for method input_type 39, // [39:39] is the sub-list for extension type_name 39, // [39:39] is the sub-list for extension extendee 0, // [0:39] is the sub-list for field type_name diff --git a/lnrpc/walletrpc/walletkit.pb.gw.go b/lnrpc/walletrpc/walletkit.pb.gw.go index 643ddb013f5..976985c0938 100644 --- a/lnrpc/walletrpc/walletkit.pb.gw.go +++ b/lnrpc/walletrpc/walletkit.pb.gw.go @@ -220,6 +220,40 @@ func local_request_WalletKit_DeriveKey_0(ctx context.Context, marshaler runtime. } +func request_WalletKit_DeriveAndStoreKey_0(ctx context.Context, marshaler runtime.Marshaler, client WalletKitClient, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) { + var protoReq signrpc.KeyLocator + var metadata runtime.ServerMetadata + + newReader, berr := utilities.IOReaderFactory(req.Body) + if berr != nil { + return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", berr) + } + if err := marshaler.NewDecoder(newReader()).Decode(&protoReq); err != nil && err != io.EOF { + return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err) + } + + msg, err := client.DeriveAndStoreKey(ctx, &protoReq, grpc.Header(&metadata.HeaderMD), grpc.Trailer(&metadata.TrailerMD)) + return msg, metadata, err + +} + +func local_request_WalletKit_DeriveAndStoreKey_0(ctx context.Context, marshaler runtime.Marshaler, server WalletKitServer, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) { + var protoReq signrpc.KeyLocator + var metadata runtime.ServerMetadata + + newReader, berr := utilities.IOReaderFactory(req.Body) + if berr != nil { + return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", berr) + } + if err := marshaler.NewDecoder(newReader()).Decode(&protoReq); err != nil && err != io.EOF { + return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err) + } + + msg, err := server.DeriveAndStoreKey(ctx, &protoReq) + return msg, metadata, err + +} + func request_WalletKit_NextAddr_0(ctx context.Context, marshaler runtime.Marshaler, client WalletKitClient, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) { var protoReq AddrRequest var metadata runtime.ServerMetadata @@ -1204,6 +1238,31 @@ func RegisterWalletKitHandlerServer(ctx context.Context, mux *runtime.ServeMux, }) + mux.Handle("POST", pattern_WalletKit_DeriveAndStoreKey_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) { + ctx, cancel := context.WithCancel(req.Context()) + defer cancel() + var stream runtime.ServerTransportStream + ctx = grpc.NewContextWithServerTransportStream(ctx, &stream) + inboundMarshaler, outboundMarshaler := runtime.MarshalerForRequest(mux, req) + var err error + var annotatedContext context.Context + annotatedContext, err = runtime.AnnotateIncomingContext(ctx, mux, req, "/walletrpc.WalletKit/DeriveAndStoreKey", runtime.WithHTTPPathPattern("/v2/wallet/key/store")) + if err != nil { + runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err) + return + } + resp, md, err := local_request_WalletKit_DeriveAndStoreKey_0(annotatedContext, inboundMarshaler, server, req, pathParams) + md.HeaderMD, md.TrailerMD = metadata.Join(md.HeaderMD, stream.Header()), metadata.Join(md.TrailerMD, stream.Trailer()) + annotatedContext = runtime.NewServerMetadataContext(annotatedContext, md) + if err != nil { + runtime.HTTPError(annotatedContext, mux, outboundMarshaler, w, req, err) + return + } + + forward_WalletKit_DeriveAndStoreKey_0(annotatedContext, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...) + + }) + mux.Handle("POST", pattern_WalletKit_NextAddr_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) { ctx, cancel := context.WithCancel(req.Context()) defer cancel() @@ -1977,6 +2036,28 @@ func RegisterWalletKitHandlerClient(ctx context.Context, mux *runtime.ServeMux, }) + mux.Handle("POST", pattern_WalletKit_DeriveAndStoreKey_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) { + ctx, cancel := context.WithCancel(req.Context()) + defer cancel() + inboundMarshaler, outboundMarshaler := runtime.MarshalerForRequest(mux, req) + var err error + var annotatedContext context.Context + annotatedContext, err = runtime.AnnotateContext(ctx, mux, req, "/walletrpc.WalletKit/DeriveAndStoreKey", runtime.WithHTTPPathPattern("/v2/wallet/key/store")) + if err != nil { + runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err) + return + } + resp, md, err := request_WalletKit_DeriveAndStoreKey_0(annotatedContext, inboundMarshaler, client, req, pathParams) + annotatedContext = runtime.NewServerMetadataContext(annotatedContext, md) + if err != nil { + runtime.HTTPError(annotatedContext, mux, outboundMarshaler, w, req, err) + return + } + + forward_WalletKit_DeriveAndStoreKey_0(annotatedContext, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...) + + }) + mux.Handle("POST", pattern_WalletKit_NextAddr_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) { ctx, cancel := context.WithCancel(req.Context()) defer cancel() @@ -2521,6 +2602,8 @@ var ( pattern_WalletKit_DeriveKey_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2}, []string{"v2", "wallet", "key"}, "")) + pattern_WalletKit_DeriveAndStoreKey_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2, 2, 3}, []string{"v2", "wallet", "key", "store"}, "")) + pattern_WalletKit_NextAddr_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2, 2, 3}, []string{"v2", "wallet", "address", "next"}, "")) pattern_WalletKit_GetTransaction_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2}, []string{"v2", "wallet", "tx"}, "")) @@ -2583,6 +2666,8 @@ var ( forward_WalletKit_DeriveKey_0 = runtime.ForwardResponseMessage + forward_WalletKit_DeriveAndStoreKey_0 = runtime.ForwardResponseMessage + forward_WalletKit_NextAddr_0 = runtime.ForwardResponseMessage forward_WalletKit_GetTransaction_0 = runtime.ForwardResponseMessage diff --git a/lnrpc/walletrpc/walletkit.pb.json.go b/lnrpc/walletrpc/walletkit.pb.json.go index 2155633f576..55314eb0b38 100644 --- a/lnrpc/walletrpc/walletkit.pb.json.go +++ b/lnrpc/walletrpc/walletkit.pb.json.go @@ -172,6 +172,31 @@ func RegisterWalletKitJSONCallbacks(registry map[string]func(ctx context.Context callback(string(respBytes), nil) } + registry["walletrpc.WalletKit.DeriveAndStoreKey"] = func(ctx context.Context, + conn *grpc.ClientConn, reqJSON string, callback func(string, error)) { + + req := &signrpc.KeyLocator{} + err := marshaler.Unmarshal([]byte(reqJSON), req) + if err != nil { + callback("", err) + return + } + + client := NewWalletKitClient(conn) + resp, err := client.DeriveAndStoreKey(ctx, req) + if err != nil { + callback("", err) + return + } + + respBytes, err := marshaler.Marshal(resp) + if err != nil { + callback("", err) + return + } + callback(string(respBytes), nil) + } + registry["walletrpc.WalletKit.NextAddr"] = func(ctx context.Context, conn *grpc.ClientConn, reqJSON string, callback func(string, error)) { diff --git a/lnrpc/walletrpc/walletkit.proto b/lnrpc/walletrpc/walletkit.proto index 2be3b8352c1..196373db1b2 100644 --- a/lnrpc/walletrpc/walletkit.proto +++ b/lnrpc/walletrpc/walletkit.proto @@ -74,9 +74,45 @@ service WalletKit { /* DeriveKey attempts to derive an arbitrary key specified by the passed KeyLocator. + + NOTE: The derived key is not recorded in the wallet, so it will not show up + in ListAccounts or ListAddresses, and the wallet will not be able to map the + returned public key back to its KeyLocator later on. Since that mapping is + required to sign with a key, callers that intend to sign with the derived + key must use DeriveAndStoreKey instead. */ rpc DeriveKey (signrpc.KeyLocator) returns (signrpc.KeyDescriptor); + /* + DeriveAndStoreKey attempts to derive an arbitrary key specified by the + passed KeyLocator, and also records that key in the wallet. This is the + variant of DeriveKey that must be used for a key the wallet is later + expected to sign with, since signing requires the wallet to be able to look + the key's KeyLocator back up. + + Recording a key implies recording every key in the family that precedes it, + so on return the family's next index (as reported by the external key count + in ListAccounts) is guaranteed to be above the requested one, and any key at + or below it will not be handed out by DeriveNextKey again. This makes the + call usable to restore a key family's derivation index after the wallet was + recovered from seed, where the wallet has no record of the indexes an + external consumer of the key family already used. + + The call is monotonic and idempotent: an index the family has already + advanced past leaves the wallet untouched, and the family's index is never + rewound. To bound the amount of work a single call can trigger, an error is + returned if reaching the requested index would require deriving more than + 25,000 keys. Key families that lnd itself derives from are reserved and + cannot be advanced through this RPC. + + NOTE: Keys in custom key families are not covered by lnd's on-chain + recovery scan guarantees. A consumer that uses them to control on-chain + outputs is expected to keep its own record of the indexes it consumed + (which this RPC exists to restore), since a large unused index gap within + a family can prevent a seed-only recovery from finding later keys. + */ + rpc DeriveAndStoreKey (signrpc.KeyLocator) returns (signrpc.KeyDescriptor); + /* NextAddr returns the next unused address within the wallet. */ diff --git a/lnrpc/walletrpc/walletkit.swagger.json b/lnrpc/walletrpc/walletkit.swagger.json index ce5b1b7601a..9daa54687e2 100644 --- a/lnrpc/walletrpc/walletkit.swagger.json +++ b/lnrpc/walletrpc/walletkit.swagger.json @@ -374,6 +374,7 @@ "/v2/wallet/key": { "post": { "summary": "DeriveKey attempts to derive an arbitrary key specified by the passed\nKeyLocator.", + "description": "NOTE: The derived key is not recorded in the wallet, so it will not show up\nin ListAccounts or ListAddresses, and the wallet will not be able to map the\nreturned public key back to its KeyLocator later on. Since that mapping is\nrequired to sign with a key, callers that intend to sign with the derived\nkey must use DeriveAndStoreKey instead.", "operationId": "WalletKit_DeriveKey", "responses": { "200": { @@ -471,6 +472,40 @@ ] } }, + "/v2/wallet/key/store": { + "post": { + "summary": "DeriveAndStoreKey attempts to derive an arbitrary key specified by the\npassed KeyLocator, and also records that key in the wallet. This is the\nvariant of DeriveKey that must be used for a key the wallet is later\nexpected to sign with, since signing requires the wallet to be able to look\nthe key's KeyLocator back up.", + "description": "Recording a key implies recording every key in the family that precedes it,\nso on return the family's next index (as reported by the external key count\nin ListAccounts) is guaranteed to be above the requested one, and any key at\nor below it will not be handed out by DeriveNextKey again. This makes the\ncall usable to restore a key family's derivation index after the wallet was\nrecovered from seed, where the wallet has no record of the indexes an\nexternal consumer of the key family already used.\n\nThe call is monotonic and idempotent: an index the family has already\nadvanced past leaves the wallet untouched, and the family's index is never\nrewound. To bound the amount of work a single call can trigger, an error is\nreturned if reaching the requested index would require deriving more than\n25,000 keys. Key families that lnd itself derives from are reserved and\ncannot be advanced through this RPC.\n\nNOTE: Keys in custom key families are not covered by lnd's on-chain\nrecovery scan guarantees. A consumer that uses them to control on-chain\noutputs is expected to keep its own record of the indexes it consumed\n(which this RPC exists to restore), since a large unused index gap within\na family can prevent a seed-only recovery from finding later keys.", + "operationId": "WalletKit_DeriveAndStoreKey", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/signrpcKeyDescriptor" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/signrpcKeyLocator" + } + } + ], + "tags": [ + "WalletKit" + ] + } + }, "/v2/wallet/psbt/finalize": { "post": { "summary": "lncli: `wallet psbt finalize`\nFinalizePsbt expects a partial transaction with all inputs and outputs fully\ndeclared and tries to sign all inputs that belong to the wallet. Lnd must be\nthe last signer of the transaction. That means, if there are any unsigned\nnon-witness inputs or inputs without UTXO information attached or inputs\nwithout witness data that do not belong to lnd's wallet, this method will\nfail. If no error is returned, the PSBT is ready to be extracted and the\nfinal TX within to be broadcast.", diff --git a/lnrpc/walletrpc/walletkit.yaml b/lnrpc/walletrpc/walletkit.yaml index d726aefb3d1..e580b4b09ee 100644 --- a/lnrpc/walletrpc/walletkit.yaml +++ b/lnrpc/walletrpc/walletkit.yaml @@ -20,6 +20,9 @@ http: - selector: walletrpc.WalletKit.DeriveKey post: "/v2/wallet/key" body: "*" + - selector: walletrpc.WalletKit.DeriveAndStoreKey + post: "/v2/wallet/key/store" + body: "*" - selector: walletrpc.WalletKit.ImportPublicKey post: "/v2/wallet/key/import" body: "*" diff --git a/lnrpc/walletrpc/walletkit_grpc.pb.go b/lnrpc/walletrpc/walletkit_grpc.pb.go index a51e7ca8912..05e4a529ce1 100644 --- a/lnrpc/walletrpc/walletkit_grpc.pb.go +++ b/lnrpc/walletrpc/walletkit_grpc.pb.go @@ -56,8 +56,42 @@ type WalletKitClient interface { // //DeriveKey attempts to derive an arbitrary key specified by the passed //KeyLocator. + // + //NOTE: The derived key is not recorded in the wallet, so it will not show up + //in ListAccounts or ListAddresses, and the wallet will not be able to map the + //returned public key back to its KeyLocator later on. Since that mapping is + //required to sign with a key, callers that intend to sign with the derived + //key must use DeriveAndStoreKey instead. DeriveKey(ctx context.Context, in *signrpc.KeyLocator, opts ...grpc.CallOption) (*signrpc.KeyDescriptor, error) // + //DeriveAndStoreKey attempts to derive an arbitrary key specified by the + //passed KeyLocator, and also records that key in the wallet. This is the + //variant of DeriveKey that must be used for a key the wallet is later + //expected to sign with, since signing requires the wallet to be able to look + //the key's KeyLocator back up. + // + //Recording a key implies recording every key in the family that precedes it, + //so on return the family's next index (as reported by the external key count + //in ListAccounts) is guaranteed to be above the requested one, and any key at + //or below it will not be handed out by DeriveNextKey again. This makes the + //call usable to restore a key family's derivation index after the wallet was + //recovered from seed, where the wallet has no record of the indexes an + //external consumer of the key family already used. + // + //The call is monotonic and idempotent: an index the family has already + //advanced past leaves the wallet untouched, and the family's index is never + //rewound. To bound the amount of work a single call can trigger, an error is + //returned if reaching the requested index would require deriving more than + //25,000 keys. Key families that lnd itself derives from are reserved and + //cannot be advanced through this RPC. + // + //NOTE: Keys in custom key families are not covered by lnd's on-chain + //recovery scan guarantees. A consumer that uses them to control on-chain + //outputs is expected to keep its own record of the indexes it consumed + //(which this RPC exists to restore), since a large unused index gap within + //a family can prevent a seed-only recovery from finding later keys. + DeriveAndStoreKey(ctx context.Context, in *signrpc.KeyLocator, opts ...grpc.CallOption) (*signrpc.KeyDescriptor, error) + // //NextAddr returns the next unused address within the wallet. NextAddr(ctx context.Context, in *AddrRequest, opts ...grpc.CallOption) (*AddrResponse, error) // lncli: `wallet gettx` @@ -432,6 +466,15 @@ func (c *walletKitClient) DeriveKey(ctx context.Context, in *signrpc.KeyLocator, return out, nil } +func (c *walletKitClient) DeriveAndStoreKey(ctx context.Context, in *signrpc.KeyLocator, opts ...grpc.CallOption) (*signrpc.KeyDescriptor, error) { + out := new(signrpc.KeyDescriptor) + err := c.cc.Invoke(ctx, "/walletrpc.WalletKit/DeriveAndStoreKey", in, out, opts...) + if err != nil { + return nil, err + } + return out, nil +} + func (c *walletKitClient) NextAddr(ctx context.Context, in *AddrRequest, opts ...grpc.CallOption) (*AddrResponse, error) { out := new(AddrResponse) err := c.cc.Invoke(ctx, "/walletrpc.WalletKit/NextAddr", in, out, opts...) @@ -688,8 +731,42 @@ type WalletKitServer interface { // //DeriveKey attempts to derive an arbitrary key specified by the passed //KeyLocator. + // + //NOTE: The derived key is not recorded in the wallet, so it will not show up + //in ListAccounts or ListAddresses, and the wallet will not be able to map the + //returned public key back to its KeyLocator later on. Since that mapping is + //required to sign with a key, callers that intend to sign with the derived + //key must use DeriveAndStoreKey instead. DeriveKey(context.Context, *signrpc.KeyLocator) (*signrpc.KeyDescriptor, error) // + //DeriveAndStoreKey attempts to derive an arbitrary key specified by the + //passed KeyLocator, and also records that key in the wallet. This is the + //variant of DeriveKey that must be used for a key the wallet is later + //expected to sign with, since signing requires the wallet to be able to look + //the key's KeyLocator back up. + // + //Recording a key implies recording every key in the family that precedes it, + //so on return the family's next index (as reported by the external key count + //in ListAccounts) is guaranteed to be above the requested one, and any key at + //or below it will not be handed out by DeriveNextKey again. This makes the + //call usable to restore a key family's derivation index after the wallet was + //recovered from seed, where the wallet has no record of the indexes an + //external consumer of the key family already used. + // + //The call is monotonic and idempotent: an index the family has already + //advanced past leaves the wallet untouched, and the family's index is never + //rewound. To bound the amount of work a single call can trigger, an error is + //returned if reaching the requested index would require deriving more than + //25,000 keys. Key families that lnd itself derives from are reserved and + //cannot be advanced through this RPC. + // + //NOTE: Keys in custom key families are not covered by lnd's on-chain + //recovery scan guarantees. A consumer that uses them to control on-chain + //outputs is expected to keep its own record of the indexes it consumed + //(which this RPC exists to restore), since a large unused index gap within + //a family can prevent a seed-only recovery from finding later keys. + DeriveAndStoreKey(context.Context, *signrpc.KeyLocator) (*signrpc.KeyDescriptor, error) + // //NextAddr returns the next unused address within the wallet. NextAddr(context.Context, *AddrRequest) (*AddrResponse, error) // lncli: `wallet gettx` @@ -1025,6 +1102,9 @@ func (UnimplementedWalletKitServer) DeriveNextKey(context.Context, *KeyReq) (*si func (UnimplementedWalletKitServer) DeriveKey(context.Context, *signrpc.KeyLocator) (*signrpc.KeyDescriptor, error) { return nil, status.Errorf(codes.Unimplemented, "method DeriveKey not implemented") } +func (UnimplementedWalletKitServer) DeriveAndStoreKey(context.Context, *signrpc.KeyLocator) (*signrpc.KeyDescriptor, error) { + return nil, status.Errorf(codes.Unimplemented, "method DeriveAndStoreKey not implemented") +} func (UnimplementedWalletKitServer) NextAddr(context.Context, *AddrRequest) (*AddrResponse, error) { return nil, status.Errorf(codes.Unimplemented, "method NextAddr not implemented") } @@ -1218,6 +1298,24 @@ func _WalletKit_DeriveKey_Handler(srv interface{}, ctx context.Context, dec func return interceptor(ctx, in, info, handler) } +func _WalletKit_DeriveAndStoreKey_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(signrpc.KeyLocator) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(WalletKitServer).DeriveAndStoreKey(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: "/walletrpc.WalletKit/DeriveAndStoreKey", + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(WalletKitServer).DeriveAndStoreKey(ctx, req.(*signrpc.KeyLocator)) + } + return interceptor(ctx, in, info, handler) +} + func _WalletKit_NextAddr_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { in := new(AddrRequest) if err := dec(in); err != nil { @@ -1681,6 +1779,10 @@ var WalletKit_ServiceDesc = grpc.ServiceDesc{ MethodName: "DeriveKey", Handler: _WalletKit_DeriveKey_Handler, }, + { + MethodName: "DeriveAndStoreKey", + Handler: _WalletKit_DeriveAndStoreKey_Handler, + }, { MethodName: "NextAddr", Handler: _WalletKit_NextAddr_Handler, diff --git a/lnrpc/walletrpc/walletkit_server.go b/lnrpc/walletrpc/walletkit_server.go index fe82b21611d..30a3ee27816 100644 --- a/lnrpc/walletrpc/walletkit_server.go +++ b/lnrpc/walletrpc/walletkit_server.go @@ -84,6 +84,10 @@ var ( Entity: "address", Action: "read", }}, + "/walletrpc.WalletKit/DeriveAndStoreKey": {{ + Entity: "address", + Action: "write", + }}, "/walletrpc.WalletKit/NextAddr": {{ Entity: "address", Action: "read", @@ -671,6 +675,49 @@ func (w *WalletKit) DeriveKey(ctx context.Context, }, nil } +// DeriveAndStoreKey attempts to derive an arbitrary key specified by the passed +// KeyLocator, and also records that key in the wallet so it can be signed with +// later on. Recording the key advances the family's next index past the +// requested one. +func (w *WalletKit) DeriveAndStoreKey(ctx context.Context, + req *signrpc.KeyLocator) (*signrpc.KeyDescriptor, error) { + + if req.KeyFamily < 0 { + return nil, fmt.Errorf("key family must not be negative") + } + if req.KeyIndex < 0 { + return nil, fmt.Errorf("key index must not be negative") + } + + // The key families lnd itself derives from are managed by their + // subsystems, and advancing one from the outside cannot be undone. Only + // custom families external consumers bring themselves can be advanced + // through this RPC. + family := keychain.KeyFamily(req.KeyFamily) + for _, reserved := range keychain.VersionZeroKeyFamilies { + if family == reserved { + return nil, fmt.Errorf("key family %d is reserved by "+ + "lnd and cannot be advanced externally", family) + } + } + + keyDesc, err := w.cfg.KeyRing.DeriveAndStoreKey(keychain.KeyLocator{ + Family: keychain.KeyFamily(req.KeyFamily), + Index: uint32(req.KeyIndex), + }) + if err != nil { + return nil, err + } + + return &signrpc.KeyDescriptor{ + KeyLoc: &signrpc.KeyLocator{ + KeyFamily: int32(keyDesc.Family), + KeyIndex: int32(keyDesc.Index), + }, + RawKeyBytes: keyDesc.PubKey.SerializeCompressed(), + }, nil +} + // NextAddr returns the next unused address within the wallet. func (w *WalletKit) NextAddr(ctx context.Context, req *AddrRequest) (*AddrResponse, error) { diff --git a/lntest/mock/secretkeyring.go b/lntest/mock/secretkeyring.go index 8ee76ad2f34..c88860d8583 100644 --- a/lntest/mock/secretkeyring.go +++ b/lntest/mock/secretkeyring.go @@ -32,6 +32,15 @@ func (s *SecretKeyRing) DeriveKey( }, nil } +// DeriveAndStoreKey currently returns dummy values. +func (s *SecretKeyRing) DeriveAndStoreKey( + _ keychain.KeyLocator) (keychain.KeyDescriptor, error) { + + return keychain.KeyDescriptor{ + PubKey: s.RootKey.PubKey(), + }, nil +} + // DerivePrivKey currently returns dummy values. func (s *SecretKeyRing) DerivePrivKey( _ keychain.KeyDescriptor) (*btcec.PrivateKey, error) { diff --git a/lntest/rpc/wallet_kit.go b/lntest/rpc/wallet_kit.go index eeab553cf32..6201f453475 100644 --- a/lntest/rpc/wallet_kit.go +++ b/lntest/rpc/wallet_kit.go @@ -42,6 +42,31 @@ func (h *HarnessRPC) DeriveKey(kl *signrpc.KeyLocator) *signrpc.KeyDescriptor { return key } +// DeriveAndStoreKey makes a RPC call to the node's WalletKitClient and asserts. +func (h *HarnessRPC) DeriveAndStoreKey( + kl *signrpc.KeyLocator) *signrpc.KeyDescriptor { + + ctxt, cancel := context.WithTimeout(h.runCtx, DefaultTimeout) + defer cancel() + + key, err := h.WalletKit.DeriveAndStoreKey(ctxt, kl) + h.NoError(err, "DeriveAndStoreKey") + + return key +} + +// DeriveAndStoreKeyErr makes a RPC call to the node's WalletKitClient and +// asserts that an error is returned. +func (h *HarnessRPC) DeriveAndStoreKeyErr(kl *signrpc.KeyLocator) error { + ctxt, cancel := context.WithTimeout(h.runCtx, DefaultTimeout) + defer cancel() + + _, err := h.WalletKit.DeriveAndStoreKey(ctxt, kl) + require.Error(h, err) + + return err +} + // SendOutputs makes a RPC call to the node's WalletKitClient and asserts. func (h *HarnessRPC) SendOutputs( req *walletrpc.SendOutputsRequest) *walletrpc.SendOutputsResponse { diff --git a/lnwallet/rpcwallet/rpcwallet.go b/lnwallet/rpcwallet/rpcwallet.go index c7181d19fba..314b59260ff 100644 --- a/lnwallet/rpcwallet/rpcwallet.go +++ b/lnwallet/rpcwallet/rpcwallet.go @@ -401,6 +401,17 @@ func (r *RPCKeyRing) DeriveKey( return r.watchOnlyKeyRing.DeriveKey(keyLoc) } +// DeriveAndStoreKey attempts to derive an arbitrary key specified by the passed +// KeyLocator, and also records that key in the watch-only wallet. Since only +// public derivation is involved, this does not require the remote signer. +// +// NOTE: This method is part of the keychain.KeyRing interface. +func (r *RPCKeyRing) DeriveAndStoreKey( + keyLoc keychain.KeyLocator) (keychain.KeyDescriptor, error) { + + return r.watchOnlyKeyRing.DeriveAndStoreKey(keyLoc) +} + // ECDH performs a scalar multiplication (ECDH-like operation) between the // target key descriptor and remote public key. The output returned will be the // sha256 of the resulting shared point serialized in compressed format. If k is diff --git a/watchtower/wtmock/keyring.go b/watchtower/wtmock/keyring.go index d1ddc204b16..901dd86df16 100644 --- a/watchtower/wtmock/keyring.go +++ b/watchtower/wtmock/keyring.go @@ -52,6 +52,17 @@ func (m *SecretKeyRing) DeriveKey( }, nil } +// DeriveAndStoreKey attempts to derive an arbitrary key specified by the passed +// KeyLocator, and also records that key in the wallet. The mock always records +// the keys it derives, so this is identical to DeriveKey. +// +// NOTE: This is part of the keychain.KeyRing interface. +func (m *SecretKeyRing) DeriveAndStoreKey( + keyLoc keychain.KeyLocator) (keychain.KeyDescriptor, error) { + + return m.DeriveKey(keyLoc) +} + // ECDH performs a scalar multiplication (ECDH-like operation) between the // target key descriptor and remote public key. The output returned will be the // sha256 of the resulting shared point serialized in compressed format. If k is