v0.7.0-rc.28

0.7.0-rc.28 (Synonym Fork)

Bug Fixes

• Fixed PeerStore::add_peer silently ignoring address updates for existing peers. When a peer's
  IP address changes (e.g., LSP node migration), add_peer now upserts the socket address and
  re-persists, instead of returning early. This fixes the issue where ldk-node's reconnection loop
  would indefinitely use a stale cached IP after an LSP node IP change.
  (See upstream issue #700)
• Backported upstream Electrum sync fix (PR #4341): Skip unconfirmed get_history entries in
  ElectrumSyncClient. Previously, mempool entries (height=0 or -1) were incorrectly treated as
  confirmed, causing get_merkle to fail for 0-conf channel funding transactions.
• Fixed duplicate payment events (PaymentReceived, PaymentSuccessful, PaymentFailed) being
  emitted when LDK replays events after node restart.
• Switched from forked rust-lightning (ovitrif/rust-lightning#0.2-electrum-fix) back to official
  upstream crates.io releases. The Electrum sync fix (PR #4341) is now in upstream
  lightning-transaction-sync v0.2.1. Also picks up lightning v0.2.2 fixes.

Synonym Fork Additions

• Added runtime APIs for dynamic address type management:
  • Node::add_address_type_to_monitor() and add_address_type_to_monitor_with_mnemonic() to add an address type to the monitored set
  • Node::remove_address_type_from_monitor() to unload an address type (persisted state retained for re-add)
  • Node::set_primary_address_type() and set_primary_address_type_with_mnemonic() to change the primary; previous primary is demoted to monitored
  • New errors: AddressTypeAlreadyMonitored, AddressTypeIsPrimary, AddressTypeNotMonitored, InvalidSeedBytes
  • Not persisted across restarts; re-apply on each start or set in Config for persistence
• Added multi-address type wallet support with a new bdk-wallet-aggregate crate:
  • AddressType enum: Legacy, NestedSegwit, NativeSegwit, Taproot
  • NodeBuilder::set_address_type() to configure the primary wallet address type
  • NodeBuilder::set_address_types_to_monitor() to track funds across multiple address types
  • Node::get_balance_for_address_type() to query per-wallet balances
  • Node::list_monitored_address_types() to list loaded wallet types
  • OnchainPayment::new_address_for_type() to generate addresses for a specific type
  • send_to_address / send_all_to_address: unified coin selection pools UTXOs from all loaded wallets and selects optimally across the full set; send_all drains all wallets
  • RBF and CPFP fee bumping work across wallets (cross-wallet inputs are re-signed)
  • Channel funding uses unified coin selection across all SegWit wallets (NestedSegwit can fund channels; Legacy excluded per BOLT 2)
  • Channel shutdown and destination scripts always use native witness addresses, with automatic fallback to a loaded NativeSegwit/Taproot wallet when the primary is Legacy or NestedSegwit
  • Splicing is restricted to native witness primaries (NativeSegwit/Taproot); non-native primaries return a graceful error
  • Change outputs go to the primary wallet
  • Monitored wallets are synced in parallel alongside the primary (Esplora and Electrum)
  • P2PKH and P2SH UTXOs are now handled in OutputSpender (previously panicked on non-witness scripts)
  • Migration-safe persistence: existing NativeSegwit wallet data is read from the legacy (un-namespaced) storage location
• Upgraded to Kotlin 2.2.0 for compatibility with consuming apps using Kotlin 2.x
• Added JitPack support for ldk-node-jvm module to enable unit testing in consuming apps
• Added runtime-adjustable wallet sync intervals for battery optimization on mobile:
  • RuntimeSyncIntervals struct with configurable onchain_wallet_sync_interval_secs,
    lightning_wallet_sync_interval_secs, and fee_rate_cache_update_interval_secs
  • Node::update_sync_intervals() to change intervals while the node is running
  • Node::current_sync_intervals() to retrieve currently active intervals
  • RuntimeSyncIntervals::battery_saving() preset (5min onchain, 2min lightning, 30min fees)
  • Minimum 10-second interval enforced for all values
  • Returns BackgroundSyncNotEnabled error if manual sync mode was configured at build time
• Optimized startup performance by parallelizing VSS reads and caching network graph locally:
  • Parallelized early reads (node_metrics, payments, wallet)
  • Parallelized channel monitors and scorer reads
  • Parallelized tail reads (output_sweeper, event_queue, peer_store)
  • Added local caching for network graph to avoid slow VSS reads on startup
• Added claimable_on_close_sats field to ChannelDetails struct. This field contains the
  amount (in satoshis) that would be claimable if the channel were force-closed now, computed
  from the channel monitor's ClaimableOnChannelClose balance. Returns None if no monitor
  exists yet (pre-funding). This replaces the workaround of approximating the claimable amount
  using outbound_capacity_msat + counterparty_reserve.
• Added reactive event system for wallet monitoring without polling:
  • Onchain Transaction Events (fully implemented):
    • OnchainTransactionReceived: Emitted when a new unconfirmed transaction is
      first detected in the mempool (instant notification for incoming payments!)
    • OnchainTransactionConfirmed: Emitted when a transaction receives confirmations
    • OnchainTransactionReplaced: Emitted when a transaction is replaced (via RBF or different transaction using a common input). Includes the replaced transaction ID and the list of conflicting replacement transaction IDs.
    • OnchainTransactionReorged: Emitted when a previously confirmed transaction
      becomes unconfirmed due to a blockchain reorg
    • OnchainTransactionEvicted: Emitted when a transaction is evicted from the mempool
  • Sync Completion Event (fully implemented):
    • SyncCompleted: Emitted when onchain wallet sync finishes successfully
  • Balance Change Event (fully implemented):
    • BalanceChanged: Emitted when onchain or Lightning balances change, allowing
      applications to update balance displays immediately without polling
• Added TransactionDetails, TxInput, and TxOutput structs to provide comprehensive
  transaction information in onchain events, including inputs and outputs. This enables
  applications to analyze transaction data themselves to detect channel funding, closures,
  and other transaction types.
• Added Node::get_transaction_details() method to retrieve transaction details for any
  transaction ID that exists in the wallet, returning None if the transaction is not found.
• Added Node::get_address_balance() method to retrieve the current balance (in satoshis) for
  any Bitcoin address. This queries the chain source (Esplora or Electrum) to get the balance.
  Throws InvalidAddress if the address string cannot be parsed or doesn't match the node's
  network. Returns 0 if the balance cannot be queried (e.g., chain source unavailable). Note: This
  method is not available for BitcoindRpc chain source.
• Added SyncType enum to distinguish between onchain wallet sync, Lightning
  wallet sync, and fee rate cache updates.
• Balance tracking is now persisted in NodeMetrics to detect changes across restarts.
• Added RBF (Replace-By-Fee) support via OnchainPayment::bump_fee_by_rbf() to replace
  unconfirmed transactions with higher fee versions. Prevents RBF of channel funding
  transactions to protect channel integrity.
• Added CPFP (Child-Pays-For-Parent) support via OnchainPayment::accelerate_by_cpfp() and
  OnchainPayment::calculate_cpfp_fee_rate() to accelerate unconfirmed transactions by
  creating child transactions with higher effective fee rates.
• Added UTXO management APIs:
  • OnchainPayment::list_spendable_outputs(): Lists all UTXOs safe to spend (excludes channel funding UTXOs).
  • OnchainPayment::select_utxos_with_algorithm(): Selects UTXOs using configurable coin selection algorithms (BranchAndBound, LargestFirst, OldestFirst, SingleRandomDraw).
  • SpendableUtxo struct and CoinSelectionAlgorithm enum for UTXO management.
• Added fee estimation APIs:
  • OnchainPayment::calculate_total_fee(): Calculates transaction fees before sending.
  • Bolt11Payment::estimate_routing_fees(): Estimates Lightning routing fees before sending.
  • Bolt11Payment::estimate_routing_fees_using_amount(): Estimates fees for amount-less invoices.
• Enhanced OnchainPayment::send_to_address() to accept optional utxos_to_spend parameter
  for manual UTXO selection.
• Added Config::include_untrusted_pending_in_spendable option to control whether unconfirmed
  funds from external sources are included in spendable_onchain_balance_sats. When set to true,
  the spendable balance will include untrusted_pending UTXOs (unconfirmed transactions received
  from external wallets). Default is false for safety, as spending unconfirmed external funds
  carries risk of double-spending. This affects all balance reporting including list_balances()
  and BalanceChanged events.
• Added ChannelDataMigration struct and Builder::set_channel_data_migration() method to migrate
  channel data from external LDK implementations (e.g., react-native-ldk). The channel manager and
  monitor data is written to the configured storage during build, before channel monitors are read.
  Storage keys for monitors are derived from the funding outpoint.
• Added derive_node_secret_from_mnemonic() utility function to derive the node's secret key from a
  BIP39 mnemonic, matching LDK's KeysManager derivation path (m/0'). This enables backup authentication
  and key verification before the node starts, using the same derivation that a running Node instance
  would use internally.