simln-lib/feature: Add ability to run with mocked ln network

Author: f3r10

Cargo.lock

@@ -270,6 +270,106 @@ project.
 ## Docker
 If you want to run the cli in a containerized environment, see the docker set up docs [here](./docker/README.md)
 
+## Advanced Usage - Network Simulation
+
+If you are looking to simulate payments are large lightning networks 
+without the resource consumption of setting up a large cluster of nodes,
+you may be interested in dispatching payments on a simulated network.
+
+To run on a simulated network, you will need to provide the desired 
+topology and channel policies for each edge in the graph. The nodes in 
+the network will be inferred from the edges provided. Simulation of 
+payments on both a mocked and real lightning network is not supported, 
+so the `sim_network` field is mutually exclusive with the `nodes` section 
+described above.
+
+The example that follows will execute random payments on a network 
+consisting of three nodes and two channels. You may specify defined 
+activity to execute on the mocked network, though you must refer to 
+nodes by their pubkey (aliases are not yet supported).
+
+```
+{
+  "sim_network": [
+    {
+      "scid": 1,
+      "capacity_msat": 250000,
+      "node_1": {
+        "pubkey": "0344f37d544896dcc95a08ddd9bdfc2b756bf3f91b3f65bce588bd9d0228c24977",
+        "max_htlc_count": 483,
+        "max_in_flight_msat": 250000,
+        "min_htlc_size_msat": 1,
+        "max_htlc_size_msat": 100000,
+        "cltv_expiry_delta": 40,
+        "base_fee": 1000,
+        "fee_rate_prop": 100
+      },
+      "node_2": {
+        "pubkey": "020a30431ce58843eedf8051214dbfadb65b107cc598b8277f14bb9b33c9cd026f",
+        "max_htlc_count": 15,
+        "max_in_flight_msat": 100000,
+        "min_htlc_size_msat": 1,
+        "max_htlc_size_msat": 50000,
+        "cltv_expiry_delta": 80,
+        "base_fee": 2000,
+        "fee_rate_prop": 500
+      }
+    },
+    {
+      "scid": 2,
+      "capacity_msat": 100000,
+      "node_1": {
+        "pubkey": "020a30431ce58843eedf8051214dbfadb65b107cc598b8277f14bb9b33c9cd026f",
+        "max_htlc_count": 200,
+        "max_in_flight_msat": 100000,
+        "min_htlc_size_msat": 1,
+        "max_htlc_size_msat": 25000,
+        "cltv_expiry_delta": 40,
+        "base_fee": 1750,
+        "fee_rate_prop": 100
+      },
+      "node_2": {
+        "pubkey": "035c0b392725bb7298d56bf1bcb23634fc509d86a39a8141d435f9d4d6cd4b12eb",
+        "max_htlc_count": 15,
+        "max_in_flight_msat": 50000,
+        "min_htlc_size_msat": 1,
+        "max_htlc_size_msat": 50000,
+        "cltv_expiry_delta": 80,
+        "base_fee": 3000,
+        "fee_rate_prop": 5
+      }
+    }
+  ]
+}
+```
+
+Note that you need to provide forwarding policies in each direction, 
+because each participant in the channel sets their own forwarding 
+policy and restrictions on their counterparty. 
+
+### Inclusions and Limitations
+
+The simulator will execute payments on the mocked out network as it 
+would for a network of real nodes. See the inclusions and exclusions 
+listed below for a description of the functionality covered by the 
+simulated network.
+
+Included: 
+* Routing Policy Enforcement: mocked channels enforce fee and CLTV 
+  requirements.
+* Channel restrictions: mocked channels abide by the in-flight 
+  count and value limitations set on channel creation.
+* Liquidity checks: HTLCs are only forwarded if the node has sufficient
+  liquidity in the mocked channel.
+
+Not included: 
+* Channel reserve: the required minimum reserve balance is not 
+  subtracted from a node's available balance.
+* On chain fees: the simulation does not subtract on chain fees from 
+  available liquidity.
+* Dust limits: the simulation node not account for restrictions on dust
+  HTLCs.
+
 ## Developers 
 
 * [Developer documentation](docs/DEVELOPER.md)

