Use associated mnemonic generation

Mnemonic generation no longer needs a separate global entry point now
that bindings expose a real mnemonic object.

Use numeric word counts for both native and binding constructors so the
APIs stay aligned without a binding-specific enum.

Co-Authored-By: HAL 9000

Author: tnull

CHANGELOG.md

@@ -5,6 +5,8 @@
   mnemonic phrases must be passed through its fallible constructor, which returns
   `NodeError::InvalidMnemonic` for invalid input; generated mnemonics can be converted back to a
   string through their language's standard string conversion.
+- `generate_entropy_mnemonic` has been removed. Use `bip39::Mnemonic::generate` in Rust and
+  `Mnemonic::generate` in the language bindings instead.
 - Migrating between storage backends does not preserve the relative creation order of
   pre-existing payments, as the generic KV store migration copies entries in an unspecified
   order. Expect the order in which `Node::list_payments` returns pre-existing payments to

README.md

@@ -17,7 +17,8 @@ The primary abstraction of the library is the [`Node`][api_docs_node], which can
 ```rust
 use ldk_node::bitcoin::secp256k1::PublicKey;
 use ldk_node::bitcoin::Network;
-use ldk_node::entropy::{generate_entropy_mnemonic, NodeEntropy};
+use ldk_node::bip39::Mnemonic;
+use ldk_node::entropy::NodeEntropy;
 use ldk_node::lightning::ln::msgs::SocketAddress;
 use ldk_node::lightning_invoice::Bolt11Invoice;
 use ldk_node::Builder;
@@ -32,7 +33,7 @@ fn main() {
 	);
 
 
-	let mnemonic = generate_entropy_mnemonic(None);
+	let mnemonic = Mnemonic::generate(24).unwrap();
 	let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
 	let node = builder.build(node_entropy).unwrap();
 

bindings/kotlin/ldk-node-android/lib/src/androidTest/kotlin/org/lightningdevkit/ldknode/AndroidLibTest.kt

@@ -34,11 +34,11 @@ class AndroidLibTest {
         val builder1 = Builder.fromConfig(config1)
         val builder2 = Builder.fromConfig(config2)
 
-        val mnemonic1 = generateEntropyMnemonic(null)
+        val mnemonic1 = Mnemonic.generate(24u)
         val nodeEntropy1 = NodeEntropy.fromBip39Mnemonic(mnemonic1, null)
         val node1 = builder1.build(nodeEntropy1)
 
-        val mnemonic2 = generateEntropyMnemonic(null)
+        val mnemonic2 = Mnemonic.generate(24u)
         val nodeEntropy2 = NodeEntropy.fromBip39Mnemonic(mnemonic2, null)
         val node2 = builder2.build(nodeEntropy2)
 

bindings/kotlin/ldk-node-jvm/lib/src/test/kotlin/org/lightningdevkit/ldknode/LibraryTest.kt

@@ -207,11 +207,11 @@ class LibraryTest {
         builder2.setChainSourceEsplora(esploraEndpoint, null)
         builder2.setCustomLogger(logWriter2)
 
-        val mnemonic1 = generateEntropyMnemonic(null)
+        val mnemonic1 = Mnemonic.generate(24u)
         val nodeEntropy1 = NodeEntropy.fromBip39Mnemonic(mnemonic1, null)
         val node1 = builder1.build(nodeEntropy1)
 
-        val mnemonic2 = generateEntropyMnemonic(null)
+        val mnemonic2 = Mnemonic.generate(24u)
         val nodeEntropy2 = NodeEntropy.fromBip39Mnemonic(mnemonic2, null)
         val node2 = builder2.build(nodeEntropy2)
 

bindings/ldk_node.udl

@@ -1,5 +1,4 @@
 namespace ldk_node {
-	Mnemonic generate_entropy_mnemonic(WordCount? word_count);
 	Config default_config();
 };
 
@@ -15,8 +14,6 @@ typedef interface NodeEntropy;
 
 typedef interface ProbingConfig;
 
-typedef enum WordCount;
-
 [Remote]
 enum LogLevel {
 	"Gossip",

bindings/python/src/ldk_node/test_ldk_node.py

@@ -8,7 +8,6 @@
 import socket
 
 from ldk_node import *
-from ldk_node import ldk_node as bindings
 
 DEFAULT_ESPLORA_SERVER_URL = "http://127.0.0.1:3002"
 DEFAULT_TEST_NETWORK = Network.REGTEST
@@ -99,7 +98,7 @@ def send_to_address(address, amount_sats):
 
 
 def setup_node(tmp_dir, esplora_endpoint, listening_addresses):
-    mnemonic = generate_entropy_mnemonic(None)
+    mnemonic = Mnemonic.generate(24)
     node_entropy = NodeEntropy.from_bip39_mnemonic(mnemonic, None)
     config = default_config()
     builder = Builder.from_config(config)
@@ -209,24 +208,24 @@ def init_features_exposed(test_case, init_features):
 class TestMnemonic(unittest.TestCase):
     def test_invalid_mnemonic_returns_node_error(self):
         invalid_mnemonic = "abandon " * 11 + "abandon"
-        mnemonic_constructor = getattr(bindings.Mnemonic, "from_str", bindings.Mnemonic)
+        mnemonic_constructor = getattr(Mnemonic, "from_str", Mnemonic)
 
         with self.assertRaises(NodeError) as error:
             mnemonic_constructor(invalid_mnemonic)
 
         self.assertIsInstance(error.exception, NodeError.InvalidMnemonic)
 
     def test_mnemonic_round_trip(self):
-        mnemonic = generate_entropy_mnemonic(None)
-        parsed_mnemonic = bindings.Mnemonic.from_str(str(mnemonic))
+        mnemonic = Mnemonic.generate(24)
+        parsed_mnemonic = Mnemonic.from_str(str(mnemonic))
 
-        self.assertIsInstance(mnemonic, bindings.Mnemonic)
+        self.assertIsInstance(mnemonic, Mnemonic)
         self.assertEqual(parsed_mnemonic, mnemonic)
         self.assertIsInstance(NodeEntropy.from_bip39_mnemonic(parsed_mnemonic, None), NodeEntropy)
 
     def test_mnemonic_functionality(self):
         entropy = bytes(16)
-        mnemonic = bindings.Mnemonic.from_entropy(entropy)
+        mnemonic = Mnemonic.from_entropy(entropy)
 
         self.assertEqual(mnemonic.words(), ["abandon"] * 11 + ["about"])
         self.assertEqual(mnemonic.word_indices(), [0] * 11 + [3])
@@ -238,10 +237,15 @@ def test_mnemonic_functionality(self):
             "c55257c360c07c72029aebc1b53c05ed0362ada38ead3e3e9efa3708e5349553"
             "1f09a6987599d18264c1e1c92f2cf141630c7a3c4ab7c81b2f001698e7463b04",
         )
-        self.assertEqual(bindings.Mnemonic.generate(WordCount.WORDS12).word_count(), 12)
+        self.assertEqual(Mnemonic.generate(12).word_count(), 12)
 
         with self.assertRaises(NodeError) as error:
-            bindings.Mnemonic.from_entropy(bytes(15))
+            Mnemonic.generate(13)
+
+        self.assertIsInstance(error.exception, NodeError.InvalidMnemonic)
+
+        with self.assertRaises(NodeError) as error:
+            Mnemonic.from_entropy(bytes(15))
 
         self.assertIsInstance(error.exception, NodeError.InvalidMnemonic)
 

src/entropy.rs

@@ -9,15 +9,12 @@
 
 use std::fmt;
 
-use bip39::rand::rngs::OsRng;
-use bip39::{Language, Mnemonic as Bip39Mnemonic};
-
 use crate::config::WALLET_KEYS_SEED_LEN;
-use crate::ffi::{maybe_deref, maybe_wrap};
+use crate::ffi::maybe_deref;
 use crate::io;
 
 #[cfg(not(feature = "uniffi"))]
-type Mnemonic = Bip39Mnemonic;
+type Mnemonic = bip39::Mnemonic;
 #[cfg(feature = "uniffi")]
 type Mnemonic = std::sync::Arc<crate::ffi::Mnemonic>;
 
@@ -124,89 +121,3 @@ impl fmt::Debug for NodeEntropy {
 		write!(f, "NODE ENTROPY")
 	}
 }
-
-/// Generates a random [BIP 39] mnemonic with the specified word count.
-///
-/// If no word count is specified, defaults to 24 words (256-bit entropy).
-///
-/// The result may be used to initialize the [`NodeEntropy`], i.e., can be given to
-/// [`NodeEntropy::from_bip39_mnemonic`].
-///
-/// [BIP 39]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
-/// [`Node`]: crate::Node
-pub fn generate_entropy_mnemonic(word_count: Option<WordCount>) -> Mnemonic {
-	let word_count = word_count.unwrap_or(WordCount::Words24).word_count();
-	let mnemonic = Bip39Mnemonic::generate_in_with(&mut OsRng, Language::English, word_count)
-		.expect("Failed to generate mnemonic");
-	maybe_wrap(mnemonic)
-}
-
-/// Supported BIP39 mnemonic word counts for entropy generation.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
-pub enum WordCount {
-	/// 12-word mnemonic (128-bit entropy)
-	Words12,
-	/// 15-word mnemonic (160-bit entropy)
-	Words15,
-	/// 18-word mnemonic (192-bit entropy)
-	Words18,
-	/// 21-word mnemonic (224-bit entropy)
-	Words21,
-	/// 24-word mnemonic (256-bit entropy)
-	Words24,
-}
-
-impl WordCount {
-	/// Returns the word count as a usize value.
-	pub fn word_count(&self) -> usize {
-		match self {
-			WordCount::Words12 => 12,
-			WordCount::Words15 => 15,
-			WordCount::Words18 => 18,
-			WordCount::Words21 => 21,
-			WordCount::Words24 => 24,
-		}
-	}
-}
-
-#[cfg(test)]
-mod tests {
-	use super::*;
-
-	#[test]
-	fn mnemonic_to_entropy_to_mnemonic() {
-		// Test default (24 words)
-		let mnemonic = generate_entropy_mnemonic(None);
-		let mnemonic_inner = maybe_deref(&mnemonic);
-		let entropy = mnemonic_inner.to_entropy();
-		assert_eq!(mnemonic_inner, &Bip39Mnemonic::from_entropy(&entropy).unwrap());
-		assert_eq!(mnemonic_inner.word_count(), 24);
-
-		// Test with different word counts
-		let word_counts = [
-			WordCount::Words12,
-			WordCount::Words15,
-			WordCount::Words18,
-			WordCount::Words21,
-			WordCount::Words24,
-		];
-
-		for word_count in word_counts {
-			let mnemonic = generate_entropy_mnemonic(Some(word_count));
-			let mnemonic_inner = maybe_deref(&mnemonic);
-			let entropy = mnemonic_inner.to_entropy();
-			assert_eq!(mnemonic_inner, &Bip39Mnemonic::from_entropy(&entropy).unwrap());
-
-			// Verify expected word count
-			let expected_words = match word_count {
-				WordCount::Words12 => 12,
-				WordCount::Words15 => 15,
-				WordCount::Words18 => 18,
-				WordCount::Words21 => 21,
-				WordCount::Words24 => 24,
-			};
-			assert_eq!(mnemonic_inner.word_count(), expected_words);
-		}
-	}
-}

src/ffi/types.rs

@@ -151,7 +151,7 @@ impl VssClientHeaderProvider for VssHeaderProviderAdapter {
 
 use crate::builder::sanitize_alias;
 pub use crate::config::{default_config, ElectrumSyncConfig, EsploraSyncConfig, TorConfig};
-pub use crate::entropy::{generate_entropy_mnemonic, NodeEntropy, WordCount};
+pub use crate::entropy::NodeEntropy;
 use crate::error::Error;
 pub use crate::liquidity::LSPS1OrderStatus;
 pub use crate::logger::{LogLevel, LogRecord, LogWriter};
@@ -1175,14 +1175,11 @@ impl Mnemonic {
 	}
 
 	/// Generates a random English mnemonic with the specified word count.
-	///
-	/// Defaults to 24 words when no word count is specified.
 	#[uniffi::constructor]
-	pub fn generate(word_count: Option<WordCount>) -> Self {
-		let word_count = word_count.unwrap_or(WordCount::Words24).word_count();
-		let inner = Bip39Mnemonic::generate(word_count)
-			.expect("WordCount always maps to a valid BIP 39 word count");
-		Self { inner }
+	pub fn generate(word_count: u8) -> Result<Self, Error> {
+		Bip39Mnemonic::generate(word_count.into())
+			.map(Self::from)
+			.map_err(|_| Error::InvalidMnemonic)
 	}
 
 	/// Returns the words in the mnemonic.
@@ -3009,7 +3006,8 @@ mod tests {
 		assert_eq!(mnemonic.to_entropy(), entropy);
 		assert_eq!(mnemonic.checksum(), 3);
 		assert_eq!(mnemonic.to_seed("TREZOR").len(), 64);
-		assert_eq!(Mnemonic::generate(Some(WordCount::Words12)).word_count(), 12);
+		assert_eq!(Mnemonic::generate(12).unwrap().word_count(), 12);
+		assert_eq!(Mnemonic::generate(13), Err(Error::InvalidMnemonic));
 		assert_eq!(Mnemonic::from_entropy(&[0; 15]), Err(Error::InvalidMnemonic));
 	}
 }

src/lib.rs

@@ -29,7 +29,8 @@
 //!
 //! use ldk_node::bitcoin::secp256k1::PublicKey;
 //! use ldk_node::bitcoin::Network;
-//! use ldk_node::entropy::{generate_entropy_mnemonic, NodeEntropy};
+//! use ldk_node::bip39::Mnemonic;
+//! use ldk_node::entropy::NodeEntropy;
 //! use ldk_node::lightning::ln::msgs::SocketAddress;
 //! use ldk_node::lightning_invoice::Bolt11Invoice;
 //! use ldk_node::Builder;
@@ -42,7 +43,7 @@
 //! 		"https://rapidsync.lightningdevkit.org/testnet/v2/snapshot".to_string(),
 //! 	);
 //!
-//! 	let mnemonic = generate_entropy_mnemonic(None);
+//! 	let mnemonic = Mnemonic::generate(24).unwrap();
 //! 	let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
 //! 	let node = builder.build(node_entropy).unwrap();
 //!
@@ -2212,11 +2213,14 @@ impl Node {
 	///
 	/// For example, you could retrieve all stored outbound payments as follows:
 	/// ```
