You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/lnd/key_import.md
+82-78Lines changed: 82 additions & 78 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,32 +1,34 @@
1
-
# Key Import
2
-
3
-
## Overview
4
-
5
-
This document serves as an introductory point for users interested in reducing\
6
-
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`\
7
-
is able to import BIP-0049 and BIP-0084 extended public keys either at the\
8
-
account path (`m/purpose'/coin_type'/account'`) or at the address index path\
9
-
(`m/purpose'/coin_type'/account'/change/address_index`) as watch-only through\
1
+
# Overview
2
+
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
10
9
the `WalletKit` APIs.
11
10
12
-
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\
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
13
14
would only be necessary when compiling from source.
14
15
15
-
##`lnd`'s Default Wallet Accounts
16
+
# `lnd`'s Default Wallet Accounts
16
17
17
18
Upon initializing `lnd`, a wallet is created with four default accounts:
18
19
19
-
* A custom BIP-0049 account (more on this later) to generate NP2WKH external\
20
+
* A custom BIP-0049 account (more on this later) to generate NP2WKH external
20
21
addresses.
21
22
* A BIP-0084 account to generate P2WKH external and change addresses.
22
-
* A catch-all BIP-0049 account where all imported BIP-0049 address keys (NP2WKH\
23
+
* A catch-all BIP-0049 account where all imported BIP-0049 address keys (NP2WKH
23
24
addresses) exist within.
24
-
* A catch-all BIP-0084 account where all imported BIP-0049 address keys (P2WKH\
25
+
* A catch-all BIP-0084 account where all imported BIP-0049 address keys (P2WKH
25
26
addresses) exist within.
26
27
27
-
Prior to `v0.13.0-beta`, these accounts were abstracted away from users. As part\
28
-
of the key import feature, they are now exposed through the new `WalletKit` RPCs\
29
-
(`ListAccounts`, `ImportAccount`, `ImportPublicKey`) and the `lncli wallet accounts` command.
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.
30
32
31
33
```shell
32
34
$ lncli wallet accounts
@@ -45,10 +47,11 @@ OPTIONS:
45
47
--help, -h show help
46
48
```
47
49
48
-
###Account Details
50
+
## Account Details
49
51
50
-
Before interacting with the new set of APIs, users will want to become familiar\
51
-
with how wallet accounts are represented within `lnd`. The`WalletKit.ListAccounts` RPC or `lncli wallet accounts list` command can be used\
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
52
55
to retrieve the details of accounts.
53
56
54
57
```shell
@@ -79,77 +82,78 @@ $ lncli wallet accounts list
79
82
}
80
83
```
81
84
82
-
There's a lot to unpack in the response above, so let's cover each account field\
83
-
in detail. As mentioned above, four default accounts should exist, though only\
84
-
two are shown in the output. The catch-all imported accounts are hidden by\
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
85
88
default until a key has been imported into them.
86
89
87
-
*`name`: Each account has a name it can be identified by. `lnd`'s default\
88
-
spendable accounts have the name "default". The default catch-all imported\
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
89
92
accounts have the name "imported".
90
-
*`extended_public_key`: The BIP-0044 extended public key for the account. Any\
91
-
addresses generated for the account are derived from this key. Each key has a\
92
-
version prefix that identifies the chain and derivation scheme being used. At\
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
93
96
the time of writing, `lnd` supports the following versions:
94
-
*`xpub/tpub`: The commonly used version prefix originally intended for\
95
-
BIP-0032 mainnet/testnet extended keys. Since `lnd` does not support\
96
-
BIP-0032 extended keys, this version serves as a catch-all for the other\
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
97
100
versions.
98
101
*`ypub/upub`: The version prefix for BIP-0049 mainnet/testnet extended keys.
99
102
*`zpub/vpub`: The version prefix for BIP-0084 mainnet/testnet extended keys.
100
-
*`address_type`: The type of addresses the account can derive. There are three\
103
+
*`address_type`: The type of addresses the account can derive. There are three
101
104
supported address types:
102
-
*`WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0084 with\
105
+
*`WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0084 with
103
106
P2WKH for external and change addresses.
104
-
*`NESTED_WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0049\
107
+
*`NESTED_WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0049
105
108
with P2WKH for external and change addresses.
106
-
*`HYBRID_NESTED_WITNESS_PUBKEY_HASH` A custom derivation scheme for BIP-0049\
107
-
used by `lnd` where NP2WKH is used for external addresses and P2WKH for\
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
108
111
change addresses.
109
-
*`master_key_fingerprint`: The 4 byte fingerprint of the master key\
110
-
corresponding to the account. This is usually required by hardware\
112
+
*`master_key_fingerprint`: The 4 byte fingerprint of the master key
113
+
corresponding to the account. This is usually required by hardware
111
114
wallet/external signers to identify the proper signing key.
112
-
*`derivation_path`: The BIP-0044 derivation path used on the master key to\
115
+
*`derivation_path`: The BIP-0044 derivation path used on the master key to
113
116
obtain the account key.
114
117
*`external_key_count`: The number of external addresses generated.
115
118
*`internal_key_count`: The number of change addresses generated.
116
-
*`watch_only`: Whether the wallet has private key information for the account.`lnd`'s default wallet accounts always have private key information, so this\
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
117
121
value is `false`.
118
122
119
-
##Key Import
123
+
# Key Import
120
124
121
-
An existing limitation to the key import APIs is that events (deposits/spends)\
122
-
for imported keys, including those derived from an imported account, will only\
123
-
be detected by lnd if they happen after the import. Rescans to detect past\
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
124
128
events are currently not supported, but will come at a later time.
125
129
126
-
###Account Key Import
130
+
## Account Key Import
127
131
128
-
The `WalletKit.ImportAccount` RPC and `lncli wallet accounts import` command can\
129
-
be used to import an account. At the time of writing, importing an account has\
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
130
134
the following request parameters:
131
135
132
136
*`name` (required): A name to identify the imported account with.
133
-
*`extended_public_key` (required): A public key that corresponds to a wallet account\
134
-
represented as an extended key. It must conform to a derivation path of the\
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
135
139
form `m/purpose'/coin_type'/account'`.
136
-
*`master_key_fingerprint` (optional): The fingerprint of the root key (also\
137
-
known as the key with derivation path m/) from which the account public key\
138
-
was derived from. This may be required by some hardware wallets for proper\
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
139
143
identification and signing.
140
-
*`address_type` (optional): An address type is only required when the extended\
141
-
account public key has a legacy version (xpub, tpub, etc.), such that the\
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
142
146
wallet cannot detect what address scheme it belongs to.
143
-
*`dry_run` (optional): Whether a dry run should be attempted when importing the\
144
-
account. This serves as a way to confirm whether the account is being imported\
145
-
correctly by returning the first N addresses for the external and internal\
146
-
branches of the account. If these addresses match as expected, then it should\
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
147
151
be safe to import the account as is.
148
152
149
-
For the sake of simplicity, we'll present an example with two `lnd` nodes Alice\
150
-
and Bob, where Alice acts as a signer _only_, and Bob manages Alice's on-chain\
151
-
BIP-0084 account by crafting transactions and watching/spending addresses. Since\
152
-
Alice will only act as a signer, we'll want to import her BIP-0084 account into\
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
153
157
Bob's node, which will require knowledge of Alice's extended public key.
154
158
155
159
Alice's BIP-0084 extended public key can be obtained as follows.
@@ -178,10 +182,10 @@ Bob can then import the account with the following command:
178
182
$ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChEMGqtxiELfZB8hm6FwBpBvfPpX2HGG8edYVV9Wupe43PEJJhhfnz1egtQNNaDXyYExn alice
179
183
```
180
184
181
-
Before Bob imports the account, they may want to confirm the account is being\
182
-
imported using the correct derivation scheme. This can be done with the dry run\
183
-
request parameter. When a dry run is done, the response will include the usual\
184
-
account details, as well as the first 5 external and change addresses, which can\
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
185
189
be used to confirm they match with what the account owner expects.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments