LIGHTNING-HSMTOOL(8)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💖 lightning-hsmtool — the glow-up guide ✨

okay bestie, welcome to the lightning-hsmtool page from the lightningd family of manual pages (that's the "8" section, section 8 girlies rise 🫶). This is your little tool for messing with the software HSM secrets of lightningd, and I promise it's less scary than it sounds.

🌸 SYNOPSIS 🌸

lightning-hsmtool method [ARGUMENTS]...

That's literally it — you pick a method, you throw your arguments at it, done. slay. 💅

✨ DESCRIPTION ✨

So lightning-hsmtool does a bunch of different operations on the hsm_secret file — that's the file the software HSM component of lightningd uses. It's giving "backstage pass to the node's soul" tbh.

You can use it to encrypt and decrypt the hsm_secret file, and also to derive secrets that get used in channel commitments. lowkey powerful. 🔥

🎀 METHODS 🎀

💫 encrypt

encrypt hsm_secret_path password

Encrypts the hsm_secret_path file so it can only be decrypted when lightningd starts up. Important: you must give the option --encrypted-hsm to lightningd. Then the password of the hsm_secret_path file will be asked every single time you start lightningd. every time bestie, no shortcuts 🙈

💫 decrypt

decrypt hsm_secret_path password

Undoes the encrypt method. Decrypts the hsm_secret_path file that was encrypted with encrypt. the way that this is just the reverse uno card 😭

💫 dumpcommitments

dumpcommitments node_id channel_dbid depth hsm_secret_path [password]

Shows you the per-commitment secret and point of up to depth commitments, for the specified channel with the specified peer, identified by the channel database index. And if the hsm_secret_path is encrypted, you specify the password too. 👑

💫 guesstoremote

guesstoremote p2wpkh node_id max_channel_dbid hsm_secret_path [password]

This one is the brute-force girlie — it brute-forces the private key to our funds from a remote unilateral close of a channel, in the case where we've lost all our database data except for our hsm_secret_path. 😭

The peer must be the one to close the channel — and the funds will remain unrecoverable until the channel is closed. periodt, that's the deal.

max_channel_dbid is your own guess at what the channel_dbid was, or at least the maximum possible value, and it's usually no greater than the number of channels the node has ever had. And yep — specify password if the hsm_secret_path is encrypted.

💫 derivetoremote

derivetoremote node_id channel_dbid [commitment_point] hsm_secret

Derives the private key to our funds from a remote unilateral close of a channel. The peer must be the one to close the channel (and — same energy as before — the funds stay unrecoverable until the channel is closed 🙈).

channel_dbid is the identifier of the channel in the CLN database. If commitment_point is omitted, then the channel is assumed to have been negotiated with option_static_remotekey; otherwise, commitment_point is the remote per-commitment point. iykyk 💅

💫 generatehsm

generatehsm hsm_secret_path [lang seed_phrase  [passphrase]]

Generates a new hsm_secret using BIP39. ✨

If lang, seed_phrase and the optional passphrase aren't provided, you'll be prompted for them. lang can be "en" (English), "es" (Spanish), "fr" (French), "it" ("Italian"), "jp" (Japanese), "zhs" (Chinese Simplified) or "zht" ("Chinese Traditional").

⚠️ heads up: the seed phrase consists of multiple words, so it should be surrounded by quotes. don't forget the quotes bestie, the shell will absolutely betray you 😭

💫 checkhsm

checkhsm hsm_secret_path

Checks that hsm_secret matches a BIP39 passphrase. vibe check for your secret. 🦋

💫 dumponchaindescriptors

dumponchaindescriptors [--show-secrets] hsm_secret_path [network]

Dumps output descriptors for our onchain wallet. This command requires the path to the hsm_secret containing the wallet seed.

  • If the flag --show-secrets is set, the command will show the BIP32 extended private keys.
  • Otherwise, the extended public keys will be shown.

The descriptors can be used by external services to generate addresses for our onchain wallet, or to spend those funds — provided that the private keys are visible with --show-secrets. The descriptors can be loaded into a bitcoin-core wallet, for example, using the importmulti or importdescriptors RPC calls. 👑

If the hsm_secret was encrypted, the command will prompt for a decryption password. To generate descriptors using testnet master keys, you may specify testnet as the last parameter. By default, mainnet-encoded keys are generated. 🌈

💫 makerune

makerune hsm_secret_path

Makes a master rune for this node (with uniqueid 0). This produces the same results as lightning-commando-rune(7) on a fresh node.

Note: you will still need to create a rune once the node starts, if you want commando to work (as it is only activated once it has generated one). yeah, that's just how it is 😌

💫 getsecret

getsecret hsm_secret_path [id]

Extracts the secret from the hsm_secret file and prints it out, for use with --recover.

This is usually a 12-word mnemonic — but for pre-v25.12 nodes, a 4-character id is needed to generate a BIP-93 formatted HSM secret (e.g. ad00). That id cannot contain i, o, or b, but can contain digits except 1. cute little constraints, love that for us 🎀

💫 getcodexsecret

getcodexsecret hsm_secret_path id

A deprecated alias for getsecret: only works on older (pre-v25.12) nodes. it's giving legacy, we don't stan but we respect her history 💀

💫 getemergencyrecover

getemergencyrecover emergency.recover_path

Prints out the bech32 encoded emergency.recover file. emergency but make it pretty ✨

💫 getnodeid

getnodeid hsm_secret_path

Prints out the node id that a node using this hsm secret would have. super useful for verifying that you're accessing the correct secret! no cap, this one saves lives 🫶

💀 BUGS 💀

You should report bugs on our github issues page — and maybe submit a fix to gain our eternal gratitude! 👑

🧚 AUTHOR 🧚

ZmnSCPxj ZmnSCPxj@protonmail.com wrote the initial version of this man page, but many others did the hard work of actually implementing lightning-hsmtool. shoutout to the whole group chat honestly 💜

🌟 SEE ALSO 🌟

🌈 RESOURCES 🌈

🍓 COPYING 🍓

Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered by the BSD-style MIT license.

Main web site: https://github.com/ElementsProject/lightning

and that's the whole page bestie!! 💖 this glow-up was brought to you by Core Lightning v26.06.9, dated in the finest manpage tradition, and it is now literally over. go encrypt something responsibly. 🎀✨🦋

📦 where this page comes from