Merge branch 'refs/heads/main' into monitor-upd-persister

# Conflicts:
#	src/io/test_utils.rs

Author: arturgontijo

.github/workflows/kotlin.yml

@@ -39,6 +39,9 @@ jobs:
       - name: Generate Kotlin JVM
         run: ./scripts/uniffi_bindgen_generate_kotlin.sh
 
+      - name: Install `bindgen-cli`
+        run: cargo install --force bindgen-cli
+
       - name: Generate Kotlin Android
         run: ./scripts/uniffi_bindgen_generate_kotlin_android.sh
 

.github/workflows/lnd-integration.yml

@@ -0,0 +1,52 @@
+name: CI Checks - LND Integration Tests
+
+on: [push, pull_request]
+
+jobs:
+  check-lnd:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check and install CMake if needed
+        # lnd_grpc_rust (via prost-build v0.10.4) requires CMake >= 3.5 but is incompatible with CMake >= 4.0.
+        # This step checks if CMake is missing, below 3.5, or 4.0 or higher, and installs CMake 3.31.6 if needed,
+        # ensuring compatibility with prost-build in ubuntu-latest.
+        run: |
+          if ! command -v cmake &> /dev/null ||
+             [ "$(cmake --version | head -n1 | cut -d' ' -f3)" \< "3.5" ] ||
+             [ "$(cmake --version | head -n1 | cut -d' ' -f3)" \> "4.0" ]; then
+            sudo apt-get update
+            sudo apt-get remove -y cmake
+            wget https://github.com/Kitware/CMake/releases/download/v3.31.6/cmake-3.31.6-Linux-x86_64.sh
+            echo "518c76bd18cc4ca5faab891db69b1289dc1bf134f394f0983a19576711b95210  cmake-3.31.6-Linux-x86_64.sh" | sha256sum -c - || {
+              echo "Error: The checksum of the downloaded file does not match the expected value!"
+              exit 1
+            }
+            chmod +x cmake-3.31.6-Linux-x86_64.sh
+            sudo ./cmake-3.31.6-Linux-x86_64.sh --prefix=/usr/local --skip-license
+          fi
+
+      - name: Create temporary directory for LND data
+        id: create-temp-dir
+        run: echo "LND_DATA_DIR=$(mktemp -d)" >> $GITHUB_ENV
+
+      - name: Start bitcoind, electrs, and LND
+        run: docker compose -f docker-compose-lnd.yml up -d
+        env:
+          LND_DATA_DIR: ${{ env.LND_DATA_DIR }}
+
+      - name: Set permissions for LND data directory
+        # In PR 4622 (https://github.com/lightningnetwork/lnd/pull/4622),
+        # LND sets file permissions to 0700, preventing test code from accessing them.
+        # This step ensures the test suite has the necessary permissions.
+        run: sudo chmod -R 755 $LND_DATA_DIR
+        env:
+          LND_DATA_DIR: ${{ env.LND_DATA_DIR }}
+
+      - name: Run LND integration tests
+        run: LND_CERT_PATH=$LND_DATA_DIR/tls.cert LND_MACAROON_PATH=$LND_DATA_DIR/data/chain/bitcoin/regtest/admin.macaroon
+          RUSTFLAGS="--cfg lnd_test" cargo test --test integration_tests_lnd -- --exact --show-output
+        env:
+          LND_DATA_DIR: ${{ env.LND_DATA_DIR }}

.github/workflows/rust.yml

@@ -46,6 +46,7 @@ jobs:
         if: matrix.msrv
         run: |
           cargo update -p home --precise "0.5.9" --verbose # home v0.5.11 requires rustc 1.81 or newer
+          cargo update -p idna_adapter --precise "1.1.0" --verbose # idna_adapter 1.2 switched to ICU4X, requiring 1.81 and newer
       - name: Set RUSTFLAGS to deny warnings
         if: "matrix.toolchain == 'stable'"
         run: echo "RUSTFLAGS=-D warnings" >> "$GITHUB_ENV"

CHANGELOG.md