README.md

@@ -14,6 +14,7 @@ anyhow = { version = "1.0.69", features = ["backtrace"] }
 clap = { version = "4.1.6", features = ["derive", "env", "std", "help", "usage", "error-context", "suggestions"], default-features = false }
 dialoguer = "0.11.0"
 log = "0.4.20"
+triggered = "0.1.2"
 serde = "1.0.183"
 serde_json = "1.0.104"
 simple_logger = "4.2.0"

sim-cli/Cargo.toml

@@ -1,7 +1,8 @@
 use clap::Parser;
 use log::LevelFilter;
-use sim_cli::parsing::{create_simulation, get_validated_activities, parse_sim_params, Cli};
+use sim_cli::parsing::{create_simulation, create_simulation_with_network, parse_sim_params, Cli};
 use simple_logger::SimpleLogger;
+use tokio_util::task::TaskTracker;
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
@@ -21,17 +22,22 @@ async fn main() -> anyhow::Result<()> {
         .init()
         .unwrap();
 
-    let (sim, nodes_info) = create_simulation(&cli, &sim_params).await?;
+    cli.validate(&sim_params)?;
+
+    let tasks = TaskTracker::new();
+
+    let (sim, validated_activities) = if sim_params.sim_network.is_empty() {
+        create_simulation(&cli, &sim_params, tasks.clone()).await?
+    } else {
+        create_simulation_with_network(&cli, &sim_params, tasks.clone()).await?
+    };
     let sim2 = sim.clone();
 
     ctrlc::set_handler(move || {
         log::info!("Shutting down simulation.");
         sim2.shutdown();
     })?;
 
-    let validated_activities =
-        get_validated_activities(&sim.nodes, nodes_info, sim_params.activity).await?;
-
     sim.run(&validated_activities).await?;
 
     Ok(())

sim-cli/src/main.rs

@@ -3,11 +3,15 @@ use bitcoin::secp256k1::PublicKey;
 use clap::{builder::TypedValueParser, Parser};
 use log::LevelFilter;
 use serde::{Deserialize, Serialize};
+use simln_lib::sim_node::{
+    ln_node_from_graph, populate_network_graph, ChannelPolicy, SimGraph, SimulatedChannel,
+};
 use simln_lib::{
     cln, cln::ClnNode, eclair, eclair::EclairNode, lnd, lnd::LndNode, serializers,
     ActivityDefinition, Amount, Interval, LightningError, LightningNode, NodeId, NodeInfo,
     Simulation, SimulationCfg, WriteResults,
 };
+use simln_lib::{ShortChannelID, SimulationError};
 use std::collections::HashMap;
 use std::fs;
 use std::ops::AsyncFn;
@@ -81,9 +85,33 @@ pub struct Cli {
     pub fix_seed: Option<u64>,
 }
 
+impl Cli {
+    pub fn validate(&self, sim_params: &SimParams) -> Result<(), anyhow::Error> {
+        // Validate that nodes and sim_graph are exclusively set
+        if !sim_params.nodes.is_empty() && !sim_params.sim_network.is_empty() {
+            return Err(anyhow!(
+                "Simulation file cannot contain {} nodes and {} sim_graph entries, 
+                simulation can only be run with real or simulated nodes not both.",
+                sim_params.nodes.len(),
+                sim_params.sim_network.len()
+            ));
+        }
+        if sim_params.nodes.is_empty() && sim_params.sim_network.is_empty() {
+            return Err(anyhow!(
+                "Simulation file must contain nodes to run with real lightning 
+                nodes or sim_graph to run with simulated nodes"
+            ));
+        }
+        Ok(())
+    }
+}
+
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct SimParams {
-    pub nodes: Vec<NodeConnection>,
+    #[serde(default)]
+    nodes: Vec<NodeConnection>,
+    #[serde(default)]
+    pub sim_network: Vec<NetworkParser>,
     #[serde(default)]
     pub activity: Vec<ActivityParser>,
 }
@@ -96,6 +124,27 @@ pub enum NodeConnection {
     Eclair(eclair::EclairConnection),
 }
 
+/// Data structure that is used to parse information from the simulation file. It is used to
+/// create a mocked network.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct NetworkParser {
+    pub scid: ShortChannelID,
+    pub capacity_msat: u64,
+    pub node_1: ChannelPolicy,
+    pub node_2: ChannelPolicy,
+}
+
+impl From<NetworkParser> for SimulatedChannel {
+    fn from(network_parser: NetworkParser) -> Self {
+        SimulatedChannel::new(
+            network_parser.capacity_msat,
+            network_parser.scid,
+            network_parser.node_1,
+            network_parser.node_2,
+        )
+    }
+}
+
 /// Data structure used to parse information from the simulation file. It allows source and destination to be
 /// [NodeId], which enables the use of public keys and aliases in the simulation description.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -140,23 +189,87 @@ impl TryFrom<&Cli> for SimulationCfg {
     }
 }
 
