review: fix Kotlin codegen collision, add tests, improve docs

- Rename FFI PaidBolt12Invoice variants from Bolt12Invoice/StaticInvoice
  to Bolt12/Static to avoid Kotlin sealed class name collisions where
  inner data classes shadowed top-level types of the same name.

- Add serialization round-trip test in bolt12_proof_of_payment to
  validate TLV tag 7 backward compatibility.

- Assert bolt12_invoice is None for BOLT11 payments in
  do_channel_full_cycle, covering all tests that use this helper.

- Add explanatory comments on the cfg-gated PaidBolt12Invoice
  re-export pattern and the clone-based Writeable impl.

- Apply cargo fmt to pre-existing formatting issues in lib.rs and
  lnurl_auth.rs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vincenzopalazzo

src/ffi/types.rs

@@ -10,6 +10,7 @@
 //
 // Make sure to add any re-exported items that need to be used in uniffi below.
 
+use std::collections::HashMap;
 use std::convert::TryInto;
 use std::ops::Deref;
 use std::str::FromStr;
@@ -44,10 +45,10 @@ pub use lightning_liquidity::lsps1::msgs::{
 };
 pub use lightning_types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
 pub use lightning_types::string::UntrustedString;
-use std::collections::HashMap;
-
-use vss_client::headers::VssHeaderProvider as VssClientHeaderProvider;
-use vss_client::headers::VssHeaderProviderError as VssClientHeaderProviderError;
+use vss_client::headers::{
+	VssHeaderProvider as VssClientHeaderProvider,
+	VssHeaderProviderError as VssClientHeaderProviderError,
+};
 
 /// Errors around providing headers for each VSS request.
 #[derive(Debug, uniffi::Error)]
