Add Liquidity Unbalanced Via Swap by mkflow27 · Pull Request #747 · balancer/b-sdk

mkflow27 · 2025-12-04T16:12:33Z

Closes #796

This PR proposes a solution for adding liquidity single sided to 2 token pools using the AddLiquidityUnbalancedViaSwapRouter.

The main problem to solve is that we want to allow users to simply input amounts in, but the router operation also expects an exactBptAmountOut.

In order to solve that, we'll need to calculate/estimate the exactBptAmountOut corresponding to the provided amounts in.

The implemented approach relies on an initial guess which is then adjusted/corrected iteratively based on how far they are from on-chain query results. A full description of each step can be found documented both in the codebase and also in this Notion doc (with illustrative example).

Integration tests have shown the approach is able to calculate/estimate BPT amounts that approximate the amounts in provided within a tolerance of 0.01% even for add liquidity amounts up to 60% of the balance of the pool.

… with adjustable

# Conflicts: # src/abi/v3/index.ts

brunoguerios · 2026-01-15T21:03:26Z

src/entities/addLiquidityUnbalancedViaSwap/index.ts

+            // target from it.
+
+            const maxAjustableTokenAmount = amountsIn[adjustableTokenIndex];
+


This is where the core solution starts. I tried adding comments explaining how each step works, but I'll try to give more details here (and later write a more complete doc in Notion).

The whole goal is to find a bptAmount that will result in a maxAdjustableAmount close enough to the one provided by the user. Ideally approximating from below, so we favor leaving some dust instead of risking a revert transaction by requiring amounts bigger than what the user provided.

start with an initial reference amount to calculate a proportional BPT. This initial guess is 50% of the maxAdjustableAmountIn provided by the user. The assumption is that ReClamms behave as a 50/50 Weighted pool and in those cases, the proportionalBptAmount calculated with 50% of the maxAdjustableAmountIn should result in a bptAmount pretty close to adding single-sided 100% of the maxAdustableAmountIn provided by the user.
1.1 the problem is that ReClamms only behave as 50/50 Weigthed when centeredness = 1. The further the current price is from the center, the bigger the error we get on the approximation above. That error has to be compensated somehow. One important thing to note is that the calculated bptAmount will result in a smaller maxAdjustableAmountIn when centeredness decreases.

we then query the add unbalanced with that bptAmount as input and get a maxAdjustableAmount as a result from it.

we can then apply the ratio between maxAdjustableAmount and maxAdjustableAmountIn (in the opposite direction) to approximate the desired bptAmount (this is what I call correction factor)

this actually overcorrects, resulting in a bptAmount that corresponds to a maxAdjustableAmount slightly greater that what the user provided

we can then repeat the process to overcorrect in the opposite direction, resulting in a bptAmount that corresponds to a maxAdjustableAmount slightly smaller than what the user provided and that is much closer to the actual amount because the error decreases significantly on each step

