PR Fixes

Author: sangbida

simln-lib/README.md

@@ -1,43 +1,19 @@
 # sim-ln
 
-A Lightning Network simulation library that enables testing and analysis of payment routing behavior in a controlled environment.
+A Lightning Network simulation library that enables testing and analysis of payment routing behavior on any Lightning Network. While primarily designed for controlled environments, it can also be used with real networks like Bitcoin signet where you don't control all nodes.
 
 ## Overview
 
 sim-ln provides a framework for simulating Lightning Network payment routing behavior, allowing developers and researchers to:
 
-- Create simulated Lightning Network topologies
-- Test payment routing strategies
-- Analyze network behavior under different conditions
-- Simulate real Lightning node implementations (LND, c-lightning, Eclair)
-
+- Generate specific or random traffic patterns on a provided Lightning graph.
+- Test payment routing strategies.
+- Analyze network behavior under different conditions.
 ## Usage
 
 Add sim-ln to your Cargo.toml:
 
 ```toml
 [dependencies]
 sim-ln = "0.1.0"
-```
-
-### Basic Example
-
-```rust
-use sim_ln::{SimulationCfg, Simulation, NodeInfo, LightningNode};
-
-// Create simulation configuration
-let config = SimulationCfg::new(
-    Some(3600),           // Run for 1 hour
-    1_000_000,           // 1000 sat expected payment size
-    1.0,                 // Normal activity level
-    None,                // No result writing
-    Some(42),            // Random seed for reproducibility
-);
-
-// Set up nodes and channels
-// ... configure your network topology
-
-// Create and run simulation
-let simulation = Simulation::new(config, nodes, activity, task_tracker);
-simulation.run().await?;
-```
+```

simln-lib/src/lib.rs

@@ -1,3 +1,6 @@
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(missing_docs)]
+
 use async_trait::async_trait;
 use bitcoin::secp256k1::PublicKey;
 use bitcoin::Network;
@@ -39,14 +42,15 @@ mod test_utils;
 /// Represents a node id, either by its public key or alias.
 #[derive(Serialize, Debug, Clone)]
 pub enum NodeId {
-    /// The node's public key
+    /// The node's public key.
     PublicKey(PublicKey),
-    /// The node's alias (human-readable name)
+    /// The node's alias (human-readable name).
     Alias(String),
 }
 
 impl NodeId {
-    /// Validates that the provided node id matches the one returned by the backend.
+    /// Validates that the provided node id matches the one returned by the backend. If the node id is an alias,
+    /// it will be updated to the one returned by the backend if there is a mismatch.
     pub fn validate(&self, node_id: &PublicKey, alias: &mut String) -> Result<(), LightningError> {
         match self {
             crate::NodeId::PublicKey(pk) => {
@@ -98,21 +102,21 @@ impl std::fmt::Display for NodeId {
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Copy)]
 pub struct ShortChannelID(u64);
 
-/// Utility function to easily convert from u64 to `ShortChannelID`
+/// Utility function to easily convert from u64 to `ShortChannelID`.
 impl From<u64> for ShortChannelID {
     fn from(value: u64) -> Self {
         ShortChannelID(value)
     }
 }
 
-/// Utility function to easily convert `ShortChannelID` into u64
+/// Utility function to easily convert `ShortChannelID` into u64.
 impl From<ShortChannelID> for u64 {
     fn from(scid: ShortChannelID) -> Self {
         scid.0
     }
 }
 
-/// See <https://github.com/lightning/bolts/blob/60de4a09727c20dea330f9ee8313034de6e50594/07-routing-gossip.md#definition-of-short_channel_id>.
+/// See <https://github.com/lightning/bolts/blob/60de4a09727c20dea330f9ee8313034de6e50594/07-routing-gossip.md#definition-of-short_channel_id>
 impl std::fmt::Display for ShortChannelID {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         write!(
@@ -129,9 +133,9 @@ impl std::fmt::Display for ShortChannelID {
 #[derive(Debug, Clone, Copy, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum ValueOrRange<T> {
-    /// A single fixed value
+    /// A single fixed value.
     Value(T),
-    /// A range [min, max) from which values are randomly sampled
+    /// A range [min, max) from which values are randomly sampled.
     Range(T, T),
 }
 
@@ -189,85 +193,85 @@ pub struct ActivityDefinition {
 /// Represents errors that can occur during simulation execution.
 #[derive(Debug, Error)]
 pub enum SimulationError {
-    /// Error that occurred during Lightning Network operations
+    /// Error that occurred during Lightning Network operations.
     #[error("Lightning Error: {0:?}")]
     LightningError(#[from] LightningError),
-    /// Error that occurred during task execution
+    /// Error that occurred during task execution.
     #[error("TaskError")]
     TaskError,
-    /// Error that occurred while writing CSV data
+    /// Error that occurred while writing CSV data.
     #[error("CSV Error: {0:?}")]
     CsvError(#[from] csv::Error),
-    /// Error that occurred during file operations
+    /// Error that occurred during file operations.
     #[error("File Error")]
     FileError,
-    /// Error that occurred during random activity generation
+    /// Error that occurred during random activity generation.
     #[error("{0}")]
     RandomActivityError(RandomActivityError),
-    /// Error that occurred in the simulated network
+    /// Error that occurred in the simulated network.
     #[error("Simulated Network Error: {0}")]
     SimulatedNetworkError(String),
-    /// Error that occurred while accessing system time
+    /// Error that occurred while accessing system time.
     #[error("System Time Error: {0}")]
     SystemTimeError(#[from] SystemTimeError),
-    /// Error that occurred when a required node was not found
+    /// Error that occurred when a required node was not found.
     #[error("Missing Node Error: {0}")]
     MissingNodeError(String),
-    /// Error that occurred in message passing channels
+    /// Error that occurred in message passing channels.
     #[error("Mpsc Channel Error: {0}")]
     MpscChannelError(String),
-    /// Error that occurred while generating payment parameters
+    /// Error that occurred while generating payment parameters.
     #[error("Payment Generation Error: {0}")]
     PaymentGenerationError(PaymentGenerationError),
-    /// Error that occurred while generating destination nodes
+    /// Error that occurred while generating destination nodes.
     #[error("Destination Generation Error: {0}")]
     DestinationGenerationError(DestinationGenerationError),
 }
 
 /// Represents errors that can occur during Lightning Network operations.
 #[derive(Debug, Error)]
 pub enum LightningError {
-    /// Error that occurred while connecting to a Lightning node
+    /// Error that occurred while connecting to a Lightning node.
     #[error("Node connection error: {0}")]
     ConnectionError(String),
-    /// Error that occurred while retrieving node information
+    /// Error that occurred while retrieving node information.
     #[error("Get info error: {0}")]
     GetInfoError(String),
-    /// Error that occurred while sending a payment
+    /// Error that occurred while sending a payment.
     #[error("Send payment error: {0}")]
     SendPaymentError(String),
-    /// Error that occurred while tracking a payment
+    /// Error that occurred while tracking a payment.
     #[error("Track payment error: {0}")]
     TrackPaymentError(String),
-    /// Error that occurred when a payment hash is invalid
+    /// Error that occurred when a payment hash is invalid.
     #[error("Invalid payment hash")]
     InvalidPaymentHash,
-    /// Error that occurred while retrieving information about a specific node
+    /// Error that occurred while retrieving information about a specific node.
     #[error("Get node info error: {0}")]
     GetNodeInfoError(String),
-    /// Error that occurred during configuration validation
+    /// Error that occurred during configuration validation.
     #[error("Config validation failed: {0}")]
     ValidationError(String),
-    /// Error that represents a permanent failure condition
+    /// Error that represents a permanent failure condition.
     #[error("Permanent error: {0:?}")]
     PermanentError(String),
-    /// Error that occurred while listing channels
+    /// Error that occurred while listing channels.
     #[error("List channels error: {0}")]
     ListChannelsError(String),
 }
 
 /// Information about a Lightning Network node.
-/// - Alias: A human-readable name for the node
+/// - Alias: A human-readable name for the node.
 /// - Features: The node's supported protocol features and capabilities, used to determine compatibility
 ///   and available functionality. In CLN, features are stored as big-endian bytes, while in LND they are
 ///   stored as a set of feature flags converted to little-endian bytes.
 #[derive(Debug, Clone)]
 pub struct NodeInfo {
-    /// The node's public key
+    /// The node's public key.
     pub pubkey: PublicKey,
-    /// A human-readable name for the node (may be empty)
+    /// A human-readable name for the node (may be empty).
     pub alias: String,
-    /// The node's supported protocol features and capabilities
+    /// The node's supported protocol features and capabilities.
     pub features: NodeFeatures,
 }
 
@@ -288,7 +292,7 @@ impl Display for NodeInfo {
 pub trait LightningNode: Send {
     /// Get information about the node.
     fn get_info(&self) -> &NodeInfo;
-    /// Get the network this node is running at
+    /// Get the network this node is running at.
     async fn get_network(&mut self) -> Result<Network, LightningError>;
     /// Keysend payment worth `amount_msat` from a source node to the destination node.
     async fn send_payment(
@@ -302,7 +306,7 @@ pub trait LightningNode: Send {
         hash: &PaymentHash,
         shutdown: Listener,
     ) -> Result<PaymentResult, LightningError>;
-    /// Gets information on a specific node
+    /// Gets information on a specific node.
     async fn get_node_info(&mut self, node_id: &PublicKey) -> Result<NodeInfo, LightningError>;
     /// Lists all channels, at present only returns a vector of channel capacities in msat because no further
     /// information is required.
@@ -315,14 +319,6 @@ pub trait LightningNode: Send {
 pub struct DestinationGenerationError(String);
 
 /// A trait for selecting destination nodes for payments in the Lightning Network.
-///
-/// This trait is responsible for choosing appropriate destination nodes from the existing network
-/// for payments to be sent to. The selection can be based on different strategies:
-/// - Predefined destinations (for deterministic payment patterns)
-/// - Random selection weighted by node capacity
-///
-/// The trait works with existing nodes in the network and is used in conjunction with
-/// the `PaymentGenerator` trait to create complete payment flows.
 pub trait DestinationGenerator: Send {
     /// choose_destination picks a destination node within the network, returning the node's information and its
     /// capacity (if available).
@@ -338,22 +334,13 @@ pub trait DestinationGenerator: Send {
 pub struct PaymentGenerationError(String);
 
 /// A trait for generating payment parameters in the Lightning Network.
-///
-/// This trait is responsible for determining when and how payments should be made,
-/// including timing, amounts, and frequency. It can be used to implement various
-/// payment strategies, from simple periodic payments to more complex patterns
-/// with random timing and amounts.
-///
 pub trait PaymentGenerator: Display + Send {
-    /// Returns the time that the payments should start
+    /// Returns the time that the payments should start.
     fn payment_start(&self) -> Option<Duration>;
 
     /// Returns the number of payments that should be made.
-    ///
-    /// # Returns
-    ///
-    /// * `Some(u64)` - The exact number of payments to make
-    /// * `None` - Payments should continue indefinitely
+    /// Returns `Some(n)` if there's a limit on the number of payments to dispatch,
+    /// or `None` otherwise.
     fn payment_count(&self) -> Option<u64>;
 
     /// Returns the number of seconds that a node should wait until firing its next payment.
@@ -381,12 +368,7 @@ pub struct PaymentResult {
 impl PaymentResult {
     /// Creates a new PaymentResult indicating that the payment was never dispatched.
     /// This is used when there was an error during the initial payment dispatch attempt.
-    ///(e.g., insufficient balance, invalid destination)
-    ///
-    /// # Returns
-    /// A PaymentResult with:
-    /// - htlc_count: 0 (no HTLCs used since payment wasn't dispatched)
-    /// - payment_outcome: NotDispatched
+    /// (e.g., insufficient balance, invalid destination) with [`PaymentOutcome::NotDispatched`].
     pub fn not_dispatched() -> Self {
         PaymentResult {
             htlc_count: 0,
@@ -396,12 +378,7 @@ impl PaymentResult {
 
     /// Creates a new PaymentResult indicating that tracking the payment failed.
     /// This is used when the payment was dispatched but the system was unable to
-    /// determine its final outcome (e.g., due to connection issues or timeouts).
-    ///
-    /// # Returns
-    /// A PaymentResult with:
-    /// - htlc_count: 0 (unknown since tracking failed)
-    /// - payment_outcome: TrackPaymentFailed
+    /// determine its final outcome (e.g., due to connection issues or timeouts) with [`PaymentOutcome::TrackPaymentFailed`].
     pub fn track_payment_failed() -> Self {
         PaymentResult {
             htlc_count: 0,
@@ -423,29 +400,29 @@ impl Display for PaymentResult {
 /// Represents all possible outcomes of a Lightning Network payment attempt.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum PaymentOutcome {
-    /// Payment completed successfully, reaching its intended recipient
+    /// Payment completed successfully, reaching its intended recipient.
     Success,
-    /// The recipient rejected the payment
+    /// The recipient rejected the payment.
     RecipientRejected,
-    /// The payment was cancelled by the sending user before completion
+    /// The payment was cancelled by the sending user before completion.
     UserAbandoned,
-    /// The payment failed after exhausting all retry attempts
+    /// The payment failed after exhausting all retry attempts.
     RetriesExhausted,
-    /// The payment expired before it could complete (e.g., HTLC timeout)
+    /// The payment expired before it could complete (e.g., HTLC timeout).
     PaymentExpired,
-    /// No viable route could be found to the destination node
+    /// No viable route could be found to the destination node.
     RouteNotFound,
-    /// An unexpected error occurred during payment processing
+    /// An unexpected error occurred during payment processing.
     UnexpectedError,
-    /// The payment failed due to incorrect payment details (e.g., wrong invoice amount)
+    /// The payment failed due to incorrect payment details (e.g., wrong invoice amount).
     IncorrectPaymentDetails,
-    /// The sending node has insufficient balance to complete the payment
+    /// The sending node has insufficient balance to complete/dispatch the payment.
     InsufficientBalance,
-    /// The payment failed for an unknown reason
+    /// The payment failed for an unknown reason.
     Unknown,
-    /// The payment was never dispatched due to an error during initial sending
+    /// The payment was never dispatched due to an error during initial sending.
     NotDispatched,
-    /// The payment was dispatched but its final status could not be determined
+    /// The payment was dispatched but its final status could not be determined.
     TrackPaymentFailed,
 }
 
@@ -570,7 +547,6 @@ impl SimulationCfg {
 /// A Lightning Network payment simulator that manages payment flows between nodes.
 /// The simulator can execute both predefined payment patterns and generate random payment activity
 /// based on configuration parameters.
-///
 #[derive(Clone)]
 pub struct Simulation {
     /// Config for the simulation itself.