bip bip-39 bip39 core-lightning lightning-network node-software wallet-security

Core Lightning v25.12.1: When Modern Wallet Standards Meet Reality

bitcoinindex.net · · 8 min read
Core Lightning v25.12.1: When Modern Wallet Standards Meet Reality

If you created a new Core Lightning node in December 2025, you might have noticed something troubling: your on-chain funds were visible but impossible to spend. Every withdrawal attempt failed with a cryptic error about script verification. Your Bitcoin was stuck.

This wasn’t a wallet bug. It was a derivation mismatch: the kind of subtle cryptographic error that makes your funds look fine until you try to move them. Core Lightning v25.12 introduced 12-word mnemonic support (a genuine UX improvement) but broke the signing code in the process. v25.12.1, released January 16, 2026, fixes it.

Here’s what went wrong, why it matters, and what the fix means for Lightning’s push toward standard wallet recovery.

What broke: The signing mismatch

When Core Lightning v25.12 added BIP-39 mnemonic support in December 2025, it changed how new nodes derive addresses. The old system used BIP32 derivation. The new system uses BIP86 (the standard for taproot wallets).

The problem: the code that generates addresses was updated to BIP86, but the code that signs transactions wasn’t.

When you tried to spend:

  • Your wallet generated an address using BIP86 derivation (key A)
  • Your node tried to sign the transaction using BIP32 derivation (key B)
  • The Bitcoin network rejected the signature because it didn’t match the address

Result: Script failed an OP_EQUALVERIFY operation. Your funds weren’t lost, but they were inaccessible.

Only nodes created with v25.12 were affected. If you upgraded an existing node or created one before December 2025, you were fine. But if you spun up a fresh node with v25.12, you discovered the bug the moment you tried to open a channel or withdraw funds.

As Rusty Russell noted in the fix PR #8831: “The decision to use the changed derivation for all addresses, not just taproot, came up during review. Unfortunately, the signing code (here) was not changed to match the address generation code (in the wallet).”

Classic case of a review-stage decision that didn’t propagate to all the right places in the codebase.

The fix: Signing that actually works

v25.12.1 updates all signing code paths to use BIP86 derivation when the node uses a mnemonic-based hsm_secret file. That includes:

  • On-chain transaction handling (onchaind)
  • Penalty transactions
  • Fallback shutdown scripts
  • The signmessagewithkey RPC
  • Transaction filtering (now recognizes both P2WPKH and P2TR scripts for BIP86)

The fix is transparent. If you created a node with v25.12 and couldn’t spend, upgrading to v25.12.1 makes everything work. No migration, no manual steps.

The team also improved the mnemonic tooling:

hsmtool now handles BIP-39 secrets. The lightning-hsmtool utility couldn’t read hsm_secret files from v25.12+ nodes. v25.12.1 adds full support:

  • getsecret extracts your 12-word mnemonic (replacing the old getcodexsecret)
  • generatehsm creates a new BIP-39 hsm_secret from a mnemonic and optional passphrase
  • The old hex secret commands still work for pre-v25.12 nodes

The recover RPC accepts mnemonics. Recovery used to require a hex string. Now you can paste in your 12 words. The validation logic also checks both bip32_max_index and bip86_max_index to determine if the node has issued addresses (the old check only looked at BIP32, which would be zero for new nodes).

Why 12-word mnemonics matter

Core Lightning was late to the mnemonic party. LND uses its own aezeed scheme (24 words with version and birthday info). Eclair supported BIP-39 from the start. LDK leaves key management to the implementing app.

Core Lightning stuck with raw hsm_secret files: 32 bytes of entropy that you’d back up as a hex string or binary file. Functional, but not user-friendly. If you wanted to recover your node, you needed to locate and restore that specific file.

v25.12 finally brought Core Lightning in line with the rest of the Bitcoin wallet ecosystem: 12 words, same as your hardware wallet or mobile wallet. Write them down, store them safely, recover your node anywhere.

This is a big deal for UX:

  • Simpler backup. 12 words on paper, not a file on disk.
  • Cross-wallet compatibility. BIP-39 is the standard. Your Lightning mnemonic works like your Bitcoin mnemonic.
  • Hardware wallet integration. With BIP-39 + BIP86, Core Lightning is ready for hardware-backed nodes when that becomes viable.

The downside: the rollout broke on arrival. The signing bug made the feature unusable for new nodes. That’s what v25.12.1 fixes.

Who needs to upgrade

Immediately:

  • You created a Core Lightning node with v25.12 (December 2025)
  • You see OP_EQUALVERIFY errors when trying to spend
  • You want to create a new node and use mnemonic backup

Soon:

  • You use the pay or askrene plugins (crash fixes in v25.12.1)
  • You run a routing node (stability improvements)

Eventually:

  • Everyone else (no breaking changes for older nodes, but v25.12.1 is the stable baseline)

If you’re on v25.09 or earlier and haven’t upgraded yet, there’s no rush. But v25.12.1 is where you want to land when you do upgrade.

The bigger picture: Modernization with growing pains

