add/modify documentation; bump SimLN version

Author: mplsgrant

docs/plugins.md

@@ -0,0 +1,25 @@
+# Plugins
+
+Plugins allow users to extend Warnet. Plugin authors can import commands from Warnet and plugin users can run plugin commands from the command line or on each invocation of `warnet deploy`.
+
+## Activating plugins from 'network.yaml'
+
+You can activate a plugin command by placing it in the `plugin` section at the bottom of each `network.yaml` file like so:
+
+````yaml
+nodes:
+  <<snip>>
+
+plugins:
+  - path/to/plugin/file/relative/to/the/network/dot/yaml/file/plugin.py
+````
+
+Warnet will execute these plugin commands after each invocation of `warnet deploy`.
+
+## Example: SimLN
+
+To get started with an example plugin, review the `README` of the `simln` plugin found in any initialized Warnet directory:
+
+1. `warnet init`
+2. `cd plugins/simln/`
+

resources/plugins/simln/README.md

@@ -0,0 +1,110 @@
+# SimLN Plugin
+
+## SimLN
+SimLN helps you generate lightning payment activity.
+
+* Website: https://simln.dev/
+* Github: https://github.com/bitcoin-dev-project/sim-ln
+
+## Usage
+SimLN uses "activity" definitions to create payment activity between lightning nodes. These definitions are in JSON format.
+
+SimLN also requires access details for each node; however, the SimLN plugin will automatically generate these access details for each LND node. The access details look like this:
+
+```` JSON
+{
+  "id": <node_id>,
+  "address": https://<ip:port or domain:port>,
+  "macaroon": <path_to_selected_macaroon>,
+  "cert": <path_to_tls_cert>
+}
+````
+
+Since SimLN already has access to those LND connection details, it means you can focus on the "activity" definitions.
+
+### Launch activity definitions from the command line
+The SimLN plugin takes "activity" definitions like so:
+
+`./simln/plugin.py launch-activiy '[{\"source\": \"tank-0003-ln\", \"destination\": \"tank-0005-ln\", \"interval_secs\": 1, \"amount_msat\": 2000}]'"''`
+
+### Launch activity definitions from within `network.yaml`
+When you initialize a new Warnet network, Warnet will create a new `network.yaml` file.  If your `network.yaml` file includes lightning nodes, then you can use SimLN to produce activity between those nodes like this:
+
+<details>
+<summary>network.yaml</summary>
+
+````yaml
+nodes:
+  - name: tank-0000
+    addnode:
+      - tank-0001
+    ln:
+      lnd: true
+
+  - name: tank-0001
+    addnode:
+      - tank-0002
+    ln:
+      lnd: true
+
+  - name: tank-0002
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+
+  - name: tank-0003
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+    lnd:
+      config: |
+        bitcoin.timelockdelta=33
+      channels:
+        - id:
+            block: 300
+            index: 1
+          target: tank-0004-ln
+          capacity: 100000
+          push_amt: 50000
+
+  - name: tank-0004
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+    lnd:
+      channels:
+        - id:
+            block: 300
+            index: 2
+          target: tank-0005-ln
+          capacity: 50000
+          push_amt: 25000
+
+  - name: tank-0005
+    addnode:
+      - tank-0000
+    ln:
+      lnd: true
+
+plugins:
+  # Take note: the path to the plugin file is relative to the `network.yaml` file. The location of your `simln.py` file and `network.yaml` file may differ than what is shown below.
+  - "../../../resources/plugins/simln/plugin.py launch-activity '[{\"source\": \"tank-0003-ln\", \"destination\": \"tank-0005-ln\", \"interval_secs\": 1, \"amount_msat\": 2000}]'"
+````
+
+</details>
+
+## Generating your own SimLn image
+The SimLN plugin fetches a SimLN docker image from dockerhub. You can generate your own docker image if you choose:
+
+1. Clone SimLN: `git clone [email protected]:bitcoin-dev-project/sim-ln.git`
+2. Follow the instructions to build a docker image as detailed int the SimLn repository.
+3. Tag the resulting docker image: `docker tag IMAGEID YOURUSERNAME/sim-ln:VERSION`
+4. Push the tagged image to you dockerhub account.
+5Modify the `values.yaml` file in the plugin's chart to reflect your username and version number:
+```YAML
+  repository: "YOURUSERNAME/sim-ln"
+  tag: "VERSION"
+```

resources/plugins/simln/charts/simln/values.yaml

@@ -1,7 +1,7 @@
 name: "simln"
 image:
   repository: "mplsgrant/sim-ln"
-  tag: "d8c165d"
+  tag: "4d33f24"
   pullPolicy: IfNotPresent
 
 workingVolume:

resources/plugins/simln/simln.py renamed to resources/plugins/simln/plugin.py

@@ -21,15 +21,11 @@
 )
 from warnet.process import run_command
 
