Skip to content

loopd: support more HTLC recovery modes, stateless and cooperative - #1203

Open
starius wants to merge 2 commits into
lightninglabs:masterfrom
starius:stateless-sweephtlc
Open

loopd: support more HTLC recovery modes, stateless and cooperative#1203
starius wants to merge 2 commits into
lightninglabs:masterfrom
starius:stateless-sweephtlc

Conversation

@starius

@starius starius commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

Allow sweephtlc to reconstruct protocol-11 Loop Out HTLCs when the local swap record is unavailable but the public swap data and preimage can be recovered.

Prefer signing by public key and use a bounded family-99 key scan only when direct signing fails or produces an invalid witness.

Also add cooperative sweep as an option applicable in both stateful and stateless modes. In stateless mode it also requires providing payment address.

So now we have a matrix.

State Spend LND key path Mode note
Stateful Unilateral Stored locator Loads the preimage, contract, and locator from Loop DB; spends the Taproot script success path.
Stateful Cooperative Stored locator Loads the contract, locator, and invoice payment-address proof from Loop DB; uses the MuSig2 Taproot key path without revealing the preimage to the server.
Stateless Unilateral Public key Reconstructs the contract without Loop DB and asks LND to sign directly with client_pubkey; no key scan occurs.
Stateless Unilateral Scan fallback Reconstructs the contract without Loop DB; an unknown public-key signing result must fail local witness verification, then family-99 scanning recovers the locator.
Stateless Cooperative Locator scan Reconstructs the contract without Loop DB, scans family 99 for the locator required by LND's MuSig2 API, and supplies the invoice payment_addr as server ownership proof.

I tested all the modes locally.

Pull Request Checklist

  • Add an entry to docs/release-notes/release-notes-next.md, or apply the
    no-changelog label (required by CI)

Allow sweephtlc to reconstruct protocol-11 Loop Out HTLCs when the
local swap record is unavailable but the public swap data and preimage
can be recovered.

Prefer signing by public key and use a bounded family-99 key scan only
when direct signing fails or produces an invalid witness.
@starius
starius marked this pull request as ready for review August 21, 2026 17:14

@bhandras bhandras left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 🎉

Allow sweephtlc to request the existing server MuSig2 signing flow so an
original Taproot Loop Out HTLC can be recovered without revealing its
preimage. Stateful recovery obtains ownership proof from the stored
invoice, while stateless recovery accepts it with the public swap data.

Keep publishing opt-in and verify the combined signature and completed
witness before returning the transaction.
@starius starius changed the title loopd: support stateless HTLC recovery loopd: support more HTLC recovery modes, stateless and cooperative Aug 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants