Skip to content

Update lnd documentation #944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 23, 2025
Merged

Update lnd documentation #944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/lnd/INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,23 +93,23 @@ following build dependencies are required:

### Installing Go

`lnd` is written in Go, with a minimum version of `1.24.8` (or, in case this
`lnd` is written in Go, with a minimum version of `1.24.9` (or, in case this
document gets out of date, whatever the Go version in the main `go.mod` file
requires). To install, run one of the following commands for your OS:

<details>
<summary>Linux (x86-64)</summary>

```
wget https://dl.google.com/go/go1.24.8.linux-amd64.tar.gz
echo "6842c516ca66c89d648a7f1dbe28e28c47b61b59f8f06633eb2ceb1188e9251d go1.24.8.linux-amd64.tar.gz" | sha256sum --check
wget https://dl.google.com/go/go1.24.9.linux-amd64.tar.gz
echo "5b7899591c2dd6e9da1809fde4a2fad842c45d3f6b9deb235ba82216e31e34a6 go1.24.9.linux-amd64.tar.gz" | sha256sum --check
```

The command above should output `go1.24.8.linux-amd64.tar.gz: OK`. If it
The command above should output `go1.24.9.linux-amd64.tar.gz: OK`. If it
doesn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install
this version of Go. If it matches, then proceed to install Go:
```
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.8.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.9.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
```
</details>
Expand All @@ -118,15 +118,15 @@ requires). To install, run one of the following commands for your OS:
<summary>Linux (ARMv6)</summary>

```
wget https://dl.google.com/go/go1.24.8.linux-armv6l.tar.gz
echo "3ed8537300ab22449885a43d2931336a571df72c5433d2db4377fe7e2d5e83db go1.24.8.linux-armv6l.tar.gz" | sha256sum --check
wget https://dl.google.com/go/go1.24.9.linux-armv6l.tar.gz
echo "39dafc8e7e5e455995f87e1ffc6b0892302ea519c1f0e59c9e2e0fda41b8aa56 go1.24.9.linux-armv6l.tar.gz" | sha256sum --check
```

The command above should output `go1.24.8.linux-armv6l.tar.gz: OK`. If it
The command above should output `go1.24.9.linux-armv6l.tar.gz: OK`. If it
isn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install
this version of Go. If it matches, then proceed to install Go:
```
sudo rm -rf /usr/local/go && tar -C /usr/local -xzf go1.24.8.linux-armv6l.tar.gz
sudo rm -rf /usr/local/go && tar -C /usr/local -xzf go1.24.9.linux-armv6l.tar.gz
export PATH=$PATH:/usr/local/go/bin
```

Expand Down
160 changes: 82 additions & 78 deletions docs/lnd/key_import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,34 @@
# Key Import

## Overview

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\
# Overview

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.

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\
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.

## `lnd`'s Default Wallet Accounts
# `lnd`'s Default Wallet Accounts

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

* A custom BIP-0049 account (more on this later) to generate NP2WKH external\
* A custom BIP-0049 account (more on this later) to generate NP2WKH external
addresses.
* A BIP-0084 account to generate P2WKH external and change addresses.
* A catch-all BIP-0049 account where all imported BIP-0049 address keys (NP2WKH\
* A catch-all BIP-0049 account where all imported BIP-0049 address keys (NP2WKH
addresses) exist within.
* A catch-all BIP-0084 account where all imported BIP-0049 address keys (P2WKH\
* A catch-all BIP-0084 account where all imported BIP-0049 address keys (P2WKH
addresses) exist within.

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.
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.

```shell
$ lncli wallet accounts
Expand All @@ -45,10 +47,11 @@ OPTIONS:
--help, -h show help
```

### Account Details
## Account Details

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\
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.

```shell
Expand Down Expand Up @@ -79,77 +82,78 @@ $ lncli wallet accounts list
}
```

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\
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.

* `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\
* `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".
* `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\
* `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:
* `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\
* `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.
* `ypub/upub`: The version prefix for BIP-0049 mainnet/testnet extended keys.
* `zpub/vpub`: The version prefix for BIP-0084 mainnet/testnet extended keys.
* `address_type`: The type of addresses the account can derive. There are three\
* `address_type`: The type of addresses the account can derive. There are three
supported address types:
* `WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0084 with\
* `WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0084 with
P2WKH for external and change addresses.
* `NESTED_WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0049\
* `NESTED_WITNESS_PUBKEY_HASH`: The standard derivation scheme for BIP-0049
with P2WKH for external and change addresses.
* `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\
* `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.
* `master_key_fingerprint`: The 4 byte fingerprint of the master key\
corresponding to the account. This is usually required by hardware\
* `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.
* `derivation_path`: The BIP-0044 derivation path used on the master key to\
* `derivation_path`: The BIP-0044 derivation path used on the master key to
obtain the account key.
* `external_key_count`: The number of external addresses generated.
* `internal_key_count`: The number of change addresses generated.
* `watch_only`: Whether the wallet has private key information for the account.`lnd`'s default wallet accounts always have private key information, so this\
* `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`.

## Key Import
# Key Import

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\
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.

### Account Key Import
## Account Key Import

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 `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:

* `name` (required): A name to identify the imported account with.
* `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\
* `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'`.
* `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\
* `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.
* `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\
* `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.
* `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\
* `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.

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\
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.

Alice's BIP-0084 extended public key can be obtained as follows.
Expand Down Expand Up @@ -178,10 +182,10 @@ Bob can then import the account with the following command:
$ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChEMGqtxiELfZB8hm6FwBpBvfPpX2HGG8edYVV9Wupe43PEJJhhfnz1egtQNNaDXyYExn alice
```

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\
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.

```shell
Expand Down Expand Up @@ -214,7 +218,7 @@ $ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChE
}
```

Once Bob has confirmed the correct account derivation scheme is being used, the\
Once Bob has confirmed the correct account derivation scheme is being used, the
account can be imported without the dry run parameter.

```shell
Expand All @@ -233,14 +237,14 @@ $ lncli-bob wallet accounts import vpub5Z9beF6NYCrHeDmKC38tM3xXMDFFSARa9sdHRPChE
}
```

#### Generating Addresses from an Imported Account
### Generating Addresses from an Imported Account

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\
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.

Following the example above, Bob is able to generate an external address for an\
Following the example above, Bob is able to generate an external address for an
incoming deposit as follows:

```shell
Expand All @@ -250,15 +254,15 @@ $ lncli-bob newaddress p2wkh --account=alice
}
```

Change addresses cannot be generated on demand, they are generated automatically\
Change addresses cannot be generated on demand, they are generated automatically
when a transaction is crafted that requires a change output.

#### Crafting Transactions through PSBTs from an Imported Account
### Crafting Transactions through PSBTs from an Imported Account

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\
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.

```shell
Expand Down
Loading