loopin: Route invoices over asset channels by sputn1ck · Pull Request #1212 · lightninglabs/loop

sputn1ck · 2026-08-26T12:54:39Z

Summary

add asset-channel Loop In invoices via tapd, with a required asset ID,
explicit edge node, and per-swap minimum output in indivisible asset units
enforce that minimum in the RFQ request, verify the accepted output, and
return/display the quoted amount; display the minimum before confirmation
use the same accepted RFQ route hint for the swap and probe invoices,
and use the selected edge for preflight and server fee quotes
require a quote covering the full 30-day invoice lifetime before funding;
reject short-lived quotes instead of risking expiry during confirmations
validate CLI inputs before quote/swap RPCs and update generated RPC/CLI docs

Asset invoices remain BTC/msat-denominated BOLT 11 invoices. The accepted
edge RFQ converts that amount into asset units. The edge's price oracle must
support the requested lifetime; the built-in one-hour mock oracle is not
sufficient for this flow.

Testing

GOWORK=off go test ./...
GOWORK=off make lint workers=4
GOWORK=off make rpc
GOWORK=off make docs-check
GOWORK=off make commitmsg-lint range="HEAD^..HEAD"
hybrid-network integration: short-quote and minimum-output rejection,
canceled probe HTLC using the swap RFQ, successful client/server completion,
and exact asset units in the selected channel and settled invoice HTLCs

Pull Request Checklist

Added an entry to docs/release-notes/release-notes-next.md

Copilot

Pull request overview

This PR extends Loop In to support routing swap/probe invoices over Taproot Asset channels by exposing asset routing parameters on the Loop In RPC/CLI and creating the invoices via tapd, pinned to the negotiated asset edge peer.

Changes:

Add asset_info (asset ID + optional asset edge node) to Loop In RPC/Swagger/CLI, and validate incompatible routing options.
Update Loop In swap initiation to create both swap and probe invoices through tapd when asset_info is set, pinning server payment/probe to the negotiated edge peer.
Add test coverage for asset invoice creation, peer pinning, and request validation; update session fixtures and release notes.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`server_mock_test.go`	Extend mock server to capture Loop In last-hop and initiator passed during swap creation.
`looprpc/client.swagger.json`	Document new Loop In `asset_info` fields in the REST/Swagger surface.
`looprpc/client.proto`	Add `AssetLoopInRequest` and `LoopInRequest.asset_info` to the public RPC API.
`looprpc/client.pb.go`	Regenerated protobuf bindings to include the new Loop In `asset_info` message/field.
`loopin.go`	Implement asset-aware Loop In flow: validate options and create swap/probe invoices via `tapd`.
`loopin_test.go`	Add tests verifying tapd invoice creation, peer pinning, and request validation for asset Loop Ins.
`loopd/swapclient_server.go`	Parse/validate `asset_info` on the daemon RPC boundary and map into internal `LoopInRequest`.
`interface.go`	Extend internal `LoopInRequest` with `AssetId` and `AssetEdgeNode`.
`docs/release-notes/release-notes-next.md`	Add release note entry for Taproot Asset channel invoice routing in Loop In.
`cmd/loop/testdata/sessions/loopin/06_loop-in-external-force.json`	Update CLI golden session output to include `asset_info`.
`cmd/loop/testdata/sessions/basic-swaps/02_loop-in.json`	Update CLI golden session output to include `asset_info`.
`cmd/loop/loopin.go`	Add CLI flags for asset loop-ins and plumb `asset_info` into the Loop In RPC request.
`client.go`	Improve logging/validation around asset loop-in usage in the client entrypoint.
`assets/client.go`	Add `TapdClient.AddAssetInvoice` helper to create (hold) invoices via tapd asset channels.
`assets/client_test.go`	Add tests for `AddAssetInvoice` covering hold vs regular invoice and incomplete responses.

Files not reviewed (1)

looprpc/client.pb.go: Generated file

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

sputn1ck · 2026-09-07T10:12:10Z

+		assetID, err := hex.DecodeString(cmd.String("asset_id"))
+		if err != nil {
+			return fmt.Errorf("invalid asset id: %w", err)
+		}
+
+		var assetEdgeNode []byte
+		if cmd.IsSet("asset_edge_node") {
+			assetEdgeNode, err = hex.DecodeString(
+				cmd.String("asset_edge_node"),
+			)
+			if err != nil {
+				return fmt.Errorf("invalid asset edge node: %w", err)
+			}
+		}


Addressed in 3caa4bf: the CLI validates the decoded 32-byte asset ID and 33-byte compressed edge public key before quote/swap RPCs. TestAssetLoopInCLI covers malformed/short IDs, missing/short edges, missing minimum output, conflicting last hops, and the edge passed to the quote.

sputn1ck · 2026-08-26T13:14:42Z

/gateway review

lightninglabs-gateway · 2026-08-26T13:15:04Z

👀 gateway review starting…

sputn1ck · 2026-08-26T18:44:57Z

/gateway review

hieblmi · 2026-09-01T14:45:46Z

+    The optional node identity public key of the asset channel peer to use for
+    RFQ negotiation. If omitted, tapd selects from the eligible asset channels.
+    */
+    bytes asset_edge_node = 2;


[P1] Require a minimum asset output: The request specifies only an asset ID and optional peer. It provides no minimum asset amount or rate floor, even though the edge quote determines how many asset units the client receives for its on-chain BTC. The quote is negotiated only after CLI confirmation and is never returned, displayed, or persisted. The daemon-wide tapd price-deviation check is not per-swap user consent. Add a quote phase or fields such as minimum_asset_amount or rate_limit, show the resulting asset amount, and enforce the limit in AddInvoiceRequest before committing the swap.

Addressed in 3caa4bf with a mandatory per-swap min_asset_amount (indivisible units). The CLI displays the minimum before confirmation; AddAssetInvoice converts it into an upward-rounded AssetRateLimit before requesting the RFQ and independently checks the accepted output before swap admission/funding. SwapResponse.asset_amount returns the accepted output and the CLI displays it. Unit tests cover an accepted exact minimum and rejection below it; the hybrid integration test also rejects an above-market minimum before any HTLC funding.

hieblmi · 2026-09-01T14:45:52Z

