multi: add static address loop in monitor

[GustavoStingelin]

Implements monitor support for static address loop-in swaps.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request implements support for static address loop-in swaps within the monitor system. It extends the existing swap type definitions to include a new variant, updates the RPC interface to allow clients to interact with and filter these swaps, and ensures that the internal marshalling and filtering logic correctly processes these transactions.

Highlights

• New Swap Type: Introduced 'StaticAddressLoopIn' as a new swap type across the codebase, including updates to internal types, RPC definitions, and Swagger documentation.
• RPC and Filtering Updates: Updated the gRPC client and server to support the new swap type, including the ability to filter by 'STATIC_ADDRESS_LOOP_IN' in list swap requests.
• Logic Enhancements: Updated swap marshalling and filtering logic to correctly handle the new static address loop-in swap type, including support for P2TR and P2WSH addresses.

New Features

🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[GustavoStingelin]

Looking for ConceptACK/suggestions.

Still need to test.

[gemini-code-assist]

Code Review

This pull request introduces support for a new swap type, STATIC_ADDRESS_LOOP_IN, updating the internal swap structures, marshalling logic, filtering, and RPC definitions. The feedback highlights a potential nil pointer dereference in marshallSwap when both HtlcAddressP2TR and HtlcAddressP2WSH are nil, and suggests adding a nil check for HtlcAddressP2WSH to prevent a panic.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[starius]

Concept ACK for API shape.

One implementation note. Monitor snapshots and subscribes only to s.swaps, populated from loop.Client.FetchSwaps and live statusChan updates. Static address loop-ins live under staticLoopInManager.GetAllSwaps() and (ListStaticAddressSwaps), so the current changes alone will not make loop monitor see them.

Some bridging is needed to deliver static loop-in updates into monitor's SwapStatus stream: initial snapshot plus live state updates. That also requires an explicit state mapping from static loop-in FSM states to generic SwapState, and filling the generic SwapInfo fields safely, especially HTLC address, amount, label, last hop, timestamps, and costs.

[starius]

This change seems unrelated to the loop monitor integration of static loop-ins. If we need it for completeness, I propose to do it in a separate commit or in a follow-up PR.

[GustavoStingelin]

The thing here is, how can we tell the monitor that this is a static loop in swap and that we are sending a new notification type, not the classic swap in or swap out notification?

SwapStatus is currently a flat struct returned in the rpc Monitor, and SwapType is the field that carries this information. Adding this option here was the best design I found so far.

Are you thinking about another option? How would that look?

[hieblmi]

Thanks @GustavoStingelin for putting up this draft PR!

I am looking a bit ahead of where we'd update the monitor with the static state, and it should probably be updateLoopIn which is triggered by the state machine after every fsm action. Given that this is called
frequently we should probably not do too much work for the monitor here and slow down the state
transitions.

Keeping future swap types in mind maybe it would make sense to send lightweight notifications
with minimum swap info to the monitor instance, and then let the monitor instance retrieve and assemble
the full swap info.

Maybe we could have a small monitor publisher in each existing and new swap config that does something like:

f.cfg.MonitorPublisher.Notify(MonitorRef{
      Type: MonitorStaticLoopIn,
      ID:   f.loopIn.SwapHash,
  })

What do you think @GustavoStingelin @starius ?

[GustavoStingelin]

@hieblmi

Maybe we could have a small monitor publisher in each existing and new swap config that does something like

I like the idea, but I have two questions:

1. Is this expected to be included in this PR?

2. IIUC could this create a race between the notification and the monitor full swap info assemble? For example:

state changes, notification is sent
state changes again, another notification is sent
monitor is still assembling the first notification
monitor reads the latest state, so the first event is shown with the second state
monitor then processes the second notification and shows the same state again

In that case, we could show the second state twice in the monitor and lose the first state transition from the monitor log.

[GustavoStingelin]

I am thinking that, in the future, we could have something like this:

message MonitorEvent {
  string id = 1;
  bytes id_bytes = 2;
  SwapKind kind = 3;
  int64 amount = 4;
  int64 initiation_time = 5;
  int64 last_update_time = 6;
  string label = 7;

  // Human friendly normalized lifecycle.
  MonitorPhase phase = 8;

  // Machine specific exact state.
  string state = 9;

  oneof details {
    LoopInMonitorDetails loop_in = 20;
    LoopOutMonitorDetails loop_out = 21;
    StaticLoopInMonitorDetails static_loop_in = 22;
    // Future swap types can be added here.
  }
}

Where:

kind answers, what is this?

LOOP_IN
LOOP_OUT
STATIC_LOOP_IN
future: INSTANT_OUT, ASSET_LOOP_OUT, etc.

phase answers, where is it broadly in the lifecycle?

INITIATING
WAITING_FOR_PAYMENT
WAITING_FOR_CHAIN
SWEEPING
SUCCESS
FAILED

state answers, what is the exact implementation state?

SIGN_HTLC_TX
MONITOR_INVOICE_HTLC_TX
PREIMAGE_REVEALED
etc.

The idea is to separate the high level swap category, the normalized monitor lifecycle, and the exact internal state. That should make the monitor API easier to extend without overloading one field with multiple meanings.

WDYT @hieblmi @starius?

[hieblmi]

I am thinking that, in the future, we could have something like this:

message MonitorEvent {
  string id = 1;
  bytes id_bytes = 2;
  SwapKind kind = 3;
  int64 amount = 4;
  int64 initiation_time = 5;
  int64 last_update_time = 6;
  string label = 7;

from SwapKind to label all fields should be available in the swap details below. Do we need them here?

// Human friendly normalized lifecycle.
MonitorPhase phase = 8;

// Machine specific exact state.
string state = 9;

state here too is part of the swap details.

oneof details {
LoopInMonitorDetails loop_in = 20;
LoopOutMonitorDetails loop_out = 21;
StaticLoopInMonitorDetails static_loop_in = 22;
// Future swap types can be added here.
}
}

[hieblmi]

@hieblmi

Maybe we could have a small monitor publisher in each existing and new swap config that does something like

I like the idea, but I have two questions:

1. Is this expected to be included in this PR?

I tend to not assemble info in the static address state machine and then send it to the monitor, rather just send a lightweight reference which the monitor can assemble from.

2. IIUC could this create a race between the notification and the monitor full swap info assemble? For example:

state changes, notification is sent
state changes again, another notification is sent
monitor is still assembling the first notification
monitor reads the latest state, so the first event is shown with the second state
monitor then processes the second notification and shows the same state again

In that case, we could show the second state twice in the monitor and lose the first state transition from the monitor log.

This is a good point! We might cache the swap state at that point in time to not miss anything, but that might defeat
the purpose of being performant.

I think as long as the data we are returning to the monitor is already in memory we can think about this optimization later.

[GustavoStingelin]

@hieblmi

from SwapKind to label all fields should be available in the swap details below. Do we need them here?

Cool, I totally agree.

I think doing that broader refactor in this PR would be too much, but I’m also not very happy with my current local code. It has some ugly workarounds to support both state models.

So what do you think about shifting to the new monitor approach now? Or would you prefer to take a look at my current code first and decide from there?

Also, just to confirm, since we release the client and loopd together, a breaking protobuf API change should not be a problem, right?

[starius]

@claude review

[claude]

Review