@@ -1,3 +1,60 @@
+# 0.5.0 - Apr. 29, 2025
+Besides numerous API improvements and bugfixes this fifth minor release notably adds support for sourcing chain and fee rate data from an Electrum backend, requesting channels via the [bLIP-51 / LSPS1](https://github.com/lightning/blips/blob/master/blip-0051.md) protocol, as well as experimental support for operating as a [bLIP-52 / LSPS2](https://github.com/lightning/blips/blob/master/blip-0052.md) service.
+
+## Feature and API updates
+- The `PaymentSuccessful` event now exposes a `payment_preimage` field (#392).
+- The node now emits `PaymentForwarded` events for forwarded payments (#404).
+- The ability to send custom TLVs as part of spontaneous payments has been added (#411).
+- The ability to override the used fee rates for on-chain sending has been added (#434).
+- The ability to set a description hash when creating a BOLT11 invoice has been added (#438).
+- The ability to export pathfinding scores has been added (#458).
+- The ability to request inbound channels from an LSP via the bLIP-51 / LSPS1 protocol has been added (#418).
+- The `ChannelDetails` returned by `Node::list_channels` now exposes fields for the channel's SCIDs (#444).
+- Lightning peer-to-peer gossip data is now being verified when syncing from a Bitcoin Core RPC backend (#428).
+- The logging sub-system was reworked to allow logging to backends using the Rust [`log`](https://crates.io/crates/log) facade, as well as via a custom logger trait (#407, #450, #454).
+- On-chain transactions are now added to the internal payment store and exposed via `Node::list_payments` (#432).
+- Inbound announced channels are now rejected if not all requirements for operating as a forwarding node (set listening addresses and node alias) have been met (#467).
+- Initial support for operating as an bLIP-52 / LSPS2 service has been added (#420).
+    - **Note**: bLIP-52 / LSPS2 support is considered 'alpha'/'experimental' and should *not* yet be used in production.
+- The `Builder::set_entropy_seed_bytes` method now takes an array rather than a `Vec` (#493).
+- The builder will now return a `NetworkMismatch` error in case of network switching (#485).
+- The `Bolt11Jit` payment variant now exposes a field telling how much fee the LSP withheld (#497).
+- The ability to disable syncing Lightning and on-chain wallets in the background has been added. If it is disabled, the user is responsible for running `Node::sync_wallets` manually (#508).
+- The ability to configure the node's announcement addresses independently from the listening addresses has been added (#484).
+- The ability to choose whether to honor the Anchor reserves when calling `send_all_to_address` has been added (#345).
+- The ability to sync the node via an Electrum backend has been added (#486).
+
+## Bug Fixes and Improvements
+- When syncing from Bitcoin Core RPC, syncing mempool entries has been made more efficient (#410, #465).
+- We now ensure the our configured fallback rates are used when the configured chain source would return huge bogus values during fee estimation (#430).
+- We now re-enabled trying to bump Anchor channel transactions for trusted counterparties in the `ContentiousClaimable` case to reduce the risk of losing funds in certain edge cases (#461).
+- An issue that would potentially have us panic on retrying the chain listening initialization when syncing from Bitcoin Core RPC has been fixed (#471).
+- The `Node::remove_payment` now also removes the respective entry from the in-memory state, not only from the persisted payment store (#514).
+
+## Compatibility Notes
+- The filesystem logger was simplified and its default path changed to `ldk_node.log` in the configured storage directory (#394).
+- The BDK dependency has been bumped to `bdk_wallet` v1.0 (#426).
+- The LDK dependency has been bumped to `lightning` v0.1 (#426).
+- The `rusqlite` dependency has been bumped to v0.31 (#403).
+- The minimum supported Rust version (MSRV) has been bumped to v1.75 (#429).
+
+In total, this release features 53 files changed, 6147 insertions, 1193 deletions, in 191 commits from 14 authors in alphabetical order:
+
+- alexanderwiederin
+- Andrei
+- Artur Gontijo
+- Ayla Greystone
+- Elias Rohrer
+- elnosh
+- Enigbe Ochekliye
+- Evan Feenstra
+- G8XSU
+- Joost Jager
+- maan2003
+- moisesPompilio
+- Rob N
+- Vincenzo Palazzo
+
 # 0.4.3 - Jan. 23, 2025
 
 This patch release fixes the broken Rust build resulting from `cargo` treating the recent v0.1.0 release of `lightning-liquidity` as API-compatible with the previous v0.1.0-alpha.6 release (even though it's not).

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ldk-node"
-version = "0.5.0+git"
+version = "0.6.0+git"
 authors = ["Elias Rohrer <[email protected]>"]
 homepage = "https://lightningdevkit.org/"
 license = "MIT OR Apache-2.0"
@@ -36,7 +36,7 @@ lightning-persister = { version = "0.1.0" }
 lightning-background-processor = { version = "0.1.0", features = ["futures"] }
 lightning-rapid-gossip-sync = { version = "0.1.0" }
 lightning-block-sync = { version = "0.1.0", features = ["rpc-client", "tokio"] }
-lightning-transaction-sync = { version = "0.1.0", features = ["esplora-async-https", "time"] }
+lightning-transaction-sync = { version = "0.1.0", features = ["esplora-async-https", "time", "electrum"] }
 lightning-liquidity = { version = "0.1.0", features = ["std"] }
 
 #lightning = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main", features = ["std"] }
@@ -47,7 +47,7 @@ lightning-liquidity = { version = "0.1.0", features = ["std"] }
 #lightning-background-processor = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main", features = ["futures"] }
 #lightning-rapid-gossip-sync = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main" }
 #lightning-block-sync = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main", features = ["rpc-client", "tokio"] }
-#lightning-transaction-sync = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main", features = ["esplora-async-https", "time"] }
+#lightning-transaction-sync = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main", features = ["esplora-async-https", "electrum", "time"] }
 #lightning-liquidity = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main" }
 
 #lightning = { path = "../rust-lightning/lightning", features = ["std"] }
@@ -58,11 +58,12 @@ lightning-liquidity = { version = "0.1.0", features = ["std"] }
 #lightning-background-processor = { path = "../rust-lightning/lightning-background-processor", features = ["futures"] }
 #lightning-rapid-gossip-sync = { path = "../rust-lightning/lightning-rapid-gossip-sync" }
 #lightning-block-sync = { path = "../rust-lightning/lightning-block-sync", features = ["rpc-client", "tokio"] }
-#lightning-transaction-sync = { path = "../rust-lightning/lightning-transaction-sync", features = ["esplora-async-https", "time"] }
+#lightning-transaction-sync = { path = "../rust-lightning/lightning-transaction-sync", features = ["esplora-async-https", "electrum", "time"] }
 #lightning-liquidity = { path = "../rust-lightning/lightning-liquidity", features = ["std"] }
 
 bdk_chain = { version = "0.21.1", default-features = false, features = ["std"] }
 bdk_esplora = { version = "0.20.1", default-features = false, features = ["async-https-rustls", "tokio"]}
+bdk_electrum = { version = "0.20.1", default-features = false, features = ["use-rustls"]}
 bdk_wallet = { version = "1.0.0", default-features = false, features = ["std", "keys-bip39"]}
 
 reqwest = { version = "0.11", default-features = false, features = ["json", "rustls-tls"] }
@@ -76,6 +77,7 @@ rand = "0.8.5"
 chrono = { version = "0.4", default-features = false, features = ["clock"] }
 tokio = { version = "1.37", default-features = false, features = [ "rt-multi-thread", "time", "sync", "macros" ] }
 esplora-client = { version = "0.11", default-features = false, features = ["tokio", "async-https-rustls"] }
+electrum-client = { version = "0.22.0", default-features = true }
 libc = "0.2"
 uniffi = { version = "0.27.3", features = ["build"], optional = true }
 serde = { version = "1.0.210", default-features = false, features = ["std", "derive"] }
@@ -92,20 +94,23 @@ winapi = { version = "0.3", features = ["winbase"] }
 lightning = { version = "0.1.0", features = ["std", "_test_utils"] }
 #lightning = { git = "https://github.com/lightningdevkit/rust-lightning", branch="main", features = ["std", "_test_utils"] }
 #lightning = { path = "../rust-lightning/lightning", features = ["std", "_test_utils"] }
-electrum-client = { version = "0.21.0", default-features = true }
-bitcoincore-rpc = { version = "0.19.0", default-features = false }
 proptest = "1.0.0"
 regex = "1.5.6"
 
 [target.'cfg(not(no_download))'.dev-dependencies]
-electrsd = { version = "0.29.0", features = ["legacy", "esplora_a33e97e1", "bitcoind_25_0"] }
+electrsd = { version = "0.33.0", default-features = false, features = ["legacy", "esplora_a33e97e1", "corepc-node_27_2"] }
 
 [target.'cfg(no_download)'.dev-dependencies]
-electrsd = { version = "0.29.0", features = ["legacy"] }
+electrsd = { version = "0.33.0", default-features = false, features = ["legacy"] }
+corepc-node = { version = "0.7.0", default-features = false, features = ["27_2"] }
 
 [target.'cfg(cln_test)'.dev-dependencies]
 clightningrpc = { version = "0.3.0-beta.8", default-features = false }
 
+[target.'cfg(lnd_test)'.dev-dependencies]
+lnd_grpc_rust = { version = "2.10.0", default-features = false }
+tokio = { version = "1.37", features = ["fs"] }
+
 [build-dependencies]
 uniffi = { version = "0.27.3", features = ["build"], optional = true }
 
@@ -123,4 +128,5 @@ check-cfg = [
 	"cfg(ldk_bench)",
 	"cfg(tokio_unstable)",
 	"cfg(cln_test)",
+	"cfg(lnd_test)",
 ]

Package.swift

@@ -3,8 +3,8 @@
 
 import PackageDescription
 
-let tag = "v0.4.2"
-let checksum = "95ea5307eb3a99203e39cfa21d962bfe3e879e62429e8c7cdf5292cae5dc35cc"
+let tag = "v0.5.0"
+let checksum = "fd9eb84a478402af8f790519a463b6e1bf6ab3987f5951cd8375afb9d39e7a4b"
 let url = "https://github.com/lightningdevkit/ldk-node/releases/download/\(tag)/LDKNodeFFI.xcframework.zip"
 
 let package = Package(

README.md

@@ -55,7 +55,7 @@ fn main() {
 LDK Node currently comes with a decidedly opinionated set of design choices:
 
 - On-chain data is handled by the integrated [BDK][bdk] wallet.
-- Chain data may currently be sourced from the Bitcoin Core RPC interface or an [Esplora][esplora] server, while support for Electrum will follow soon.
+- Chain data may currently be sourced from the Bitcoin Core RPC interface, or from an [Electrum][electrum] or [Esplora][esplora] server.
 - Wallet and channel state may be persisted to an [SQLite][sqlite] database, to file system, or to a custom back-end to be implemented by the user.
 - Gossip data may be sourced via Lightning's peer-to-peer network or the [Rapid Gossip Sync](https://docs.rs/lightning-rapid-gossip-sync/*/lightning_rapid_gossip_sync/) protocol.
 - Entropy for the Lightning and on-chain wallets may be sourced from raw bytes or a [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) mnemonic. In addition, LDK Node offers the means to generate and persist the entropy bytes to disk.
@@ -72,6 +72,7 @@ The Minimum Supported Rust Version (MSRV) is currently 1.75.0.
 [rust_crate]: https://crates.io/
 [ldk]: https://lightningdevkit.org/
 [bdk]: https://bitcoindevkit.org/
+[electrum]: https://github.com/spesmilo/electrum-protocol
 [esplora]: https://github.com/Blockstream/esplora
 [sqlite]: https://sqlite.org/
 [rust]: https://www.rust-lang.org/

bindings/kotlin/ldk-node-android/gradle.properties

@@ -2,4 +2,4 @@ org.gradle.jvmargs=-Xmx1536m
 android.useAndroidX=true
 android.enableJetifier=true
 kotlin.code.style=official
-libraryVersion=0.4.2
+libraryVersion=0.5.0

bindings/kotlin/ldk-node-jvm/gradle.properties

@@ -1,3 +1,3 @@
 org.gradle.jvmargs=-Xmx1536m
 kotlin.code.style=official
-libraryVersion=0.4.2
+libraryVersion=0.5.0

bindings/ldk_node.udl

@@ -7,6 +7,7 @@ dictionary Config {
 	string storage_dir_path;
 	Network network;
 	sequence<SocketAddress>? listening_addresses;
+	sequence<SocketAddress>? announcement_addresses;
 	NodeAlias? node_alias;
 	sequence<PublicKey> trusted_peers_0conf;
 	u64 probing_liquidity_limit_multiplier;
@@ -19,12 +20,32 @@ dictionary AnchorChannelsConfig {
 	u64 per_channel_reserve_sats;
 };
 
-dictionary EsploraSyncConfig {
+dictionary BackgroundSyncConfig {
 	u64 onchain_wallet_sync_interval_secs;
 	u64 lightning_wallet_sync_interval_secs;
 	u64 fee_rate_cache_update_interval_secs;
 };
 
+dictionary EsploraSyncConfig {
+	BackgroundSyncConfig? background_sync_config;
+};
+
+dictionary ElectrumSyncConfig {
+	BackgroundSyncConfig? background_sync_config;
+};
+
+dictionary LSPS2ServiceConfig {
+	string? require_token;
+	boolean advertise_service;
+	u32 channel_opening_fee_ppm;
+	u32 channel_over_provisioning_ppm;
+	u64 min_channel_opening_fee_msat;
+	u32 min_channel_lifetime;
+	u32 max_client_to_self_delay;
+	u64 min_payment_size_msat;
+	u64 max_payment_size_msat;
+};
+
 enum LogLevel {
 	"Gossip",
 	"Trace",
@@ -55,19 +76,22 @@ interface Builder {
 	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);
 	void set_gossip_source_p2p();
 	void set_gossip_source_rgs(string rgs_server_url);
 	void set_liquidity_source_lsps1(PublicKey node_id, SocketAddress address, string? token);
 	void set_liquidity_source_lsps2(PublicKey node_id, SocketAddress address, string? token);
 	void set_storage_dir_path(string storage_dir_path);
 	void set_filesystem_logger(string? log_file_path, LogLevel? max_log_level);
-	void set_log_facade_logger(LogLevel? max_log_level);
+	void set_log_facade_logger();
 	void set_custom_logger(LogWriter log_writer);
 	void set_network(Network network);
 	[Throws=BuildError]
 	void set_listening_addresses(sequence<SocketAddress> listening_addresses);
 	[Throws=BuildError]
+	void set_announcement_addresses(sequence<SocketAddress> announcement_addresses);
+	[Throws=BuildError]
 	void set_node_alias(string node_alias);
 	[Throws=BuildError]
 	Node build();
@@ -92,9 +116,11 @@ interface Node {
 	Event wait_next_event();
 	[Async]
 	Event next_event_async();
+	[Throws=NodeError]
 	void event_handled();
 	PublicKey node_id();
 	sequence<SocketAddress>? listening_addresses();
+	sequence<SocketAddress>? announcement_addresses();
 	NodeAlias? node_alias();
 	Bolt11Payment bolt11_payment();
 	Bolt12Payment bolt12_payment();
@@ -302,13 +328,15 @@ enum BuildError {
 	"InvalidSystemTime",
 	"InvalidChannelMonitor",
 	"InvalidListeningAddresses",
+	"InvalidAnnouncementAddresses",
 	"InvalidNodeAlias",
 	"ReadFailed",
 	"WriteFailed",
 	"StoragePathAccessFailed",
 	"KVStoreSetupFailed",
 	"WalletSetupFailed",
 	"LoggerSetupFailed",
+	"NetworkMismatch",
 };
 
 [Trait]
@@ -373,7 +401,7 @@ interface ClosureReason {
 interface PaymentKind {
 	Onchain(Txid txid, ConfirmationStatus status);
 	Bolt11(PaymentHash hash, PaymentPreimage? preimage, PaymentSecret? secret);
-	Bolt11Jit(PaymentHash hash, PaymentPreimage? preimage, PaymentSecret? secret, LSPFeeLimits lsp_fee_limits);
+	Bolt11Jit(PaymentHash hash, PaymentPreimage? preimage, PaymentSecret? secret, u64? counterparty_skimmed_fee_msat, LSPFeeLimits lsp_fee_limits);
 	Bolt12Offer(PaymentHash? hash, PaymentPreimage? preimage, PaymentSecret? secret, OfferId offer_id, UntrustedString? payer_note, u64? quantity);
 	Bolt12Refund(PaymentHash? hash, PaymentPreimage? preimage, PaymentSecret? secret, UntrustedString? payer_note, u64? quantity);
 	Spontaneous(PaymentHash hash, PaymentPreimage? preimage);
@@ -412,6 +440,7 @@ dictionary PaymentDetails {
 	PaymentId id;
 	PaymentKind kind;
 	u64? amount_msat;
+	u64? fee_paid_msat;
 	PaymentDirection direction;
 	PaymentStatus status;
 	u64 latest_update_timestamp;