Merge pull request #2999 from keyuebao/keyue/update-ldk-docs
[rust-lightning] / CHANGELOG.md
index a050afb7264b0220c7862671950f1a894b3004e3..3e473a22a1cd0b86fe1dc18d0c1c0f98ff58f6d2 100644 (file)
@@ -1,4 +1,281 @@
-# 0.0.117 - XXX - "Everything but the Twelve Sinks"
+# 0.0.121 - Jan 22, 2024 - "Unwraps are Bad"
+
+## Bug Fixes
+ * Fix a deadlock when calling `batch_funding_transaction_generated` with
+   invalid input (#2841).
+
+## Security
+0.0.121 fixes a denial-of-service vulnerability which is reachable from
+untrusted input from peers in rare cases if we have a public channel or in
+common cases if `P2PGossipSync` is used.
+ * A peer that failed to complete its handshake would cause a reachable
+   `unwrap` in LDK since 0.0.119 when LDK attempts to broadcast gossip to all
+   peers (#2842).
+
+In total, this release features 4 files changed, 52 insertions, 10
+deletions in 4 commits from 2 authors, in alphabetical order:
+ * Jeffrey Czyz
+ * Matt Corallo
+
+# 0.0.120 - Jan 17, 2024 - "Unblinded Fuzzers"
+
+## API Updates
+ * The `PeerManager` bound on `UtxoLookup` was removed entirely. This enables
+   use of `UtxoLookup` in cases broken in 0.0.119 by #2773 (#2822).
+ * LDK now exposes and fully implements the route blinding feature (#2812).
+ * The `lightning-transaction-sync` crate no longer relies on system time
+   without the `time` feature (#2799, #2817).
+ * `lightning::onion_message`'s module layout has changed (#2821).
+ * `Event::ChannelClosed` now includes the `channel_funding_txo` (#2800).
+ * `CandidateRouteHop` variants were destructured into individual structs,
+   hiding some fields which were not generally consumable (#2802).
+
+## Bug Fixes
+ * Fixed a rare issue where `lightning-net-tokio` may not fully flush its send
+   buffer, leading to connection hangs (#2832).
+ * Fixed a panic which may occur when connecting to a peer if we opened a second
+   channel with that peer while they were disconnected (#2808).
+ * Retries for a payment which previously failed in a blinded path will now
+   always use an alternative blinded path (#2818).
+ * `Feature`'s `Eq` and `Hash` implementation now ignore dummy bytes (#2808).
+ * Some missing `DiscardFunding` or `ChannelClosed` events are now generated in
+   rare funding-related failures (#2809).
+ * Fixed a privacy issue in blinded path generation where the real
+   `cltv_expiry_delta` would be exposed to senders (#2831).
+
+## Security
+0.0.120 fixes a denial-of-service vulnerability which is reachable from
+untrusted input from peers if the `UserConfig::manually_accept_inbound_channels`
+option is enabled.
+ * A peer that sent an `open_channel` message with the `channel_type` field
+   unfilled would trigger a reachable `unwrap` since LDK 0.0.117 (#2808).
+ * In protocols where a funding output is shared with our counterparty before
+   it is given to LDK, a malicious peer could have caused a reachable panic
+   by reusing the same funding info in (#2809).
+
+In total, this release features 67 files changed, 3016 insertions, 2473
+deletions in 79 commits from 9 authors, in alphabetical order:
+ * Elias Rohrer
+ * Jeffrey Czyz
+ * JoseĢ A.P
+ * Matt Corallo
+ * Tibo-lg
+ * Valentine Wallace
+ * benthecarman
+ * optout
+ * shuoer86
+
+# 0.0.119 - Dec 15, 2023 - "Spring Cleaning for Christmas"
+
+## API Updates
+ * The LDK crate ecosystem MSRV has been increased to 1.63 (#2681).
+ * The `bitcoin` dependency has been updated to version 0.30 (#2740).
+ * `lightning-invoice::payment::*` have been replaced with parameter generation
+   via `payment_parameters_from[_zero_amount]_invoice` (#2727).
+ * `{CoinSelection,Wallet}Source::sign_tx` are now `sign_psbt`, providing more
+   information, incl spent outputs, about the transaction being signed (#2775).
+ * Logger `Record`s now include `channel_id` and `peer_id` fields. These are
+   opportunistically filled in when a log record is specific to a given channel
+   and/or peer, and may occasionally be spuriously empty (#2314).
+ * When handling send or reply onion messages (e.g. for BOLT12 payments), a new
+   `Event::ConnectionNeeded` may be raised, indicating a direct connection
+   should be made to a payee or an introduction point. This event is expected to
+   be removed once onion message forwarding is widespread in the network (#2723)
+ * Scoring data decay now happens via `ScoreUpDate::time_passed`, called from
+   `lightning-background-processor`. `process_events_async` now takes a new
+   time-fetch function, and `ScoreUpDate` methods now take the current time as a
+   `Duration` argument. This avoids fetching time during pathfinding (#2656).
+ * Receiving payments to multi-hop blinded paths is now supported (#2688).
+ * `MessageRouter` and `Router` now feature methods to generate blinded paths to
+   the local node for incoming messages and payments. `Router` now extends
+   `MessageRouter`, and both are used in `ChannelManager` when processing or
+   creating BOLT12 structures to generate multi-hop blinded paths (#1781).
+ * `lightning-transaction-sync` now supports Electrum-based sync (#2685).
+ * `Confirm::get_relevant_txids` now returns the height at which a transaction
+   was confirmed. This can be used to assist in reorg detection (#2685).
+ * `ConfirmationTarget::MaxAllowedNonAnchorChannelRemoteFee` has been removed.
+   Non-anchor channel feerates are bounded indirectly through
+   `ChannelConfig::max_dust_htlc_exposure` (#2696).
+ * `lightning-invoice` `Description`s now rely on `UntrustedString` for
+   sanitization (#2730).
+ * `ScoreLookUp::channel_penalty_msat` now uses `CandidateRouteHop` (#2551).
+ * The `EcdsaChannelSigner` trait was moved to `lightning::sign::ecdsa` (#2512).
+ * `SignerProvider::get_destination_script` now takes `channel_keys_id` (#2744)
+ * `SpendableOutputDescriptor::StaticOutput` now has `channel_keys_id` (#2749).
+ * `EcdsaChannelSigner::sign_counterparty_commitment` now takes HTLC preimages
+   for both inbound and outbound HTLCs (#2753).
+ * `ClaimedHTLC` now includes a `counterparty_skimmed_fee_msat` field (#2715).
+ * `peel_payment_onion` was added to decode an encrypted onion for a payment
+   without receiving an HTLC. This allows for stateless verification of if a
+   theoretical payment would be accepted prior to receipt (#2700).
+ * `create_payment_onion` was added to construct an encrypted onion for a
+   payment path without sending an HTLC immediately (#2677).
+ * Various keys used in channels are now wrapped to provide type-safety for
+   specific usages of the keys (#2675).
+ * `TaggedHash` now includes the raw `tag` and `merkle_root` (#2687).
+ * `Offer::is_expired_no_std` was added (#2689).
+ * `PaymentPurpose::preimage()` was added (#2768).
+ * `temporary_channel_id` can now be specified in `create_channel` (#2699).
+ * Wire definitions for splicing messages were added (#2544).
+ * Various `lightning-invoice` structs now impl `Display`, now have pub fields,
+   or impl `From` (#2730).
+ * The `Hash` trait is now implemented for more structs, incl P2P msgs (#2716).
+
+## Performance Improvements
+ * Memory allocations (though not memory usage) have been substantially reduced,
+   meaning less overhead and hopefully less memory fragmentation (#2708, #2779).
+
+## Bug Fixes
+ * Since 0.0.117, calling `close_channel*` on a channel which has not yet been
+   funded would previously result in an infinite loop and hang (#2760).
+ * Since 0.0.116, sending payments requiring data in the onion for the recipient
+   which was too large for the onion may have caused corruption which resulted
+   in payment failure (#2752).
+ * Cooperative channel closure on channels with remaining output HTLCs may have
+   spuriously force-closed (#2529).
+ * In LDK versions 0.0.116 through 0.0.118, in rare cases where skimmed fees are
+   present on shutdown the `ChannelManager` may fail to deserialize (#2735).
+ * `ChannelConfig::max_dust_exposure` values which, converted to absolute fees,
+   exceeded 2^63 - 1 would result in an overflow and could lead to spurious
+   payment failures or channel closures (#2722).
+ * In cases where LDK is operating with provably-stale state, it panics to
+   avoid funds loss. This may not have happened in cases where LDK was behind
+   only exactly one state, leading instead to a revoked broadcast and funds
+   loss (#2721).
+ * Fixed a bug where decoding `Txid`s from Bitcoin Core JSON-RPC responses using
+   `lightning-block-sync` would not properly byte-swap the hash. Note that LDK
+   does not use this API internally (#2796).
+
+## Backwards Compatibility
+ * `ChannelManager`s written with LDK 0.0.119 are no longer readable by versions
+   of LDK prior to 0.0.113. Users wishing to downgrade to LDK 0.0.112 or before
+   can read an 0.0.119-serialized `ChannelManager` with a version of LDK from
+   0.0.113 to 0.0.118, re-serialize it, and then downgrade (#2708).
+ * Nodes that upgrade to 0.0.119 and subsequently downgrade after receiving a
+   payment to a blinded path may leak recipient information if one or more of
+   those HTLCs later fails (#2688).
+ * Similarly, forwarding a blinded HTLC and subsequently downgrading to an LDK
+   version prior to 0.0.119 may result in leaking the path information to the
+   payment sender (#2540).
+
+In total, this release features 148 files changed, 13780 insertions, 6279
+deletions in 280 commits from 22 authors, in alphabetical order:
+ * Arik Sosman
+ * Chris Waterson
+ * Elias Rohrer
+ * Evan Feenstra
+ * Gursharan Singh
+ * Jeffrey Czyz
+ * John Cantrell
+ * Lalitmohansharma1
+ * Matt Corallo
+ * Matthew Rheaume
+ * Orbital
+ * Rachel Malonson
+ * Valentine Wallace
+ * Willem Van Lint
+ * Wilmer Paulino
+ * alexanderwiederin
+ * benthecarman
+ * henghonglee
+ * jbesraa
+ * olegkubrakov
+ * optout
+ * shaavan
+
+
+# 0.0.118 - Oct 23, 2023 - "Just the Twelve Sinks"
+
+## API Updates
+ * BOLT12 sending and receiving is now supported as an alpha feature. You may
+   run into unexpected issues and will need to have a direct connection with
+   the offer's blinded path introduction points as messages are not yet routed.
+   We are seeking feedback from early testers (#2578, #2039).
+ * `ConfirmationTarget` has been rewritten to provide information about the
+   specific use LDK needs the feerate estimate for, rather than the generic
+   low-, medium-, and high-priority estimates. This allows LDK users to more
+   accurately target their feerate estimates (#2660). For those wishing to
+   retain their existing behavior, see the table below for conversion.
+ * `ChainHash` is now used in place of `BlockHash` where it represents the
+   genesis block (#2662).
+ * `lightning-invoice` payment utilities now take a `Deref` to
+   `AChannelManager` (#2652).
+ * `peel_onion` is provided to statelessly decode an `OnionMessage` (#2599).
+ * `ToSocketAddrs` + `Display` are now impl'd for `SocketAddress` (#2636, #2670)
+ * `Display` is now implemented for `OutPoint` (#2649).
+ * `Features::from_be_bytes` is now provided (#2640).
+
+For those moving to the new `ConfirmationTarget`, the new variants in terms of
+the old mempool/low/medium/high priorities are as follows:
+ * `OnChainSweep` = `HighPriority`
+ * `MaxAllowedNonAnchorChannelRemoteFee` = `max(25 * 250, HighPriority * 10)`
+ * `MinAllowedAnchorChannelRemoteFee` = `MempoolMinimum`
+ * `MinAllowedNonAnchorChannelRemoteFee` = `Background - 250`
+ * `AnchorChannelFee` = `Background`
+ * `NonAnchorChannelFee` = `Normal`
+ * `ChannelCloseMinimum` = `Background`
+
+## Bug Fixes
+ * Calling `ChannelManager::close_channel[_with_feerate_and_script]` on a
+   channel which did not exist would immediately hang holding several key
+   `ChannelManager`-internal locks (#2657).
+ * Channel information updates received from a failing HTLC are no longer
+   applied to our `NetworkGraph`. This prevents a node which we attempted to
+   route a payment through from being able to learn the sender of the payment.
+   In some rare cases, this may result in marginally reduced payment success
+   rates (#2666).
+ * Anchor outputs are now properly considered when calculating the amount
+   available to send in HTLCs. This can prevent force-closes in anchor channels
+   when sending payments which overflow the available balance (#2674).
+ * A peer that sends an `update_fulfill_htlc` message for a forwarded HTLC,
+   then reconnects prior to sending a `commitment_signed` (thus retransmitting
+   their `update_fulfill_htlc`) may result in the channel stalling and being
+   unable to make progress (#2661).
+ * In exceedingly rare circumstances, messages intended to be sent to a peer
+   prior to reconnection can be sent after reconnection. This could result in
+   undefined channel state and force-closes (#2663).
+
+## Backwards Compatibility
+
+ * Creating a blinded path to receive a payment then downgrading to LDK prior to
+   0.0.117 may result in failure to receive the payment (#2413).
+ * Calling `ChannelManager::pay_for_offer` or
+   `ChannelManager::create_refund_builder` may prevent downgrading to LDK prior
+   to 0.0.118 until the payment times out and has been removed (#2039).
+
+## Node Compatibility
+ * LDK now sends a bogus `channel_reestablish` message to peers when they ask to
+   resume an unknown channel. This should cause LND nodes to force-close and
+   broadcast the latest channel state to the chain. In order to trigger this
+   when we wish to force-close a channel, LDK now disconnects immediately after
+   sending a channel-closing `error` message. This should result in cooperative
+   peers also working to confirm the latest commitment transaction when we wish
+   to force-close (#2658).
+
+## Security
+0.0.118 expands mitigations against transaction cycling attacks to non-anchor
+channels, though note that no mitigations which exist today are considered robust
+to prevent the class of attacks.
+ * In order to mitigate against transaction cycling attacks, non-anchor HTLC
+   transactions are now properly re-signed before broadcasting (#2667).
+
+In total, this release features 61 files changed, 3470 insertions, 1503
+deletions in 85 commits from 12 authors, in alphabetical order:
+ * Antonio Yang
+ * Elias Rohrer
+ * Evan Feenstra
+ * Fedeparma74
+ * Gursharan Singh
+ * Jeffrey Czyz
+ * Matt Corallo
+ * Sergi Delgado Segura
+ * Vladimir Fomene
+ * Wilmer Paulino
+ * benthecarman
+ * slanesuke
+
+
+# 0.0.117 - Oct 3, 2023 - "Everything but the Twelve Sinks"
 
 ## API Updates
  * `ProbabilisticScorer`'s internal models have been substantially improved,
@@ -142,8 +419,36 @@ channel(s) from counterparties which are miners.
    until they've reached 100 confirmations, this could have resulted in
    accepting HTLC(s) which are not enforcible on-chain (#1924).
 
-up to date as of 620244dc2ec3153a61e009b80a8c59cf41514482
-XXX: add diff statas
+In total, this release features 121 files changed, 20477 insertions, 8184
+deletions in 381 commits from 27 authors, in alphabetical order:
+ * Alec Chen
+ * Allan Douglas R. de Oliveira
+ * Antonio Yang
+ * Arik Sosman
+ * Chris Waterson
+ * David Caseria
+ * DhananjayPurohit
+ * Dom Zippilli
+ * Duncan Dean
+ * Elias Rohrer
+ * Erik De Smedt
+ * Evan Feenstra
+ * Gabor Szabo
+ * Gursharan Singh
+ * Jeffrey Czyz
+ * Joseph Goulden
+ * Lalitmohansharma1
+ * Matt Corallo
+ * Rachel Malonson
+ * Sergi Delgado Segura
+ * Valentine Wallace
+ * Vladimir Fomene
+ * Willem Van Lint
+ * Wilmer Paulino
+ * benthecarman
+ * jbesraa
+ * optout
+
 
 # 0.0.116 - Jul 21, 2023 - "Anchoring the Roadmap"