From 9c5434955ec7b6f75440f670668b26bb08bf7e00 Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Mon, 1 Aug 2022 16:04:35 +0100 Subject: [PATCH 01/57] Adds tutorial introudction page --- docs/.vuepress/config.js | 7 +++++ .../building-a-node-with-ldk/introduction.md | 31 +++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 docs/tutorials/building-a-node-with-ldk/introduction.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 750792ac2..75d7830af 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -127,6 +127,13 @@ const tutorialSidebar = [ collapsable: false, children: [ "/tutorials/getting-started", + { + title: "Building a node with LDK", + collapsable: false, + children: [ + ["/tutorials/building-a-node-with-ldk/introduction", "Introduction"], + ], + }, "/tutorials/build_a_node_in_java", "/tutorials/build_a_node_in_rust", ], diff --git a/docs/tutorials/building-a-node-with-ldk/introduction.md b/docs/tutorials/building-a-node-with-ldk/introduction.md new file mode 100644 index 000000000..8881b39e5 --- /dev/null +++ b/docs/tutorials/building-a-node-with-ldk/introduction.md @@ -0,0 +1,31 @@ +# Building a Node with LDK + +## Learn how to build a basic LDK node from scratch using LDK + +The following tutorials will show you how to build the simplest lightning node using LDK, that fufills the following tasks: + +1. **Connect to peers** +2. **Open channels** +3. **Send Payments** +4. **Receive Payments** +5. **Close channels** + +### Foundational Components + +Let's start by looking at the core components we'll need to make this node work for the tasks we outlined above. + +1. A Peer Manager, for establishing TCP/IP connections to other nodes on the lightning network. +2. A Channel Manager, to open and close channels. +3. Payments & Routing, ability to create and pay invoices. + +To make the above work we also need a series of supporting modules, including: + - A Fee Estimator + - A Logger + - A Transaction Broadcaster + - A Network Graph + - A Persister + - An Event Handler + - A Transaction Filter + - A Chain Monitor + - A Keys Manager + - A Scorer \ No newline at end of file From ce32f6e7a8d7832d8ffedefbf7d272bfe9ebc352 Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Mon, 8 Aug 2022 13:16:56 +0100 Subject: [PATCH 02/57] Consolidate building a node tutorials --- docs/.vuepress/config.js | 6 +- .../building-a-node-with-ldk/introduction.md | 30 +- .../setting-up-a-channel-manager.md | 988 ++++++++++++++++++ 3 files changed, 1009 insertions(+), 15 deletions(-) create mode 100644 docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 75d7830af..498632a40 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -132,10 +132,12 @@ const tutorialSidebar = [ collapsable: false, children: [ ["/tutorials/building-a-node-with-ldk/introduction", "Introduction"], + [ + "/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager", + "Setting up a Channel Manager", + ], ], }, - "/tutorials/build_a_node_in_java", - "/tutorials/build_a_node_in_rust", ], }, ]; diff --git a/docs/tutorials/building-a-node-with-ldk/introduction.md b/docs/tutorials/building-a-node-with-ldk/introduction.md index 8881b39e5..d840a0900 100644 --- a/docs/tutorials/building-a-node-with-ldk/introduction.md +++ b/docs/tutorials/building-a-node-with-ldk/introduction.md @@ -2,6 +2,10 @@ ## Learn how to build a basic LDK node from scratch using LDK +::: tip Note +For an integrated example of an LDK node in Rust, see the [Sample Node](https://github.com/lightningdevkit/ldk-sample) +::: + The following tutorials will show you how to build the simplest lightning node using LDK, that fufills the following tasks: 1. **Connect to peers** @@ -14,18 +18,18 @@ The following tutorials will show you how to build the simplest lightning node u Let's start by looking at the core components we'll need to make this node work for the tasks we outlined above. -1. A Peer Manager, for establishing TCP/IP connections to other nodes on the lightning network. -2. A Channel Manager, to open and close channels. +1. A `PeerManager`, for establishing TCP/IP connections to other nodes on the lightning network. +2. A `ChannelManager`, to open and close channels. 3. Payments & Routing, ability to create and pay invoices. -To make the above work we also need a series of supporting modules, including: - - A Fee Estimator - - A Logger - - A Transaction Broadcaster - - A Network Graph - - A Persister - - An Event Handler - - A Transaction Filter - - A Chain Monitor - - A Keys Manager - - A Scorer \ No newline at end of file +To make the above work we also need to setup a series of supporting modules, including: +1. A `FeeEstimator` +2. A `Logger` +3. A `TransactionBroadcaster` +4. A `NetworkGraph` +5. A `Persister` +6. An `EventHandler` +7. A `TransactionFilter` +8. A `ChainMonitor` +9. A `KeysManager` +10. A `Scorer` diff --git a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md new file mode 100644 index 000000000..e467f2192 --- /dev/null +++ b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md @@ -0,0 +1,988 @@ +# Setting up a ChannelManager + +The ChannelManager is responsible for several tasks related to managing channel state. This includes keeping track of many channels, sending messages to appropriate channels, creating channels and more. + +## Adding a ChannelManager + +To add a `ChannelManager` to your application, run: + + + + + + + + +There are a few dependencies needed to get this working. Let's walk through setting up each one so we can plug them into our `ChannelManager`. + +### Step 1. Initialize the `FeeEstimator` + + + + + + + + + +**What it's used for:** estimating fees for on-chain transactions that LDK wants broadcasted. + +**Implementation notes:** +1. Fees must be returned in: satoshis per 1000 weight units +2. Fees must be no smaller than 253 (equivalent to 1 satoshi/vbyte, rounded up) +3. To reduce network traffic, you may want to cache fee results rather than +retrieving fresh ones every time + +**Dependencies:** *none* + +**References:** [Rust `FeeEstimator` docs](https://docs.rs/lightning/*/lightning/chain/chaininterface/trait.FeeEstimator.html), [Java `FeeEstimator` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/FeeEstimator.java) + +### Step 2. Initialize the `Logger` +**What it's used for:** LDK logging + + + + + + + + + +**Implementation notes:** you'll likely want to write the logs to a file for debugging purposes. + +**Dependencies:** *none* + +**References:** [Rust `Logger` docs](https://docs.rs/lightning/*/lightning/util/logger/trait.Logger.html), [Java `Logger` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Logger.java) + +### Step 3. Initialize the `BroadcasterInterface` +**What it's used for:** broadcasting various transactions to the bitcoin network + + + + + + + + + +**Dependencies:** *none* + +**References:** [Rust `BroadcasterInterface` docs](https://docs.rs/lightning/*/lightning/chain/chaininterface/trait.BroadcasterInterface.html), [Java `BroadcasterInterface` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/BroadcasterInterface.java) + +### Step 4. Initialize `Persist` +**What it's used for:** persisting `ChannelMonitor`s, which contain crucial channel data, in a timely manner + + + + + + + + + + + + + +**Implementation notes:** +* `ChannelMonitor`s are objects which are capable of +responding to on-chain events for a given channel. Thus, you will have one +`ChannelMonitor` per channel. They are persisted in real-time and the `Persist` +methods will block progress on sending or receiving payments until they return. +You must ensure that `ChannelMonitor`s are durably persisted to disk before +returning or you may lose funds. +* If you implement a custom persister, it's important to read the trait docs (linked in References) to make sure you satisfy the API requirements, particularly for `update_persisted_channel` + +**Dependencies:** *none* + +**References:** [Rust `Persister` docs](https://docs.rs/lightning/*/lightning/chain/chainmonitor/trait.Persist.html), [Java `Persister` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Persist.java) + +### Optional: Initialize the Transaction `Filter` +**You must follow this step if:** you are *not* providing full blocks to LDK, +i.e. if you're using BIP 157/158 or Electrum as your chain backend + +**What it's used for:** if you are not providing full blocks, LDK uses this +object to tell you what transactions and outputs to watch for on-chain. You'll +inform LDK about these transactions/outputs in Step 14. + + + + + + + + + + +**Implementation notes:** see the [Blockchain Data](/blockchain_data/introduction.md) guide for more info + +**Dependencies:** *none* + +**References:** [Rust `Filter` docs](https://docs.rs/lightning/*/lightning/chain/trait.Filter.html), [Java `Filter` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Filter.java) + +### Step 5. Initialize the `ChainMonitor` +**What it's used for:** tracking one or more `ChannelMonitor`s and using them to monitor the chain for lighting transactions that are relevant to our node, and broadcasting transactions if need be. + + + + + + + + + +**Implementation notes:** `Filter` must be non-`None` if you're using Electrum or BIP 157/158 as your chain backend + +**Dependencies:** `FeeEstimator`, `Logger`, `BroadcasterInterface`, `Persist` + +**Optional dependency:** `Filter` + +**References:** [Rust `ChainMonitor` docs](https://docs.rs/lightning/*/lightning/chain/chainmonitor/struct.ChainMonitor.html), [Java `ChainMonitor` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/ChainMonitor.java) + +### Step 6. Initialize the `KeysManager` +**What it's used for:** providing keys for signing Lightning transactions + + + + + + + + + +**Implementation notes:** +* See the [Key Management](/key_management.md) guide for more info +* Note that you must write the `key_seed` you give to the `KeysManager` on + startup to disk, and keep using it to initialize the `KeysManager` every time + you restart. This `key_seed` is used to derive your node's secret key (which + corresponds to its node pubkey) and all other secret key material. +* The current time is part of the `KeysManager`'s parameters because it is used to derive +random numbers from the seed where required, to ensure all random +generation is unique across restarts. + +**Dependencies:** random bytes + +**References:** [Rust `KeysManager` docs](https://docs.rs/lightning/*/lightning/chain/keysinterface/struct.KeysManager.html), [Java `KeysManager` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/KeysManager.java) + +### Step 7. Read `ChannelMonitor` state from disk + +**What it's used for:** if LDK is restarting and has at least 1 channel, its `ChannelMonitor`s will need to be (1) fed to the `ChannelManager` and (2) synced to chain. + + + + + + + + + +**Dependencies:** `KeysManager` + +**References:** [Rust `load_outputs_to_watch` docs](https://docs.rs/lightning/*/lightning/chain/channelmonitor/struct.ChannelMonitor.html#method.load_outputs_to_watch) + +### Step 8. Initialize the `ChannelManager` +**What it's used for:** managing channel state + + + + + + + + + +**Implementation notes:** No methods should be called on `ChannelManager` until +*after* Step 9. + +**Dependencies:** `KeysManager`, `FeeEstimator`, `ChainMonitor`, `BroadcasterInterface`, `Logger` +* If restarting: `ChannelMonitor`s and `ChannelManager` bytes from Step 7 and Step 18 respectively + +**References:** [Rust `ChannelManager` docs](https://docs.rs/lightning/*/lightning/ln/channelmanager/struct.ChannelManager.html), [Java `ChannelManager` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/ChannelManager.java) + +### Step 9. 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 + +**Example:** + + + + + + + + +**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` sample module 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. + * `ChannelManager`'s is in `channel_manager_constructor.channel_manager_latest_block_hash` + * Each `ChannelMonitor`'s is in `channel_manager_constructor.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_constructor.chain_sync_completed(..)` to complete the initial sync process. + + + +**Electrum** + +Otherwise, you can use LDK's `Confirm` interface as in the examples above. The high-level steps are as follows: + 1. Tell LDK about relevant confirmed and unconfirmed transactions. + 2. Tell LDK what your best known block header and height is. + 3. Call `channel_manager_constructor.chain_sync_completed(..)` to complete the initial sync process. + +**More details about LDK's interfaces to provide chain info in Step 14** + +**References:** [Rust `Confirm` docs](https://docs.rs/lightning/*/lightning/chain/trait.Confirm.html), [Rust `Listen` docs](https://docs.rs/lightning/*/lightning/chain/trait.Listen.html), [Rust `lightning_block_sync` module docs](https://docs.rs/lightning-block-sync/*/lightning_block_sync/) + +**Dependencies:** `ChannelManager`, `ChainMonitor`, `ChannelMonitor`s +* If providing providing full blocks or BIP 157/158: set of `ChannelMonitor`s +* If using Electrum: `ChainMonitor` + +### Step 10. Give `ChannelMonitor`s to `ChainMonitor` +**What it's used for:** `ChainMonitor` is responsible for updating the `ChannelMonitor`s during LDK node operation. + + + + + + + + + +**Dependencies:** +* `ChainMonitor`, set of `ChannelMonitor`s and their funding outpoints +* Step 9 must be completed prior to this step \ No newline at end of file From c069152fa656ae3c628f5123b0607b97bab04577 Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Mon, 22 Aug 2022 13:55:18 +0100 Subject: [PATCH 03/57] Adds P2PGossip Sync docs --- .../building-a-node-with-ldk/introduction.md | 2 +- .../setting-up-a-channel-manager.md | 73 ++++++++++++++++++- 2 files changed, 70 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/building-a-node-with-ldk/introduction.md b/docs/tutorials/building-a-node-with-ldk/introduction.md index d840a0900..95879daaf 100644 --- a/docs/tutorials/building-a-node-with-ldk/introduction.md +++ b/docs/tutorials/building-a-node-with-ldk/introduction.md @@ -1,6 +1,6 @@ # Building a Node with LDK -## Learn how to build a basic LDK node from scratch using LDK +## Learn how to build a basic LDK node from scratch ::: tip Note For an integrated example of an LDK node in Rust, see the [Sample Node](https://github.com/lightningdevkit/ldk-sample) diff --git a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md index e467f2192..862d6e675 100644 --- a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md +++ b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md @@ -70,6 +70,8 @@ There are a few dependencies needed to get this working. Let's walk through sett ### Step 1. Initialize the `FeeEstimator` +**What it's used for:** estimating fees for on-chain transactions that LDK wants broadcasted. + -**What it's used for:** estimating fees for on-chain transactions that LDK wants broadcasted. - **Implementation notes:** 1. Fees must be returned in: satoshis per 1000 weight units 2. Fees must be no smaller than 253 (equivalent to 1 satoshi/vbyte, rounded up) @@ -342,7 +342,7 @@ retrieving fresh ones every time - + @@ -122,12 +122,25 @@ There are a few dependencies needed to get this working. Let's walk through sett From a6198315bbe27dcfd5fdd529ef37287feb92d996 Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Wed, 25 Jan 2023 15:04:50 +0000 Subject: [PATCH 13/57] Rename variables in broadcaster code samples --- .../setting-up-a-channel-manager.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md index 32a4dcf62..a108e640e 100644 --- a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md +++ b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md @@ -155,7 +155,7 @@ retrieving fresh ones every time **References:** [Rust `FeeEstimator` docs](https://docs.rs/lightning/*/lightning/chain/chaininterface/trait.FeeEstimator.html), [Java `FeeEstimator` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/FeeEstimator.java) -### Step 2. Initialize the `Logger` +### Initialize the `Logger` **What it's used for:** LDK logging @@ -202,11 +202,13 @@ retrieving fresh ones every time @@ -218,7 +220,7 @@ retrieving fresh ones every time **References:** [Rust `Logger` docs](https://docs.rs/lightning/*/lightning/util/logger/trait.Logger.html), [Java `Logger` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Logger.java) -### Step 3. Initialize the `BroadcasterInterface` +### Initialize the `BroadcasterInterface` **What it's used for:** broadcasting various transactions to the bitcoin network @@ -241,7 +243,7 @@ retrieving fresh ones every time @@ -257,11 +259,13 @@ retrieving fresh ones every time From e9549da0605f002c61dac5e9e78b5f570b3ab56b Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Wed, 25 Jan 2023 17:03:09 +0000 Subject: [PATCH 14/57] Removes channel_watch instructions --- .../setting-up-a-channel-manager.md | 149 ++++++------------ 1 file changed, 52 insertions(+), 97 deletions(-) diff --git a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md index a108e640e..9a9f67d04 100644 --- a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md +++ b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md @@ -275,7 +275,7 @@ retrieving fresh ones every time **References:** [Rust `BroadcasterInterface` docs](https://docs.rs/lightning/*/lightning/chain/chaininterface/trait.BroadcasterInterface.html), [Java `BroadcasterInterface` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/BroadcasterInterface.java) -### Step 4. Initialize `Persist` +### Initialize `Persist` **What it's used for:** persisting `ChannelMonitor`s, which contain crucial channel data, in a timely manner @@ -311,42 +311,40 @@ retrieving fresh ones every time @@ -418,7 +418,7 @@ inform LDK about these transactions/outputs in Step 14. @@ -457,7 +460,7 @@ inform LDK about these transactions/outputs in Step 14. **References:** [Rust `Filter` docs](https://docs.rs/lightning/*/lightning/chain/trait.Filter.html), [Java `Filter` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Filter.java) -### Step 5. Initialize the `ChainMonitor` +### Initialize the `ChainMonitor` **What it's used for:** tracking one or more `ChannelMonitor`s and using them to monitor the chain for lighting transactions that are relevant to our node, and broadcasting transactions if need be. @@ -466,9 +469,7 @@ inform LDK about these transactions/outputs in Step 14. ```rust let filter: Option> = // leave this as None or insert the Filter trait object - let chain_monitor = ChainMonitor::new( - filter, &broadcaster, &logger, &fee_estimator, &persister - ); + let chain_monitor = ChainMonitor::new(filter, &broadcaster, &logger, &fee_estimator, &persister); ``` @@ -477,9 +478,7 @@ inform LDK about these transactions/outputs in Step 14. ```java final filter = // leave this as `null` or insert the Filter object. - final chain_monitor = ChainMonitor.of(filter, tx_broadcaster, logger, - fee_estimator, persister); - + final chainMonitor = ChainMonitor.of(filter, txBroadcaster, logger, feeEstimator, persister); ``` @@ -501,7 +500,7 @@ inform LDK about these transactions/outputs in Step 14. **References:** [Rust `ChainMonitor` docs](https://docs.rs/lightning/*/lightning/chain/chainmonitor/struct.ChainMonitor.html), [Java `ChainMonitor` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/ChainMonitor.java) -### Step 6. Initialize the `KeysManager` +### Initialize the `KeysManager` **What it's used for:** providing keys for signing Lightning transactions @@ -559,7 +558,8 @@ inform LDK about these transactions/outputs in Step 14. ```kotlin val keySeed = ByteArray(32) - + // val keysManager = KeysManager.of( keySeed, System.currentTimeMillis() / 1000, @@ -583,7 +583,7 @@ generation is unique across restarts. **References:** [Rust `KeysManager` docs](https://docs.rs/lightning/*/lightning/chain/keysinterface/struct.KeysManager.html), [Java `KeysManager` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/KeysManager.java) -### Step 7. Read `ChannelMonitor` state from disk +### Read `ChannelMonitor` state from disk **What it's used for:** if LDK is restarting and has at least 1 channel, its `ChannelMonitor`s will need to be (1) fed to the `ChannelManager` and (2) synced to chain. @@ -608,19 +608,19 @@ generation is unique across restarts. ```java // Initialize the array where we'll store the `ChannelMonitor`s read from disk. - final ArrayList channel_monitor_list = new ArrayList<>(); + final ArrayList channelMonitorList = new ArrayList<>(); // For each monitor stored on disk, deserialize it and place it in // `channel_monitors`. for (... : monitor_files) { - byte[] channel_monitor_bytes = // read the bytes from disk the same way you - // wrote them in Step 4 - channel_monitor_list.add(channel_monitor_bytes); + byte[] channelMonitorBytes = // read the bytes from disk + + channelMonitorList.add(channelMonitorBytes); } // Convert the ArrayList into an array so we can pass it to // `ChannelManagerConstructor`. - final byte[][] channel_monitors = (byte[][])channel_monitor_list.toArray(new byte[1][]); + final byte[][] channelMonitors = (byte[][])channelMonitorList.toArray(new byte[1][]); ``` @@ -646,7 +646,7 @@ generation is unique across restarts. **References:** [Rust `load_outputs_to_watch` docs](https://docs.rs/lightning/*/lightning/chain/channelmonitor/struct.ChannelMonitor.html#method.load_outputs_to_watch) -### Step 8. Initialize the `ChannelManager` +### Initialize the `ChannelManager` **What it's used for:** managing channel state @@ -706,21 +706,21 @@ generation is unique across restarts. ```java /* FRESH CHANNELMANAGER */ - int block_height = // ; - byte[] best_block_hash = // ; - ChannelManagerConstructor channel_manager_constructor = new ChannelManagerConstructor( - Network.LDKNetwork_Bitcoin, UserConfig.default(), best_block_hash, - block_height, keys_manager.as_KeysInterface(), fee_estimator, chain_monitor, - router, tx_broadcaster, logger); + int bestBlockHeight = // ; + byte[] bestBlockHash = // ; + ChannelManagerConstructor channelManagerConstructor = new ChannelManagerConstructor( + Network.LDKNetwork_Bitcoin, UserConfig.default(), bestBlockHash, + bestBlockHeight, keysManager.as_KeysInterface(), feeEstimator, chainMonitor, + router, txBroadcaster, logger); /* RESTARTING CHANNELMANAGER */ - byte[] serialized_channel_manager = // - ChannelManagerConstructor channel_manager_constructor = new ChannelManagerConstructor( - serialized_channel_manager, channel_monitors, keys_manager.as_KeysInterface(), - fee_estimator, chain_monitor, filter, router, tx_broadcaster, logger); + byte[] serializedChannelManager = // + ChannelManagerConstructor channelManagerConstructor = new ChannelManagerConstructor( + serializedChannelManager, channelMonitors, keysManager.as_KeysInterface(), + feeEstimator, chainMonitor, filter, router, txBroadcaster, logger); - final ChannelManager channel_manager = channel_manager_constructor.channel_manager; + final ChannelManager channelManager = channelManagerConstructor.channel_manager; ``` @@ -734,11 +734,11 @@ generation is unique across restarts. serializedChannelManager, channelMonitors, userConfig, - keysManager?.as_KeysInterface(), + keysManager.as_KeysInterface(), feeEstimator, chainMonitor, txFilter, - router!!.write(), + router.write(), txBroadcaster, logger ); @@ -749,7 +749,7 @@ generation is unique across restarts. userConfig, latestBlockHash, latestBlockHeight, - keysManager?.as_KeysInterface(), + keysManager.as_KeysInterface(), feeEstimator, chainMonitor, router, @@ -762,14 +762,14 @@ generation is unique across restarts. **Implementation notes:** No methods should be called on `ChannelManager` until -*after* Step 9. +*after* the `ChannelMonitor`s and `ChannelManager` are synced to the chain tip (next step). **Dependencies:** `KeysManager`, `FeeEstimator`, `ChainMonitor`, `BroadcasterInterface`, `Logger` * If restarting: `ChannelMonitor`s and `ChannelManager` bytes from Step 7 and Step 18 respectively **References:** [Rust `ChannelManager` docs](https://docs.rs/lightning/*/lightning/ln/channelmanager/struct.ChannelManager.html), [Java `ChannelManager` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/ChannelManager.java) -### Step 9. Sync `ChannelMonitor`s and `ChannelManager` to 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 **Example:** @@ -953,58 +953,13 @@ Otherwise, you can use LDK's `Confirm` interface as in the examples above. The h 2. Tell LDK what your best known block header and height is. 3. Call `channel_manager_constructor.chain_sync_completed(..)` to complete the initial sync process. -**More details about LDK's interfaces to provide chain info in Step 14** - **References:** [Rust `Confirm` docs](https://docs.rs/lightning/*/lightning/chain/trait.Confirm.html), [Rust `Listen` docs](https://docs.rs/lightning/*/lightning/chain/trait.Listen.html), [Rust `lightning_block_sync` module docs](https://docs.rs/lightning-block-sync/*/lightning_block_sync/) **Dependencies:** `ChannelManager`, `ChainMonitor`, `ChannelMonitor`s * If providing providing full blocks or BIP 157/158: set of `ChannelMonitor`s * If using Electrum: `ChainMonitor` -### Step 10. Give `ChannelMonitor`s to `ChainMonitor` -**What it's used for:** `ChainMonitor` is responsible for updating the `ChannelMonitor`s during LDK node operation. - - - - - - - - - -**Dependencies:** -* `ChainMonitor`, set of `ChannelMonitor`s and their funding outpoints -* Step 9 must be completed prior to this step - -### Step 11: Optional: Initialize the `P2PGossipSync` +###Optional: Initialize the `P2PGossipSync` **You must follow this step if:** you need LDK to provide routes for sending payments (i.e. you are *not* providing your own routes) From 32b076e08dc05c1a1a623925c1dcba5d7c04d6eb Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Wed, 25 Jan 2023 17:06:27 +0000 Subject: [PATCH 15/57] Removes channel_watch instructions --- .../building-a-node-with-ldk/setting-up-a-channel-manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md index 9a9f67d04..81f8cea2d 100644 --- a/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md +++ b/docs/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager.md @@ -959,7 +959,7 @@ Otherwise, you can use LDK's `Confirm` interface as in the examples above. The h * If providing providing full blocks or BIP 157/158: set of `ChannelMonitor`s * If using Electrum: `ChainMonitor` -###Optional: Initialize the `P2PGossipSync` +### Optional: Initialize the `P2PGossipSync` **You must follow this step if:** you need LDK to provide routes for sending payments (i.e. you are *not* providing your own routes) From 5365b0ee60e88a0605425c288e909b24dd460348 Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Thu, 23 Feb 2023 11:33:41 -0500 Subject: [PATCH 16/57] Adds handling events page --- docs/.vuepress/config.js | 4 ++ .../handling-events.md | 67 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 docs/tutorials/building-a-node-with-ldk/handling-events.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 915472ab6..af381a9b0 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -136,6 +136,10 @@ const tutorialSidebar = [ "/tutorials/building-a-node-with-ldk/setting-up-a-channel-manager", "Setting up a Channel Manager", ], + [ + "/tutorials/building-a-node-with-ldk/handling-events", + "Handling Events", + ], [ "/tutorials/building-a-node-with-ldk/setting-up-a-peer-manager", "Setting up a Peer Manager", diff --git a/docs/tutorials/building-a-node-with-ldk/handling-events.md b/docs/tutorials/building-a-node-with-ldk/handling-events.md new file mode 100644 index 000000000..3b3e2dc9e --- /dev/null +++ b/docs/tutorials/building-a-node-with-ldk/handling-events.md @@ -0,0 +1,67 @@ +# Handling Events + +LDK requires that you handle many different events throughout your app's life cycle. You can learn more by reading about our event-driven [architecture](/overview/architecture.md). + +To start handling events in your application, run: + + + + + + + + From 3bba3183c6981f2d927431ed4c6145320bb24468 Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Tue, 14 Mar 2023 10:48:30 +0000 Subject: [PATCH 17/57] Link to Rust API docs --- .../building-a-node-with-ldk/introduction.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/tutorials/building-a-node-with-ldk/introduction.md b/docs/tutorials/building-a-node-with-ldk/introduction.md index 95879daaf..a355f1c53 100644 --- a/docs/tutorials/building-a-node-with-ldk/introduction.md +++ b/docs/tutorials/building-a-node-with-ldk/introduction.md @@ -8,28 +8,28 @@ For an integrated example of an LDK node in Rust, see the [Sample Node](https:// The following tutorials will show you how to build the simplest lightning node using LDK, that fufills the following tasks: -1. **Connect to peers** -2. **Open channels** +1. **Connecting to Peers** +2. **Open Channels** 3. **Send Payments** 4. **Receive Payments** -5. **Close channels** +5. **Close Channels** ### Foundational Components Let's start by looking at the core components we'll need to make this node work for the tasks we outlined above. -1. A `PeerManager`, for establishing TCP/IP connections to other nodes on the lightning network. -2. A `ChannelManager`, to open and close channels. +1. A [`PeerManager`](https://docs.rs/lightning/*/lightning/ln/peer_handler/struct.PeerManager.html), for establishing TCP/IP connections to other nodes on the lightning network. +2. A [`ChannelManager`](https://docs.rs/lightning/*/lightning/ln/channelmanager/struct.ChannelManager.html), to open and close channels. 3. Payments & Routing, ability to create and pay invoices. To make the above work we also need to setup a series of supporting modules, including: -1. A `FeeEstimator` -2. A `Logger` -3. A `TransactionBroadcaster` -4. A `NetworkGraph` -5. A `Persister` -6. An `EventHandler` -7. A `TransactionFilter` -8. A `ChainMonitor` -9. A `KeysManager` -10. A `Scorer` +1. A [`FeeEstimator`](https://docs.rs/lightning/*/lightning/chain/chaininterface/trait.FeeEstimator.html) +2. A [`Logger`](https://docs.rs/lightning/*/lightning/util/logger/index.html) +3. A Transaction [`Broadcaster`](https://docs.rs/lightning/*/lightning/chain/chaininterface/trait.BroadcasterInterface.html) +4. A [`NetworkGraph`](https://docs.rs/lightning/*/lightning/routing/gossip/struct.NetworkGraph.html) +5. A [`Persister`](https://docs.rs/lightning/*/lightning/util/persist/trait.Persister.html) +6. An [`EventHandler`](https://docs.rs/lightning/*/lightning/util/events/trait.EventHandler.html) +7. A Transaction [`Filter`](https://docs.rs/lightning/*/lightning/chain/trait.Filter.html) +8. A [`ChainMonitor`](https://docs.rs/lightning/*/lightning/chain/chainmonitor/index.html) +9. A [`KeysManager`](https://docs.rs/lightning/*/lightning/chain/keysinterface/struct.KeysManager.html) +10. A [`Scorer`](https://docs.rs/lightning/*/lightning/routing/scoring/index.html) From ad64818588f9bc9c16351450c3d50c85b76b362b Mon Sep 17 00:00:00 2001 From: Conor Okus Date: Tue, 14 Mar 2023 19:47:31 +0000 Subject: [PATCH 18/57] Remove Java code snippets --- .../connect-to-peers.md | 39 +-- .../handling-events.md | 49 +--- .../opening-a-channel.md | 84 ++---- .../setting-up-a-channel-manager.md | 268 ++---------------- .../setting-up-a-peer-manager.md | 14 +- 5 files changed, 56 insertions(+), 398 deletions(-) diff --git a/docs/tutorials/building-a-node-with-ldk/connect-to-peers.md b/docs/tutorials/building-a-node-with-ldk/connect-to-peers.md index 488d1c1b4..0f132f139 100644 --- a/docs/tutorials/building-a-node-with-ldk/connect-to-peers.md +++ b/docs/tutorials/building-a-node-with-ldk/connect-to-peers.md @@ -2,11 +2,11 @@ In this section you'll learn how to join the lightning network. -Firstly we need to have the ability to do high performance I/O operations. LDK provides default implementations for initializing all of your networking needs. If you are using Rust, you can use our simple socket handling library `lightning_net_tokio`. In Java you can use the `NioPeerHandler` which uses Java's NIO I/O interface. +Firstly we need to have the ability to do high performance I/O operations. LDK provides default implementations for initializing all of your networking needs. If you are using Rust, you can use our simple socket handling library `lightning_net_tokio`. In Kotlin/Java you can use the `NioPeerHandler` which uses Java's NIO I/O interface. **What it's used for**: making peer connections, facilitating peer data to and from LDK - + - - -