Expose background probing service

Allow operators to enable either built-in probing strategy through the
config file, CLI arguments, or environment variables. Validate strategy
settings and document the risk of probes locking outbound liquidity.

AI assistance: OpenAI Codex was used to implement and verify this
change.

Author: benthecarman

contrib/ldk-server-config.toml

@@ -9,6 +9,23 @@ alias = "ldk_server"                          # Lightning node alias
 #rgs_server_url = "https://rapidsync.lightningdevkit.org/snapshot/v2/"  # Optional: RGS URL for rapid gossip sync
 #async_payments_role = "client"               # Optional async payments role: "client" or "server"
 
+# Background probing service (optional)
+# CAUTION: Probes send real HTLCs and can lock outbound liquidity until they time out.
+# See docs/configuration.md for complete field descriptions.
+# Set only the field required by the selected strategy.
+# "high_degree" requires top_node_count. "random_walk" requires max_hops.
+#[probing]
+#strategy = "high_degree"                     # Required. No default. See the strategy recommendations in the documentation.
+#top_node_count = 100                          # Required for "high_degree". No default. Start with 100.
+# max_hops must be at least 2. LDK Node changes values greater than 19 to 19.
+#max_hops = 5                                  # Required for "random_walk". No default. Start with 5.
+#interval_secs = 10                            # Time between probe attempts (default: 10 seconds)
+# Built-in probes use at least 1000000 msat before routing fees. Lower limits prevent all probes.
+#max_locked_msat = 100000000                   # Maximum total in-flight probe liquidity (default: 100k sats)
+# This virtual scorer cost is not paid. It decreases to zero over 24 hours.
+#diversity_penalty_msat = 250                  # Optional. Only affects "high_degree".
+#cooldown_secs = 3600                          # Node re-probe cooldown for "high_degree" (default: 1 hour)
+
 # Storage settings
 [storage.disk]
 dir_path = "/tmp/ldk-server/"                 # Path for LDK and BDK data persistence, optional, defaults to ~/Library/Application Support/ldk-server/ on macOS, ~/.ldk-server/ on Linux

docs/configuration.md

@@ -59,6 +59,44 @@ this node to go offline. Set `async_payments_role = "server"` to hold async paym
 and onion messages for peers. The server role requires an announceable node configuration.
 Leave the field unset to disable async payments.
 
+### `[probing]`
+
+Enables LDK Node's background probing service to train the payment scorer with current
+channel-liquidity information. Probing is disabled when this section and the corresponding
+CLI/environment options are absent.
+
+The `strategy` field selects one of two path-selection methods:
+
+- **`"high_degree"`** probes toward highly connected public nodes. The service uses the
+  payment scorer to select a path.
+- **`"random_walk"`** constructs random paths through the public graph. This strategy does
+  not use the payment scorer to select a path.
+
+The section accepts these fields:
+
+| Field | Requirement and default | Description |
+| --- | --- | --- |
+| `strategy` | Required. No default. | Selects `"high_degree"` or `"random_walk"`. Start with `"random_walk"` for a payment node. Use `"high_degree"` for a dedicated probing node. |
+| `top_node_count` | Required for `"high_degree"`. No default. Start with `100`. | Sets the number of highly connected public nodes in the destination set. The strategy cycles through this set. The value must be greater than `0`. |
+| `max_hops` | Required for `"random_walk"`. No default. Start with `5`. | Sets the maximum number of hops in a random path. The value must be at least `2`. LDK Node changes values greater than `19` to `19`. |
+| `interval_secs` | Optional. The default is `10`. | Sets the number of seconds between probe attempts. LDK Node changes `0` to its minimum interval of 100 milliseconds. |
+| `max_locked_msat` | Optional. The default is `100000000` (100,000 satoshis). | Limits the total amount and pending fees of in-flight probes. The service skips a probe that exceeds the remaining limit. Built-in probes use 1,000,000 through 10,000,000 millisatoshis before routing fees. |
+| `diversity_penalty_msat` | Optional. The default is `0`. | Adds a virtual routing cost to recently probed channels. The service does not pay this amount. The cost decreases to zero over 24 hours and encourages different paths. This field only affects `"high_degree"`. |
+| `cooldown_secs` | Optional. The default is `3600`. | Sets the time before `"high_degree"` can select the same destination again. The strategy starts a new cycle immediately after it probes all destinations. |
+
+```toml
+[probing]
+strategy = "high_degree"
+top_node_count = 100
+interval_secs = 30
+max_locked_msat = 100000000
+diversity_penalty_msat = 250
+cooldown_secs = 3600
+```
+
+> **Caution:** Probes send real HTLCs over real channels. A probe can lock outbound liquidity
+> until its HTLC expires. Use `max_locked_msat` to limit this risk.
+
 ### `[storage.disk]`
 
 Where persistent data is stored. Defaults to `~/.ldk-server/` on Linux and

ldk-server/src/main.rs

@@ -207,6 +207,10 @@ fn main() {
 		builder.set_gossip_source_rgs(rgs_server_url);
 	}
 
+	if let Some(probing_config) = config_file.probing_config {
+		builder.set_probing_config(probing_config);
+	}
+
 	if let Err(e) = builder.set_async_payments_role(config_file.async_payments_role) {
 		error!("Failed to configure async payments role: {e}");
 		std::process::exit(-1);