Merge pull request #241 from sangbida/sangbida/docs

Update simln-lib docs

Author: carlaKC

simln-lib/README.md

@@ -0,0 +1,20 @@
+# sim-ln
+
+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:
+
+- 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"
+```

simln-lib/src/lib.rs

@@ -1,3 +1,5 @@
+#![deny(rustdoc::broken_intra_doc_links)]
+
 use async_trait::async_trait;
 use bitcoin::secp256k1::PublicKey;
 use bitcoin::Network;
@@ -35,13 +37,18 @@ pub mod serializers;
 pub mod sim_node;
 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.
     PublicKey(PublicKey),
+    /// The node's alias (human-readable name).
     Alias(String),
 }
 
 impl NodeId {
+    /// 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) => {
@@ -66,6 +73,7 @@ impl NodeId {
         Ok(())
     }
 
+    /// Returns the public key of the node if it is a public key node id.
     pub fn get_pk(&self) -> Result<&PublicKey, String> {
         if let NodeId::PublicKey(pk) = self {
             Ok(pk)
@@ -92,21 +100,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!(
@@ -123,7 +131,9 @@ impl std::fmt::Display for ShortChannelID {
 #[derive(Debug, Clone, Copy, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum ValueOrRange<T> {
+    /// A single fixed value.
     Value(T),
+    /// A range [min, max) from which values are randomly sampled.
     Range(T, T),
 }
 
@@ -178,58 +188,87 @@ pub struct ActivityDefinition {
     pub amount_msat: Amount,
 }
 
+/// Represents errors that can occur during simulation execution.
 #[derive(Debug, Error)]
 pub enum SimulationError {
+    /// Error that occurred during Lightning Network operations.
     #[error("Lightning Error: {0:?}")]
     LightningError(#[from] LightningError),
+    /// Error that occurred during task execution.
     #[error("TaskError")]
     TaskError,
+    /// Error that occurred while writing CSV data.
     #[error("CSV Error: {0:?}")]
     CsvError(#[from] csv::Error),
+    /// Error that occurred during file operations.
     #[error("File Error")]
     FileError,
+    /// Error that occurred during random activity generation.
     #[error("{0}")]
     RandomActivityError(RandomActivityError),
+    /// Error that occurred in the simulated network.
     #[error("Simulated Network Error: {0}")]
     SimulatedNetworkError(String),
+    /// 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("Missing Node Error: {0}")]
     MissingNodeError(String),
+    /// Error that occurred in message passing channels.
     #[error("Mpsc Channel Error: {0}")]
     MpscChannelError(String),
+    /// Error that occurred while generating payment parameters.
     #[error("Payment Generation Error: {0}")]
     PaymentGenerationError(PaymentGenerationError),
+    /// 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("Node connection error: {0}")]
     ConnectionError(String),
+    /// Error that occurred while retrieving node information.
     #[error("Get info error: {0}")]
     GetInfoError(String),
+    /// Error that occurred while sending a payment.
     #[error("Send payment error: {0}")]
     SendPaymentError(String),
+    /// Error that occurred while tracking a payment.
     #[error("Track payment error: {0}")]
     TrackPaymentError(String),
+    /// 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("Get node info error: {0}")]
     GetNodeInfoError(String),
+    /// Error that occurred during configuration validation.
     #[error("Config validation failed: {0}")]
     ValidationError(String),
+    /// Error that represents a permanent failure condition.
     #[error("Permanent error: {0:?}")]
     PermanentError(String),
+    /// 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.
+/// - Features: The node's supported protocol features and capabilities,
+///   used to determine compatibility and available
 #[derive(Debug, Clone)]
 pub struct NodeInfo {
+    /// The node's public key.
     pub pubkey: PublicKey,
+    /// A human-readable name for the node (may be empty).
     pub alias: String,
+    /// The node's supported protocol features and capabilities.
     pub features: NodeFeatures,
 }
 
@@ -250,7 +289,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(
@@ -264,17 +303,19 @@ 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.
     async fn list_channels(&mut self) -> Result<Vec<u64>, LightningError>;
 }
 
+/// Represents an error that occurs when generating a destination for a payment.
 #[derive(Debug, Error)]
 #[error("Destination generation error: {0}")]
 pub struct DestinationGenerationError(String);
 
+/// A trait for selecting destination nodes for payments in the Lightning Network.
 pub trait DestinationGenerator: Send {
     /// choose_destination picks a destination node within the network, returning the node's information and its
     /// capacity (if available).
@@ -284,15 +325,18 @@ pub trait DestinationGenerator: Send {
     ) -> Result<(NodeInfo, Option<u64>), DestinationGenerationError>;
 }
 
+/// Represents an error that occurs when generating payments.
 #[derive(Debug, Error)]
 #[error("Payment generation error: {0}")]
 pub struct PaymentGenerationError(String);
 
+/// A trait for generating payment parameters in the Lightning Network.
 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 the number of payments that should be made.
+    /// 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.
@@ -305,20 +349,32 @@ pub trait PaymentGenerator: Display + Send {
     ) -> Result<u64, PaymentGenerationError>;
 }
 
+/// Represents the result of a payment attempt.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PaymentResult {
+    /// The number of HTLCs (Hash Time Locked Contracts) used in the payment attempt.
+    /// Multiple HTLCs may be used for a single payment when using techniques like multi-part payments or when
+    /// retrying failed payment paths.
     pub htlc_count: usize,
+    /// The final outcome of the payment attempt, indicating whether it succeeded or failed
+    /// (and if failed, the reason for failure).
     pub payment_outcome: PaymentOutcome,
 }
 
 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) with
+    /// [`PaymentOutcome::NotDispatched`].
     pub fn not_dispatched() -> Self {
         PaymentResult {
             htlc_count: 0,
             payment_outcome: PaymentOutcome::NotDispatched,
         }
     }
 
+    /// 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)
+    /// with [`PaymentOutcome::TrackPaymentFailed`].
     pub fn track_payment_failed() -> Self {
         PaymentResult {
             htlc_count: 0,
@@ -337,19 +393,32 @@ 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.
     Success,
+    /// The recipient rejected the payment.
     RecipientRejected,
+    /// The payment was cancelled by the sending user before completion.
     UserAbandoned,
+    /// The payment failed after exhausting all retry attempts.
     RetriesExhausted,
+    /// The payment expired before it could complete (e.g., HTLC timeout).
     PaymentExpired,
+    /// No viable route could be found to the destination node.
     RouteNotFound,
+    /// An unexpected error occurred during payment processing.
     UnexpectedError,
+    /// The payment failed due to incorrect payment details (e.g., wrong invoice amount).
     IncorrectPaymentDetails,
+    /// The sending node has insufficient balance to complete/dispatch the payment.
     InsufficientBalance,
+    /// The payment failed for an unknown reason.
     Unknown,
+    /// 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.
     TrackPaymentFailed,
 }
 
@@ -471,6 +540,9 @@ 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.
@@ -489,6 +561,7 @@ pub struct Simulation {
     shutdown_listener: Listener,
 }
 
+/// Configuration for writing simulation results to CSV files.
 #[derive(Clone)]
 pub struct WriteResults {
     /// Data directory where CSV result files are written.