From acc6d15c20294f959fe2590ba6925ae41a76833c Mon Sep 17 00:00:00 2001
From: Conor Okus <conor.okus@hotmail.co.uk>
Date: Tue, 15 Nov 2022 16:01:07 +0000
Subject: [PATCH 1/4] Adds combined wallet guidance

---
 docs/key_management.md | 91 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 90 insertions(+), 1 deletion(-)

diff --git a/docs/key_management.md b/docs/key_management.md
index 491908e4c..fba0ed3a5 100644
--- a/docs/key_management.md
+++ b/docs/key_management.md
@@ -2,12 +2,17 @@
 
 Relevant reference: [Rust docs](https://docs.rs/lightning/*/lightning/chain/keysinterface/struct.KeysManager.html)
 
-LDK Private Key Information is primarily provided through the `chain::keysinterface::KeysInterface` trait. It includes a few basic methods to get public and private key information, as well as a method to get an instance of a second trait which provides per-channel information - `chain::keysinterface::ChannelKeys`. While a custom `KeysInterface` implementation allows simple flexibility to control derivation of private keys, `ChannelKeys` focuses on signing Lightning transactions and is primarily useful if you want to store private key material on a separate device which enforces Lightning protocol details.
+LDK Private Key Information is primarily provided through the `chain::keysinterface::KeysInterface` trait. It includes a few basic methods to get public and private key information, as well as a method to get an instance of a second trait which provides per-channel information - `chain::keysinterface::ChannelKeys`.
+ 
+While a custom `KeysInterface` implementation allows simple flexibility to control derivation of private keys, `ChannelKeys` focuses on signing Lightning transactions and is primarily useful if you want to store private key material on a separate device which enforces Lightning protocol details.
 
 A simple implementation of `KeysInterface` is provided in the form of `chain::keysinterface::KeysManager`, see its documentation for more details on its key derivation. It uses `chain::keysinterface::InMemoryChannelKeys` for channel signing, which is likely an appropriate signer for custom `KeysInterface` implementations as well.
 
 A `KeysManager` can be constructed simply with only a 32-byte seed and some integers which ensure uniqueness across restarts (defined as `starting_time_secs` and `starting_time_nanos`).
 
+<CodeSwitcher :languages="{rust:'Rust', java:'Java', kotlin:'Kotlin'}">
+  <template v-slot:rust>
+
 ```rust
 let mut random_32_bytes = [0; 32];
 // Fill in random_32_bytes with secure random data, or, on restart, reload the seed from disk.
@@ -15,6 +20,90 @@ let start_time = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap
 let keys_interface_impl = lightning::chain::keysinterface::KeysManager::new(&random_32_bytes, start_time.as_secs(), start_time.subsec_nanos());
 ```
 
+  </template>
+
+  <template v-slot:java>
+
+```java
+byte[] key_seed = new byte[32];
+// Fill in random_32_bytes with secure random data, or, on restart, reload the seed from disk.
+KeysManager keys_manager = KeysManager.of(key_seed,
+    System.currentTimeMillis() / 1000,
+    (int) (System.currentTimeMillis() * 1000)
+);
+```
+
+  </template>
+
+  <template v-slot:kotlin>
+
+```kotlin
+val key_seed = ByteArray(32)
+// Fill in random_32_bytes with secure random data, or, on restart, reload the seed from disk.
+val keys_manager = KeysManager.of(
+    key_seed,
+    System.currentTimeMillis() / 1000, (System.currentTimeMillis() * 1000).toInt()
+)
+```
+
+  </template>
+</CodeSwitcher>
+
+# Creating a Unified Wallet
+LDK makes it simple to combine an on-chain and off-chain wallet in the same app. This means users don’t need to worry about storing 2 different recovery phrases. For apps containing a hierarchical deterministic wallet (or “HD Wallet”) we recommend using the entropy from a [hardened child key derivation](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch05.asciidoc#hardened-child-key-derivation) path for your LDK seed.
+
+Using a [BDK](https://bitcoindevkit.org/)-based wallet the steps would be as follows:
+ 1) Generate a mnemonic/entropy 
+ 2) Build an HD wallet from that. That's now your on-chain wallet, and you can derive any BIP-compliant on-chain wallet/path for it from there.
+ 3) Derive the private key at `m/535'/535'/535'` (or some other custom path). That's 32 bytes and is your starting entropy for your LDK wallet.
+
+<CodeSwitcher :languages="{rust:'Rust', kotlin:'Kotlin'}">
+  <template v-slot:rust>
+
+```rust
+// Use BDK to create and build the HD wallet
+let mnemonic = Mnemonic::parse_in_normalized(
+        Language::English,
+        "sock lyrics village put galaxy famous pass act ship second diagram pull"
+    ).unwrap();
+let seed: [u8; 64] = mnemonic.to_seed_normalized("");
+let master_xprv = ExtendedPrivKey::new_master(Network::Testnet, &seed).unwrap();
+let secp = Secp256k1::new();
+let xprv: ExtendedPrivKey = master_xprv.ckd_priv(&secp, ChildNumber::Hardened { index: 535 }).unwrap();
+let ldk_seed: [u8; 32] = xprv.private_key.secret_bytes();
+
+// Seed the LDK KeysManager with the private key at m/535h
+let cur = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap();
+let keys_manager = KeysManager::new(&ldk_seed, cur.as_secs(), cur.subsec_nanos());
+```
+
+ </template>
+ <template v-slot:kotlin>
+
+```kotlin
+// Use BDK to create and build the HD wallet
+val mnemonic = Mnemonic.fromString("sock lyrics village put galaxy famous pass act ship second diagram pull")
+val bip32RootKey = DescriptorSecretKey(network = Network.TESTNET, mnemonic = mnemonic, password = null)
+val ldkDerivationPath = DerivationPath("m/535h")
+val ldkChild: DescriptorSecretKey = bip32RootKey.derive(ldkDerivationPath)
+
+@OptIn(kotlin.ExperimentalUnsignedTypes::class)
+val entropy: ByteArray = ldkChild.secretBytes().toUByteArray().toByteArray()
+
+// Seed the LDK KeysManager with the private key at m/535h
+val keysManager = KeysManager.of(
+    entropy,
+    System.currentTimeMillis() / 1000,
+    (System.currentTimeMillis() * 1000).toInt()
+);
+```
+
+ </template>
+</CodeSwitcher>
+
+
+
+
 Spending On-Chain Funds
 =======================
 When a channel has been closed and some outputs on chain are spendable only by us, LDK provides a `util::events::Event::SpendableOutputs` event in return from `ChannelMonitor::get_and_clear_pending_events()`. It contains a list of `chain::keysinterface::SpendableOutputDescriptor` objects which describe the output and provide all necessary information to spend it.