+	/// # #[cfg(not(feature = "uniffi"))]
+	/// # fn main() -> Result<(), ldk_node::NodeError> {
 	/// # use ldk_node::Builder;
 	/// # use ldk_node::config::Config;
 	/// # use ldk_node::payment::{PaymentDetails, PaymentDirection};
 	/// # use ldk_node::bitcoin::Network;
-	/// # use ldk_node::entropy::{generate_entropy_mnemonic, NodeEntropy};
+	/// # use ldk_node::bip39::Mnemonic;
+	/// # use ldk_node::entropy::NodeEntropy;
 	/// # use rand::distr::Alphanumeric;
 	/// # use rand::{rng, Rng};
 	/// # let mut config = Config::default();
@@ -2226,7 +2230,7 @@ impl Node {
 	/// # temp_path.push(rand_dir);
 	/// # config.storage_dir_path = temp_path.display().to_string();
 	/// # let builder = Builder::from_config(config);
-	/// # let mnemonic = generate_entropy_mnemonic(None);
+	/// # let mnemonic = Mnemonic::generate(24).unwrap();
 	/// # let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
 	/// # let node = builder.build(node_entropy.into()).unwrap();
 	/// let mut outbound = Vec::new();
@@ -2241,7 +2245,10 @@ impl Node {
 	/// 		None => break,
 	/// 	}
 	/// }
-	/// # Ok::<(), ldk_node::NodeError>(())
+	/// # Ok(())
+	/// # }
+	/// # #[cfg(feature = "uniffi")]
+	/// # fn main() {}
 	/// ```
 	pub fn list_payments(
 		&self, page_token: Option<payment::PageToken>,

tests/common/mod.rs

@@ -37,11 +37,12 @@ use bitcoin::{
 use electrsd::corepc_node::{Client as BitcoindClient, Node as BitcoinD};
 use electrsd::electrum_client::ElectrumApi;
 use electrsd::{corepc_node, ElectrsD};
+use ldk_node::bip39::Mnemonic;
 use ldk_node::config::{
 	AsyncPaymentsRole, Config, ElectrumSyncConfig, EsploraSyncConfig, HRNResolverConfig,
 	HumanReadableNamesConfig,
 };
-use ldk_node::entropy::{generate_entropy_mnemonic, NodeEntropy};
+use ldk_node::entropy::NodeEntropy;
 use ldk_node::io::sqlite_store::SqliteStore;
 use ldk_node::payment::{
 	PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus, TransactionType,
@@ -644,8 +645,11 @@ impl Default for TestConfig {
 		let log_writer = Default::default();
 		let store_type = Default::default();
 
-		let mnemonic = generate_entropy_mnemonic(None);
+		let mnemonic = Mnemonic::generate(24).unwrap();
+		#[cfg(not(feature = "uniffi"))]
 		let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
+		#[cfg(feature = "uniffi")]
+		let node_entropy = NodeEntropy::from_seed_bytes(mnemonic.to_seed("").to_vec()).unwrap();
 		let async_payments_role = None;
 		let wallet_rescan_from_height = None;
 		let force_wallet_full_scan = false;