Balancer Stable Math Swap Pricing as Balances Change
Balancer Stable Math prices correlated-asset swaps using normalized pool balances, an amplification parameter and the amount that enters the pricing curve. Higher amplification keeps pricing flatter near balance parity; increasingly uneven balances make further depletion more expensive. The applicable swap fee and token rates also affect the quote. These relationships explain why a stable pool can offer a favorable small-trade quote without fixing the rate for larger trades. The approved protocol winddown separately constrains swap availability.
In short: A stable-pool quote combines fee-adjusted input with the curve’s response to normalized balances, so amplification alone doesn’t determine output.
A quote from a fee-adjusted input
A stable-pool quote requires compatible token amounts, the pool’s normalized balances and the amplification value applicable at the quotation time. An executable swap also requires an initialized pool with swaps enabled. The v3 Router can simulate an exact-input operation without transferring tokens, returning the amount that the specified operation would produce.
The winddown plan sets October 30, 2026 as the withdrawals-only transition for pausable pools, subject to designated v3 extensions. Specific v3 pools may remain active under partner extensions requested by October 16, 2026, until the scheduled Vault pause on November 30, 2026. Bug bounty coverage ends on October 30, 2026, including for those extended pools. Pools that cannot be paused follow a different path and keep working. A mathematical output doesn’t override these operating restrictions.
An exact-input calculation
For this hypothetical v3 calculation, assume an active standard stable pool without hooks. Both tokens have 18 decimals and an assumed parity relationship, with no rate adjustment. Each starting balance is 12,344 tokens, the human-readable amplification setting is 84 and the static swap fee is 0.18%. The input is 734 input tokens, with a minimum acceptable output of 731.914 output tokens.
The fee takes 1.3212 input tokens from the gross payment, leaving 732.6788 tokens for the curve calculation. The equal starting balances give an invariant of 24,688 normalized token units. Adding the fee-adjusted input raises the mathematical input balance to 13,076.6788. Solving for the output balance while preserving that invariant leaves approximately 11,611.834231 output tokens.
The calculated quote is approximately 732.165769 output tokens, clearing the stated minimum. About 0.513031 normalized units separate that output from the fee-adjusted input because the trade moves along the curve. The mathematical input balance excludes fee proceeds; it isn’t the final accounting balance. A query against that assumed pool state would reproduce the output without executing a swap. Changing amplification, balances or the fee changes this calculation.
Pool balances and amplification
Amplification controls the curve’s flatness around parity, while normalized balances determine where the pool sits on that curve. A higher setting supports near-parity exchange across a wider range of balances. A lower setting lets the price respond more strongly as the pool becomes uneven. Neither setting establishes the assets’ economic value outside the pool.
Liquidity depth matters alongside the setting: the same input causes a larger relative balance change in a smaller pool.
Stable pricing suits assets expected to maintain a common value or a known conversion relationship. Weighted pools use configured token weights and a different invariant. That distinction concerns the assets’ pricing relationship, not an automatic ranking of swap quality. An available quote still reflects the selected pool’s depth and fee configuration.
When does a stable-pool swap move away from parity?
A stable-pool swap moves away from parity when its direction and size push normalized balances further into the curve’s uneven region. Spending an abundant token to remove a scarce token increases that pressure. The average exchange rate across the entire trade can therefore differ from the marginal rate at its start. Adding the scarce token and removing the abundant token can improve balance instead. Amplification shapes both directions, although a flat central region doesn’t provide unlimited output liquidity.
A depeg can break the economic relationship that the curve assumes. If the pool continues pricing near that relationship, swaps can leave liquidity providers holding more of the discounted asset.
Curve impact and static or StableSurge fees
Curve impact changes the mathematical exchange rate as balances move, while the swap fee charges part of the input amount.
The static fee
The static fee enters an exact-input calculation before Stable Math solves the output amount. Increasing that fee reduces the input that reaches the curve, even with unchanged starting balances. Its configured percentage is a live pool parameter. Network gas pays for transaction execution separately and doesn’t enter the pool’s invariant equation.
The StableSurge fee
StableSurge retains the Stable Math invariant and adds a dynamic fee rule based on balance imbalance. The configured threshold and maximum surge fee control that rule.
Increasing imbalance
The hook estimates post-swap imbalance without accounting for swap fees. It can raise the fee above the static base when that estimate exceeds both the threshold and starting imbalance, provided the configured maximum exceeds the base. Trade direction and size can therefore affect both curve impact and the applicable fee.
Reducing imbalance
The hook uses the base fee when its estimated post-swap imbalance is no greater than the starting imbalance. The threshold and maximum fee don’t define a universal setting for every stable pool.
Token rates and normalized balances
The v3 Vault scales token balances to 18 decimal places before passing them to pool mathematics. Decimal scaling aligns numerical precision across tokens. Rate scaling then adjusts their relative value where the registered token configuration requires it. These operations explain why raw wallet quantities alone cannot reproduce every stable-pool quote.
A rate provider supplies a conversion that can reflect an underlying asset relationship or an oracle, depending on its implementation. Its value can change even when nobody swaps. The Vault incorporates rates into live balances, together with applicable yield-fee adjustments. A changing rate can therefore move the pool’s mathematical balance away from parity without changing its raw token inventory. The pricing calculation inherits the registered provider’s conversion.
Amplification updates and quotation time
An authorized amplification update can change swap pricing while token balances remain unchanged. The v3 StablePool contract interpolates between its starting and target values using the block timestamp. A quote needs the value applicable at that timestamp; using the eventual target prematurely produces a different curve. The contract exposes both the current amplification value and whether an update is underway. Fees and rates follow their own configuration and update mechanisms; an amplification schedule doesn’t establish their values.
The invariant and contract rounding
The invariant, conventionally called D, describes the balance relationship that Stable Math preserves during its fee-adjusted swap calculation. The implementation first calculates D from all pool balances. It then changes the specified input or output balance and solves for the other balance. This computation uses an iterative solver, so a simple subtraction cannot independently establish the unknown swap amount.
Contract rounding also affects reproducibility. The v3 library rounds an exact-input output downward overall and an exact-output input upward overall. Decimal and rate conversions add their own directional rounding. A calculator that uses unrestricted decimal arithmetic can consequently differ from an executable quote. Fee proceeds also affect final accounting, so the invariant held during the pricing calculation isn’t a promise that the final pool invariant stays unchanged.
The v3 StablePool code also checks for extreme imbalance. A converged curve calculation can still fail that check.
Things people ask
Can a v2 Stable Math calculator reproduce a v3 quote?
A v2 calculator can reproduce the underlying curve calculation when its balance inputs and amplification convention match. A complete v3 quote also requires the applicable scaling, fee logic and contract rounding. A dynamic fee hook can introduce another difference. Matching the invariant formula alone doesn’t establish that the calculator has reproduced the amount that a v3 Router would return.
How many tokens can a standard v3 stable pool contain?
Standard v3 stable pools support up to five tokens under their Stable Math limit. The invariant uses every underlying token balance, even when the swap exchanges only two of them. A calculator that discards the other balances changes the pricing problem. The two-token worked calculation is a simplified case, not the full range that the mathematics supports.
Does an exact-output stable swap charge its fee on the output?
The v3 swap fee applies to the required input amount. Stable Math first calculates the fee-adjusted input needed for the requested output. Ignoring rounding, the gross input equals that mathematical input divided by one minus the applicable fee fraction. The contract then applies its rounding rules. Charging the percentage against the requested output would misstate the payment.
What happens when the Stable Math solver fails to converge?
The v3 math library reverts when its iterative solver fails to converge within the allowed iterations. It doesn’t return a valid output amount from an unfinished calculation. An offchain calculator that accepts its last approximation after failure differs from that behavior. Increasing a slippage allowance cannot make a failed invariant or balance calculation succeed.
Is the contract’s amplification value already the human-readable setting?
The v3 getter returns a precision-scaled amplification value alongside its precision. Dividing the value by that precision gives the human-readable pool setting. Math functions that expect the scaled representation must receive that representation. Supplying an unscaled value changes the calculation or can cause a revert. Amplification precision and token decimals describe separate numerical conventions.
Are single-token stable-pool withdrawals free of swap fees?
Normal single-token withdrawals incur swap fees on their non-proportional portion. Proportional withdrawals normally return assets in the pool’s existing ratios without swap fees or curve price impact. In v3, an earlier liquidity addition to the same pool within the same Vault unlock call triggers a round-trip fee on the withdrawal amounts. A single-token withdrawal uses invariant and balance calculations to price the concentrated output. These distinctions describe normal liquidity operations while enabled; a withdrawal restriction can limit the available operation.
Updated on