+struct NodeMapping {
+    pk_node_map: HashMap<PublicKey, NodeInfo>,
+    alias_node_map: HashMap<String, NodeInfo>,
+}
+
+pub async fn create_simulation_with_network(
+    cli: &Cli,
+    sim_params: &SimParams,
+    tasks: TaskTracker,
+) -> Result<(Simulation, Vec<ActivityDefinition>), anyhow::Error> {
+    let cfg: SimulationCfg = SimulationCfg::try_from(cli)?;
+    let SimParams {
+        nodes: _,
+        sim_network,
+        activity: _activity,
+    } = sim_params;
+
+    // Convert nodes representation for parsing to SimulatedChannel
+    let channels = sim_network
+        .clone()
+        .into_iter()
+        .map(SimulatedChannel::from)
+        .collect::<Vec<SimulatedChannel>>();
+
+    let mut nodes_info = HashMap::new();
+    for channel in &channels {
+        let (node_1_info, node_2_info) = channel.create_simulated_nodes();
+        nodes_info.insert(node_1_info.pubkey, node_1_info);
+        nodes_info.insert(node_2_info.pubkey, node_2_info);
+    }
+
+    let (shutdown_trigger, shutdown_listener) = triggered::trigger();
+
+    // Setup a simulation graph that will handle propagation of payments through the network
+    let simulation_graph = Arc::new(Mutex::new(
+        SimGraph::new(channels.clone(), tasks.clone(), shutdown_trigger.clone())
+            .map_err(|e| SimulationError::SimulatedNetworkError(format!("{:?}", e)))?,
+    ));
+
+    // Copy all simulated channels into a read-only routing graph, allowing to pathfind for
+    // individual payments without locking th simulation graph (this is a duplication of the channels,
+    // but the performance tradeoff is worthwhile for concurrent pathfinding).
+    let routing_graph = Arc::new(
+        populate_network_graph(channels)
+            .map_err(|e| SimulationError::SimulatedNetworkError(format!("{:?}", e)))?,
+    );
+
+    let nodes = ln_node_from_graph(simulation_graph.clone(), routing_graph).await;
+    let validated_activities =
+        get_validated_activities(&nodes, nodes_info, sim_params.activity.clone()).await?;
+
+    Ok((
+        Simulation::new(cfg, nodes, tasks, shutdown_trigger, shutdown_listener),
+        validated_activities,
+    ))
+}
+
 /// Parses the cli options provided and creates a simulation to be run, connecting to lightning nodes and validating
 /// any activity described in the simulation file.
 pub async fn create_simulation(
     cli: &Cli,
     sim_params: &SimParams,
-) -> Result<(Simulation, HashMap<PublicKey, NodeInfo>), anyhow::Error> {
+    tasks: TaskTracker,
+) -> Result<(Simulation, Vec<ActivityDefinition>), anyhow::Error> {
     let cfg: SimulationCfg = SimulationCfg::try_from(cli)?;
-
     let SimParams {
         nodes,
+        sim_network: _sim_network,
         activity: _activity,
     } = sim_params;
 
     let (clients, clients_info) = get_clients(nodes.to_vec()).await?;
-    let tasks = TaskTracker::new();
+    let (shutdown_trigger, shutdown_listener) = triggered::trigger();
 
-    Ok((Simulation::new(cfg, clients, tasks), clients_info))
+    let validated_activities =
+        get_validated_activities(&clients, clients_info, sim_params.activity.clone()).await?;
+
+    Ok((
+        Simulation::new(cfg, clients, tasks, shutdown_trigger, shutdown_listener),
+        validated_activities,
+    ))
 }
 
 /// Connects to the set of nodes providing, returning a map of node public keys to LightningNode implementations and