@@ -817,23 +818,27 @@ impl AsRef<LdkStaticInvoice> for StaticInvoice {
 /// The BOLT12 invoice that was paid, surfaced in [`Event::PaymentSuccessful`].
 ///
 /// [`Event::PaymentSuccessful`]: crate::Event::PaymentSuccessful
+///
+/// Note: The variant names intentionally differ from their contained types to avoid
+/// name collisions in Kotlin codegen, where sealed class inner classes would shadow
+/// top-level types of the same name.
 #[derive(Debug, Clone, PartialEq, Eq, uniffi::Enum)]
 pub enum PaidBolt12Invoice {
 	/// The BOLT12 invoice, allowing the user to perform proof of payment.
-	Bolt12Invoice(Arc<Bolt12Invoice>),
+	Bolt12(Arc<Bolt12Invoice>),
 	/// The static invoice, used in async payments, where the user cannot perform proof of
 	/// payment.
-	StaticInvoice(Arc<StaticInvoice>),
+	Static(Arc<StaticInvoice>),
 }
 
 impl From<LdkPaidBolt12Invoice> for PaidBolt12Invoice {
 	fn from(ldk: LdkPaidBolt12Invoice) -> Self {
 		match ldk {
 			LdkPaidBolt12Invoice::Bolt12Invoice(invoice) => {
-				PaidBolt12Invoice::Bolt12Invoice(Arc::new(Bolt12Invoice::from(invoice)))
+				PaidBolt12Invoice::Bolt12(Arc::new(Bolt12Invoice::from(invoice)))
 			},
 			LdkPaidBolt12Invoice::StaticInvoice(invoice) => {
-				PaidBolt12Invoice::StaticInvoice(Arc::new(StaticInvoice::from(invoice)))
+				PaidBolt12Invoice::Static(Arc::new(StaticInvoice::from(invoice)))
 			},
 		}
 	}
@@ -842,10 +847,10 @@ impl From<LdkPaidBolt12Invoice> for PaidBolt12Invoice {
 impl From<PaidBolt12Invoice> for LdkPaidBolt12Invoice {
 	fn from(wrapper: PaidBolt12Invoice) -> Self {
 		match wrapper {
-			PaidBolt12Invoice::Bolt12Invoice(invoice) => {
+			PaidBolt12Invoice::Bolt12(invoice) => {
 				LdkPaidBolt12Invoice::Bolt12Invoice(invoice.inner.clone())
 			},
-			PaidBolt12Invoice::StaticInvoice(invoice) => {
+			PaidBolt12Invoice::Static(invoice) => {
 				LdkPaidBolt12Invoice::StaticInvoice(invoice.inner.clone())
 			},
 		}
@@ -854,6 +859,8 @@ impl From<PaidBolt12Invoice> for LdkPaidBolt12Invoice {
 
 impl Writeable for PaidBolt12Invoice {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), lightning::io::Error> {
+		// We clone `self` to convert it into the LDK native type for serialization.
+		// This only runs during event persistence, so the overhead is acceptable.
 		let ldk_type: LdkPaidBolt12Invoice = self.clone().into();
 		ldk_type.write(w)
 	}

src/lib.rs

@@ -115,8 +115,6 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 use std::{any::Any, sync::Weak};
 
 pub use balance::{BalanceDetails, LightningBalance, PendingSweepBalance};
-pub use bip39;
-pub use bitcoin;
 use bitcoin::secp256k1::PublicKey;
 use bitcoin::{Address, Amount};
 #[cfg(feature = "uniffi")]
@@ -141,7 +139,6 @@ use ffi::*;
 use gossip::GossipSource;
 use graph::NetworkGraph;
 use io::utils::write_node_metrics;
-pub use lightning;
 use lightning::chain::BestBlock;
 use lightning::impl_writeable_tlv_based;
 use lightning::ln::chan_utils::FUNDING_TRANSACTION_WITNESS_WEIGHT;
@@ -153,9 +150,6 @@ use lightning::sign::EntropySource;
 use lightning::util::persist::KVStoreSync;
 use lightning::util::wallet_utils::{Input, Wallet as LdkWallet};
 use lightning_background_processor::process_events_async;
-pub use lightning_invoice;
-pub use lightning_liquidity;
-pub use lightning_types;
 use liquidity::{LSPS1Liquidity, LiquiditySource};
 use lnurl_auth::LnurlAuth;
 use logger::{log_debug, log_error, log_info, log_trace, LdkLogger, Logger};
@@ -167,14 +161,16 @@ use payment::{
 };
 use peer_store::{PeerInfo, PeerStore};
 use runtime::Runtime;
-pub use tokio;
 use types::{
 	Broadcaster, BumpTransactionEventHandler, ChainMonitor, ChannelManager, DynStore, Graph,
 	HRNResolver, KeysManager, OnionMessenger, PaymentStore, PeerManager, Router, Scorer, Sweeper,
 	Wallet,
 };
 pub use types::{ChannelDetails, CustomTlvRecord, PeerDetails, SyncAndAsyncKVStore, UserChannelId};
-pub use vss_client;
+pub use {
+	bip39, bitcoin, lightning, lightning_invoice, lightning_liquidity, lightning_types, tokio,
+	vss_client,
+};
 
 use crate::scoring::setup_background_pathfinding_scores_sync;
 use crate::wallet::FundingAmount;

src/lnurl_auth.rs

@@ -5,18 +5,19 @@
 // http://opensource.org/licenses/MIT>, at your option. You may not use this file except in
 // accordance with one or both of these licenses.
 
-use crate::logger::{log_debug, log_error, Logger};
-use crate::Error;
+use std::sync::Arc;
 
+use bitcoin::bech32;
 use bitcoin::bip32::{ChildNumber, Xpriv};
-use bitcoin::hashes::{hex::FromHex, sha256, Hash, HashEngine, Hmac, HmacEngine};
+use bitcoin::hashes::hex::FromHex;
+use bitcoin::hashes::{sha256, Hash, HashEngine, Hmac, HmacEngine};
 use bitcoin::secp256k1::{All, Message, Secp256k1, SecretKey};
-use lightning::util::logger::Logger as LdkLogger;
-
-use bitcoin::bech32;
 use bitreq::Client;
+use lightning::util::logger::Logger as LdkLogger;
 use serde::{Deserialize, Serialize};
-use std::sync::Arc;
+
+use crate::logger::{log_debug, log_error, Logger};
+use crate::Error;
 
 /// The BIP-32 hardened child index used for LNURL-auth key derivation as defined by LUD-05.
 pub(crate) const LNURL_AUTH_HARDENED_CHILD_INDEX: u32 = 138;
@@ -188,9 +189,10 @@ fn linking_key_path(hashing_key: &[u8; 32], domain_name: &str) -> Vec<ChildNumbe
 
 #[cfg(test)]
 mod tests {
-	use super::*;
 	use bitcoin::Network;
 
+	use super::*;
+
 	fn build_auth(seed: [u8; 32]) -> LnurlAuth {
 		let logger = Arc::new(Logger::new_log_facade());
 		let xprv = Xpriv::new_master(Network::Bitcoin, &seed).unwrap();

src/payment/mod.rs

@@ -26,6 +26,9 @@ pub use store::{
 };
 pub use unified::{UnifiedPayment, UnifiedPaymentResult};
 
+// We re-export `PaidBolt12Invoice` from different modules depending on the `uniffi` feature.
+// Under UniFFI, enum variants containing non-primitive types must be `Arc`-wrapped, so we use a
+// custom wrapper defined in `ffi::types`. Without UniFFI, we re-export the LDK native type directly.
 #[cfg(feature = "uniffi")]
 pub use crate::ffi::PaidBolt12Invoice;
 #[cfg(not(feature = "uniffi"))]

tests/common/mod.rs

@@ -953,7 +953,17 @@ pub(crate) async fn do_channel_full_cycle<E: ElectrumApi>(
 	});
 	assert_eq!(inbound_payments_b.len(), 1);
 
-	expect_event!(node_a, PaymentSuccessful);
+	// Verify bolt12_invoice is None for BOLT11 payments
+	match node_a.next_event_async().await {
+		ref e @ Event::PaymentSuccessful { ref bolt12_invoice, .. } => {
+			println!("{} got event {:?}", node_a.node_id(), e);
+			assert!(bolt12_invoice.is_none(), "bolt12_invoice should be None for BOLT11 payments");
+			node_a.event_handled().unwrap();
+		},
+		ref e => {
+			panic!("{} got unexpected event!: {:?}", std::stringify!(node_a), e);
+		},
+	}
 	expect_event!(node_b, PaymentReceived);
 	assert_eq!(node_a.payment(&payment_id).unwrap().status, PaymentStatus::Succeeded);
 	assert_eq!(node_a.payment(&payment_id).unwrap().direction, PaymentDirection::Outbound);

tests/integration_tests_rust.rs

@@ -37,6 +37,7 @@ use ldk_node::{Builder, Event, NodeError};
 use lightning::ln::channelmanager::PaymentId;
 use lightning::routing::gossip::{NodeAlias, NodeId};
 use lightning::routing::router::RouteParametersConfig;
+use lightning::util::ser::{Readable, Writeable};
 use lightning_invoice::{Bolt11InvoiceDescription, Description};
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 use log::LevelFilter;
@@ -1317,37 +1318,44 @@ async fn bolt12_proof_of_payment() {
 		node_a.bolt12_payment().send(&offer, Some(1), Some("Test".to_string()), None).unwrap();
 
 	// Wait for payment and verify proof of payment
-	match node_a.next_event_async().await {
+	let event = node_a.next_event_async().await;
+	match &event {
 		Event::PaymentSuccessful {
 			payment_id: event_payment_id,
 			payment_hash,
 			payment_preimage,
 			fee_paid_msat: _,
 			bolt12_invoice,
 		} => {
-			assert_eq!(event_payment_id, Some(payment_id));
+			assert_eq!(*event_payment_id, Some(payment_id));
 
 			// Verify proof of payment: sha256(preimage) == payment_hash
 			let preimage = payment_preimage.expect("preimage should be present");
 			let computed_hash = Sha256Hash::hash(&preimage.0);
-			assert_eq!(PaymentHash(computed_hash.to_byte_array()), payment_hash);
+			assert_eq!(PaymentHash(computed_hash.to_byte_array()), *payment_hash);
 
 			// Verify the BOLT12 invoice is present and contains the correct payment hash
-			let paid_invoice =
-				bolt12_invoice.expect("bolt12_invoice should be present for BOLT12 payments");
+			let paid_invoice = bolt12_invoice
+				.as_ref()
+				.expect("bolt12_invoice should be present for BOLT12 payments");
 			match paid_invoice {
 				PaidBolt12Invoice::Bolt12Invoice(invoice) => {
-					assert_eq!(invoice.payment_hash(), payment_hash);
+					assert_eq!(invoice.payment_hash(), *payment_hash);
 					assert_eq!(invoice.amount_msats(), expected_amount_msat);
 				},
 				PaidBolt12Invoice::StaticInvoice(_) => {
 					panic!("Expected Bolt12Invoice, got StaticInvoice");
 				},
 			}
 
+			// Verify serialization round-trip (tests TLV tag 7 backward compatibility)
+			let encoded = event.encode();
+			let decoded: Event = Readable::read(&mut std::io::Cursor::new(&encoded)).unwrap();
+			assert_eq!(event, decoded);
+
 			node_a.event_handled().unwrap();
 		},
-		ref e => {
+		e => {
 			panic!("Unexpected event: {:?}", e);
 		},
 	}