Skip to content

liquidity: dry run, budget check and client swap limits for easy autoloop - #1301

Draft
keyancassis wants to merge 8 commits into
lightninglabs:masterfrom
keyancassis:easy-autoloop-dry-run
Draft

keyancassis wants to merge 8 commits into
lightninglabs:masterfrom
keyancassis:easy-autoloop-dry-run

Conversation

@keyancassis

@keyancassis keyancassis commented Nov 17, 2026 •

Copy link
Copy Markdown

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:

  • channel order;
  • the fee limit check;
  • the fees held for swaps in flight;
  • channel backoff;
  • the order of the checks.

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 SuggestSwaps

SuggestSwaps only looks at peer and channel rules, which easy autoloop ignores. With easy autoloop on and no rules set, the call fails with ErrNoRules. With rules left over, it describes swaps that easy autoloop will never make.

The decision is now split from the dispatch: planEasyAutoloopSwap returns the Loop Out to make, or the reason that none is made. dispatchBestEasyAutoloopSwap only dispatches. With easy autoloop on, SuggestSwaps returns 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 new easy_autoloop_reason field on SuggestSwapsResponse. A reason for the whole node doesn't fit the per-channel disqualified list, 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:

  • the channel's peer is excluded (AUTO_REASON_PEER_EXCLUDED, new);
  • the channel is inactive (AUTO_REASON_CHANNEL_INACTIVE, new);
  • a recent swap over it failed (AUTO_REASON_FAILURE_BACKOFF);
  • another swap is using it (AUTO_REASON_LOOP_OUT);
  • it holds less than the minimum swap size (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 rest ReasonBudgetInsufficient. 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:

  • Spent fees alone reach the budget: reported as AUTO_REASON_BUDGET_ELAPSED. Autoloop waits for the budget to start over.
  • The budget isn't spent yet, but the worst-case fees held for swaps in flight fill it: reported as 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/--maxamt had no effect on it. It now uses getSwapRestrictions, 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

  • New unit tests in liquidity/easy_autoloop_plan_test.go cover 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-lint reports no new issues.
  • The recorded suggestswaps sessions are updated for the new field.
  • Not yet tested on regtest.

Pull Request Checklist

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

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.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 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 file
  • looprpc/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,
}},
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