← Watch feed
Add LUD-21 (LNURL-pay Verify) support (#7250)
Public commit record
100/100 · Strong
What the developer wrote
Authored by Roxanne
Add LUD-21 (LNURL-pay Verify) support (#7250)
* Add LUD-21 (LNURL-pay Verify) support
Implements the LUD-21 verify endpoint for Lightning Address payments,
enabling external services to verify payment settlement without
authentication.
Changes:
- New GET /lnurlp/{username}/verify/{paymentHash} endpoint
- Callback response includes verify URL when LUD-21 is enabled
- Payment hashes indexed in search data for efficient lookup
- LUD21Enabled toggle in LNURL payment method config (default: true)
- Settings UI toggle matching LUD-12 pattern
- Swagger API docs updated
Closes #7248
* Use case-insensitive comparison for payment hash in LUD-21 verify
* Address Nicolas review: use AddressInvoices instead of AdditionalSearchTerms
- Replace AddSearchTerms with AddAddressInvoice for payment hash indexing
- Replace TextSearch lookup with GetInvoiceFromAddress in verify endpoint
- Add storeId validation on verify endpoint (cross-store isolation)
- Add payment hash to TrackedDestinations in LightningLikePaymentHandler
- Add rate limiting (ZoneLimits.Verify) to verify endpoint
- Add integration test for LUD-21 verify endpoint flow
* Remove rate limiting from LUD-21 verify endpoint
Rate limiting will be discussed and added in a follow-up.
* Fix verify endpoint: idempotent AddAddressInvoice, normalize payment hash
- Make AddAddressInvoice upsert to avoid duplicate key violations
on (Address, PaymentMethodId)
- Normalize payment hash to lowercase for consistent DB lookups
(store, query, and verify URL generation)
* test(LUD-21): properly exercise cross-store isolation in CanUseLUD21VerifyEndpoint
The previous storeId-isolation assertion did not actually validate the
intended behavior. store2 only had a Lightning Address configured, but
no Lightning node / LNURL payment method. The verify endpoint bails out
with 404 "Not available" at UILNURLController.cs:487-489 before
reaching the invoice-lookup / store-isolation check at L492-494, so the
old assertion would pass even if the isolation logic were broken.
Fix:
- Configure BTC-LN and BTC-LNURL (LUD21Enabled = true) on store2 via
UpdateStorePaymentMethod, mirroring what RegisterLightningNodeAsync
does for store1.
- Strengthen the assertion to also verify the response body's reason
is "Not found" rather than "Not available", proving the request
reached the actual store-isolation branch.
* feat(LUD-21): validate paymentHash is 64 hex chars before lookup
LnurlPayVerify previously accepted any non-empty paymentHash string and
only normalized casing. A Lightning payment hash is exactly 32 bytes /
64 hex characters, so reject anything else up front to avoid pointless
DB lookups on garbage input and return a consistent "Not found"
response shape.
* fix(LUD-21): standardize LnurlPayVerify not-found reason to "Not found"
LnurlPayVerify previously returned three different reason strings for
not-found cases ("Unknown username", "Not available", "Not found"),
which leaks information about which lookup branch failed and was flagged
in CodeRabbit review.
Collapse the username/store-resolution branches to a single "Not found"
reason. The LUD-21 feature-disabled branch keeps its distinct "Not
available" reason because that's a genuinely different operational
condition (feature off vs resource missing) and the new test relies on
the distinction to validate the cross-store isolation path.
* test(LUD-21): fix LN Address fetch path to use /.well-known/lnurlp/{username}
CanUseLUD21VerifyEndpoint was calling /lnurlp/{username} to fetch the
LNURL-pay request, but that path has no route. The actual LUD-16
Lightning Address resolver is published at /.well-known/lnurlp/{username}
(see ResolveLightningAddress in UILNURLController.cs and existing usage
in PlaywrightTests / TestAccount). The wrong path made the test fail at
the very first GET with 404, before the verify endpoint logic could be
exercised at all.
* fix(LUD-21): close TOCTOU race in AddAddressInvoice + harden preimage assertion
CodeRabbit followup:
1. AddAddressInvoice was check-then-insert, so two concurrent LNURL
callbacks for the same (Address, PaymentMethodId) could both observe
existing == null and both attempt to INSERT, causing the second one
to throw on the unique-key constraint. Wrap the insert path in
try/catch (DbUpdateException) and swallow the violation - both
writers are inserting identical data, so the operation is naturally
idempotent under contention. The update branch is kept on its own
SaveChangesAsync so failures there still propagate.
2. The preimage assertion in CanUseLUD21VerifyEndpoint was
Assert.Null(verifyResult["preimage"]?.ToString()), which depends on
how the global JSON serializer handles null values - if the field is
serialized as JSON null instead of being omitted, ToString() returns
the empty string and the assertion fails. Compare against the
JTokenType.Null sentinel directly so the test is robust to either
serializer mode.
* refactor(LUD-21): flush tracked payment hash via UpdatePrompt overload
Consolidates the two-call sequence in the LNURL callback (UpdatePrompt
followed by a separate AddAddressInvoice) into a single UpdatePrompt
call that accepts an optional trackedDestinations list and flushes
AddressInvoices rows inside the same DbContext transaction.
- Ensures the payment-hash index row is written atomically with the
prompt update so a crash between the two calls can no longer leave
the prompt persisted without its verify-lookup row.
- Keeps idempotency under concurrent LNURL callbacks (existing row
check + DbUpdateException swallow, matching AddAddressInvoice).
- Controller no longer reaches into the repository twice for a single
logical state transition.
No behavior change for existing UpdatePrompt callers (trackedDestinations
defaults to null).
* fix(LUD-21): split SaveChanges in UpdatePrompt, exclude concurrency from inner catch
Addresses both items from coderabbit review on dcfdf88:
1. DbUpdateConcurrencyException is a DbUpdateException subtype, so the
inner catch in the trackedDestinations flush would have silently
swallowed concurrency conflicts on the invoice row, breaking the
outer retry loop. Narrowed the inner catch with
'when (ex is not DbUpdateConcurrencyException)'.
2. Batching the prompt blob update and the AddressInvoices insert into
a single SaveChangesAsync meant a unique-key violation on the
tracked destination would roll back the entire unit of work and
silently drop the prompt blob update. Split into two
SaveChangesAsync calls: the blob update runs first and any error
propagates (concurrency still retries via the outer catch); the
tracked-destination flush runs after with its own scoped,
unique-key-only swallow.
* test(LUD-21): cover repeat-callback idempotency and hash validation
Adds three assertions inside the existing CanLNURLPayVerify integration test
to illustrate and guard the UpdatePrompt(trackedDestinations) refactor:
- Repeat LNURL callback with the SAME amount: exercises the idempotent
flush path where the AddressInvoices row for the payment hash already
exists. The second callback must return 200 and the verify endpoint
must still resolve the hash afterward (no duplicate row, no throw).
- Repeat LNURL callback with a DIFFERENT amount: a new payment hash is
minted. The new verify URL must resolve, proving the new hash is
indexed in AddressInvoices and the prompt blob transition persists.
- Verify endpoint with a malformed (non-hex / wrong-length) paymentHash
segment must return 404 with Reason 'Not found' at the 64-hex guard
before any DB lookup is performed.
* Address NicolasDorier review feedback on LUD-21
- Remove username from verify route (/lnurlp/verify/{paymentHash}),
look up store from invoice instead; enables verify for all LNURL,
not only Lightning Address
- Replace EF check-then-act in AddressInvoices with SQL INSERT ON
CONFLICT DO NOTHING (single roundtrip, no partial-dup DbContext
corruption)
- Remove IgnoreAntiforgeryToken on GET route
- Remove payment hash tracking from LightningLikePaymentHandler
(only needed for LNURL path, already handled in UILNURLController)
- Standardize all error responses to "Not found"
- Simplify tests: drop cross-store-via-username and unknown-username
checks (no longer applicable without username in route)
* Address NicolasDorier review: guard trackedDestinations on LUD21Enabled, deduplicate AddressInvoices upsert
- trackedDestinations is now null when LUD21 is not enabled, preventing
unnecessary AddressInvoices rows for stores that don't use verify.
- Extract UpsertAddressInvoice helper to eliminate the duplicated INSERT
SQL across AddAddressInvoice, UpdatePrompt, and NewPaymentPrompt.
---------
Co-authored-by: r1ckstardev <r1ckstardev@users.noreply.github.com>
Co-authored-by: r1ckstardev <me@r0ckstar.dev>
✓ Descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context✓ Explains rationale or failure mode✓ Mentions testing or verification✓ Links an issue, advisory, or supporting reference✓ Names security-relevant behavior explicitly
What changed, and why it matters
This commit adds a new public feature to BTCPay Server called LUD-21, which lets anyone check whether a Lightning Network payment has settled by knowing its payment hash. The feature is enabled by default. The code went through several review rounds that fixed information-leakage issues, race conditions, and input-validation problems. The final version appears reasonably hardened, but because it intentionally exposes invoice settlement status and the payment preimage to unauthenticated callers, it carries a real privacy and operational risk if a merchant does not realize it is on by default.
Recommended action
Operators should review whether they need LUD-21 and consider disabling it if exposing settlement/preimage data to unauthenticated third parties is undesirable. The project should add rate limiting to /lnurlp/verify/{paymentHash} promptly, because the removal of rate limiting was left as a follow-up. A security note in release notes explaining the new default-on public endpoint would help merchants make an informed choice.
Security signals we found
01
New unauthenticated GET endpoint exposes invoice settlement status and Lightning preimage for a known payment hash
02
Feature is enabled by default (LUD21Enabled = true) in LNURL payment method config
03
Payment hash is indexed in AddressInvoices and exposed through callback verify URL
04
Multiple review iterations addressed information disclosure (uniform "Not found" responses), race conditions (UPSERT instead of check-then-insert), and input validation (64-hex guard)
05
Cross-store isolation is enforced by looking up the invoice first and then validating the store's LUD-21 setting
06
Preimage is returned only when invoice status is Settled or Processing
07
Rate limiting was added and then explicitly removed, to be discussed in a follow-up
Evidence from the diff
The change implements the LNURL-pay LUD-21 verify endpoint. It adds GET /lnurlp/verify/{paymentHash}, returns {status, settled, preimage, pr} for a matching invoice, and includes a verify URL in LNURL-pay callback responses when LUD21Enabled is true (default true). Payment hashes are indexed via AddressInvoices using INSERT … ON CONFLICT DO NOTHING. The endpoint validates that paymentHash is exactly 64 hex characters, normalizes to lowercase, looks up the invoice through AddressInvoices, confirms the store has LUD-21 enabled, and verifies the hash matches the prompt details before returning the preimage only for settled/processing invoices. Review feedback removed the username from the route, standardized error reasons to “Not found”, removed antiforgery token exemption, and added cross-store isolation by resolving the store from the invoice.
Changed components
BTCPayServer/Controllers/UILNURLController.csBTCPayServer/Services/Invoices/InvoiceRepository.csBTCPayServer/Payments/LNURLPay/LNURLPaymentMethodConfig.csBTCPayServer/Controllers/UIStoresController.LightningLike.csBTCPayServer/Views/UIStores/LightningSettings.cshtmlBTCPayServer/Models/StoreViewModels/LightningSettingsViewModel.csBTCPayServer/wwwroot/swagger/v1/swagger.template.stores-payment-methods.lnurl.jsonBTCPayServer.Tests/LightningTests.csInspect captured patch +233 / −12
diff --git a/BTCPayServer.Tests/LightningTests.cs b/BTCPayServer.Tests/LightningTests.cs
index 7c4d5b8..d0a6a28 100644
--- a/BTCPayServer.Tests/LightningTests.cs
+++ b/BTCPayServer.Tests/LightningTests.cs
@@ -955,4 +955,105 @@ public class LightningTests(ITestOutputHelper testOutputHelper) : UnitTestBase(t
Assert.Null(conf["useBech32Scheme"]); // default stripped
#pragma warning restore CS0618 // Type or member is obsolete
}
+
+ [Fact(Timeout = 60 * 20 * 1000)]
+ [Trait("Integration", "Integration")]
+ [Trait("Lightning", "Lightning")]
+ public async Task CanUseLUD21VerifyEndpoint()
+ {
+ using var tester = CreateServerTester();
+ tester.ActivateLightning();
+ await tester.StartAsync();
+ await tester.EnsureChannelsSetup();
+ var user = tester.NewAccount();
+ await user.GrantAccessAsync(true);
+ var client = await user.CreateClient(Policies.Unrestricted);
+
+ // Enable LNURL and Lightning
+ var methods = await client.GetStorePaymentMethods(user.StoreId);
+ await user.RegisterLightningNodeAsync("BTC", false);
+
+ // Set up a Lightning Address
+ var username = Guid.NewGuid().ToString("n").Substring(0, 8);
+ await client.AddOrUpdateStoreLightningAddress(user.StoreId, username,
+ new LightningAddressData());
+
+ // Verify endpoint returns 404 for unknown payment hash
+ var fakeHash = "0000000000000000000000000000000000000000000000000000000000000000";
+ var response = await tester.PayTester.HttpClient.GetAsync(
+ $"/lnurlp/verify/{fakeHash}");
+ Assert.Equal(System.Net.HttpStatusCode.NotFound, response.StatusCode);
+
+ // Create an invoice via LNURL-pay flow to get a real payment hash.
+ // The Lightning Address resolver lives at /.well-known/lnurlp/{username}
+ // (LUD-16). The bare /lnurlp/{username} path has no route.
+ var lnurlResponse = await tester.PayTester.HttpClient.GetAsync(
+ $"/.well-known/lnurlp/{username}");
+ Assert.Equal(System.Net.HttpStatusCode.OK, lnurlResponse.StatusCode);
+ var lnurlPayRequest = JObject.Parse(await lnurlResponse.Content.ReadAsStringAsync());
+ var callback = lnurlPayRequest["callback"]?.ToString();
+ Assert.NotNull(callback);
+
+ // Make the callback with minimum amount to create a Lightning invoice
+ var minSendable = lnurlPayRequest["minSendable"]?.Value<long>() ?? 1000;
+ var callbackUri = new Uri(callback);
+ var callbackPath = callbackUri.PathAndQuery;
+ var separator = callbackPath.Contains('?') ? "&" : "?";
+ var callbackResponse = await tester.PayTester.HttpClient.GetAsync(
+ $"{callbackPath}{separator}amount={minSendable}");
+ Assert.Equal(System.Net.HttpStatusCode.OK, callbackResponse.StatusCode);
+ var callbackResult = JObject.Parse(await callbackResponse.Content.ReadAsStringAsync());
+
+ // Check if verify URL is present in callback response
+ var verifyUrl = callbackResult["verify"]?.ToString();
+ Assert.NotNull(verifyUrl);
+
+ // Extract payment hash from verify URL
+ var verifyUri = new Uri(verifyUrl);
+ var verifyPath = verifyUri.PathAndQuery;
+
+ // Call verify endpoint - invoice should exist but not be settled yet
+ var verifyResponse = await tester.PayTester.HttpClient.GetAsync(verifyPath);
+ Assert.Equal(System.Net.HttpStatusCode.OK, verifyResponse.StatusCode);
+ var verifyResult = JObject.Parse(await verifyResponse.Content.ReadAsStringAsync());
+ Assert.Equal("OK", verifyResult["status"]?.ToString());
+ Assert.False(verifyResult["settled"]?.Value<bool>());
+ var preimageToken = verifyResult["preimage"];
+ Assert.True(preimageToken is null || preimageToken.Type == JTokenType.Null,
+ "Expected preimage to be null or absent for an unsettled invoice");
+ Assert.NotNull(verifyResult["pr"]?.ToString());
+
+ // Repeat the callback with the SAME amount. Exercises the idempotent flush
+ // branch in UpdatePrompt(trackedDestinations): the AddressInvoices row for
+ // the payment hash already exists, so the flush loop should take the
+ // "existing is not null" path without throwing or duplicating rows, and
+ // the verify endpoint should still resolve the hash afterward.
+ var callbackResponse2 = await tester.PayTester.HttpClient.GetAsync(
+ $"{callbackPath}{separator}amount={minSendable}");
+ Assert.Equal(System.Net.HttpStatusCode.OK, callbackResponse2.StatusCode);
+ var verifyResponse2 = await tester.PayTester.HttpClient.GetAsync(verifyPath);
+ Assert.Equal(System.Net.HttpStatusCode.OK, verifyResponse2.StatusCode);
+
+ // Repeat the callback with a DIFFERENT amount. UpdatePrompt should persist
+ // the new prompt blob AND index the new payment hash in AddressInvoices so
+ // the new verify URL resolves.
+ var newAmount = minSendable * 2;
+ var callbackResponse3 = await tester.PayTester.HttpClient.GetAsync(
+ $"{callbackPath}{separator}amount={newAmount}");
+ Assert.Equal(System.Net.HttpStatusCode.OK, callbackResponse3.StatusCode);
+ var callbackResult3 = JObject.Parse(await callbackResponse3.Content.ReadAsStringAsync());
+ var verifyUrl3 = callbackResult3["verify"]?.ToString();
+ Assert.NotNull(verifyUrl3);
+ var verifyPath3 = new Uri(verifyUrl3).PathAndQuery;
+ var verifyResponse3 = await tester.PayTester.HttpClient.GetAsync(verifyPath3);
+ Assert.Equal(System.Net.HttpStatusCode.OK, verifyResponse3.StatusCode);
+
+ // Malformed paymentHash (non-hex / wrong length) must be rejected at the
+ // 64-hex guard before any DB lookup, returning Reason "Not found".
+ var malformedResponse = await tester.PayTester.HttpClient.GetAsync(
+ $"/lnurlp/verify/not-a-hex-hash");
+ Assert.Equal(System.Net.HttpStatusCode.NotFound, malformedResponse.StatusCode);
+ var malformedBody = JObject.Parse(await malformedResponse.Content.ReadAsStringAsync());
+ Assert.Equal("Not found", malformedBody["reason"]?.ToString());
+ }
}
diff --git a/BTCPayServer/Controllers/UILNURLController.cs b/BTCPayServer/Controllers/UILNURLController.cs
index 85a48d1..5269783 100644
--- a/BTCPayServer/Controllers/UILNURLController.cs
+++ b/BTCPayServer/Controllers/UILNURLController.cs
@@ -461,6 +461,63 @@ namespace BTCPayServer
return Ok(lnurlRequest);
}
+ /// <summary>
+ /// LUD-21: Verify payment status for an LNURL payment.
+ /// Returns settlement status and preimage for a given payment hash.
+ /// </summary>
+ [HttpGet("~/lnurlp/verify/{paymentHash}")]
+ [EnableCors(CorsPolicies.All)]
+ public async Task<IActionResult> LnurlPayVerify(string paymentHash)
+ {
+ if (string.IsNullOrEmpty(paymentHash))
+ return NotFound();
+
+ // A Lightning payment hash is exactly 32 bytes / 64 hex chars.
+ // Reject anything else up front to avoid pointless DB lookups on garbage input.
+ if (paymentHash.Length != 64 || !paymentHash.All(Uri.IsHexDigit))
+ return NotFound(new LNUrlStatusResponse { Status = "ERROR", Reason = "Not found" });
+
+ paymentHash = paymentHash.ToLowerInvariant();
+
+ var cryptoCode = "BTC";
+ var pmi = PaymentTypes.LNURL.GetPaymentMethodId(cryptoCode);
+
+ // Find invoice by payment hash via AddressInvoices index
+ var invoice = await _invoiceRepository.GetInvoiceFromAddress(pmi, paymentHash);
+ if (invoice is null)
+ return NotFound(new LNUrlStatusResponse { Status = "ERROR", Reason = "Not found" });
+
+ var store = await _storeRepository.FindStore(invoice.StoreId);
+ if (store is null)
+ return NotFound(new LNUrlStatusResponse { Status = "ERROR", Reason = "Not found" });
+
+ var lnUrlPmi = GetLNUrlPaymentMethodId(cryptoCode, store, out var lnUrlMethod);
+ if (lnUrlPmi is null || !lnUrlMethod.LUD21Enabled)
+ return NotFound(new LNUrlStatusResponse { Status = "ERROR", Reason = "Not found" });
+
+ var prompt = invoice.GetPaymentPrompt(pmi);
+ if (prompt is null)
+ return NotFound(new LNUrlStatusResponse { Status = "ERROR", Reason = "Not found" });
+
+ var handler = (LNURLPayPaymentHandler)_handlers[pmi];
+ var details = handler.ParsePaymentPromptDetails(prompt.Details);
+
+ if (!string.Equals(details.PaymentHash?.ToString(), paymentHash, StringComparison.Ordinal))
+ return NotFound(new LNUrlStatusResponse { Status = "ERROR", Reason = "Not found" });
+
+ var settled = invoice.Status == InvoiceStatus.Settled ||
+ invoice.Status == InvoiceStatus.Processing;
+ var preimage = settled ? details.Preimage?.ToString() : null;
+
+ return Ok(new
+ {
+ status = "OK",
+ settled,
+ preimage,
+ pr = prompt.Destination
+ });
+ }
+
[HttpGet("pay/lnaddress/{username}")]
[EnableCors(CorsPolicies.All)]
[IgnoreAntiforgeryToken]
@@ -808,17 +865,34 @@ namespace BTCPayServer
if (updatePaymentMethod)
{
- await _invoiceRepository.UpdatePrompt(invoiceId, lightningPaymentMethod);
+ // Index payment hash for LUD-21 verify lookup via AddressInvoices,
+ // flushed atomically with the prompt update.
+ var trackedDestinations = lnurlSupportedPaymentMethod.LUD21Enabled && promptDetails.PaymentHash is not null
+ ? new[] { promptDetails.PaymentHash.ToString().ToLowerInvariant() }
+ : null;
+ await _invoiceRepository.UpdatePrompt(invoiceId, lightningPaymentMethod, trackedDestinations);
_eventAggregator.Publish(new InvoiceNewPaymentDetailsEvent(invoiceId, promptDetails, pmi));
}
- return Ok(new LNURLPayRequest.LNURLPayRequestCallbackResponse
+ var callbackResponse = JObject.FromObject(new LNURLPayRequest.LNURLPayRequestCallbackResponse
{
Disposable = true,
Routes = Array.Empty<string>(),
Pr = lightningPaymentMethod.Destination,
SuccessAction = successAction
});
+
+ // LUD-21: Add verify URL if enabled
+ if (lnurlSupportedPaymentMethod.LUD21Enabled &&
+ promptDetails.PaymentHash is not null)
+ {
+ callbackResponse["verify"] = _linkGenerator.GetUriByAction(
+ nameof(LnurlPayVerify), "UILNURL",
+ new { paymentHash = promptDetails.PaymentHash.ToString().ToLowerInvariant() },
+ Request.Scheme, Request.Host, Request.PathBase);
+ }
+
+ return Ok(callbackResponse);
}
return BadRequest(new LNUrlStatusResponse
diff --git a/BTCPayServer/Controllers/UIStoresController.LightningLike.cs b/BTCPayServer/Controllers/UIStoresController.LightningLike.cs
index 87eb77b..d1d49ab 100644
--- a/BTCPayServer/Controllers/UIStoresController.LightningLike.cs
+++ b/BTCPayServer/Controllers/UIStoresController.LightningLike.cs
@@ -185,7 +185,8 @@ public partial class UIStoresController
store.SetPaymentMethodConfig(_handlers[lnurl], new LNURLPaymentMethodConfig
{
UseBech32Scheme = true,
- LUD12Enabled = false
+ LUD12Enabled = false,
+ LUD21Enabled = true
});
await _storeRepo.UpdateStore(store);
@@ -257,6 +258,7 @@ public partial class UIStoresController
vm.LNURLEnabled = !store.GetStoreBlob().GetExcludedPaymentMethods().Match(lnurlId);
vm.LNURLBech32Mode = lnurl.UseBech32Scheme;
vm.LUD12Enabled = lnurl.LUD12Enabled;
+ vm.LUD21Enabled = lnurl.LUD21Enabled;
}
return View(vm);
@@ -300,7 +302,8 @@ public partial class UIStoresController
var lnurl = GetConfig<LNURLPaymentMethodConfig>(lnurlId, store);
if (lnurl is null || (
lnurl.UseBech32Scheme != vm.LNURLBech32Mode ||
- lnurl.LUD12Enabled != vm.LUD12Enabled))
+ lnurl.LUD12Enabled != vm.LUD12Enabled ||
+ lnurl.LUD21Enabled != vm.LUD21Enabled))
{
needUpdate = true;
}
@@ -308,7 +311,8 @@ public partial class UIStoresController
store.SetPaymentMethodConfig(_handlers[lnurlId], new LNURLPaymentMethodConfig
{
UseBech32Scheme = vm.LNURLBech32Mode,
- LUD12Enabled = vm.LUD12Enabled
+ LUD12Enabled = vm.LUD12Enabled,
+ LUD21Enabled = vm.LUD21Enabled
});
if (store.SetStoreBlob(blob))
diff --git a/BTCPayServer/Models/StoreViewModels/LightningSettingsViewModel.cs b/BTCPayServer/Models/StoreViewModels/LightningSettingsViewModel.cs
index e9701a0..9d8b3ab 100644
--- a/BTCPayServer/Models/StoreViewModels/LightningSettingsViewModel.cs
+++ b/BTCPayServer/Models/StoreViewModels/LightningSettingsViewModel.cs
@@ -26,5 +26,8 @@ namespace BTCPayServer.Models.StoreViewModels
[Display(Name = "Allow payee to pass a comment")]
public bool LUD12Enabled { get; set; }
+
+ [Display(Name = "Enable LNURL-pay verify endpoint (LUD-21)")]
+ public bool LUD21Enabled { get; set; }
}
}
diff --git a/BTCPayServer/Payments/LNURLPay/LNURLPaymentMethodConfig.cs b/BTCPayServer/Payments/LNURLPay/LNURLPaymentMethodConfig.cs
index c7ca220..375ff5c 100644
--- a/BTCPayServer/Payments/LNURLPay/LNURLPaymentMethodConfig.cs
+++ b/BTCPayServer/Payments/LNURLPay/LNURLPaymentMethodConfig.cs
@@ -11,5 +11,12 @@ namespace BTCPayServer.Payments.Lightning
[JsonProperty("lud12Enabled")]
public bool LUD12Enabled { get; set; } = true;
+ /// <summary>
+ /// LUD-21: LNURL-pay verify endpoint. Allows external services to verify
+ /// Lightning payment settlement without authentication.
+ /// </summary>
+ [JsonProperty("lud21Enabled")]
+ public bool LUD21Enabled { get; set; } = true;
+
}
}
diff --git a/BTCPayServer/Services/Invoices/InvoiceRepository.cs b/BTCPayServer/Services/Invoices/InvoiceRepository.cs
index b2432bb..5b168ba 100644
--- a/BTCPayServer/Services/Invoices/InvoiceRepository.cs
+++ b/BTCPayServer/Services/Invoices/InvoiceRepository.cs
@@ -77,6 +77,18 @@ namespace BTCPayServer.Services.Invoices
return row is null ? null : ToEntity(row);
}
+ public async Task AddAddressInvoice(string invoiceId, PaymentMethodId paymentMethodId, string address)
+ {
+ await using var context = _applicationDbContextFactory.CreateContext();
+ await UpsertAddressInvoice(context, invoiceId, paymentMethodId.ToString(), address);
+ }
+
+ private static async Task UpsertAddressInvoice(ApplicationDbContext context, string invoiceId, string paymentMethodId, string address)
+ {
+ await context.Database.ExecuteSqlInterpolatedAsync(
+ $"""INSERT INTO "AddressInvoices" ("Address", "PaymentMethodId", "InvoiceDataId") VALUES ({address}, {paymentMethodId}, {invoiceId}) ON CONFLICT ("Address", "PaymentMethodId") DO NOTHING""");
+ }
+
/// <summary>
/// Returns all invoices which either:
/// * Have the <paramref name="paymentMethodId"/> activated and are pending
@@ -330,7 +342,7 @@ retry:
}
}
}
- public async Task UpdatePrompt(string invoiceId, PaymentPrompt prompt)
+ public async Task UpdatePrompt(string invoiceId, PaymentPrompt prompt, IEnumerable<string> trackedDestinations = null)
{
retry:
using (var context = _applicationDbContextFactory.CreateContext())
@@ -346,7 +358,20 @@ retry:
return;
invoiceEntity.SetPaymentPrompt(prompt.PaymentMethodId, prompt);
invoice.SetBlob(invoiceEntity);
+ // Persist the blob update first, on its own SaveChanges.
+ // A DbUpdateConcurrencyException here must propagate so the
+ // outer catch can retry; a unique-key violation on
+ // AddressInvoices must not be able to roll this back.
await context.SaveChangesAsync();
+
+ if (trackedDestinations is not null)
+ {
+ var pmi = prompt.PaymentMethodId.ToString();
+ foreach (var tracked in trackedDestinations)
+ {
+ await UpsertAddressInvoice(context, invoiceId, pmi, tracked);
+ }
+ }
}
catch (DbUpdateConcurrencyException)
{
@@ -367,14 +392,10 @@ retry:
var existing = invoiceEntity.GetPaymentPrompt(prompt.PaymentMethodId);
if (existing.Destination != prompt.Destination && prompt.Activated && prompt.Destination is not null)
{
+ var pmi = paymentPromptContext.PaymentMethodId.ToString();
foreach (var tracked in paymentPromptContext.TrackedDestinations)
{
- await context.AddressInvoices.AddAsync(new AddressInvoiceData()
- {
- InvoiceDataId = invoiceId,
- Address = tracked,
- PaymentMethodId = paymentPromptContext.PaymentMethodId.ToString()
- });
+ await UpsertAddressInvoice(context, invoiceId, pmi, tracked);
}
AddToTextSearch(context, invoice, prompt.Destination);
}
diff --git a/BTCPayServer/Views/UIStores/LightningSettings.cshtml b/BTCPayServer/Views/UIStores/LightningSettings.cshtml
index a397135..083c646 100644
--- a/BTCPayServer/Views/UIStores/LightningSettings.cshtml
+++ b/BTCPayServer/Views/UIStores/LightningSettings.cshtml
@@ -105,6 +105,13 @@
<label asp-for="LUD12Enabled" class="form-check-label"></label>
</div>
</div>
+ <div class="form-group mb-3">
+ <div class="d-flex align-items-center">
+ <input type="checkbox" asp-for="LUD21Enabled" class="btcpay-toggle me-3" />
+ <label asp-for="LUD21Enabled" class="form-check-label"></label>
+ </div>
+ <div class="form-text" text-translate="true">Allows external services to verify Lightning payment settlement via LNURL-pay without authentication</div>
+ </div>
</div>
</div>
</div>
diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores-payment-methods.lnurl.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores-payment-methods.lnurl.json
index 54c4b05..689f6ca 100644
--- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores-payment-methods.lnurl.json
+++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores-payment-methods.lnurl.json
@@ -12,6 +12,10 @@
"lud12Enabled": {
"type": "boolean",
"description": "Allow comments to be passed on via lnurl."
+ },
+ "lud21Enabled": {
+ "type": "boolean",
+ "description": "Whether to include a [LUD-21](https://github.com/lnurl/luds/blob/luds/21.md) verify URL in LNURL-pay callback responses, enabling external services to verify payment settlement without authentication."
}
}
}
Risk score
Our methodology →Why this scored 41/100
Human-validated context
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
No validated notes yet.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.