Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions docs/api-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ RPCs with no permission mapping return `UNIMPLEMENTED`, even for admin tokens.
| `invoices:create` | Create BOLT11/BOLT12 invoices and incoming refund requests |
| `payments:read` | Read payments, forwarded payments, and forwarding statistics |
| `payments:claim` | Claim or fail held BOLT11 payments |
| `payments:send` | Send BOLT11, BOLT12, spontaneous, unified, and refund payments; splice out |
| `payments:send` | Send BOLT11, BOLT12, spontaneous and unified payments and probes; splice out |
| `channels:read` | List channels |
| `channels:manage` | Open, configure, cooperatively close, splice funds into channels, or bump pending splice fees |
| `channels:force_close` | Force-close channels |
Expand Down Expand Up @@ -187,8 +187,15 @@ total fee rate in sat/vB; omit it to use an automatic rate. The response contain
|-------------------------|-------------------------------------------------------------------|
| `Bolt11Receive` | Create an invoice (fixed or variable amount) with automatic claim |
| `Bolt11Send` | Pay a BOLT11 invoice (with optional routing config) |
| `Bolt11SendProbes` | Send preflight probes for a BOLT11 invoice |
| `Bolt11SendUnderpaying` | Send part of the amount for a fixed-amount BOLT11 invoice |

Preflight probes send temporary HTLCs along the paths of the route that would be used to pay and
update the scorer. They do not make a payment, but can temporarily lock channel liquidity. Probing
is useful only if the probes have time to settle before the actual payment; otherwise, they may tie
up liquidity the payment needs. For variable-amount invoices, provide `amount_msat` to probe using
the intended amount.

> [!NOTE]
> `Bolt11SendUnderpaying` sends one part of a multi-part payment (MPP) for a fixed-amount
> BOLT11 invoice. Other nodes must send compatible partial payments for the same invoice
Expand Down Expand Up @@ -230,10 +237,11 @@ a channel just-in-time when the invoice is paid.

### Spontaneous and Unified Send

| RPC | Description |
|-------------------|--------------------------------------------------------------------------------|
| `SpontaneousSend` | Send a keysend payment to a node ID |
| `UnifiedSend` | Pay a BIP 21 URI, BIP 353 Human-Readable Name, BOLT11 invoice, or BOLT12 offer |
| RPC | Description |
|---------------------------|--------------------------------------------------------------------------------|
| `SpontaneousSend` | Send a keysend payment to a node ID |
| `SpontaneousSendProbes` | Send preflight probes for a spontaneous payment to a node ID |
| `UnifiedSend` | Pay a BIP 21 URI, BIP 353 Human-Readable Name, BOLT11 invoice, or BOLT12 offer |

### Channel Management

Expand Down
71 changes: 66 additions & 5 deletions e2e-tests/tests/e2e.rs
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,12 @@ use ldk_node::lightning_invoice::Bolt11Invoice;
use ldk_server_client::error::LdkServerErrorCode::{InvalidRequestError, LightningError};
use ldk_server_client::ldk_server_grpc::api::{
onchain_send_request, open_channel_request, Bolt11ClaimForIdRequest, Bolt11FailForIdRequest,
Bolt11ReceiveRequest, Bolt11SendRequest, Bolt12ReceiveRequest, BumpChannelFundingFeeRequest,
GetChannelForwardingStatsRequest, GetForwardedPaymentDetailsRequest, GetPaymentDetailsRequest,
ListChannelForwardingStatsRequest, ListChannelPairForwardingStatsRequest, ListChannelsRequest,
ListForwardedPaymentsRequest, OnchainBumpFeeRequest, OnchainReceiveRequest, OnchainSendRequest,
OpenChannelRequest,
Bolt11ReceiveRequest, Bolt11SendProbesRequest, Bolt11SendRequest, Bolt12ReceiveRequest,
BumpChannelFundingFeeRequest, GetChannelForwardingStatsRequest,
GetForwardedPaymentDetailsRequest, GetPaymentDetailsRequest, ListChannelForwardingStatsRequest,
ListChannelPairForwardingStatsRequest, ListChannelsRequest, ListForwardedPaymentsRequest,
OnchainBumpFeeRequest, OnchainReceiveRequest, OnchainSendRequest, OpenChannelRequest,
SpontaneousSendProbesRequest,
};
use ldk_server_client::ldk_server_grpc::events::event_envelope::Event;
use ldk_server_client::ldk_server_grpc::events::{
Expand Down Expand Up @@ -1156,6 +1157,66 @@ async fn test_cli_bolt11_send() {
assert!(!received.payment.as_ref().unwrap().payment_id.is_empty());
}

#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
async fn test_payment_preflight_probes() {
let bitcoind = TestBitcoind::new();
let server_a = LdkServerHandle::start(&bitcoind).await;
let server_b = LdkServerHandle::start(&bitcoind).await;
setup_funded_channel(&bitcoind, &server_a, &server_b, 100_000).await;

let fixed_invoice = server_b
.client()
.bolt11_receive(Bolt11ReceiveRequest {
amount_msat: Some(10_000_000),
description: None,
expiry_secs: 3600,
})
.await
.unwrap();
let variable_invoice = server_b
.client()
.bolt11_receive(Bolt11ReceiveRequest {
amount_msat: None,
description: None,
expiry_secs: 3600,
})
.await
.unwrap();
let payment_ids_before: Vec<_> =
list_payments(&server_a).await.into_iter().map(|payment| payment.payment_id).collect();

server_a
.client()
.bolt11_send_probes(Bolt11SendProbesRequest {
invoice: fixed_invoice.invoice,
amount_msat: None,
route_parameters: None,
})
.await
.unwrap();
server_a
.client()
.bolt11_send_probes(Bolt11SendProbesRequest {
invoice: variable_invoice.invoice,
amount_msat: Some(10_000_000),
route_parameters: None,
})
.await
.unwrap();
server_a
.client()
.spontaneous_send_probes(SpontaneousSendProbesRequest {
amount_msat: 100_000,
node_id: server_b.node_id().to_string(),
})
.await
.unwrap();

let payment_ids_after: Vec<_> =
list_payments(&server_a).await.into_iter().map(|payment| payment.payment_id).collect();
assert_eq!(payment_ids_after, payment_ids_before);
}

#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
async fn test_cli_bolt11_send_underpaying_split_payment() {
let bitcoind = TestBitcoind::new();
Expand Down
98 changes: 79 additions & 19 deletions ldk-server-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -35,32 +35,34 @@ use ldk_server_client::ldk_server_grpc::api::{
Bolt11ReceiveVariableAmountViaJitChannelRequest,
Bolt11ReceiveVariableAmountViaJitChannelResponse, Bolt11ReceiveViaJitChannelForHashRequest,
Bolt11ReceiveViaJitChannelForHashResponse, Bolt11ReceiveViaJitChannelRequest,
Bolt11ReceiveViaJitChannelResponse, Bolt11SendRequest, Bolt11SendResponse,
Bolt11SendUnderpayingRequest, Bolt11SendUnderpayingResponse, Bolt12CreatePayerProofRequest,
Bolt12CreatePayerProofResponse, Bolt12ReceiveRefundRequest, Bolt12ReceiveRefundResponse,
Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRefundRequest, Bolt12SendRefundResponse,
Bolt12SendRequest, Bolt12SendResponse, BumpChannelFundingFeeRequest,
BumpChannelFundingFeeResponse, CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest,
ConnectPeerResponse, CreateMacaroonRequest, CreateMacaroonResponse, DecodeInvoiceRequest,
DecodeInvoiceResponse, DecodeOfferRequest, DecodeOfferResponse, DisconnectPeerRequest,
DisconnectPeerResponse, ExportPathfindingScoresRequest, ForceCloseChannelRequest,
ForceCloseChannelResponse, GetBalancesRequest, GetBalancesResponse,
GetChannelForwardingStatsRequest, GetChannelForwardingStatsResponse,
GetForwardedPaymentDetailsRequest, GetForwardedPaymentDetailsResponse,
GetForwardedPaymentTrackingModeRequest, GetForwardedPaymentTrackingModeResponse,
GetNodeInfoRequest, GetNodeInfoResponse, GetPaymentDetailsRequest, GetPaymentDetailsResponse,
GetPermissionsRequest, GetPermissionsResponse, GraphGetChannelRequest, GraphGetChannelResponse,
GraphGetNodeRequest, GraphGetNodeResponse, GraphListChannelsRequest, GraphListChannelsResponse,
Bolt11ReceiveViaJitChannelResponse, Bolt11SendProbesRequest, Bolt11SendProbesResponse,
Bolt11SendRequest, Bolt11SendResponse, Bolt11SendUnderpayingRequest,
Bolt11SendUnderpayingResponse, Bolt12CreatePayerProofRequest, Bolt12CreatePayerProofResponse,
Bolt12ReceiveRefundRequest, Bolt12ReceiveRefundResponse, Bolt12ReceiveRequest,
Bolt12ReceiveResponse, Bolt12SendRefundRequest, Bolt12SendRefundResponse, Bolt12SendRequest,
Bolt12SendResponse, BumpChannelFundingFeeRequest, BumpChannelFundingFeeResponse,
CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse,
CreateMacaroonRequest, CreateMacaroonResponse, DecodeInvoiceRequest, DecodeInvoiceResponse,
DecodeOfferRequest, DecodeOfferResponse, DisconnectPeerRequest, DisconnectPeerResponse,
ExportPathfindingScoresRequest, ForceCloseChannelRequest, ForceCloseChannelResponse,
GetBalancesRequest, GetBalancesResponse, GetChannelForwardingStatsRequest,
GetChannelForwardingStatsResponse, GetForwardedPaymentDetailsRequest,
GetForwardedPaymentDetailsResponse, GetForwardedPaymentTrackingModeRequest,
GetForwardedPaymentTrackingModeResponse, GetNodeInfoRequest, GetNodeInfoResponse,
GetPaymentDetailsRequest, GetPaymentDetailsResponse, GetPermissionsRequest,
GetPermissionsResponse, GraphGetChannelRequest, GraphGetChannelResponse, GraphGetNodeRequest,
GraphGetNodeResponse, GraphListChannelsRequest, GraphListChannelsResponse,
GraphListNodesRequest, GraphListNodesResponse, ListChannelForwardingStatsRequest,
ListChannelPairForwardingStatsRequest, ListChannelsRequest, ListChannelsResponse,
ListForwardedPaymentsRequest, ListMacaroonsRequest, ListMacaroonsResponse, ListPaymentsRequest,
ListPeersRequest, ListPeersResponse, OnchainBumpFeeRequest, OnchainBumpFeeResponse,
OnchainReceiveRequest, OnchainReceiveResponse, OnchainSendRequest, OnchainSendResponse,
OpenChannelRequest, OpenChannelResponse, RevokeMacaroonRequest, RevokeMacaroonResponse,
SignMessageRequest, SignMessageResponse, SpliceInRequest, SpliceInResponse, SpliceOutRequest,
SpliceOutResponse, SpontaneousSendRequest, SpontaneousSendResponse, UnifiedSendRequest,
UnifiedSendResponse, UpdateChannelConfigRequest, UpdateChannelConfigResponse,
VerifySignatureRequest, VerifySignatureResponse,
SpliceOutResponse, SpontaneousSendProbesRequest, SpontaneousSendProbesResponse,
SpontaneousSendRequest, SpontaneousSendResponse, UnifiedSendRequest, UnifiedSendResponse,
UpdateChannelConfigRequest, UpdateChannelConfigResponse, VerifySignatureRequest,
VerifySignatureResponse,
};
use ldk_server_client::ldk_server_grpc::permissions::MacaroonPreset;
use ldk_server_client::ldk_server_grpc::types::{
Expand Down Expand Up @@ -311,6 +313,21 @@ enum Commands {
)]
max_channel_saturation_power_of_half: Option<u32>,
},
#[command(about = "Send temporary preflight HTLC probes for a BOLT11 invoice")]
Bolt11SendProbes {
#[arg(help = "A BOLT11 invoice to probe routes for")]
invoice: String,
#[arg(help = "Intended amount for a variable-amount invoice, e.g. 50sat")]
amount: Option<Amount>,
#[arg(long, help = "Maximum total routing fee, e.g. 50sat or 50000msat")]
max_total_routing_fee: Option<Amount>,
#[arg(long, help = "Maximum total CLTV delta for the route")]
max_total_cltv_expiry_delta: Option<u32>,
#[arg(long, help = "Maximum number of paths that may be probed")]
max_path_count: Option<u32>,
#[arg(long, help = "Maximum channel saturation power of one half")]
max_channel_saturation_power_of_half: Option<u32>,
},
#[command(
about = "Send part of a fixed-amount BOLT11 invoice. Other nodes must send partial payments for the same invoice until the combined amount equals the invoice amount"
)]
Expand Down Expand Up @@ -495,6 +512,13 @@ enum Commands {
)]
preimage: Option<Preimage>,
},
#[command(about = "Send temporary preflight HTLC probes for a spontaneous payment")]
SpontaneousSendProbes {
#[arg(help = "The hex-encoded public key of the destination node")]
node_id: String,
#[arg(help = "The amount to probe with, e.g. 50sat or 50000msat")]
amount: Amount,
},
#[command(
about = "Pay a BIP 21 URI, BIP 353 Human-Readable Name, BOLT11 invoice, or BOLT12 offer"
)]
Expand Down Expand Up @@ -1100,6 +1124,32 @@ async fn main() {
.await,
);
},
Commands::Bolt11SendProbes {
invoice,
amount,
max_total_routing_fee,
max_total_cltv_expiry_delta,
max_path_count,
max_channel_saturation_power_of_half,
} => {
let route_parameters = RouteParametersConfig {
max_total_routing_fee_msat: max_total_routing_fee.map(|amount| amount.to_msat()),
max_total_cltv_expiry_delta: max_total_cltv_expiry_delta
.unwrap_or(DEFAULT_MAX_TOTAL_CLTV_EXPIRY_DELTA),
max_path_count: max_path_count.unwrap_or(DEFAULT_MAX_PATH_COUNT),
max_channel_saturation_power_of_half: max_channel_saturation_power_of_half
.unwrap_or(DEFAULT_MAX_CHANNEL_SATURATION_POWER_OF_HALF),
};
handle_response_result::<_, Bolt11SendProbesResponse>(
client
.bolt11_send_probes(Bolt11SendProbesRequest {
invoice,
amount_msat: amount.map(|amount| amount.to_msat()),
route_parameters: Some(route_parameters),
})
.await,
);
},
Commands::Bolt11SendUnderpaying {
invoice,
amount,
Expand Down Expand Up @@ -1279,6 +1329,16 @@ async fn main() {
.await,
);
},
Commands::SpontaneousSendProbes { node_id, amount } => {
handle_response_result::<_, SpontaneousSendProbesResponse>(
client
.spontaneous_send_probes(SpontaneousSendProbesRequest {
amount_msat: amount.to_msat(),
node_id,
})
.await,
);
},
Commands::Pay {
uri,
amount,
Expand Down
Loading
Loading