Repository navigation
liquidity: dry run, budget check and client swap limits for easy autoloop - #1301
Draft
keyancassis wants to merge 8 commits into
Draft
keyancassis wants to merge 8 commits into
keyancassis wants to merge 8 commits into
Conversation
Easy autoloop decided what to swap and dispatched the swap in one function, so nothing else could ask what it would do. Move the decision into planEasyAutoloopSwap, which returns the loop out to make or the reason that no swap is made, and leave only the dispatch in dispatchBestEasyAutoloopSwap. The swaps that are dispatched and the errors that are logged stay the same. Two reasons are added for outcomes that had none: the amount over the target is below the minimum swap size, and no channel is eligible.
Easy autoloop works towards one target for the whole node, so the reason that it is not swapping does not belong to a channel or a peer and cannot be reported in the disqualified list. Add the easy_autoloop_reason field to SuggestSwapsResponse for it, along with the two reasons that only easy autoloop has: the amount to swap is below the minimum swap size, and no channel is eligible. The recorded suggestswaps sessions are updated, since the command now prints the new field.
SuggestSwaps only looked at peer and channel rules. With easy autoloop enabled the rules are not used, so the call described swaps that would never be made, and it failed when no rules were set. Return what easy autoloop would do instead when it is enabled: the loop out that it would make next, or the reason that it would not make one. The swap is built as a dry run, so no wallet address is derived for it. This lets a client show why easy autoloop is waiting without repeating its checks. The rule based autoloop asks the planner without the easy autoloop branch, so the dry run swap is never dispatched, even when easy autoloop is enabled after the autoloop tick chose the rule based path.
Easy autoloop only used the server's swap size limits, and ignored the minimum and maximum swap amounts set by the client. A node with a large balance had no way to ask for fewer, larger swaps. Use the same restrictions as the rule based planner, which narrows the server's limits by the client's. With a client minimum above the server's, easy autoloop waits until the balance is at least that far over the target.
Easy autoloop only checked that some of the fee budget was left before it dispatched a swap. A swap that could cost more than the remaining budget was still dispatched, so a single swap could take the node over its budget. Compare what the swap could cost with what is left of the budget, and wait when it does not fit. The cost leaves out the large multiplier on the miner fee, as the fee limit check does, so that an edge-case miner fee does not keep a small budget from ever being used. When the budget check fails because the worst-case fees held for swaps in flight fill a budget that is not spent yet, report budget insufficient rather than elapsed, since there may be room again once those swaps finish. Only the reported reason changes, as no swap is dispatched either way.
Easy autoloop skips a channel when it is inactive or its peer is excluded, besides the reasons that the rule based planner already reports. Add the two reasons, so that SuggestSwaps can list each channel that easy autoloop skipped in disqualified, along with why.
With no eligible channel, the dry run only said that every channel was inactive, excluded, used by another swap, backing off after a failed swap, or below the minimum swap size. A client could not tell which of these held, although each calls for something different, such as including a peer again or waiting until a failed swap's backoff ends. The channel picker now returns the reason that it skipped each channel it checked, and SuggestSwaps lists them in disqualified. They are listed when a swap is suggested too, so a client can see that the channel holding the most was skipped and why. The picker no longer returns an error, since it never had one to return.
Document that easy autoloop respects the client's swap size limits and the remaining fee budget, and that loop suggestswaps shows what it would do next. Add release notes for the three changes.
keyancassis
force-pushed
the
easy-autoloop-dry-run
branch
from
November 17, 2026 19:54
89a9d5b to
7f24994
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Test fixtures use promoted fields as composite-literal keys instead of initializing the embedded structs explicitly, preventing the liquidity tests from compiling.
2 open issues
2 files not reviewed
looprpc/client.pb.go: Generated filelooprpc/client_grpc.pb.go: Generated file
What changed in this PR
Adds a dry run for Bitcoin easy autoloop through SuggestSwaps, allowing clients to explain its next action without duplicating liquidity-manager logic.
Changes:
- Separates planning from dispatch and reports node-level waiting reasons and skipped channels.
- Applies client swap-size limits and checks remaining fee budget, excluding the edge-case miner-fee allowance.
- Adds planner tests, updates RPC definitions and recorded CLI responses, and documents the behavior changes.
| File | Description |
|---|---|
looprpc/client.swagger.json |
Exposes new reasons and response field in REST documentation. |
looprpc/client.proto |
Defines easy-autoloop reasons and response field. |
looprpc/client.pb.go |
Updates generated protobuf types and descriptors. |
looprpc/client_grpc.pb.go |
Updates generated service comments for dry-run behavior. |
loopd/swapclient_server.go |
Maps planner reasons into RPC responses. |
liquidity/reasons.go |
Adds internal reasons and their text representations. |
liquidity/liquidity.go |
Separates planning from dispatch and applies budget and size checks. |
liquidity/easy_autoloop_plan_test.go |
Adds dry-run, channel-selection, limit, and budget test cases. |
docs/release-notes/release-notes-next.md |
Records new functionality and behavior changes. |
docs/autoloop.md |
Explains dry runs, limits, and waiting reasons. |
cmd/loop/testdata/sessions/static-autoloop/03_loop-suggestswaps-static-loop-in.json |
Adds the response field to the static-autoloop recording. |
cmd/loop/testdata/sessions/liquidity/09_loop-suggestswaps-success.json |
Adds the response field to the liquidity recording. |
Review effort: Balanced
Comment on lines
+49
to
+51
| Label: labels.AutoloopLabel(swap.TypeOut), | ||
| InitiationTime: testBudgetStart, | ||
| MaxMinerFee: 1000, |
Comment on lines
+59
to
+73
| Events: []*loopdb.LoopEvent{{ | ||
| Cost: loopdb.SwapCost{Server: 1000}, | ||
| State: loopdb.StateSuccess, | ||
| Time: testTime, | ||
| }}, | ||
| Contract: autoOutContract, | ||
| } | ||
|
|
||
| // chan1Failed is a swap over the first channel that failed to | ||
| // pay within the failure backoff. | ||
| chan1Failed = &loopdb.LoopOut{ | ||
| Events: []*loopdb.LoopEvent{{ | ||
| State: loopdb.StateFailOffchainPayments, | ||
| Time: testTime, | ||
| }}, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Easy autoloop has no way to report what it would do next. A client that wants to explain why autoloop is waiting has to repeat its internal logic:
Terminal does this today for its node-level autoloop settings. This PR adds a dry run. It also closes two gaps where easy autoloop behaves differently from the rule-based planner.
Dry run through
SuggestSwapsSuggestSwapsonly looks at peer and channel rules, which easy autoloop ignores. With easy autoloop on and no rules set, the call fails withErrNoRules. With rules left over, it describes swaps that easy autoloop will never make.The decision is now split from the dispatch:
planEasyAutoloopSwapreturns the Loop Out to make, or the reason that none is made.dispatchBestEasyAutoloopSwaponly dispatches. With easy autoloop on,SuggestSwapsreturns that Loop Out, built as a dry run so that no wallet address is derived. If no swap would be made, the reason goes in a neweasy_autoloop_reasonfield onSuggestSwapsResponse. A reason for the whole node doesn't fit the per-channeldisqualifiedlist, hence the separate field.Two reasons are added for outcomes that had none:
AUTO_REASON_BELOW_MINIMUM: the amount over the target is below the minimum swap size.AUTO_REASON_NO_ELIGIBLE_CHANNEL: no channel is eligible.The response also lists, in
disqualified, each channel that easy autoloop skipped and why. That covers the channels before the one it would swap from, or each channel it checked when it would not swap. Without this, "no eligible channel" can't tell a client which situation it is in, though each needs something different from the user:AUTO_REASON_PEER_EXCLUDED, new);AUTO_REASON_CHANNEL_INACTIVE, new);AUTO_REASON_FAILURE_BACKOFF);AUTO_REASON_LOOP_OUT);AUTO_REASON_BELOW_MINIMUM).The autoloop tick dispatches the same swaps and logs the same errors as before. The rule-based tick asks the planner without the easy autoloop branch, so the dry run swap is never dispatched, even when easy autoloop is enabled after the tick has chosen the rule-based path.
All of this applies to easy autoloop for bitcoin. Easy autoloop for assets is unchanged and isn't part of the dry run.
Keep each easy autoloop swap within the fee budget
Easy autoloop only checked that some budget was left, so one swap could take the node over its budget. The rule-based planner already compares each swap's fees with what is left (
fees <= available) and marks the restReasonBudgetInsufficient. Easy autoloop now does the same, and waits when the swap doesn't fit.The cost leaves out the 50× miner fee multiplier, as the fee limit check does, so that a small budget is not kept from ever being used. A swap that meets such a miner fee can still go over the budget. The rule-based planner counts the full
MaxMinerFee. Happy to match it instead if that's preferred. Swaps in flight are still held at their full worst case.When the budget check fails, the dry run now separates two cases:
AUTO_REASON_BUDGET_ELAPSED. Autoloop waits for the budget to start over.AUTO_REASON_BUDGET_INSUFFICIENT, the reason the rule-based planner already uses for budget that is allocated to other swaps. Once those swaps finish, only what they actually paid counts, so there may be room again before the budget starts over.Respect the client's swap size limits
Easy autoloop sized swaps with the server's limits only, so
loop setparams --minamt/--maxamthad no effect on it. It now usesgetSwapRestrictions, like the rule-based planner. With a client minimum above the server's, it waits until the balance is at least that far over the target, which gives a large node fewer, larger swaps. As with the rules, easy autoloop now stops with an error while the client's limits are outside the server's. This is listed under Breaking Changes in the release notes.Testing
liquidity/easy_autoloop_plan_test.gocover the plan, the reasons, the dry run, the skipped channels, the client limits and the budget check. They also check that the rule-based path never gets the dry run swap.go test ./liquidity/... ./loopd/... ./cmd/loop/...passes on every commit.golangci-lintreports no new issues.suggestswapssessions are updated for the new field.Pull Request Checklist
docs/release-notes/release-notes-next.md, or apply theno-changeloglabel (required by CI)