Skip to content

Commit 7e695f5

Browse files
Leo Weesegitbook-bot
Leo Weese
authored and
gitbook-bot
committed
GITBOOK-495: change request with no subject merged in GitBook
1 parent 4316e39 commit 7e695f5

File tree

5 files changed

+63
-235
lines changed

5 files changed

+63
-235
lines changed

‎SUMMARY.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,6 @@
7474
* [Sweeper](lightning-network-tools/lnd/sweeper.md)
7575
* [Debugging LND](lightning-network-tools/lnd/debugging_lnd.md)
7676
* [Fuzzing LND](lightning-network-tools/lnd/fuzz.md)
77-
* [LND and etcd](lightning-network-tools/lnd/etcd.md)
7877
* [LND API documentation](https://lightning.engineering/api-docs/api/lnd/)
7978
* [Channel Acceptor](lightning-network-tools/lnd/channel-acceptor.md)
8079
* [RPC Middleware Interceptor](lightning-network-tools/lnd/rpc-middleware-interceptor.md)

‎docs/lnd/key_import.md

Lines changed: 42 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,21 @@
1-
# Overview
1+
# Key Import
2+
3+
## Overview
24

3-
This document serves as an introductory point for users interested in reducing
4-
their hot-wallet risks, allowing them to maintain on-chain funds outside of
5-
`lnd` but still be able to manage them within `lnd`. As of `v0.13.0-beta`, `lnd`
6-
is able to import BIP-0049 and BIP-0084 extended public keys either at the
7-
account path (`m/purpose'/coin_type'/account'`) or at the address index path
8-
(`m/purpose'/coin_type'/account'/change/address_index`) as watch-only through
9-
the `WalletKit` APIs.
5+
This document serves as an introductory point for users interested in reducing their hot-wallet risks, allowing them to maintain on-chain funds outside of `lnd` but still be able to manage them within `lnd`. As of `v0.13.0-beta`, `lnd` is able to import BIP-0049 and BIP-0084 extended public keys either at the account path (`m/purpose'/coin_type'/account'`) or at the address index path (`m/purpose'/coin_type'/account'/change/address_index`) as watch-only through the `WalletKit` APIs.
106

11-
Note that in order to follow the rest of this document and/or use the
12-
`WalletKit` APIs, users will need to obtain an `lnd` build compiled with the
13-
`walletrpc` tag. Our release builds already include this tag by default, so this
14-
would only be necessary when compiling from source.
7+
Note that in order to follow the rest of this document and/or use the `WalletKit` APIs, users will need to obtain an `lnd` build compiled with the `walletrpc` tag. Our release builds already include this tag by default, so this would only be necessary when compiling from source.
158

16-
# `lnd`'s Default Wallet Accounts
9+
## `lnd`'s Default Wallet Accounts
1710

1811
Upon initializing `lnd`, a wallet is created with four default accounts:
1912

20-
* A custom BIP-0049 account (more on this later) to generate NP2WKH external
21-
addresses.
13+
* A custom BIP-0049 account (more on this later) to generate NP2WKH external addresses.
2214
* A BIP-0084 account to generate P2WKH external and change addresses.
23-
* A catch-all BIP-0049 account where all imported BIP-0049 address keys (NP2WKH
24-
addresses) exist within.
25-
* A catch-all BIP-0084 account where all imported BIP-0049 address keys (P2WKH
26-
addresses) exist within.
15+
* A catch-all BIP-0049 account where all imported BIP-0049 address keys (NP2WKH addresses) exist within.
16+
* A catch-all BIP-0084 account where all imported BIP-0049 address keys (P2WKH addresses) exist within.
2717

28-
Prior to `v0.13.0-beta`, these accounts were abstracted away from users. As part
29-
of the key import feature, they are now exposed through the new `WalletKit` RPCs
30-
(`ListAccounts`, `ImportAccount`, `ImportPublicKey`) and the `lncli wallet
31-
accounts` command.
18+
Prior to `v0.13.0-beta`, these accounts were abstracted away from users. As part of the key import feature, they are now exposed through the new `WalletKit` RPCs (`ListAccounts`, `ImportAccount`, `ImportPublicKey`) and the `lncli wallet accounts` command.
3219

3320
```shell
3421
$ lncli wallet accounts
@@ -47,12 +34,9 @@ OPTIONS:
4734
--help, -h show help
4835
```
4936

50-
## Account Details
37+
### Account Details
5138

52-
Before interacting with the new set of APIs, users will want to become familiar
53-
with how wallet accounts are represented within `lnd`. The
54-
`WalletKit.ListAccounts` RPC or `lncli wallet accounts list` command can be used
55-
to retrieve the details of accounts.
39+
Before interacting with the new set of APIs, users will want to become familiar with how wallet accounts are represented within `lnd`. The `WalletKit.ListAccounts` RPC or `lncli wallet accounts list` command can be used to retrieve the details of accounts.
5640

5741
```shell
5842
$ lncli wallet accounts list
@@ -82,79 +66,38 @@ $ lncli wallet accounts list
8266
}
8367
```
8468

85-
There's a lot to unpack in the response above, so let's cover each account field
86-
in detail. As mentioned above, four default accounts should exist, though only
87-
two are shown in the output. The catch-all imported accounts are hidden by
88-
default until a key has been imported into them.
89-
90-
* `name`: Each account has a name it can be identified by. `lnd`'s default
91-
spendable accounts have the name "default". The default catch-all imported
92-
accounts have the name "imported".
93-
* `extended_public_key`: The BIP-0044 extended public key for the account. Any
94-
addresses generated for the account are derived from this key. Each key has a
95-
version prefix that identifies the chain and derivation scheme being used. At
96-
the time of writing, `lnd` supports the following versions:
97-
* `xpub/tpub`: The commonly used version prefix originally intended for
98-
BIP-0032 mainnet/testnet extended keys. Since `lnd` does not support
99-
BIP-0032 extended keys, this version serves as a catch-all for the other
100-
versions.
69+
There's a lot to unpack in the response above, so let's cover each account field in detail. As mentioned above, four default accounts should exist, though only two are shown in the output. The catch-all imported accounts are hidden by default until a key has been imported into them.
70+
71+
* `name`: Each account has a name it can be identified by. `lnd`'s default spendable accounts have the name "default". The default catch-all imported accounts have the name "imported".
72+
* `extended_public_key`: The BIP-0044 extended public key for the account. Any addresses generated for the account are derived from this key. Each key has a version prefix that identifies the chain and derivation scheme being used. At the time of writing, `lnd` supports the following versions:
73+
* `xpub/tpub`: The commonly used version prefix originally intended for BIP-0032 mainnet/testnet extended keys. Since `lnd` does not support BIP-0032 extended keys, this version serves as a catch-all for the other versions.
10174
* `ypub/upub`: The version prefix for BIP-0049 mainnet/testnet extended keys.
10275
* `zpub/vpub`: The version prefix for BIP-0084 mainnet/testnet extended keys.
103-
* `address_type`: The type of addresses the account can derive. There are three
104-
supported address types:
105-
* `WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0084 with
106-
P2WKH for external and change addresses.
107-
* `NESTED_WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0049
108-
with P2WKH for external and change addresses.
109-
* `HYBRID_NESTED_WITNESS_PUBKEY_HASH` A custom derivation scheme for BIP-0049
110-
used by `lnd` where NP2WKH is used for external addresses and P2WKH for
111-
change addresses.
112-
* `master_key_fingerprint`: The 4 byte fingerprint of the master key
113-
corresponding to the account. This is usually required by hardware
114-
wallet/external signers to identify the proper signing key.
115-
* `derivation_path`: The BIP-0044 derivation path used on the master key to
116-
obtain the account key.
76+
* `address_type`: The type of addresses the account can derive. There are three supported address types:
77+
* `WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0084 with P2WKH for external and change addresses.
78+
* `NESTED_WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0049 with P2WKH for external and change addresses.
79+
* `HYBRID_NESTED_WITNESS_PUBKEY_HASH` A custom derivation scheme for BIP-0049 used by `lnd` where NP2WKH is used for external addresses and P2WKH for change addresses.
80+
* `master_key_fingerprint`: The 4 byte fingerprint of the master key corresponding to the account. This is usually required by hardware wallet/external signers to identify the proper signing key.
81+
* `derivation_path`: The BIP-0044 derivation path used on the master key to obtain the account key.
11782
* `external_key_count`: The number of external addresses generated.
11883
* `internal_key_count`: The number of change addresses generated.
119-
* `watch_only`: Whether the wallet has private key information for the account.
120-
`lnd`'s default wallet accounts always have private key information, so this
121-
value is `false`.
84+
* `watch_only`: Whether the wallet has private key information for the account. `lnd`'s default wallet accounts always have private key information, so this value is `false`.
12285

123-
# Key Import
86+
## Key Import
12487

125-
An existing limitation to the key import APIs is that events (deposits/spends)
126-
for imported keys, including those derived from an imported account, will only
127-
be detected by lnd if they happen after the import. Rescans to detect past
128-
events are currently not supported, but will come at a later time.
88+
An existing limitation to the key import APIs is that events (deposits/spends) for imported keys, including those derived from an imported account, will only be detected by lnd if they happen after the import. Rescans to detect past events are currently not supported, but will come at a later time.
12989

130-
## Account Key Import
90+
### Account Key Import
13191

132-
The `WalletKit.ImportAccount` RPC and `lncli wallet accounts import` command can
133-
be used to import an account. At the time of writing, importing an account has
134-
the following request parameters:
92+
The `WalletKit.ImportAccount` RPC and `lncli wallet accounts import` command can be used to import an account. At the time of writing, importing an account has the following request parameters:
13593

13694
* `name` (required): A name to identify the imported account with.
137-
* `extended_public_key` (required): A public key that corresponds to a wallet account
138-
represented as an extended key. It must conform to a derivation path of the
139-
form `m/purpose'/coin_type'/account'`.
140-
* `master_key_fingerprint` (optional): The fingerprint of the root key (also
141-
known as the key with derivation path m/) from which the account public key
142-
was derived from. This may be required by some hardware wallets for proper
143-
identification and signing.
144-
* `address_type` (optional): An address type is only required when the extended
145-
account public key has a legacy version (xpub, tpub, etc.), such that the
146-
wallet cannot detect what address scheme it belongs to.
147-
* `dry_run` (optional): Whether a dry run should be attempted when importing the
148-
account. This serves as a way to confirm whether the account is being imported
149-
correctly by returning the first N addresses for the external and internal
150-
branches of the account. If these addresses match as expected, then it should
151-
be safe to import the account as is.
152-
153-
For the sake of simplicity, we'll present an example with two `lnd` nodes Alice
154-
and Bob, where Alice acts as a signer _only_, and Bob manages Alice's on-chain
155-
BIP-0084 account by crafting transactions and watching/spending addresses. Since
156-
Alice will only act as a signer, we'll want to import her BIP-0084 account into
157-
Bob's node, which will require knowledge of Alice's extended public key.
95+
* `extended_public_key` (required): A public key that corresponds to a wallet account represented as an extended key. It must conform to a derivation path of the form `m/purpose'/coin_type'/account'`.
96+
* `master_key_fingerprint` (optional): The fingerprint of the root key (also known as the key with derivation path m/) from which the account public key was derived from. This may be required by some hardware wallets for proper identification and signing.
97+
* `address_type` (optional): An address type is only required when the extended account public key has a legacy version (xpub, tpub, etc.), such that the wallet cannot detect what address scheme it belongs to.
98+
* `dry_run` (optional): Whether a dry run should be attempted when importing the account. This serves as a way to confirm whether the account is being imported correctly by returning the first N addresses for the external and internal branches of the account. If these addresses match as expected, then it should be safe to import the account as is.
99+
100+
For the sake of simplicity, we'll present an example with two `lnd` nodes Alice and Bob, where Alice acts as a signer _only_, and Bob manages Alice's on-chain BIP-0084 account by crafting transactions and watching/spending addresses. Since Alice will only act as a signer, we'll want to import her BIP-0084 account into Bob's node, which will require knowledge of Alice's extended public key.
158101

159102
Alice's BIP-0084 extended public key can be obtained as follows.
160103

@@ -182,11 +125,7 @@ Bob can then import the account with the following command:
182125
$ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChEMGqtxiELfZB8hm6FwBpBvfPpX2HGG8edYVV9Wupe43PEJJhhfnz1egtQNNaDXyYExn alice
183126
```
184127

185-
Before Bob imports the account, they may want to confirm the account is being
186-
imported using the correct derivation scheme. This can be done with the dry run
187-
request parameter. When a dry run is done, the response will include the usual
188-
account details, as well as the first 5 external and change addresses, which can
189-
be used to confirm they match with what the account owner expects.
128+
Before Bob imports the account, they may want to confirm the account is being imported using the correct derivation scheme. This can be done with the dry run request parameter. When a dry run is done, the response will include the usual account details, as well as the first 5 external and change addresses, which can be used to confirm they match with what the account owner expects.
190129

191130
```shell
192131
$ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChEMGqtxiELfZB8hm6FwBpBvfPpX2HGG8edYVV9Wupe43PEJJhhfnz1egtQNNaDXyYExn alice --dry_run
@@ -218,8 +157,7 @@ $ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChE
218157
}
219158
```
220159

221-
Once Bob has confirmed the correct account derivation scheme is being used, the
222-
account can be imported without the dry run parameter.
160+
Once Bob has confirmed the correct account derivation scheme is being used, the account can be imported without the dry run parameter.
223161

224162
```shell
225163
$ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChEMGqtxiELfZB8hm6FwBpBvfPpX2HGG8edYVV9Wupe43PEJJhhfnz1egtQNNaDXyYExn alice
@@ -237,15 +175,11 @@ $ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChE
237175
}
238176
```
239177

240-
### Generating Addresses from an Imported Account
178+
#### Generating Addresses from an Imported Account
241179

242-
External addresses from an imported account can be generated through the
243-
existing `Lightning.NewAddress` RPC and `lncli newaddress` command, as they now
244-
take an additional optional parameter to specify which account the address
245-
should be derived from.
180+
External addresses from an imported account can be generated through the existing `Lightning.NewAddress` RPC and `lncli newaddress` command, as they now take an additional optional parameter to specify which account the address should be derived from.
246181

247-
Following the example above, Bob is able to generate an external address for an
248-
incoming deposit as follows:
182+
Following the example above, Bob is able to generate an external address for an incoming deposit as follows:
249183

250184
```shell
251185
$ lncli-bob newaddress p2wkh --account=alice
@@ -254,16 +188,11 @@ $ lncli-bob newaddress p2wkh --account=alice
254188
}
255189
```
256190

257-
Change addresses cannot be generated on demand, they are generated automatically
258-
when a transaction is crafted that requires a change output.
191+
Change addresses cannot be generated on demand, they are generated automatically when a transaction is crafted that requires a change output.
259192

260-
### Crafting Transactions through PSBTs from an Imported Account
193+
#### Crafting Transactions through PSBTs from an Imported Account
261194

262-
Assuming a deposit of 1 tBTC was made to the address above
263-
(`bcrt1q8zdjz2q92eh7jw9ah3upf2u9553226gq79el5l`), Bob should be able to craft a
264-
transaction spending their new UTXO. Since Bob is unable to sign the transaction
265-
themselves, they'll use PSBTs to craft the transaction, and provide it to Alice
266-
to sign.
195+
Assuming a deposit of 1 tBTC was made to the address above (`bcrt1q8zdjz2q92eh7jw9ah3upf2u9553226gq79el5l`), Bob should be able to craft a transaction spending their new UTXO. Since Bob is unable to sign the transaction themselves, they'll use PSBTs to craft the transaction, and provide it to Alice to sign.
267196

268197
```shell
269198
$ lncli-bob wallet psbt fund --account=alice --outputs="{\"bcrt1qpjqr663tylcksysa4u76xvremee9k8af3pqd5h\": 500000}" --sat_per_vbyte=1

0 commit comments

Comments
 (0)