Merge pull request #716 from tnull/2025-11-introduce-mandatory-node-entropy

Introduce new mandatory `NodeEntropy` object

Author: tnull

README.md

@@ -14,20 +14,26 @@ LDK Node is a self-custodial Lightning node in library form. Its central goal is
 The primary abstraction of the library is the [`Node`][api_docs_node], which can be retrieved by setting up and configuring a [`Builder`][api_docs_builder] to your liking and calling one of the `build` methods. `Node` can then be controlled via commands such as `start`, `stop`, `open_channel`, `send`, etc.
 
 ```rust
-use ldk_node::Builder;
-use ldk_node::lightning_invoice::Bolt11Invoice;
-use ldk_node::lightning::ln::msgs::SocketAddress;
 use ldk_node::bitcoin::secp256k1::PublicKey;
 use ldk_node::bitcoin::Network;
+use ldk_node::entropy::{generate_entropy_mnemonic, NodeEntropy};
+use ldk_node::lightning::ln::msgs::SocketAddress;
+use ldk_node::lightning_invoice::Bolt11Invoice;
+use ldk_node::Builder;
 use std::str::FromStr;
 
 fn main() {
 	let mut builder = Builder::new();
 	builder.set_network(Network::Testnet);
 	builder.set_chain_source_esplora("https://blockstream.info/testnet/api".to_string(), None);
-	builder.set_gossip_source_rgs("https://rapidsync.lightningdevkit.org/testnet/snapshot".to_string());
+	builder.set_gossip_source_rgs(
+		"https://rapidsync.lightningdevkit.org/testnet/snapshot".to_string(),
+	);
+
 
-	let node = builder.build().unwrap();
+	let mnemonic = generate_entropy_mnemonic(None);
+	let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
+	let node = builder.build(node_entropy).unwrap();
 
 	node.start().unwrap();
 

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

@@ -34,8 +34,13 @@ class AndroidLibTest {
         val builder1 = Builder.fromConfig(config1)
         val builder2 = Builder.fromConfig(config2)
 
-        val node1 = builder1.build()
-        val node2 = builder2.build()
+        val mnemonic1 = generateEntropyMnemonic(null)
+        val nodeEntropy1 = NodeEntropy.fromBip39Mnemonic(mnemonic1, null)
+        val node1 = builder1.build(nodeEntropy1)
+
+        val mnemonic2 = generateEntropyMnemonic(null)
+        val nodeEntropy2 = NodeEntropy.fromBip39Mnemonic(mnemonic2, null)
+        val node2 = builder2.build(nodeEntropy2)
 
         node1.start()
         node2.start()

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

@@ -193,8 +193,13 @@ class LibraryTest {
         builder2.setChainSourceEsplora(esploraEndpoint, null)
         builder2.setCustomLogger(logWriter2)
 
-        val node1 = builder1.build()
-        val node2 = builder2.build()
+        val mnemonic1 = generateEntropyMnemonic(null)
+        val nodeEntropy1 = NodeEntropy.fromBip39Mnemonic(mnemonic1, null)
+        val node1 = builder1.build(nodeEntropy1)
+
+        val mnemonic2 = generateEntropyMnemonic(null)
+        val nodeEntropy2 = NodeEntropy.fromBip39Mnemonic(mnemonic2, null)
+        val node2 = builder2.build(nodeEntropy2)
 
         node1.start()
         node2.start()

bindings/ldk_node.udl

@@ -47,6 +47,20 @@ dictionary LSPS2ServiceConfig {
 	boolean client_trusts_lsp;
 };
 
+interface NodeEntropy {
+	[Name=from_bip39_mnemonic]
+	constructor(Mnemonic mnemonic, string? passphrase);
+	[Throws=EntropyError, Name=from_seed_bytes]
+	constructor(bytes seed_bytes);
+	[Throws=EntropyError, Name=from_seed_path]
+	constructor(string seed_path);
+};
+
+enum EntropyError {
+	"InvalidSeedBytes",
+	"InvalidSeedFile",
+};
+
 enum WordCount {
 	"Words12",
 	"Words15",
@@ -80,10 +94,6 @@ interface Builder {
 	constructor();
 	[Name=from_config]
 	constructor(Config config);
-	void set_entropy_seed_path(string seed_path);
-	[Throws=BuildError]
-	void set_entropy_seed_bytes(sequence<u8> seed_bytes);
-	void set_entropy_bip39_mnemonic(Mnemonic mnemonic, string? passphrase);
 	void set_chain_source_esplora(string server_url, EsploraSyncConfig? config);
 	void set_chain_source_electrum(string server_url, ElectrumSyncConfig? config);
 	void set_chain_source_bitcoind_rpc(string rpc_host, u16 rpc_port, string rpc_user, string rpc_password);
@@ -107,15 +117,15 @@ interface Builder {
 	[Throws=BuildError]
 	void set_async_payments_role(AsyncPaymentsRole? role);
 	[Throws=BuildError]
-	Node build();
+	Node build(NodeEntropy node_entropy);
 	[Throws=BuildError]
-	Node build_with_fs_store();
+	Node build_with_fs_store(NodeEntropy node_entropy);
 	[Throws=BuildError]
-	Node build_with_vss_store(string vss_url, string store_id, string lnurl_auth_server_url, record<string, string> fixed_headers);
+	Node build_with_vss_store(NodeEntropy node_entropy, string vss_url, string store_id, string lnurl_auth_server_url, record<string, string> fixed_headers);
 	[Throws=BuildError]
-	Node build_with_vss_store_and_fixed_headers(string vss_url, string store_id, record<string, string> fixed_headers);
+	Node build_with_vss_store_and_fixed_headers(NodeEntropy node_entropy, string vss_url, string store_id, record<string, string> fixed_headers);
 	[Throws=BuildError]
-	Node build_with_vss_store_and_header_provider(string vss_url, string store_id, VssHeaderProvider header_provider);
+	Node build_with_vss_store_and_header_provider(NodeEntropy node_entropy, string vss_url, string store_id, VssHeaderProvider header_provider);
 };
 
 interface Node {
@@ -357,8 +367,6 @@ dictionary BestBlock {
 
 [Error]
 enum BuildError {
-	"InvalidSeedBytes",
-	"InvalidSeedFile",
 	"InvalidSystemTime",
 	"InvalidChannelMonitor",
 	"InvalidListeningAddresses",

bindings/python/src/ldk_node/test_ldk_node.py

@@ -97,13 +97,15 @@ def send_to_address(address, amount_sats):
 
 
 def setup_node(tmp_dir, esplora_endpoint, listening_addresses):
+    mnemonic = generate_entropy_mnemonic(None)
+    node_entropy = NodeEntropy.from_bip39_mnemonic(mnemonic, None)
     config = default_config()
     builder = Builder.from_config(config)
     builder.set_storage_dir_path(tmp_dir)
     builder.set_chain_source_esplora(esplora_endpoint, None)
     builder.set_network(DEFAULT_TEST_NETWORK)
     builder.set_listening_addresses(listening_addresses)
-    return builder.build()
+    return builder.build(node_entropy)
 
 def get_esplora_endpoint():
     if os.environ.get('ESPLORA_ENDPOINT'):