-		return nil, err
+	var probeInvoice string
+	if assetLoopIn {
+		assetProbe, err := cfg.assets.AddAssetInvoice(


[P1] Probe the exact RFQ used by the swap: This second AddAssetInvoice call negotiates a new RFQ. Checking only that its peer matches is insufficient: the probe and swap invoices have different RFQ IDs, virtual SCIDs, rates, limits, and policies. A probe can therefore succeed with a smaller asset requirement or different final-hop fee while the actual swap quote fails after the BTC HTLC is funded. Create the probe and swap invoices from the same accepted RFQ-backed route hint, or otherwise verify and reserve the exact rate, SCID, and capacity used by the swap invoice.

Addressed in 3caa4bf: there is now one tapd AddInvoice/RFQ negotiation. The returned BOLT 11 hint is checked against the accepted peer and virtual SCID, then reused unchanged in lnd AddHoldInvoice for the probe, with the same msat amount. The unit test compares the hints and asserts only one tapd call. The integration test observes a canceled probe HTLC on the selected physical channel, compares probe/swap RFQ hints, and subsequently settles the swap using that RFQ.

hieblmi · 2026-09-01T14:45:58Z

+
+		// Pin the probe and the server payment to the same edge node as
+		// the swap invoice.
+		request.LastHop = &quotePeer


[P1] Do not treat the tapd reference quote as edge selection: When no edge is supplied, tapd negotiates with multiple peers and returns its most-expensive quote as the reference quote while putting multiple RFQ hints in the invoice. That response is not a selected route, but this code treats its peer as one and pins the server to it, forcing the worst-priced edge and disabling the other hints. The server fee quote was also calculated earlier with LastHop unset, so its invoice amount may not match this route fee. Require an explicit edge for now, or add a pre-swap selection phase that chooses an approved quote before calculating server fees.

Addressed in 3caa4bf by requiring an explicit asset_edge_node. The client sets LastHop before its server fee quote and requires exactly one RFQ hint matching the requested peer and accepted virtual SCID. The multi-peer reference quote is no longer treated as route selection.

hieblmi · 2026-09-01T14:46:04Z

+// assetLoopInInvoiceExpiry is the invoice lifetime an asset edge must cover
+// with its RFQ quote. If an on-chain funding transaction does not confirm in
+// this window, the swap fails safely and the client can reclaim the HTLC.
+const assetLoopInInvoiceExpiry = int64(60 * 60)


[P1] Invoice lifetime is shorter than the payment lifecycle: The asset invoice and RFQ expire after one hour, but the server normally waits 3-6 confirmations and retries failed payments only after one hour. Normal block variance alone makes expiration likely, particularly for six-confirmation swaps. Once funded, failure can send the client to the default 1000-block refund path. The RFQ must cover confirmation and retry time, or RFQ and invoice creation must be deferred until the HTLC is sufficiently confirmed.

Addressed in 3caa4bf: the asset invoice now requests a 30-day lifetime, and the client verifies that both the invoice and accepted quote cover that lifetime before swap admission/funding. This adds substantial confirmation/retry margin over the current maximum accepted 1500-block HTLC delta; an edge that cannot offer that lifetime is rejected rather than funding a one-hour quote. The built-in one-hour mock oracle therefore cannot serve this flow. Unit and hybrid-network tests cover short-lived quote rejection, and the hybrid test uses a controllable long-lived oracle for the successful swap.

hieblmi · 2026-09-01T14:46:26Z

+
+		assetInfo = &looprpc.AssetLoopInRequest{
+			AssetId:       assetID,
+			AssetEdgeNode: assetEdgeNode,


[P2] Quote the explicit asset edge in the CLI: asset_edge_node is placed in AssetInfo here, but the preflight quote below uses only the separate last_hop flag. The CLI therefore displays and uses a fee cap for a different route, while Loop internally re-quotes with the asset edge and may fail with ErrSwapFeeTooHigh. Make asset_edge_node the effective LoopInLastHop and reject conflicting values.

Addressed in 3caa4bf: asset_edge_node becomes the effective LoopInLastHop for the CLI preflight quote and swap request, and conflicting last_hop values fail before either RPC. TestAssetLoopInCLI verifies both the conflict rejection and the exact peer passed to GetLoopInQuote.

sputn1ck · 2026-09-07T10:18:57Z

/gateway review

Wrap tapd's asset-aware invoice RPC so Loop In can create regular and hold invoices payable through a selected asset channel.

Create Loop In swap and probe invoices through tapd, pin both invoices to the negotiated asset edge, and pass that edge to the server as the final hop.

Let RPC and CLI callers select an asset and optional channel peer for Loop In while preserving the existing BTC invoice behavior by default.

Record the new Taproot Asset invoice path in the next Loop release notes.

Include the new asset Loop In flags in the generated man page and Markdown command reference.

Require an explicit edge and minimum asset output before accepting an asset Loop In. Apply the output floor to the RFQ and report the accepted amount to the caller. Reuse the same RFQ route hint for the probe and require quote validity for the full 30-day swap invoice lifetime. Validate CLI inputs before quoting and use the selected edge for both fee quotes and swap initiation. Cover the limits and shared probe hint with unit tests and regenerate RPC and CLI documentation.

Copilot AI lite review requested due to automatic review settings August 26, 2026 12:54

Copilot started reviewing on behalf of sputn1ck August 26, 2026 12:55 View session

Copilot AI reviewed Aug 26, 2026

View reviewed changes

hieblmi self-requested a review September 1, 2026 13:29

hieblmi reviewed Sep 1, 2026

View reviewed changes

levmi assigned sputn1ck Sep 3, 2026

sputn1ck requested a review from hieblmi September 7, 2026 10:18

sputn1ck added 6 commits September 7, 2026 12:19

assets: Add asset invoice creation

41df4a7

Wrap tapd's asset-aware invoice RPC so Loop In can create regular and hold invoices payable through a selected asset channel.

loopin: Route invoices over asset channels

7cdf2c3

Create Loop In swap and probe invoices through tapd, pin both invoices to the negotiated asset edge, and pass that edge to the server as the final hop.

looprpc: Expose asset Loop In options

9e8127e

Let RPC and CLI callers select an asset and optional channel peer for Loop In while preserving the existing BTC invoice behavior by default.

docs: Note asset Loop In support

9502196

Record the new Taproot Asset invoice path in the next Loop release notes.

docs: Regenerate CLI reference

fb00871

Include the new asset Loop In flags in the generated man page and Markdown command reference.

sputn1ck force-pushed the kon/asset-loop-in-invoices branch from 3caa4bf to 62b84e2 Compare September 7, 2026 10:22

Uh oh!

Conversation

sputn1ck commented Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Pull Request Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sputn1ck commented Aug 26, 2026

Uh oh!

lightninglabs-gateway Bot commented Aug 26, 2026

Uh oh!

sputn1ck commented Aug 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sputn1ck commented Sep 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sputn1ck commented Aug 26, 2026 •

edited

Loading