From 8c7f50622d7390e283d8c0d51f92f6ffca99ba9a Mon Sep 17 00:00:00 2001
From: Conor Okus <conor.okus@hotmail.co.uk>
Date: Tue, 13 Feb 2024 22:17:40 -0500
Subject: [PATCH 1/3] Adds lightning-transaction-sync in favor of Confirm

---
 .../setting-up-a-channel-manager.md           | 94 +++++++++++++------
 1 file changed, 66 insertions(+), 28 deletions(-)

diff --git a/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
index 59f681bb6..753b13bcf 100644
--- a/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
+++ b/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
@@ -931,16 +931,18 @@ _after_ the `ChannelMonitor`s and `ChannelManager` are synced to the chain tip (
 
 ### Sync `ChannelMonitor`s and `ChannelManager` to chain tip
 
-**What it's used for:** this step is only necessary if you're restarting and have open channels. This step ensures that LDK channel state is up-to-date with the bitcoin blockchain
+**What it's used for:** this step is only necessary if you're restarting and have open channels. This step ensures that LDK channel state is up-to-date with the bitcoin blockchain.
+
+There are 2 main options for synchronizing to chain on startup:
+
+#### Full Blocks or BIP 157/158 (Compact Block Filters)
 
 **Example:**
 
-<CodeSwitcher :languages="{rust:'Rust', kotlin:'Kotlin', swift:'Swift'}">
+<CodeSwitcher :languages="{rust:'Rust'}">
   <template v-slot:rust>
   
   ```rust
-  // Full Blocks or BIP 157/158
-
 use lightning_block_sync::init;
 use lightning_block_sync::poll;
 use lightning_block_sync::UnboundedCache;
@@ -1006,17 +1008,74 @@ chain_tip = Some(
     .await
     .unwrap(),
 );
+```
+
+</template>
+
+</CodeSwitcher>
+
+**Implementation notes:**
+
+If you are connecting full blocks or using BIP 157/158, then it is recommended to use
+LDK's [`lightning_block_sync`](https://docs.rs/lightning-block-sync/*/lightning_block_sync/) crate as in the example above: the high-level steps that must be done for both `ChannelManager` and each `ChannelMonitor` are as follows:
+
+1. Get the last blockhash that each object saw.
+   - Receive the latest block hash when through [deserializtion](https://docs.rs/lightning/*/lightning/ln/channelmanager/struct.ChannelManagerReadArgs.html) of the `ChannelManager` via `read()`
+   - Each `ChannelMonitor`'s is in `channel_manager.channel_monitors`, as the 2nd element in each tuple
+2. For each object, if its latest known blockhash has been reorged out of the chain, then disconnect blocks using `channel_manager.as_Listen().block_disconnected(..)` or `channel_monitor.block_disconnected(..)` until you reach the last common ancestor with the main chain.
+3. For each object, reconnect blocks starting from the common ancestor until it gets to your best known chain tip using `channel_manager.as_Listen().block_connected(..)` and/or `channel_monitor.block_connected(..)`.
+4. Call `channel_manager.chain_sync_completed(..)` to complete the initial sync process.
+
+
+#### Electrum or Esplora
+
+Alternatively, you can use LDK's [`lightning-transaction-sync`](https://docs.rs/lightning-transaction-sync/*/lightning_transaction_sync/) crate. This provides utilities for syncing LDK via the transaction-based [`Confirm`](https://docs.rs/lightning/*/lightning/chain/trait.Confirm.html)interface.
 
+**Example:**
+
+<CodeSwitcher :languages="{rust:'Rust', kotlin:'Kotlin', swift:'Swift'}">
+  <template v-slot:rust>
   
-````
+  ```rust
+let tx_sync = Arc::new(EsploraSyncClient::new(
+	esplora_server_url,
+	Arc::clone(&some_logger),
+));
+
+let chain_monitor = Arc::new(ChainMonitor::new(
+	Some(Arc::clone(&tx_sync)),
+	Arc::clone(&some_broadcaster),
+	Arc::clone(&some_logger),
+	Arc::clone(&some_fee_estimator),
+	Arc::clone(&some_persister),
+));
+
+let channel_manager = Arc::new(ChannelManager::new(
+	Arc::clone(&some_fee_estimator),
+	Arc::clone(&chain_monitor),
+	Arc::clone(&some_broadcaster),
+	Arc::clone(&some_router),
+	Arc::clone(&some_logger),
+	Arc::clone(&some_entropy_source),
+	Arc::clone(&some_node_signer),
+	Arc::clone(&some_signer_provider),
+	user_config,
+	chain_params,
+));
+
+let confirmables = vec![
+	&*channel_manager as &(dyn Confirm + Sync + Send),
+	&*chain_monitor as &(dyn Confirm + Sync + Send),
+];
+
+tx_sync.sync(confirmables).unwrap();
+```
 
 </template>
 
 <template v-slot:kotlin>
 
 ```java
-// Electrum/Esplora
-
 // Retrieve transaction IDs to check the chain for un-confirmation.
 val relevantTxIdsFromChannelManager: Array<ByteArray> = channelManager .as_Confirm().get_relevant_txids()
 val relevantTxIdsFromChannelManager: Array<ByteArray> = chainMonitor.as_Confirm().get_relevant_txids()
@@ -1062,8 +1121,6 @@ channelManagerConstructor.chain_sync_completed(customEventHandler);
   <template v-slot:swift>
 
 ```Swift
-// Electrum/Esplora
-
 // Retrieve transaction IDs to check the chain for un-confirmation.
 let relevantTxIds1 = channelManager?.asConfirm().getRelevantTxids() ?? []
 let relevantTxIds2 = chainMonitor?.asConfirm().getRelevantTxids() ?? []
@@ -1118,25 +1175,6 @@ channelManagerConstructor.chainSyncCompleted(persister: channelManagerPersister)
 
 </CodeSwitcher>
 
-**Implementation notes:**
-
-There are 2 main options for synchronizing to chain on startup:
-
-**Full Blocks or BIP 157/158**
-
-If you are connecting full blocks or using BIP 157/158, then it is recommended to use
-LDK's `lightning_block_sync` crate as in the example above: the high-level steps that must be done for both `ChannelManager` and each `ChannelMonitor` are as follows:
-
-1. Get the last blockhash that each object saw.
-   - Receive the latest block hash when through [deserializtion](https://docs.rs/lightning/*/lightning/ln/channelmanager/struct.ChannelManagerReadArgs.html) of the `ChannelManager` via `read()`
-   - Each `ChannelMonitor`'s is in `channel_manager.channel_monitors`, as the 2nd element in each tuple
-2. For each object, if its latest known blockhash has been reorged out of the chain, then disconnect blocks using `channel_manager.as_Listen().block_disconnected(..)` or `channel_monitor.block_disconnected(..)` until you reach the last common ancestor with the main chain.
-3. For each object, reconnect blocks starting from the common ancestor until it gets to your best known chain tip using `channel_manager.as_Listen().block_connected(..)` and/or `channel_monitor.block_connected(..)`.
-4. Call `channel_manager.chain_sync_completed(..)` to complete the initial sync process.
-
-**Electrum/Esplora**
-
-Alternatively, you can use LDK's `lightning-transaction-sync` crate. This provides utilities for syncing LDK via the transaction-based `Confirm` interface.
 
 ### Optional: Initialize `P2PGossipSync or RapidGossipSync`
 

From a0f100281ec1a9b4e242203719bd985b2bad7c42 Mon Sep 17 00:00:00 2001
From: Conor Okus <conor.okus@proton.me>
Date: Thu, 15 Feb 2024 11:36:32 -0500
Subject: [PATCH 2/3] Update
 docs/building-a-node-with-ldk/setting-up-a-channel-manager.md

Co-authored-by: Elias Rohrer <dev@tnull.de>
---
 docs/building-a-node-with-ldk/setting-up-a-channel-manager.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
index 753b13bcf..0a5580093 100644
--- a/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
+++ b/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
@@ -1029,7 +1029,7 @@ LDK's [`lightning_block_sync`](https://docs.rs/lightning-block-sync/*/lightning_
 
 #### Electrum or Esplora
 
-Alternatively, you can use LDK's [`lightning-transaction-sync`](https://docs.rs/lightning-transaction-sync/*/lightning_transaction_sync/) crate. This provides utilities for syncing LDK via the transaction-based [`Confirm`](https://docs.rs/lightning/*/lightning/chain/trait.Confirm.html)interface.
+Alternatively, you can use LDK's [`lightning-transaction-sync`](https://docs.rs/lightning-transaction-sync/*/lightning_transaction_sync/) crate. This provides utilities for syncing LDK via the transaction-based [`Confirm`](https://docs.rs/lightning/*/lightning/chain/trait.Confirm.html) interface.
 
 **Example:**
 

From 4f8109a91f884430d1e5a56febf4a82087d29564 Mon Sep 17 00:00:00 2001
From: Conor Okus <conor.okus@hotmail.co.uk>
Date: Fri, 16 Feb 2024 14:49:34 -0500
Subject: [PATCH 3/3] Removes steps that only work in Kotlin

---
 .../setting-up-a-channel-manager.md           | 21 +++++++++++--------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
index 0a5580093..e2b9e34eb 100644
--- a/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
+++ b/docs/building-a-node-with-ldk/setting-up-a-channel-manager.md
@@ -937,6 +937,8 @@ There are 2 main options for synchronizing to chain on startup:
 
 #### Full Blocks or BIP 157/158 (Compact Block Filters)
 
+You can use LDK's [lightning-block-sync](https://docs.rs/lightning-block-sync/*/lightning_block_sync/) crate. This provides utilities for syncing LDK via a block-based interface.
+
 **Example:**
 
 <CodeSwitcher :languages="{rust:'Rust'}">
@@ -1014,18 +1016,13 @@ chain_tip = Some(
 
 </CodeSwitcher>
 
-**Implementation notes:**
+::: tip Full block syncing in mobile environments
 
-If you are connecting full blocks or using BIP 157/158, then it is recommended to use
-LDK's [`lightning_block_sync`](https://docs.rs/lightning-block-sync/*/lightning_block_sync/) crate as in the example above: the high-level steps that must be done for both `ChannelManager` and each `ChannelMonitor` are as follows:
+Block syncing for mobile clients tends to present several challenges due to resource contraints and network limitiations typically associated with mobile devices. It requires a full node and usually fetches blocks over RPC.
 
-1. Get the last blockhash that each object saw.
-   - Receive the latest block hash when through [deserializtion](https://docs.rs/lightning/*/lightning/ln/channelmanager/struct.ChannelManagerReadArgs.html) of the `ChannelManager` via `read()`
-   - Each `ChannelMonitor`'s is in `channel_manager.channel_monitors`, as the 2nd element in each tuple
-2. For each object, if its latest known blockhash has been reorged out of the chain, then disconnect blocks using `channel_manager.as_Listen().block_disconnected(..)` or `channel_monitor.block_disconnected(..)` until you reach the last common ancestor with the main chain.
-3. For each object, reconnect blocks starting from the common ancestor until it gets to your best known chain tip using `channel_manager.as_Listen().block_connected(..)` and/or `channel_monitor.block_connected(..)`.
-4. Call `channel_manager.chain_sync_completed(..)` to complete the initial sync process.
+Compact block filters (CBFs) are an alternative approach to syncing the blockchain that addresses some of the challenges associated with mobile clients. Please start a [discussion](https://github.com/orgs/lightningdevkit/discussions) if you would like us to expose `lightning-block-sync` in our bindings. 
 
+:::
 
 #### Electrum or Esplora
 
@@ -1076,6 +1073,9 @@ tx_sync.sync(confirmables).unwrap();
 <template v-slot:kotlin>
 
 ```java
+// Note: This example calls the Confirm interface directly. The lightning-transaction-sync crate will 
+// be available in the next bindings release.
+
 // Retrieve transaction IDs to check the chain for un-confirmation.
 val relevantTxIdsFromChannelManager: Array<ByteArray> = channelManager .as_Confirm().get_relevant_txids()
 val relevantTxIdsFromChannelManager: Array<ByteArray> = chainMonitor.as_Confirm().get_relevant_txids()
@@ -1121,6 +1121,9 @@ channelManagerConstructor.chain_sync_completed(customEventHandler);
   <template v-slot:swift>
 
 ```Swift
+// Note: This example calls the Confirm interface directly. The lightning-transaction-sync crate will 
+// be available in the next bindings release.
+
 // Retrieve transaction IDs to check the chain for un-confirmation.
 let relevantTxIds1 = channelManager?.asConfirm().getRelevantTxids() ?? []
 let relevantTxIds2 = chainMonitor?.asConfirm().getRelevantTxids() ?? []