From 5a608081d156ba3b66ec522559c430fcfbd829dc Mon Sep 17 00:00:00 2001
From: Conor Okus <conor.okus@hotmail.co.uk>
Date: Tue, 15 Nov 2022 17:27:22 +0000
Subject: [PATCH 2/4] Add advantages

---
 docs/key_management.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/key_management.md b/docs/key_management.md
index fba0ed3a5..ca2d45544 100644
--- a/docs/key_management.md
+++ b/docs/key_management.md
@@ -101,8 +101,11 @@ val keysManager = KeysManager.of(
  </template>
 </CodeSwitcher>
 
+::: tip Protection for on-chain wallet
 
+An advantage to this approach is that the LDK entropy is contained within your initial mnemonic and a user only has one master private key to backup and secure. Another added benefit is that if your lightning keys were to be leaked we reduce the exposure to those funds and not the rest of the on-chain wallet. 
 
+:::
 
 Spending On-Chain Funds
 =======================

From ad082e130204c198dcafbe699460b853bbd8733f Mon Sep 17 00:00:00 2001
From: Conor Okus <conor.okus@hotmail.co.uk>
Date: Thu, 17 Nov 2022 15:37:08 +0000
Subject: [PATCH 3/4] Adds supported networks comment

---
 docs/key_management.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/key_management.md b/docs/key_management.md
index ca2d45544..ea389a4e7 100644
--- a/docs/key_management.md
+++ b/docs/key_management.md
@@ -67,6 +67,7 @@ let mnemonic = Mnemonic::parse_in_normalized(
         "sock lyrics village put galaxy famous pass act ship second diagram pull"
     ).unwrap();
 let seed: [u8; 64] = mnemonic.to_seed_normalized("");
+// Other supported networks include mainnet (Bitcoin), Regtest, Signet
 let master_xprv = ExtendedPrivKey::new_master(Network::Testnet, &seed).unwrap();
 let secp = Secp256k1::new();
 let xprv: ExtendedPrivKey = master_xprv.ckd_priv(&secp, ChildNumber::Hardened { index: 535 }).unwrap();

From 8d6cd12145a27f5a665e6f40741110f20d0a85a2 Mon Sep 17 00:00:00 2001
From: Conor Okus <conor.okus@hotmail.co.uk>
Date: Thu, 17 Nov 2022 15:48:07 +0000
Subject: [PATCH 4/4] Update comment

---
 docs/key_management.md | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/docs/key_management.md b/docs/key_management.md
index ea389a4e7..3fd4a8aad 100644
--- a/docs/key_management.md
+++ b/docs/key_management.md
@@ -55,9 +55,9 @@ LDK makes it simple to combine an on-chain and off-chain wallet in the same app.
 Using a [BDK](https://bitcoindevkit.org/)-based wallet the steps would be as follows:
  1) Generate a mnemonic/entropy 
  2) Build an HD wallet from that. That's now your on-chain wallet, and you can derive any BIP-compliant on-chain wallet/path for it from there.
