Leave configurable dust when swapping tokens

[kaze-cow]

Description

Leave a small amount of wei of every token instead of selling the full balance.

By leaving a very small buffer of tokens in the contract and not swapping them out, solvers which have made an off-by-one error in their calculations of the output amount (seems to be surprisingly common occurence) will not see their simulations revert. Additionally, leaving small buffers of tokens saves gas (15000 gas units after every drip, to be exact) by not re-initializing the storage slot repetedly after every drip.

Changes

• Subtracts a configurable dust amount from each token's on-chain balance before quoting and posting swap orders, ensuring the settlement contract is never fully drained
• Adds --leave-dust <wei> CLI option (default: 10 wei) wired through IConfig
• • Renames balance to adjustedBalance in GetTokensToSwapResult to make it clear the value has been modified

Out of scope

Leaving dust for the WETH/ETH withdrawal path requires a contract change and will be handled in a follow-up PR.

Test plan

• Run keeper with no --leave-dust flag and verify orders use balance - 10 as sell amount
• Run keeper with --leave-dust 100 and verify orders use balance - 100
• Confirm the settlement contract retains the expected dust amount after orders fill
• Confirm leaving large numbers of small token amounts in the settlement contract does not negatively impact performance of getTokensToSwap() excessively.

🤖 Generated with Claude Code

[anxolin]

Why is this common for solvers to be off by 1wei?

My fear is this will cover a real issue instead of fixing it.
Maybe this is related? https://nomevlabs.slack.com/archives/C0375NV72SC/p1778247355352829

We should investigate the examples on revert by 1wei

[kaze-cow]

Why is this common for solvers to be off by 1wei?

From my time working with both Fractal and Quasi, their solvers have had separate issues where the solver was unable to operate or provide a settlement solution because upon the backend simulating their order identifies that it fails because the buffer gets cleared before it can execute. At least in fractal's case, they confirmed that the order didn't fill because there was no more buffer of an expected token and they had to fix an off-by-one error in their solver calculation. Possibly speculation on my part, but my guess is that this happens because their own infra just generates the bytecode for their proposed solution without actually running the simulation to see if it works themselves.

We don't have control over the quality of the solver solutions that they generate. So it doesn't hurt to improve reliability of the service by maintaining small buffers, right?

As mentioned before there is another gas-related benefit, so there doesn't seem to be any real downside to implementing this PR.

Maybe this is related? https://nomevlabs.slack.com/archives/C0375NV72SC/p1778247355352829

The linked thread has to do quotes, whereas this PR is a separate potential off-by-one issues related to solvers submitting quotes that are reverting/unable to be verified because they are 1 wei off.

(Also couldn't you make the same arument about the proposal of the thread itself, because if it is ultimately "correct" to ceil the quote calculation and we change to to be more pessimistic, then that isn't actually fixing the root issue)