@@ -194,9 +307,7 @@ async fn get_clients(
 
 /// Adds a lightning node to a client map and tracking maps used to lookup node pubkeys and aliases for activity
 /// validation.
-async fn add_node_to_maps(
-    nodes: &HashMap<PublicKey, NodeInfo>,
-) -> Result<(HashMap<PublicKey, NodeInfo>, HashMap<String, NodeInfo>), LightningError> {
+fn add_node_to_maps(nodes: &HashMap<PublicKey, NodeInfo>) -> Result<NodeMapping, LightningError> {
     let mut pk_node_map = HashMap::new();
     let mut alias_node_map = HashMap::new();
 
@@ -228,7 +339,10 @@ async fn add_node_to_maps(
         pk_node_map.insert(node_info.pubkey, node_info.clone());
     }
 
-    Ok((pk_node_map, alias_node_map))
+    Ok(NodeMapping {
+        pk_node_map,
+        alias_node_map,
+    })
 }
 
 /// Validates a set of defined activities, cross-checking aliases and public keys against the set of clients that
@@ -372,8 +486,10 @@ pub async fn get_validated_activities(
             "no nodes for query".to_string(),
         ))
     };
-    let (pk_node_map, alias_node_map) = add_node_to_maps(&nodes_info).await?;
-    let validated_activities =
-        validate_activities(activity.to_vec(), pk_node_map, alias_node_map, get_node).await?;
-    Ok(validated_activities)
+    let NodeMapping {
+        pk_node_map,
+        alias_node_map,
+    } = add_node_to_maps(&nodes_info)?;
+
+    validate_activities(activity.to_vec(), pk_node_map, alias_node_map, get_node).await
 }

sim-cli/src/parsing.rs

@@ -89,7 +89,7 @@ impl std::fmt::Display for NodeId {
 }
 
 /// Represents a short channel ID, expressed as a struct so that we can implement display for the trait.
-#[derive(Debug, Clone, PartialEq, Eq, Hash, Copy)]
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Copy, Serialize, Deserialize)]
 pub struct ShortChannelID(u64);
 
 /// Utility function to easily convert from u64 to `ShortChannelID`
@@ -476,7 +476,7 @@ pub struct Simulation {
     /// Config for the simulation itself.
     cfg: SimulationCfg,
     /// The lightning node that is being simulated.
-    pub nodes: HashMap<PublicKey, Arc<Mutex<dyn LightningNode>>>,
+    nodes: HashMap<PublicKey, Arc<Mutex<dyn LightningNode>>>,
     /// Results logger that holds the simulation statistics.
     results: Arc<Mutex<PaymentResultLogger>>,
     /// Track all tasks spawned for use in the simulation. When used in the `run` method, it will wait for
@@ -510,8 +510,9 @@ impl Simulation {
         cfg: SimulationCfg,
         nodes: HashMap<PublicKey, Arc<Mutex<dyn LightningNode>>>,
         tasks: TaskTracker,
+        shutdown_trigger: Trigger,
+        shutdown_listener: Listener,
     ) -> Self {
-        let (shutdown_trigger, shutdown_listener) = triggered::trigger();
         Self {
             cfg,
             nodes,