- 3) Derive the private key at `m/535'/535'/535'` (or some other custom path). That's 32 bytes and is your starting entropy for your LDK wallet.
+ 3) Derive the private key at `m/535h` (or some other custom path). That's 32 bytes and is your starting entropy for your LDK wallet.
 
-<CodeSwitcher :languages="{rust:'Rust', kotlin:'Kotlin'}">
+<CodeSwitcher :languages="{rust:'Rust', java:'Java', kotlin:'Kotlin'}">
   <template v-slot:rust>
 
 ```rust
@@ -79,6 +79,37 @@ let keys_manager = KeysManager::new(&ldk_seed, cur.as_secs(), cur.subsec_nanos()
 ```
 
  </template>
+
+ <template v-slot:java>
+
+```java
+// Use BDK to create and build the HD wallet
+Mnemonic mnemonic = Mnemonic.Companion.fromString("sock lyrics " +
+                "village put galaxy " +
+                "famous pass act ship second diagram pull");
+
+// Other supported networks include mainnet (Bitcoin), Regtest, Signet
+DescriptorSecretKey bip32RootKey = new DescriptorSecretKey(Network.TESTNET, mnemonic, null);
+
+DerivationPath ldkDerivationPath = new DerivationPath("m/535h");
+DescriptorSecretKey ldkChild = bip32RootKey.derive(ldkDerivationPath);
+        
+ByteArrayOutputStream bos = new ByteArrayOutputStream();
+ObjectOutputStream oos = new ObjectOutputStream(bos);
+oos.writeObject(ldkChild.secretBytes());
+byte[] entropy = bos.toByteArray();
+
+// Seed the LDK KeysManager with the private key at m/535h
+var startupTime = System.currentTimeMillis();
+KeysManager keysManager = KeysManager.of(
+        entropy,
+        startupTime / 1000,
+        (int) (startupTime * 1000)
+);
+```
+
+ </template>
+
  <template v-slot:kotlin>
 
 ```kotlin