Update simln-lib docs #241

sangbida · 2025-03-28T08:57:25Z

Documentation Updates for simln-lib

Changes

Updated doc comments in lib.rs
Updated README.md

Testing

This is what it looks like when I run cargo doc --open locally.

Note

Working on a usage example with Polar. Current gRPC issue documented here.

carlaKC · 2025-04-02T15:16:25Z

Let me know when this needs a first pass!

sangbida · 2025-04-03T11:30:56Z

Let me know when this needs a first pass!

Yep, thanks for checking in, have been moving slowly on this one sadly but I'll tag you when this is ready for a review.

sangbida · 2025-04-09T11:32:10Z

simln-lib/README.md

+sim-ln = "0.1.0"
+```
+
+### Basic Example


Should I take this out for now and add it when the polar file is also ready? This example won't work if it was copy pasted as is, for example, some of tokio needs to be added in as a dependency. Some of the node configuration can also be tricky.

Let's go ahead and take this out for now. Not particularly because we want a polar file, but because an example that won't compile isn't great - perhaps we can just link to sim-cli for an example of how to use it in the meantime?

sangbida · 2025-04-09T11:53:21Z

@carlaKC This one is ready for a review :) Let me know what you think, happy to change/remove anything if it seems redundant.

carlaKC

I've been very nitpicky because we're doing a big docs overhaul, but looking very good overall!

carlaKC · 2025-04-14T17:25:11Z

simln-lib/README.md

@@ -0,0 +1,13 @@
+# sim-ln
+
+A Lightning Network simulation library that enables testing and analysis of payment routing behavior in a controlled environment.


nit: in a controlled environment / on any lightning network.

We could theoretically run on signet where you don't control all the nodes.

simln-lib/README.md

carlaKC · 2025-04-14T17:26:14Z

simln-lib/README.md

+- Create simulated Lightning Network topologies
+- Test payment routing strategies
+- Analyze network behavior under different conditions
+- Simulate real Lightning node implementations (LND, c-lightning, Eclair)


I think we can remove this last line until we have the ability to run with simulated mode fully in simln

carlaKC · 2025-04-14T17:27:08Z

simln-lib/README.md

+
+sim-ln provides a framework for simulating Lightning Network payment routing behavior, allowing developers and researchers to:
+
+- Create simulated Lightning Network topologies


This sounds to me like sim-ln allows you to spin up different channel graphs, which isn't the case. Could we change this bullet point to something about specific or random traffic patterns?

carlaKC · 2025-04-14T17:27:29Z

simln-lib/src/lib.rs

 #[derive(Serialize, Debug, Clone)]
 pub enum NodeId {
+    /// The node's public key


nit: here and a few other places in the PR, end comments with a full stop.

carlaKC · 2025-04-14T17:41:10Z

sim-cli/src/parsing.rs

-    let clients_clone = clients.clone();
-    let get_node = move |pk: &PublicKey| async move {
-        if let Some(c) = clients_clone.values().next() {
+    let get_node = async |pk: &PublicKey| -> Result<NodeInfo, LightningError> {


Ah, this can be squashed with the previous commit

carlaKC · 2025-04-14T17:43:54Z

simln-lib/README.md

+sim-ln = "0.1.0"
+```
+
+### Basic Example


Let's go ahead and take this out for now. Not particularly because we want a polar file, but because an example that won't compile isn't great - perhaps we can just link to sim-cli for an example of how to use it in the meantime?

carlaKC · 2025-04-14T17:44:59Z

simln-lib/src/lib.rs

+/// 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 (for simulating network activity)


I don't think we should have details about implementations in trait documentation, likewise below for PaymentGenerator

carlaKC · 2025-04-14T17:45:54Z

simln-lib/src/lib.rs

+    /// # Returns
+    ///
+    /// * `Some(u64)` - The exact number of payments to make


I don't think this adds much, and this won't always be Some

simln-lib/src/lib.rs

sangbida · 2025-04-28T09:03:52Z

Hey @carlaKC, I added these to the top of the docs file but this means we woud need to add in docs for all public functions in the lightning implementations. Not sure if I have done this incorrectly, or we want to add docs for those in this PR as well?

 #![deny(rustdoc::broken_intra_doc_links)]
#![deny(missing_docs)]

carlaKC · 2025-04-28T13:08:36Z

Hey @carlaKC, I added these to the top of the docs file but this means we woud need to add in docs for all public functions in the lightning implementations. Not sure if I have done this incorrectly, or we want to add docs for those in this PR as well?

My comment definitely could have been clearer - I meant that we'll want to turn them on in the future (not this PR), so might as well get our docs conventions in line now.

Let's remove it for now and come back to it in a follow up 👍

I added these to the top of the docs file but this means we would need to add in docs for all public functions in the lightning implementations

This is being correctly enforced, but we can handle in a follow up.

carlaKC

