Skip to content

Restore legacy keys_seed compatibility with safe entropy-source detection #252

Description

@Billa05

Problem

Older versions of LDK Server initialized node entropy using:

NodeEntropy::from_seed_path("<storage_dir>/keys_seed")

This produced a raw 64-byte keys_seed file that determines both the Lightning node identity and on-chain wallet keys.

Current LDK Server only checks for keys_mnemonic. If it is absent, it generates a new BIP39 mnemonic even when a valid legacy keys_seed already exists.

For legacy deployments this can:

  • Derive a different Lightning node ID and on-chain wallet.
  • Fail startup with a wallet descriptor mismatch when existing node state is present.
  • Write a new mnemonic beside the authoritative legacy seed, leaving two ambiguous entropy sources.
  • Make migration to current LDK Server require a local source-code patch.

A legacy raw seed cannot be converted into a BIP39 mnemonic while preserving the same NodeEntropy. BIP39 mnemonic derivation produces different seed bytes, so retaining the original node identity requires continuing to load the raw seed.

This behavior was discussed in #197, where legacy support was intentionally removed before release. However, deployments using earlier LDK Server revisions still need a safe migration path.

Proposed behavior

Select the entropy source based on the files already present:

keys_mnemonic keys_seed Behavior
Present Absent Load the BIP39 mnemonic
Absent Present Load the legacy raw seed
Absent Absent Generate and persist a new BIP39 mnemonic
Present Present Fail with a clear ambiguity error

When both files exist, silently preferring either is unsafe:

  • The mnemonic may have been generated accidentally during a failed legacy upgrade.
  • The seed may be stale on an installation that intentionally uses the mnemonic.

The error should explain that the operator must identify and explicitly retain the entropy source corresponding to the existing node identity.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions