Improve Lightning payout processing
What changed, and why it matters
This commit hardens how BTCPay Server marks Lightning payouts as paid. It adds checks that ensure a payout is still in the expected state and that its payment proof has not unexpectedly changed before the system finalizes it. This reduces the risk of a payout being incorrectly marked as completed—through race conditions, retries, or tampering—while the underlying proof data has changed. The change is defensive and appears aimed at preventing double-payout or state-confusion bugs in automated Lightning withdrawals.
Review related payout handlers and other payment methods for similar missing state/proof preconditions; consider adding audit logging when MarkPaid returns InvalidState due to mismatched expected state or proof; ensure automated tests cover concurrent payout transitions.
Security signals we found
Adds state-and-proof equality precondition before finalizing payout
Closes race-condition window in Lightning payout state transitions
Prevents potential duplicate or incorrect completion of Lightning payouts
Defensive validation of payout proof blob integrity
Evidence from the diff
The patch introduces optimistic concurrency-style validation into the payout completion path. PullPaymentHostedService.HandleMarkPaid now accepts optional ExpectedState and ExpectedProof fields and rejects the MarkPaid request with PayoutPaidResult.InvalidState if the stored payout state or proof blob does not match the caller’s expectation. LightningPendingPayoutListener captures the original proof blob before processing and passes ExpectedState = InProgress and the original proof when calling MarkPaid. LightningAutomatedPayoutProcessor passes ExpectedState = AwaitingPayment when moving a payout to InProgress. This closes a window where concurrent or repeated operations could transition a payout based on stale or mutated data.
Changed components
BTCPayServer/HostedServices/PullPaymentHostedService.csBTCPayServer/Payments/Lightning/LightningPendingPayoutListener.csBTCPayServer/PayoutProcessors/Lightning/LightningAutomatedPayoutProcessor.csInspect captured patch +19 / −4
### BTCPayServer/HostedServices/PullPaymentHostedService.cs
@@ -599,6 +599,14 @@ private async Task HandleMarkPaid(InternalPayoutPaidRequest req)
return;
}
+ if (req.Request.ExpectedState is { } expectedState &&
+ (payout.State != expectedState ||
+ !JToken.DeepEquals(payout.GetProofBlobJson(), req.Request.ExpectedProof)))
+ {
+ req.Completion.SetResult(MarkPayoutRequest.PayoutPaidResult.InvalidState);
+ return;
+ }
+
if (payout.State is PayoutState.Completed or PayoutState.Cancelled)
{
req.Completion.SetResult(MarkPayoutRequest.PayoutPaidResult.InvalidState);
@@ -980,6 +988,8 @@ public enum PayoutPaidResult
public JObject Proof { get; set; }
public PayoutState State { get; set; } = PayoutState.Completed;
public PayoutBlob UpdateBlob { get; internal set; }
+ public PayoutState? ExpectedState { get; internal set; }
+ public JObject ExpectedProof { get; internal set; }
public static string GetErrorMessage(PayoutPaidResult result)
{
### BTCPayServer/Payments/Lightning/LightningPendingPayoutListener.cs
@@ -84,6 +84,9 @@ private async Task Act()
var client =
pm.CreateLightningClient(networks[pmi], _options.Value, _lightningClientFactoryService);
+ var expectedProofs = payoutByStoreByPaymentMethod.ToDictionary(
+ payoutData => payoutData.Id,
+ payoutData => payoutData.GetProofBlobJson());
foreach (PayoutData payoutData in payoutByStoreByPaymentMethod)
{
var handler = _payoutHandlers.TryGet(payoutData.GetPayoutMethodId()) as LightningLikePayoutHandler;
@@ -131,18 +134,19 @@ private async Task Act()
proof.Preimage = payment.Preimage;
payoutData.SetProofBlob(proof, null);
}
- }
+ }
foreach (PayoutData payoutData in payoutByStoreByPaymentMethod)
{
if (payoutData.State != PayoutState.InProgress)
{
- // This update can fail if the payout has been updated in the meantime
await _pullPaymentHostedService.MarkPaid(new HostedServices.MarkPayoutRequest()
{
PayoutId = payoutData.Id,
State = payoutData.State,
- Proof = payoutData.State is PayoutState.Completed ? JsonParser.ParseObject(payoutData.Proof) : null
+ Proof = payoutData.State is PayoutState.Completed ? JsonParser.ParseObject(payoutData.Proof) : null,
+ ExpectedState = PayoutState.InProgress,
+ ExpectedProof = expectedProofs[payoutData.Id]
});
}
}
### BTCPayServer/PayoutProcessors/Lightning/LightningAutomatedPayoutProcessor.cs
@@ -73,7 +73,8 @@ public async Task<ResultVM> HandlePayout(PayoutData payoutData, ILightningClient
{
State = PayoutState.InProgress,
PayoutId = payoutData.Id,
- Proof = null
+ Proof = null,
+ ExpectedState = PayoutState.AwaitingPayment
});
if (res != MarkPayoutRequest.PayoutPaidResult.Ok)
return InvalidState(payoutData.Id);Why this scored 59/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.