LGTM, feel free to squash this all down to one commit (if it's easier) or go ahead and squash fixups.

Only high level comment is that the line wrapping looks a little off - can update to 120 across the board (non-blocking).

As for enforcing docs, let's just go with #![deny(rustdoc::broken_intra_doc_links)] (and add it to sim-cli/src/lib.rs as well).

carlaKC · 2025-04-28T13:09:10Z

simln-lib/README.md

+- Generate specific or random traffic patterns on a provided Lightning graph.
+- Test payment routing strategies.
+- Analyze network behavior under different conditions.
+## Usage


nit: missing newline above Usage

carlaKC · 2025-04-28T13:10:32Z

simln-lib/src/lib.rs

@@ -1,3 +1,6 @@
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(missing_docs)]


If we remove missing_docs I believe we should be able to keep #![deny(rustdoc::broken_intra_doc_links)] as-is to make sure code references are correct.

carlaKC · 2025-04-28T13:13:33Z

simln-lib/src/lib.rs

+/// - 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.


nit: I don't think that we need information about LND/CLN on this level, can remove.

When we get around to adding comments to the individual LN impls, that would be a good place to make note of these type of implementation details.

carlaKC · 2025-04-28T13:15:35Z

simln-lib/src/lib.rs

    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`].


nit: line wrapping is off here

Add ValueOrRange logs Add NodeInfo logs Add PaymentResult docs Add PaymentOutcome docs Fix up url and add simulation logs Remove spurious change Add basic usage Update doc for WriteResults Add Simulation and Lightning error docs Add DestinationGenerator and PaymentGenerator docs quick tidy up of a few doc comments Fix up formatting and some language Fix up NodeInfo and NodeFeatures comments PR Fixes Fix line wrapping to 120 chars

sangbida · 2025-04-29T03:23:43Z

Thanks for the review @carlaKC! I've taken out #![deny(missing_docs)] for now and fixed the line wrapping issues, CI seems to be happy with it as well!

Add a readme

271db36

sangbida changed the title ~~Add a readme~~ Update simln-lib docs Mar 31, 2025

sangbida mentioned this pull request Mar 31, 2025

docs: Improve Crate Documentation #205

Open

carlaKC added this to the V2.4 milestone Apr 2, 2025

sangbida force-pushed the sangbida/docs branch from d065f27 to 4186627 Compare April 9, 2025 10:58

sangbida commented Apr 9, 2025

View reviewed changes

sangbida marked this pull request as ready for review April 9, 2025 11:51

carlaKC reviewed Apr 14, 2025

View reviewed changes

sangbida force-pushed the sangbida/docs branch 3 times, most recently from 6e56367 to 0095a23 Compare April 27, 2025 11:18

carlaKC reviewed Apr 28, 2025

View reviewed changes

sangbida force-pushed the sangbida/docs branch 3 times, most recently from 8a2a18d to 168a921 Compare April 29, 2025 01:23

sangbida force-pushed the sangbida/docs branch from 168a921 to 0bebc63 Compare April 29, 2025 01:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update simln-lib docs #241

Update simln-lib docs #241

sangbida commented Mar 28, 2025 •

edited

Loading

carlaKC commented Apr 2, 2025

sangbida commented Apr 3, 2025

sangbida Apr 9, 2025

carlaKC Apr 14, 2025

sangbida commented Apr 9, 2025

carlaKC left a comment

carlaKC Apr 14, 2025

carlaKC Apr 14, 2025

carlaKC Apr 14, 2025

carlaKC Apr 14, 2025

carlaKC Apr 14, 2025

carlaKC Apr 14, 2025

carlaKC Apr 14, 2025

carlaKC Apr 14, 2025

sangbida commented Apr 28, 2025

carlaKC commented Apr 28, 2025

carlaKC left a comment

carlaKC Apr 28, 2025

carlaKC Apr 28, 2025

carlaKC Apr 28, 2025

carlaKC Apr 28, 2025

sangbida commented Apr 29, 2025 •

edited

Loading

		@@ -0,0 +1,13 @@
		# sim-ln

		A Lightning Network simulation library that enables testing and analysis of payment routing behavior in a controlled environment.


		sim-ln provides a framework for simulating Lightning Network payment routing behavior, allowing developers and researchers to:

		- Create simulated Lightning Network topologies

		@@ -1,3 +1,6 @@
		#![deny(rustdoc::broken_intra_doc_links)]
		#![deny(missing_docs)]

Update simln-lib docs #241

Are you sure you want to change the base?

Update simln-lib docs #241

Conversation

sangbida commented Mar 28, 2025 • edited Loading

Documentation Updates for simln-lib

Changes

Testing

Note

carlaKC commented Apr 2, 2025

sangbida commented Apr 3, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sangbida commented Apr 9, 2025

carlaKC left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sangbida commented Apr 28, 2025

carlaKC commented Apr 28, 2025

carlaKC left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sangbida commented Apr 29, 2025 • edited Loading

sangbida commented Mar 28, 2025 •

edited

Loading

sangbida commented Apr 29, 2025 •

edited

Loading