+# Tt is common for Warnet objects to have a "mission" tag to query them in the cluster.
 # To make a "mission" tag for your plugin, declare it using the variable name MISSION. This will
 # be read by the warnet log system and status system.
-# This should match the pod's "mission" value in this plugin's associated helm file.
+# This must match the pod's "mission" value in the plugin's associated helm file.
 MISSION = "simln"
-
-# Each pod we deploy should have a primary container. We make the name of that primary container
-# explicit here using the variable name CONTAINER which Warnet uses internally in its log and status
-# systems.
-# Again, this should match the container name provided in the associated helm file.
 PRIMARY_CONTAINER = MISSION
 
 PLUGIN_DIR_TAG = "plugin_dir"
@@ -50,7 +46,7 @@ class SimLNError(Exception):
 
 # Warnet uses a python package called "click" to manage terminal interactions with the user.
 # Each plugin must declare a click "group" by decorating a function named after the plugin.
-# This makes your plugin available in the plugin section of Warnet.
+# Using click makes it easy for users to interact with your plugin.
 @click.group()
 @click.pass_context
 def simln(ctx):
@@ -60,13 +56,8 @@ def simln(ctx):
     ctx.obj[PLUGIN_DIR_TAG] = Path(plugin_dir)
 
 
-# Make sure to register your plugin by adding the group function like so:
-def warnet_register_plugin(register_command):
-    register_command(simln)  # <-- We added the group function here.
-
-
-# The group function name is then used in decorators to create commands. These commands are
-# available to users when they access your plugin from the command line in Warnet.
+# The group name is then used in decorators to create commands. These commands are
+# available to users when they access your plugin from the command line.
 @simln.command()
 def list_pod_names():
     """Get a list of SimLN pod names"""
@@ -81,11 +72,10 @@ def download_results(pod_name: str):
     print(f"Downloaded results to: {dest}")
 
 
-# When we want to use a command inside our plugin and also provide that command to the user, we like
-# to create a private function whose name starts with an underscore. We also make a public function
-# with the same name except that we leave off the underscore, decorate it with the command
-# decorator, and also provide an instructive doc string which Warnet will display in the help
-# section of the command line program.
+# When we want to use a command inside our plugin and also provide that command to the user, it
+# helps to create a private function whose name starts with an underscore. We also make a public
+# function with the same name except that we leave off the underscore, decorate it with the command
+# decorator, and also provide an instructive doc string for the user.
 def _get_example_activity() -> list[dict]:
     pods = get_mission(LIGHTNING_MISSION)
     try:

test/ln_test.py

@@ -18,7 +18,7 @@ def __init__(self):
         self.imported_network_dir = self.tmpdir / "imported_network"
         self.scen_dir = Path(os.path.dirname(__file__)).parent / "resources" / "scenarios"
         self.plugins_dir = Path(os.path.dirname(__file__)).parent / "resources" / "plugins"
-        self.simln_exec = Path("simln/simln.py")
+        self.simln_exec = Path("simln/plugin.py")
 
     def run_test(self):
         try:

test/simln_test.py

@@ -1,17 +1,14 @@
 #!/usr/bin/env python3
 import ast
-import json
 import os
 from functools import partial
 from pathlib import Path
-from time import sleep
 from typing import Optional
 
 import pexpect
 from test_base import TestBase
 
-from warnet.constants import LIGHTNING_MISSION
-from warnet.k8s import download, get_mission, wait_for_pod
+from warnet.k8s import download, wait_for_pod
 from warnet.process import run_command
 
 
@@ -20,7 +17,7 @@ def __init__(self):
         super().__init__()
         self.network_dir = Path(os.path.dirname(__file__)) / "data" / "ln"
         self.plugins_dir = Path(os.path.dirname(__file__)).parent / "resources" / "plugins"
-        self.simln_exec = "plugins/simln/simln.py"
+        self.simln_exec = "plugins/simln/plugin.py"
 
     def run_test(self):
         try:
@@ -52,20 +49,6 @@ def copy_results(self):
         download(pod, Path("/working/results"), Path("."))
         self.wait_for_predicate(self.found_results_locally)
 
-    def wait_for_gossip_sync(self, expected: int):
-        self.log.info(f"Waiting for sync (expecting {expected})...")
-        current = 0
-        while current < expected:
-            current = 0
-            pods = get_mission(LIGHTNING_MISSION)
-            for v1_pod in pods:
-                node = v1_pod.metadata.name
-                chs = json.loads(run_command(f"warnet ln rpc {node} describegraph"))["edges"]
-                self.log.info(f"{node}: {len(chs)} channels")
-                current += len(chs)
-            sleep(1)
-        self.log.info("Synced")
-
     def found_results_remotely(self, pod: Optional[str] = None) -> bool:
         if pod is None:
             pod = self.get_first_simln_pod()