Overview: this PR wires static-address loop-in swaps into the generic Monitor gRPC stream (and loop monitor CLI output), including a new static_loop_in_state oneof field on SwapStatus, a snapshot/live-update dedup mechanism for new subscribers, and a SendUpdate callback from the loop-in FSM so status changes are pushed to Monitor subscribers as they happen. Solid feature with generally good test coverage (unit tests for the dedup race, the state mapping, the SQL store's LastUpdateTime bookkeeping, etc.), plus a bonus fix (see below). A few things worth a look before merge:

Potential issues

1. ListSwaps / SwapInfo / AbandonSwap can't see static loop-in swaps (loopd/swapclient_server.go). processStatusUpdates now explicitly skips caching TypeStaticAddressLoopIn updates into s.swaps (confirmed intentional by TestStaticAddressLoopInStatusUpdateDoesNotEnterGenericSwapCache). Since ListSwaps, SwapInfo, and AbandonSwap all read exclusively from s.swaps, a static loop-in swap that now shows up in loop monitor will be invisible to loop listswaps/SwapInfo and can't be abandoned via AbandonSwap (it'll just 404 with "swap with hash ... not found"). That may be intentional scope-limiting (there's already a dedicated ListStaticAddressSwaps RPC), but it's a bit of a surprising asymmetry for API consumers — worth confirming this is the desired UX, or at least calling it out in the PR description/docs.

2. Duplicated "should we show cost" predicate (cmd/loop/main.go, logSwap). The loopState != INITIATED && != HTLC_PUBLISHED && != PREIMAGE_REVEALED check is now written out twice — once inside the STATIC_LOOP_IN / UNKNOWN_STATIC_ADDRESS_SWAP_STATE case, and once in the else branch for non-static swaps. Worth extracting into a small isCostFinal(state looprpc.SwapState) bool helper to avoid the two copies drifting.

3. Test gap around showCost for static loop-ins. TestLogSwapDisplaysStaticLoopInTypeAndStage only asserts the state label/P2TR text; it doesn't assert that (cost: ...) is suppressed for the "in-flight" static states (INIT_HTLC, SIGN_HTLC_TX, etc.) or shown for terminal ones (SUCCEEDED, FAILED_STATIC_ADDRESS_SWAP, ...). Given the new switch in logSwap is the only piece of new logic there, a couple of require.Contains/require.NotContains checks on "(cost:" for a suppressed vs. shown state would close the gap.

4. GetAllSwaps fetches the full static loop-in history on every new Monitor subscription (staticaddr/loopin/manager.go GetAllSwaps → GetStaticAddressLoopInSwapsByStates(ctx, AllStates), called from appendStaticAddressLoopInMonitorSnapshot). This is a full-table read (not filtered to pending/recent) on every loop monitor connect/reconnect. Probably fine at current scale and consistent with how s.swaps is already loaded wholesale at startup, but worth keeping in mind if static loop-in volume grows.

Nice catches / good practices

• SwapInfo now takes s.swapsLock before reading s.swaps (loopd/swapclient_server.go) — this looks like a pre-existing unlocked read that got fixed incidentally here.
• The snapshot/live-update duplicate-suppression logic (staticAddressLoopInMonitorHighWater / isInitialStaticAddressLoopInStale) correctly handles the race where a subscriber is registered before the DB snapshot for static swaps is fetched, and it's directly tested (TestMonitorSuppressesStaticAddressLoopInSnapshotLiveDuplicate) rather than just asserted by inspection — good defensive test for a genuinely subtle race.
• sendUpdate in staticaddr/loopin/fsm.go/actions.go only logs (doesn't fail the FSM transition) if the notify fails, which is the right call since the state is already durably persisted by that point (covered by TestInitHtlcActionIgnoresSendUpdateErrorAfterPersistence).

Minor

• swap/type.go: IsOut()'s doc comment was trimmed to just describe the "Out" case; consider also updating it to note it returns false for both TypeIn and TypeStaticAddressLoopIn, since a caller might reasonably (but incorrectly) treat !IsOut() as "is a regular loop-in" — not a bug today since static loop-ins never reach s.swaps, but a latent trap if that changes later.

Nothing here looks blocking — mostly scoping/consistency questions and small test/DRY nits. Nice work on the race-condition handling for the snapshot/live-update overlap.

[starius]

Great progress! 🚀

I found a couple of weak points in this PR, also we need to sync with @hieblmi about a couple of changes (see below).

Could you also go through Claude's feedback and address the real issues, please?

[starius]

HTLC address is not the same as staticAddress. These are two different addresses and it is very important to separate them. We got issues previously when people sent funds to HTLC addresses by mistake.

HTLC address also exists and is a property of a static loop-in (as well as of other swap types). It should be loaded/computed and put here.

Static address is a long-living address which is reused by (potentially) many deposits and many static loop-ins. Probably we need a new field to pass it here. The new field for the static address will only be filled if the swap is a static loop-in.

[hieblmi]

Imo we shouldn't show the htlc address in the static world as this is a backup transaction by the server that is rarely ever shown as we try to avoid publishing it and instead sweep directly.

If we still think this is useful information we could recreate like it is done in loopin.go:

func (l *StaticAddressLoopIn) getHtlc(chainParams *chaincfg.Params)

[GustavoStingelin]

We are no longer putting the reusable static address into the HTLC field. Now, we only set HtlcAddressP2WSH to the actual HTLC address.

@hieblmi Yeah, if it is not needed, I agree that we should remove it and simplify this even further. However, I would also prefer not to expose HtlcAddressP2WSH here if it should not be populated. That would bring us back to the broader monitor refactor, though.

If you all agree that it should be left empty for now, I can change it. Otherwise, we can open a follow up issue for a broader refactor. It is up to you.

[starius]

I think loopdb.StateFailAbandoned is a wrong state for Failed and SucceededTransitioningFailed.

@hieblmi What do you think?

[hieblmi]

Technically not correct as abandoned is reserved in the old loop world for manual swap abandonment, if a swap is borked e.g., similar to how lnd allows abandoning channels.

@GustavoStingelin do we need the mapping of the static states into the old states?
I think we can just rely on the static swap state and leave the old state empty? So just use

	StaticAddressLoopInState: swp.GetState(),

[GustavoStingelin]

changed to not map like that, now all use the default enum zero value (StateInitiatedfor old school loop) when it is static

[starius]

I would maybe add/keep a comment saying this mirrors ListStaticAddressSwaps: only actual persisted client-visible server cost is reported; onchain/offchain remain zero until static loop-ins persist real fee data.

[starius]

Claude raised an interesting point. We do now have an inconsistency of loop monitor and loop listswaps / loop swapinfo.

Users might see a swap hash in loop monitor and try to check its information in loop listswaps or loop swapinfo and be confused that the swap is missing (because it is a static loop-in).

I propose to add a note on CLI side to loop listswaps output and its docs that it covers only traditional loop-ins and loop-outs, not static loop-ins. We have command loop static listswaps which should be used instead - tell this in the message.

For loop swapinfo <swap> we don't have a direct replacement in the static world. @hieblmi would it make sense to extend loop swapinfo <swap> so it works for static loop-ins as well? Or is it better to add loop static swapinfo <swap> command and in loop swapinfo tell the user to use the new command instead if we detect that the hash is of a static loop-in?

[hieblmi]

For loop swapinfo <swap> we don't have a direct replacement in the static world. @hieblmi would it make sense to extend loop swapinfo <swap> so it works for static loop-ins as well? Or is it better to add loop static swapinfo <swap> command and in loop swapinfo tell the user to use the new command instead if we detect that the hash is of a static loop-in?

I think we should either add loop static swapinfo <swap> or extend existing loop static listswaps with a --swap_hash param. In the future the goal is to get rid of loop swapinfo respectively replace it with loop static [swapinfo|listswaps]

[GustavoStingelin]

added the CLI observation, I guess we can create some good follow-up issues from this PR, right?

[hieblmi]

Thanks for the changes so far @GustavoStingelin 🚀 I've left some comments.

Overall I wonder if we could simplify the monitoring approach without having to modify all too much of the existing flows and also be extensible when future swap types need to be monitored.

What about if we seed a staticSwaps map[lntypes.Hash]loop.SwapInfo once from the database during daemon startup, then update it in processStatusUpdates. Monitor could register and snapshot both legacy and static maps under the same lock.

That would eliminate:

• Full database reads on every monitor connection.
• Snapshot/live timestamp deduplication.
• Most of the race-specific logic.
• The need to put static swaps into the legacy s.swaps map or expose them through
  ListSwaps.

[hieblmi]

Here comes back my initial performance concern, since we don't want to slow further down the state transitions of the state machine.

We should add godocs pointing out that sendUpdate is not supposed to do heavy lifting. If the updates become to heavy(like calculating htlc address from given parameters or something else) we could queue the monitor updates. But for now lgtm.

[GustavoStingelin]

added godocs in the sendUpdate function definition

[hieblmi]

Just tested the current set of changes in regtest by submitting a static and legacy swap, looks good:

loop --network=regtest monitor               ✔  20:14:42 
Note: offchain cost may report as 0 after loopd restart during swap
2026-07-14T20:15:12+02:00 STATIC_LOOP_IN INIT_HTLC 0.00250000 BTC - P2TR: bcrt1phnvwg3wg70e4asnn5wty05v57vcd6xvrk8cek98muw0etzkgvw3q6xmxm5
2026-07-14T20:15:12+02:00 STATIC_LOOP_IN SIGN_HTLC_TX 0.00250000 BTC - P2TR: bcrt1phnvwg3wg70e4asnn5wty05v57vcd6xvrk8cek98muw0etzkgvw3q6xmxm5
2026-07-14T20:15:13+02:00 STATIC_LOOP_IN MONITOR_INVOICE_HTLC_TX 0.00250000 BTC - P2TR: bcrt1phnvwg3wg70e4asnn5wty05v57vcd6xvrk8cek98muw0etzkgvw3q6xmxm5
2026-07-14T20:15:13+02:00 STATIC_LOOP_IN PAYMENT_RECEIVED 0.00250000 BTC - P2TR: bcrt1phnvwg3wg70e4asnn5wty05v57vcd6xvrk8cek98muw0etzkgvw3q6xmxm5 (cost: server 1825, onchain 0, offchain 0)
2026-07-14T20:15:13+02:00 STATIC_LOOP_IN SUCCEEDED 0.00250000 BTC - P2TR: bcrt1phnvwg3wg70e4asnn5wty05v57vcd6xvrk8cek98muw0etzkgvw3q6xmxm5 (cost: server 1825, onchain 0, offchain 0)
2026-07-14T20:15:42+02:00 LOOP_IN INITIATED 0.00250000 BTC - P2TR: bcrt1p0u95wwwnxd00w4qyj6yaf2latsnsnmfg2lxsckpqqpunu5fgfk7smlgpgq
2026-07-14T20:15:42+02:00 LOOP_IN HTLC_PUBLISHED 0.00250000 BTC - P2TR: bcrt1p0u95wwwnxd00w4qyj6yaf2latsnsnmfg2lxsckpqqpunu5fgfk7smlgpgq
2026-07-14T20:16:00+02:00 LOOP_IN INVOICE_SETTLED 0.00250000 BTC - P2TR: bcrt1p0u95wwwnxd00w4qyj6yaf2latsnsnmfg2lxsckpqqpunu5fgfk7smlgpgq (cost: server 0, onchain 3850, offchain 0)

Noticed that the on-chain fee of a static swap is currently 0 but should be the sum of the deposit fees of a swap. Opened an issue for it #1174

[GustavoStingelin]

The other RPC call changes are deferred for a future follow-up issue/pr.

[GustavoStingelin]

@starius @hieblmi Thanks for the reviews! All comments addressed.