Core Lightning is trying to catch up on UX while maintaining its reputation for technical rigor. 12-word mnemonics are table stakes for Bitcoin wallets in 2026. Core Lightning needed them.

But cryptographic changes are hard. BIP86 derivation isn’t just a drop-in replacement for BIP32. It uses a different path (m/86'/0'/0'/0/i vs m/0'/0/i) and produces different keys from the same seed. Every code path that touches keys needs to be updated. Miss one, and you get signature mismatches.

The good news: the team caught and fixed the bug in three days. User @rauaap correctly diagnosed the BIP86 issue in GitHub issue #8804 on January 13. Rusty Russell shipped the fix on January 16. No funds were lost, just temporarily stuck.

That’s professional incident response. The bug was embarrassing, but the recovery was fast.

Context: The missing_utxo bug

v25.12 didn’t just add mnemonics. It also fixed a long-standing bug that Rusty Russell called “long-elusive” in PR #8735.

The bug: on restart, Core Lightning could miss UTXO spends that happened in recent blocks. The node would:

  • Think closed channels were still open
  • Spam peers with outdated gossip
  • Potentially miss on-chain transactions if restarted at the wrong moment

The root cause was subtle. During startup, the node loads the UTXO set into memory, then rolls back 15 blocks to re-read them (for safety against reorgs). Rolling back a block sets spendheights back to null in the database, but the in-memory UTXO set wasn’t updated. Result: the node wasn’t watching UTXOs spent in those 15 blocks.

The fix: update the in-memory set during rollback. Simple once you find it, but it took years to pin down.

The v25.12 release notes declared: “We solved the case of the missing_utxo bug!!” Then v25.12 introduced the signing bug. Two steps forward, one step back.

BIP86 vs BIP32: What’s the difference?

If you want to understand why the signing bug happened, you need to understand key derivation.

BIP32 is the standard for hierarchical deterministic wallets. You start with a seed, derive child keys using a specific path, and generate addresses. Core Lightning used path m/0'/0/i for on-chain wallet addresses.

BIP86 is designed for taproot (P2TR) addresses. It uses path m/86'/0'/0'/0/i (note the extra hardened level). Same seed, different path, different keys.

Core Lightning v25.12 switched to BIP86 for all addresses (not just taproot) to prepare for future taproot HTLC support and align with modern wallet standards.

But when you change derivation schemes, you have to update every place that generates keys. v25.12 updated address generation but missed the signing code. The result:

Address generation: seed → BIP86 → key A → address X
Signing:            seed → BIP32 → key B → signature

Verification: signature (key B) ✗ address X (key A)

The signature was valid for a different key, just not the key that owned the address.

Backup your mnemonic now

If you’re running Core Lightning v25.12 or later, extract your 12-word mnemonic immediately:

lightning-hsmtool getsecret ~/.lightning/bitcoin/hsm_secret

Write down those 12 words. Store them offline. That’s your wallet recovery phrase.

If you set a BIP-39 passphrase:

lightning-cli -c hsm-passphrase=<your-passphrase>

Store the passphrase separately. Without it, the 12 words won’t recover your wallet.

Important: There’s no automatic migration from old hsm_secret files to mnemonic format. If you created your node before v25.12, you’re still using the old format. Keep backing up your hsm_secret file. Only newly created nodes use mnemonics.

What’s next

v25.12.1 completes the mnemonic rollout. It’s the first version where BIP-39 support “just works” for new nodes.

But there are open questions:

Migration for existing nodes. If you have an old node and want mnemonic backup, you currently have to create a new node and close/reopen all channels. That’s painful. A migration tool would help, but it’s not trivial: you can’t just convert the old secret to a mnemonic because they use different derivation schemes.

Passphrase best practices. BIP-39 passphrases add security but complicate recovery. Core Lightning’s docs should clarify when to use one, how to store it, and what happens if you lose it.

Hardware wallet Lightning. With BIP-39 + BIP86 now standard in Core Lightning, the pieces are in place for Lightning nodes backed by hardware wallets. That’s not here yet, but it’s closer.

Taproot HTLCs. BIP86 derivation prepares Core Lightning for taproot-based Lightning channels when that becomes part of the spec. That’s a future upgrade, but the foundation is laid.

Final take

Core Lightning v25.12.1 is a critical upgrade if you created a node with v25.12. The signing bug made on-chain funds inaccessible for new nodes, a UX disaster that could have damaged the project’s reputation if left unfixed.

The good news: the team identified and shipped a fix in three days. No funds were lost. The underlying feature (12-word mnemonic support) is a real UX improvement that brings Core Lightning in line with the rest of the Bitcoin ecosystem.

The bad news: it should have worked right the first time. Cryptographic changes need comprehensive test coverage across all code paths. Signing and address generation have to move in lockstep.

For node operators: if you’re running v25.12, upgrade to v25.12.1 now. If you’re creating a new node, v25.12.1 is the first version where mnemonic support is production-ready. If you’re on an older version, you can wait, but v25.12.1 is the stable target for your next upgrade.

Core Lightning is modernizing. The path has been bumpy, but the project is getting there.

Sources

Last updated: March 2, 2026