fixup! Add BOLT11 underpaying send RPC

AI-assisted-by: OpenAI Codex

Author: benthecarman

docs/api-guide.md

@@ -93,11 +93,17 @@ All RPCs are unary (single request, single response) unless noted otherwise.
 
 ### BOLT11 Payments
 
-| RPC                       | Description                                                                        |
-|---------------------------|------------------------------------------------------------------------------------|
-| `Bolt11Receive`           | Create an invoice (fixed or variable amount) with automatic claim                  |
-| `Bolt11Send`              | Pay a BOLT11 invoice (with optional routing config)                                |
-| `Bolt11SendUnderpaying`   | Pay less than the invoice amount when the receiver accepts underpaying HTLCs       |
+| RPC                     | Description                                                       |
+|-------------------------|-------------------------------------------------------------------|
+| `Bolt11Receive`         | Create an invoice (fixed or variable amount) with automatic claim |
+| `Bolt11Send`            | Pay a BOLT11 invoice (with optional routing config)               |
+| `Bolt11SendUnderpaying` | Send part of the amount for a BOLT11 invoice                      |
+
+> [!NOTE]
+> `Bolt11SendUnderpaying` sends one part of a multi-part payment (MPP) for a BOLT11
+> invoice. Other nodes must send compatible partial payments for the same invoice until
+> the combined amount equals the invoice amount. Without those payments, the receiver
+> holds the incomplete MPP payment and eventually fails it.
 
 ### BOLT11 Hodl Invoices
 

ldk-server-cli/src/main.rs

@@ -247,12 +247,14 @@ enum Commands {
 		)]
 		max_channel_saturation_power_of_half: Option<u32>,
 	},
-	#[command(about = "Underpay a BOLT11 invoice")]
+	#[command(
+		about = "Send part of a BOLT11 invoice. Other nodes must send partial payments for the same invoice until the combined amount equals the invoice amount"
+	)]
 	Bolt11SendUnderpaying {
 		#[arg(help = "A BOLT11 invoice for a payment within the Lightning Network")]
 		invoice: String,
 		#[arg(
-			help = "Amount to send, e.g. 50sat or 50000msat. Must be less than the invoice amount"
+			help = "Amount from this payer, for example 50sat or 50000msat. Must be less than the invoice amount"
 		)]
 		amount: Amount,
 		#[arg(

ldk-server-client/src/client.rs

@@ -244,7 +244,11 @@ impl LdkServerClient {
 		self.grpc_unary(&request, BOLT11_SEND_PATH).await
 	}
 
-	/// Send an underpaying payment for a BOLT11 invoice.
+	/// Send part of the amount for a BOLT11 invoice.
+	///
+	/// Other nodes must send partial payments for the same invoice until the combined amount equals
+	/// the invoice amount. Without those payments, the receiver holds the incomplete MPP payment
+	/// and eventually fails it.
 	pub async fn bolt11_send_underpaying(
 		&self, request: Bolt11SendUnderpayingRequest,
 	) -> Result<Bolt11SendUnderpayingResponse, LdkServerError> {

ldk-server-grpc/src/api.rs

@@ -376,7 +376,9 @@ pub struct Bolt11SendResponse {
 	#[prost(string, tag = "1")]
 	pub payment_id: ::prost::alloc::string::String,
 }
-/// Send an underpaying payment for a BOLT11 invoice.
+/// Send part of the amount for a BOLT11 invoice.
+/// Other nodes must send partial payments for the same invoice until the combined amount equals the invoice amount.
+/// Without those payments, the receiver holds the incomplete MPP payment and eventually fails it.
 /// See more: <https://docs.rs/ldk-node/latest/ldk_node/payment/struct.Bolt11Payment.html#method.send_using_amount_underpaying>
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
@@ -387,7 +389,7 @@ pub struct Bolt11SendUnderpayingRequest {
 	/// An invoice for a payment within the Lightning Network.
 	#[prost(string, tag = "1")]
 	pub invoice: ::prost::alloc::string::String,
-	/// Amount in millisatoshis to send. Must be less than the amount required by the invoice.
+	/// Amount in millisatoshis from this payer. Must be less than the amount required by the invoice.
 	#[prost(uint64, tag = "2")]
 	pub amount_msat: u64,
 	/// Configuration options for payment routing and pathfinding.

ldk-server-grpc/src/proto/api.proto

@@ -296,14 +296,16 @@ message Bolt11SendResponse {
   string payment_id = 1;
 }
 
-// Send an underpaying payment for a BOLT11 invoice.
+// Send part of the amount for a BOLT11 invoice.
+// Other nodes must send partial payments for the same invoice until the combined amount equals the invoice amount.
+// Without those payments, the receiver holds the incomplete MPP payment and eventually fails it.
 // See more: https://docs.rs/ldk-node/latest/ldk_node/payment/struct.Bolt11Payment.html#method.send_using_amount_underpaying
 message Bolt11SendUnderpayingRequest {
 
   // An invoice for a payment within the Lightning Network.
   string invoice = 1;
 
-  // Amount in millisatoshis to send. Must be less than the amount required by the invoice.
+  // Amount in millisatoshis from this payer. Must be less than the amount required by the invoice.
   uint64 amount_msat = 2;
 
   // Configuration options for payment routing and pathfinding.
@@ -950,7 +952,8 @@ service LightningNode {
   rpc Bolt11ReceiveVariableAmountViaJitChannel(Bolt11ReceiveVariableAmountViaJitChannelRequest) returns (Bolt11ReceiveVariableAmountViaJitChannelResponse);
   // Send a payment for a BOLT11 invoice.
   rpc Bolt11Send(Bolt11SendRequest) returns (Bolt11SendResponse);
-  // Send an underpaying payment for a BOLT11 invoice.
+  // Send part of the amount for a BOLT11 invoice.
+  // Other nodes must send partial payments for the same invoice until the combined amount equals the invoice amount.
   rpc Bolt11SendUnderpaying(Bolt11SendUnderpayingRequest) returns (Bolt11SendUnderpayingResponse);
   // Return a BOLT12 offer.
   rpc Bolt12Receive(Bolt12ReceiveRequest) returns (Bolt12ReceiveResponse);

ldk-server-mcp/src/tools/mod.rs

@@ -141,7 +141,7 @@ pub fn build_tool_registry() -> ToolRegistry {
 		),
 		tool_spec(
 			"bolt11_send_underpaying",
-			"Underpay a BOLT11 Lightning invoice",
+			"Send part of a BOLT11 invoice. Other nodes must send partial payments for the same invoice until the combined amount equals the invoice amount",
 			schema::bolt11_send_underpaying_schema,
 			|client, args| Box::pin(handlers::handle_bolt11_send_underpaying(client, args)),
 		),

ldk-server-mcp/src/tools/schema.rs

@@ -317,11 +317,11 @@ pub fn bolt11_send_underpaying_schema() -> Value {
 		"properties": {
 			"invoice": {
 				"type": "string",
-				"description": "A BOLT11 invoice string to underpay"
+				"description": "The BOLT11 invoice that all payers use"
 			},
 			"amount_msat": {
 				"type": "integer",
-				"description": "Amount in millisatoshis to send. Must be less than the invoice amount"
+				"description": "Amount in millisatoshis from this payer. Must be less than the invoice amount"
 			},
 			"route_parameters": route_parameters_config_schema()
 		},