diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 750792ac2..d7533d956 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -4,7 +4,7 @@ const themeConfig = require("@spiralbtc/vuepress-devkit-theme/config"); const title = "Lightning Dev Kit Documentation"; const baseUrl = "https://lightningdevkit.org"; const githubUrl = "https://github.com/lightningdevkit"; -const discordUrl = "https://discord.gg/xaYE3pDQpm"; +const discordUrl = "https://discord.gg/5AcknnMfBw"; const themeColor = "#ffffff"; const docsSidebar = [ @@ -16,35 +16,48 @@ const docsSidebar = [ title: "Introduction", path: "/introduction/", collapsable: true, - children: [["/introduction/use_cases", "Use Cases"]], - }, - "/running-a-sample-ldk-node", - { - title: "Overview", - collapsable: true, children: [ - ["/overview/architecture", "Architecture"], - ["/overview/peer-management", "Peer Management"], - ["/overview/persistent_storage", "Persistent Storage"], - ["/overview/blockchain_data", "Blockchain Data"], - ["/overview/wallet_management", "Wallet Management"], - ["/overview/networking", "Networking"], - ["/overview/private_key_management", "Private Key Management"], - ["/overview/transactions", "Transactions"], - ["/overview/random_number_generation", "Random Number Generation"], + ["/introduction/use-cases", "Use Cases"], + ["/introduction/architecture", "Architecture"], + ["/introduction/peer-management", "Peer Management"], + ["/introduction/persistent_storage", "Persistent Storage"], + ["/introduction/blockchain_data", "Blockchain Data"], + ["/introduction/wallet_management", "Wallet Management"], + ["/introduction/networking", "Networking"], + ["/introduction/private_key_management", "Private Key Management"], + ["/introduction/transactions", "Transactions"], + [ + "/introduction/random_number_generation", + "Random Number Generation", + ], ], }, { - title: "Payments", - path: "/payments/", + title: "Building a node with LDK", collapsable: true, children: [ - ["/payments/connecting_peers", "Connecting Peers"], - ["/payments/managing_channels", "Managing Channels"], - ["/payments/sending_payments", "Sending Payments"], - ["/payments/receiving_payments", "Receiving Payments"], + ["/building-a-node-with-ldk/introduction", "Introduction"], + ["/building-a-node-with-ldk/installation", "Installation"], + [ + "/building-a-node-with-ldk/setting-up-a-channel-manager", + "Setting up a Channel Manager" + ], + ["/building-a-node-with-ldk/handling-events", "Handling Events"], + [ + "/building-a-node-with-ldk/setting-up-a-peer-manager", + "Setting up a Peer Manager" + ], + ["/building-a-node-with-ldk/connect-to-peers", "Connect to Peers"], + ["/building-a-node-with-ldk/opening-a-channel", "Opening a Channel"], + ["/building-a-node-with-ldk/sending-payments", "Sending Payments"], + [ + "/building-a-node-with-ldk/receiving-payments", + "Receiving Payments" + ], + ["/building-a-node-with-ldk/closing-a-channel", "Closing a Channel"], ], }, + "/running-a-sample-ldk-node", { title: "Blockchain Data", collapsable: true, @@ -57,7 +70,7 @@ const docsSidebar = [ ["/blockchain_data/confirmed_transactions", "Confirmed Transactions"], [ "/blockchain_data/transaction_broadcasting", - "Transaction Broadcasting", + "Transaction Broadcasting" ], ], }, @@ -76,59 +89,42 @@ const docsSidebar = [ ["https://docs.rs/lightning/*/lightning/", "lightning"], [ "https://docs.rs/lightning-background-processor/*/lightning_background_processor/", - "lightning-background-processor", + "lightning-background-processor" ], [ "https://docs.rs/lightning-block-sync/*/lightning_block_sync/", - "lightning-block-sync", + "lightning-block-sync" ], [ "https://docs.rs/lightning-invoice/*/lightning_invoice/", - "lightning-invoice", + "lightning-invoice" ], [ "https://docs.rs/lightning-net-tokio/*/lightning_net_tokio/", - "lightning-net-tokio", + "lightning-net-tokio" ], [ "https://docs.rs/lightning-persister/*/lightning_persister/", - "lightning-persister", + "lightning-persister" ], [ "https://docs.rs/lightning-rapid-gossip-sync/*/lightning_rapid_gossip_sync/", - "lightning-rapid-gossip-sync", + "lightning-rapid-gossip-sync" ], [ "https://docs.rs/lightning-transaction-sync/*/lightning_transaction_sync/", - "lightning-transaction-sync", + "lightning-transaction-sync" ], [ "https://docs.rs/lightning-custom-message/*/lightning_custom_message/", - "lightning-custom-message", + "lightning-custom-message" ], ], }, [ - "https://github.com/lightningdevkit/ldk-garbagecollected/tree/main/src/main/java/org/ldk", - "Java/Kotlin", + "https://github.com/arik-so/SwiftLightning/tree/master/Documentation", + "Swift", ], - ["https://github.com/lightningdevkit/ldk-swift", "Swift"], - [ - "https://github.com/lightningdevkit/ldk-garbagecollected/tree/main/ts", - "TypeScript", - ], - ], - }, -]; - -const tutorialSidebar = [ - { - title: "Tutorials", - collapsable: false, - children: [ - "/tutorials/getting-started", - "/tutorials/build_a_node_in_java", - "/tutorials/build_a_node_in_rust", ], }, ]; @@ -186,13 +182,9 @@ module.exports = { text: "Docs", link: "/introduction/", }, - { - text: "Tutorials", - link: "/tutorials/getting-started", - }, { text: "Case Studies", - link: "/case-studies", + link: "/case-studies/", }, { text: "Blog", @@ -212,11 +204,43 @@ module.exports = { sidebar: { "/_blog/": blogSidebar, "/blog/": blogSidebar, - "/tutorials/": tutorialSidebar, "/": docsSidebar, }, footer: { links: [ + { + title: "Docs", + children: [ + { + text: "Introduction", + link: "/introduction/", + }, + { + text: "Building a node with LDK", + link: "/building-a-node-with-ldk/introduction", + }, + { + text: "Running a sample LDK node", + link: "/running-a-sample-ldk-node/", + }, + { + text: "Architecture", + link: "/introduction/architecture/", + }, + { + text: "Blockchain Data", + link: "/blockchain_data/introduction/", + }, + { + text: "Key Management", + link: "/key_management/", + }, + { + text: "Examples", + link: "/examples/", + }, + ], + }, { title: "Community", children: [ @@ -252,39 +276,6 @@ module.exports = { }, ], }, - { - title: "Docs", - children: [ - { - text: "Introduction", - link: "/introduction/", - }, - { - text: "Sample LDK node", - link: "/running-a-sample-ldk-node/", - }, - { - text: "Architecture", - link: "/overview/architecture/", - }, - { - text: "Payments", - link: "/payments/", - }, - { - text: "Blockchain Data", - link: "/blockchain_data/introduction/", - }, - { - text: "Key Management", - link: "/key_management/", - }, - { - text: "Examples", - link: "/examples/", - }, - ], - }, { title: "Resources", children: [ @@ -301,10 +292,6 @@ module.exports = { { title: "Other", children: [ - { - text: "Tutorials", - link: "/tutorials/getting-started/", - }, { text: "Bitcoin Dev Kit", link: "https://bitcoindevkit.org/", diff --git a/docs/build_node2.md b/docs/build_node2.md deleted file mode 100644 index 2118d613e..000000000 --- a/docs/build_node2.md +++ /dev/null @@ -1,51 +0,0 @@ -# Building a Node - -## Introduction -In this guide, we'll be walking through how to build a Lightning node using LDK in Java. - -The process breaks down to 3 overarching steps: -1. Initializing LDK's channel, peer, chain monitoring, and (optionally) routing objects on startup. - * These objects will be parameterized by various other objects that can be from either your custom logic or one of LDK's supplied modules. -2. Starting loops to (a) poll for new peers and (b) periodically nudge the channel and peer objects so they can properly maintain their state. -3. Connect and disconnect blocks to LDK as they come in. - -## Part 1: Startup -// start w/ a diagram -// could use a mac to do that - -### Chain Monitoring -At a high level, the first step is initializing a [`ChainMonitor` struct](https://docs.rs/lightning/0.0.12/lightning/chain/chainmonitor/struct.ChainMonitor.html) using [this]. See an example in one of our tests [in Java]. - -This will look something like this: -```java - logger = Logger.new_impl((String arg) -> System.out.println(seed + ": " + arg)); - fee_estimator = FeeEstimator.new_impl((confirmation_target -> 253)); - tx_broadcaster = BroadcasterInterface.new_impl(tx -> { - // bro - }); -``` - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/building-a-node-with-ldk/closing-a-channel.md b/docs/building-a-node-with-ldk/closing-a-channel.md new file mode 100644 index 000000000..fc274e97d --- /dev/null +++ b/docs/building-a-node-with-ldk/closing-a-channel.md @@ -0,0 +1,150 @@ +# Closing a Channel + +Begins the process of closing a channel. After this call (plus some timeout), no new HTLCs will be accepted on the given channel, and after additional timeout/the closing of all pending HTLCs, the channel will be closed on chain. + + + + + + + + +To claim Funds directly into a custom wallet like BDK wallet using a custom `KeysManager` see the [Key Management](/key_management.md) guide for more info. + +# SpendableOutputs Event Handling + + + + + + + + +**References:** [Rust `SpendableOutputs` docs](https://docs.rs/lightning/*/lightning/events/enum.Event.html#variant.SpendableOutputs), [Java/Kotlin `SpendableOutputs` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Event.java#L802) \ No newline at end of file diff --git a/docs/building-a-node-with-ldk/connect-to-peers.md b/docs/building-a-node-with-ldk/connect-to-peers.md new file mode 100644 index 000000000..2a000b94a --- /dev/null +++ b/docs/building-a-node-with-ldk/connect-to-peers.md @@ -0,0 +1,129 @@ +# Connect to Peers + +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 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 + + + + + + + + + + +Connections to other peers are established with `PeerManager`. You'll need to know the pubkey and address of another node that you want as a peer. Once the connection is established and the handshake is complete, `PeerManager` will show the peer's pubkey in its list of peers. + + + + + + + + + + +**Dependencies:** `PeerManager` + +**References:** [Rust `lightning-net-tokio` docs](https://docs.rs/lightning-net-tokio/*/lightning_net_tokio/), [Rust `PeerManager` docs](https://docs.rs/lightning/*/lightning/ln/peer_handler/struct.PeerManager.html), [Java/Kotlin `NioPeerHandler` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/batteries/NioPeerHandler.java), +[Java/Kotlin `PeerManager` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/PeerManager.java), diff --git a/docs/building-a-node-with-ldk/handling-events.md b/docs/building-a-node-with-ldk/handling-events.md new file mode 100644 index 000000000..add5c29de --- /dev/null +++ b/docs/building-a-node-with-ldk/handling-events.md @@ -0,0 +1,72 @@ +# 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: + + + + + + + + + + +References: [Rust `Event` docs](https://docs.rs/lightning/*/lightning/util/events/enum.Event.html), [Java/Kotlin `Event` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Event.java) diff --git a/docs/building-a-node-with-ldk/installation.md b/docs/building-a-node-with-ldk/installation.md new file mode 100644 index 000000000..6249a3326 --- /dev/null +++ b/docs/building-a-node-with-ldk/installation.md @@ -0,0 +1,84 @@ +# Getting started + +Welcome to the Lightning Development Kit documentation! + +If you have any questions about anything related to LDK, feel free to ask our community on [GitHub Discussions](https://github.com/orgs/lightningdevkit/discussions) or join us on [Discord](https://discord.gg/xaYE3pDQpm). + +## Installation + +Add LDK to a project by configuring the respective config files: + + + + + + + +Example usage after installation is complete: + + + + + + + + +::: tip Installing LDK Swift +Add ldk-swift package using the Swift Package Manager. + +To import the package, use: `import LightningDevKit` + +::: diff --git a/docs/building-a-node-with-ldk/introduction.md b/docs/building-a-node-with-ldk/introduction.md new file mode 100644 index 000000000..a169a58fc --- /dev/null +++ b/docs/building-a-node-with-ldk/introduction.md @@ -0,0 +1,36 @@ +# Building a Node with 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) +::: + +The following tutorials will show you how to build the simplest lightning node using LDK, that fufills the following tasks: + +1. **Connecting to Peers** +2. **Opening Channels** +3. **Sending Payments** +4. **Receiving Payments** +5. **Closing 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 [`ChannelManager`](https://docs.rs/lightning/*/lightning/ln/channelmanager/struct.ChannelManager.html), to open and close channels. +2. A networking stack (https://docs.rs/lightning-net-tokio/*/lightning_net_tokio/index.html), for establishing TCP/IP connections to other nodes on the lightning network. +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`](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/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/sign/struct.KeysManager.html) +10. A [`Scorer`](https://docs.rs/lightning/*/lightning/routing/scoring/index.html) diff --git a/docs/building-a-node-with-ldk/opening-a-channel.md b/docs/building-a-node-with-ldk/opening-a-channel.md new file mode 100644 index 000000000..22b236a16 --- /dev/null +++ b/docs/building-a-node-with-ldk/opening-a-channel.md @@ -0,0 +1,302 @@ +# Opening a Channel + +Channels are the basic building blocks of the Lightning Network. With channels, you can transact not only with your immediate peers but with others on the network. Let's explore how to open a channel with LDK. + +Now that you have a peer, you can open a channel with them using `ChannelManager`. You'll need the peer's pubkey as before along with: + +- the amount in sats to use when funding the channel, +- any msats to push to your peer, +- an id which is given back in the `FundingGenerationReady` event, +- an optional `UserConfig` for overriding `ChannelManager` defaults + +Channels can be announced to the network or can remain private, which is controlled via `UserConfig::announced_channel`. + + + + + + + + + + +# FundingGenerationReady Event Handling + +At this point, an outbound channel has been initiated with your peer and it will appear in `ChannelManager::list_channels`. However, the channel is not yet funded. Once your peer accepts the channel, you will be notified with a `FundingGenerationReady` event. It's then your responsibility to construct the funding transaction and pass it to ChannelManager, which will broadcast it once it receives your channel counterparty's signature. + +::: tip Note + +Remember that the funding transaction must only spend [SegWit](https://bitcoinops.org/en/topics/segregated-witness/) inputs. + +::: + + + + + + + + + + +**References:** [Rust `FundingGenerationReady` docs](https://docs.rs/lightning/*/lightning/util/events/enum.Event.html#variant.FundingGenerationReady), [Java `FundingGenerationReady` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Event.java#L95) + +# Broadcasting the Funding Transaction + +After crafting the funding transaction you'll need to send it to the Bitcoin network where it will hopefully be mined and added to the blockchain. You'll need to watch this transaction and wait for a minimum of 6 confirmations before the channel is ready to use. + + + + + + + + + + +**References:** [Rust `BroadcasterInterface` docs](https://docs.rs/lightning/*/lightning/chain/chaininterface/trait.BroadcasterInterface.html), [Java/Kotlin `BroadcasterInterface` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/BroadcasterInterface.java) + +::: tip Keep LDK in sync + +Remember if you are restarting and have open channels then you should [let LDK know about the latest channel state.](./setting-up-a-channel-manager/#sync-channelmonitors-and-channelmanager-to-chain-tip) + +::: diff --git a/docs/building-a-node-with-ldk/receiving-payments.md b/docs/building-a-node-with-ldk/receiving-payments.md new file mode 100644 index 000000000..1cf525ddd --- /dev/null +++ b/docs/building-a-node-with-ldk/receiving-payments.md @@ -0,0 +1,158 @@ +# Receiving Payments + +To receive a payment, you'll need to create an invoice of your own with an +amount and description. `ChannelManager` contains the remaining information +needed for the invoice. Use the provided utility to generate an invoice and +register a pending payment in `ChannelManager`. + + + + + + + + +While it is possible to create an invoice without using the utility, +`ChannelManager` will reject any incoming HTLCs for unregistered payments to +protect your privacy. In this case, use either `create_inbound_payment` or +`create_inbound_payment_for_hash` to register a payment with `ChannelManager` +before creating the invoice with the returned payment hash and/or secret. +You might also opt to for `inbound_payment`, useful for generating invoices for [phantom node payments](https://docs.rs/lightning/*/lightning/sign/struct.PhantomKeysManager.html) without a ChannelManager. + +# PaymentClaimable Event Handling + +As with sending a payment, LDK will generate an event once a payment is +received. It is your responsibility to handle the `PaymentClaimable` event by +using `ChannelManager` to release the preimage and claim the funds. + + + + + + + + +**References:** [Rust `PaymentClaimable` docs](https://docs.rs/lightning/*/lightning/events/enum.Event.html#variant.PaymentClaimable), [Java/Kotlin `PaymentClaimable` bindings](https://github.com/lightningdevkit/ldk-garbagecollected/blob/main/src/main/java/org/ldk/structs/Event.java#L261) diff --git a/docs/payments/sending_payments.md b/docs/building-a-node-with-ldk/sending-payments.md similarity index 50% rename from docs/payments/sending_payments.md rename to docs/building-a-node-with-ldk/sending-payments.md index f2788de6b..58bffdeb1 100644 --- a/docs/payments/sending_payments.md +++ b/docs/building-a-node-with-ldk/sending-payments.md @@ -5,7 +5,7 @@ string in accordance with BOLT 11. After parsing the invoice, you'll need to find a route from your node to the recipient and then make the payment using `ChannelManager`. - + -