the existing tests already result in 0.004% error for an amountIn that is 60% of the pool balance, so 2 iterations seem to be fine (we'll need more tests to validate this)

I hope this makes it clear, but I'll spend more time polishing this next week ;)

# Conflicts: # src/abi/v3/index.ts # src/abi/v3/unbalancedAddViaSwapRouter.ts

brunoguerios · 2026-01-28T19:06:49Z

src/entities/addLiquidityUnbalancedViaSwap/index.ts

+        if (calculatedVsProvidedRatio > WAD) {
+            throw new SDKError(
+                'Error',
+                'Add Liquidity Unbalanced Via Swap',
+                'Exact BPT out calculation failed. Please add a smaller or less unbalanced liquidity amount.',
+            );
+        }


This extra check should prevent scenarios where the approximation fails. I was able to force it to fail by adding liquidity above 60% the pool balance. I'd say it's safer to throw in such cases and ask the user to provide a smaller/less unbalanced amount in.

# Conflicts: # test/v3/createPool/stable/stable.integration.test.ts

test/v3/addLiquidityUnbalancedViaSwap/addLiquidityUnbalancedViaSwap.integration.test.ts

johngrantuk · 2026-02-02T11:16:15Z

test/v3/addLiquidityUnbalancedViaSwap/addLiquidityUnbalancedViaSwap.integration.test.ts

+const WETH = TOKENS[chainId].WETH;
+
+// Toggle to control whether test results should be logged to files
+const ENABLE_LOGGING = false;


Not sure if this logging is useful to keep?

It was super useful for debugging, but I agree it might to be useful long term. I'll remove that 👍

johngrantuk · 2026-02-02T11:19:40Z

test/v3/addLiquidityUnbalancedViaSwap/addLiquidityUnbalancedViaSwap.test.ts

+                    addLiquidityUnbalancedViaSwap.buildCall(buildCallInput);
+
+                expect(result).toHaveProperty('callData');
+                expect(result).toHaveProperty('to');


Should be able to test this is known contract address? Possible same with some other values?

I refactored a bit this part of the test. Properties were already implicitly verified on all other tests, so I removed this section.

Contract address was indeed incorrect btw 👀
Apparently the attribute to from queryOutput is not used anywhere 😅
I think it's useful to keep it anyway, since it's relevant information to whoever is consuming that functionality from the SDK.

johngrantuk

Few small comments otherwise looking good.

test/v3/addLiquidityUnbalancedViaSwap/addLiquidityUnbalancedViaSwap.integration.test.ts

johngrantuk · 2026-02-03T15:48:31Z

src/entities/addLiquidityUnbalancedViaSwap/index.ts

@@ -0,0 +1,212 @@
+import { encodeFunctionData, maxUint256, parseEther, zeroAddress } from 'viem';


Noticed theres quite a few unused imports that don't seem to be picked up.

johngrantuk · 2026-02-03T15:53:01Z

src/entities/addLiquidityUnbalancedViaSwap/index.ts

+        const output: AddLiquidityUnbalancedViaSwapQueryOutput = {
+            pool: poolState.address,
+            bptOut,
+            exactAmountIn: TokenAmount.fromRawAmount(


Does this need to be returned? Might be confusing to user. Instead we can just hardcode 0 amount in buildCall?

Yeah, the problem here is that buildCall requires exactToken address information and I don't have it available otherwise because buildCall doesn't expect poolState as input.
I believe the best way to provide that info is by returning exactTokenAmount in the queryOutput.
Let me know if you think there's a better approach.

johngrantuk · 2026-02-03T15:59:16Z

test/v3/addLiquidityUnbalancedViaSwap/addLiquidityUnbalancedViaSwap.integration.test.ts

+                    balanceDeltas[expectedAdjustableToken.index === 0 ? 1 : 0];
+                const bptDelta = balanceDeltas[2];
+
+                // TODO: check value is within range for adjustableAmountIn provided


Still to do?

It was, but I just pushed the fix - thanks 🙏

johngrantuk

Couple of small nits but otherwise LGTM. Thanks for getting it over the line!

mkflow27 and others added 26 commits December 4, 2025 16:30

feat: wip for unbalanced join via swap

2132f35

feat: add adjustable amount token in

6594e94

refactor: strip previous functionality to focus on single sided joins…

0a1bf0a

… with adjustable

Merge branch 'main' into unbalanced-add-Router

43768d4

fix: build

ef3ac40

chore: move block number to test

67d0463

chore: lint

e48964d

chore: adjust helper contracts to work with partial deploys

46dc803

chore: lint

a4d0726

Merge branch 'main' into unbalanced-add-Router

6008298

fix: chain id

363d667

refactor: change slippage to bpt amounts

f60c549

docs: comments on slippage

4b26fb9

test: changes to tests

81c875f

feat: introduce passthrough simulateContract for sendTxGetBalances

0cdedb5

chore: format

cad30c4

feat: passthrough sim to understand possible reverts

c6358f3

Merge branch 'main' into unbalanced-add-Router

024eef7

test: update test

191583e

wip: add virtual balance + balance addition

0d37475

wip: add virtual balances to reference amount

9ec506f

Merge remote-tracking branch 'origin/main' into unbalanced-add-Router

e8d4bb4

# Conflicts: # src/abi/v3/index.ts

Apply correction factor approach to adjust bpt amounts

f16b336

Remove unnecessary helper methods

9686ff7

Rename join with add

ceeaf1e

Remove unnecessary attributes

5cbe44f

brunoguerios reviewed Jan 15, 2026

View reviewed changes

brunoguerios added 3 commits January 26, 2026 17:02

Refactor inputs

b0592e0

Merge remote-tracking branch 'origin/main' into unbalanced-add-Router

9ba77ca

# Conflicts: # src/abi/v3/index.ts # src/abi/v3/unbalancedAddViaSwapRouter.ts

Refactor integration tests to run on mainnet instead of sepolia

1c84aaf

brunoguerios reviewed Jan 28, 2026

View reviewed changes

brunoguerios added 8 commits January 29, 2026 15:21

Remove exactAmountIn from input

23b8080

Forward maxAdjustableAmountIn provided by the user

959b3bc

Return expected adjustable amount in

9ff700e

Remove getReClammPoolStateWithBalances

7cd6977

Minor fix

a2571be

Minor test refactor

8ae49a6

Fix unit test

55a2936

Merge remote-tracking branch 'origin/main' into unbalanced-add-Router

9cd6b42

# Conflicts: # test/v3/createPool/stable/stable.integration.test.ts

johngrantuk reviewed Feb 2, 2026

View reviewed changes

test/v3/addLiquidityUnbalancedViaSwap/addLiquidityUnbalancedViaSwap.integration.test.ts Show resolved Hide resolved

johngrantuk reviewed Feb 2, 2026

View reviewed changes

johngrantuk requested changes Feb 2, 2026

View reviewed changes

johngrantuk reviewed Feb 2, 2026

View reviewed changes

test/v3/addLiquidityUnbalancedViaSwap/addLiquidityUnbalancedViaSwap.integration.test.ts Show resolved Hide resolved

brunoguerios added 7 commits February 2, 2026 13:46

Remove the gnosis test in favor of a single integration test

050cbe5

Remove logging logic from integration test

68678bc

Refactor unit test

348ff6c

Add integration tests for buildCallWithPermit2 signature

090434d

Refactor interface to expect an expectedAdjustableAmountIn as input

7963939

Refactor solution to have variable iterations with tolerance check

721a0c9

Add test with native asset

8580050

brunoguerios requested a review from johngrantuk February 3, 2026 14:51

johngrantuk reviewed Feb 3, 2026

View reviewed changes

johngrantuk approved these changes Feb 3, 2026

View reviewed changes

brunoguerios added 2 commits February 3, 2026 14:08

Properly check value amount

3ca7bc0

Merge remote-tracking branch 'origin/main' into unbalanced-add-Router

dcba69f

brunoguerios merged commit 8a88d09 into main Feb 3, 2026
5 checks passed

brunoguerios deleted the unbalanced-add-Router branch February 3, 2026 17:52

		// target from it.

		const maxAjustableTokenAmount = amountsIn[adjustableTokenIndex];

		@@ -0,0 +1,212 @@
		import { encodeFunctionData, maxUint256, parseEther, zeroAddress } from 'viem';

Conversation

mkflow27 commented Dec 4, 2025 • edited by brunoguerios Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brunoguerios Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

brunoguerios Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johngrantuk left a comment

Choose a reason for hiding this comment

Uh oh!

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!

johngrantuk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mkflow27 commented Dec 4, 2025 •

edited by brunoguerios

Loading

brunoguerios Jan 28, 2026 •

edited

Loading

brunoguerios Feb 2, 2026 •

edited

Loading