handle race conditons in funding venues, bps mismatch

Author: royvardhan

sdk/packages/simplex/src/funding/aerodrome/AerodromeFundingPlanner.ts

@@ -1,9 +1,10 @@
 import type { HexString } from "@hyperbridge/sdk"
 import type { ERC7821Call } from "@hyperbridge/sdk"
 import { encodeFunctionData, maxUint256 } from "viem"
+import { Mutex } from "async-mutex"
 import type { ChainClientManager } from "@/services/ChainClientManager"
 import type { FillerConfigService } from "@/services/FillerConfigService"
-import type { FundingVenue, AerodromeOutputFundingConfig, HydratedPool } from "@/funding/types"
+import type { FundingPlanResult, FundingVenue, AerodromeOutputFundingConfig, HydratedPool } from "@/funding/types"
 import { AerodromeLiquidityState } from "@/funding/aerodrome/AerodromeLiquidityState"
 import { AERODROME_GAUGE_ABI, AERODROME_ROUTER_ABI } from "@/config/abis/Aerodrome"
 import { ERC20_ABI } from "@/config/abis/ERC20"
@@ -13,8 +14,6 @@ const logger = getLogger("aerodrome-funding")
 
 /** Slippage for `amount0Min` / `amount1Min` (99.90 % of quote ≈ 0.10 % slip). */
 const MIN_AMOUNT_OUT_BPS = 9990
-/** Gas multiplier (bps, 1e4 = 1×) applied to `callGasLimit` when funding prepends are present (2×). */
-const FUNDING_GAS_MULTIPLIER_BPS = 20000
 const MAX_BS_ITER = 48
 
 // ============================================================================
@@ -73,6 +72,8 @@ export class AerodromeFundingPlanner implements FundingVenue {
 	name = "Aerodrome"
 	/** Long-lived state per chain, keyed by chain identifier. */
 	private stateByChain = new Map<string, AerodromeLiquidityState>()
+	/** Per-chain mutex serialising planWithdrawalForToken to prevent concurrent state races. */
+	private mutexByChain = new Map<string, Mutex>()
 
 	constructor(
 		private readonly clientManager: ChainClientManager,
@@ -85,14 +86,10 @@ export class AerodromeFundingPlanner implements FundingVenue {
 	 * Throws on missing/invalid required fields. Address availability
 	 * is checked later in `initialise()` when configService is available.
 	 */
-	static validateConfig(
-		pools: { chain?: string; pair?: string; gauge?: string }[],
-	): void {
+	static validateConfig(pools: { chain?: string; pair?: string; gauge?: string }[]): void {
 		for (const pool of pools) {
 			if (!pool.chain?.trim()) {
-				throw new Error(
-					"Each Aerodrome outputFunding pool must have a non-empty 'chain' (e.g. EVM-8453)",
-				)
+				throw new Error("Each Aerodrome outputFunding pool must have a non-empty 'chain' (e.g. EVM-8453)")
 			}
 			if (!pool.pair) {
 				throw new Error("Each Aerodrome pool must include a 'pair' address")
@@ -123,6 +120,7 @@ export class AerodromeFundingPlanner implements FundingVenue {
 			const state = new AerodromeLiquidityState(chain, pools, router, solver, this.clientManager)
 			await state.hydrate()
 			this.stateByChain.set(chain, state)
+			this.mutexByChain.set(chain, new Mutex())
 		}
 	}
 
@@ -163,122 +161,124 @@ export class AerodromeFundingPlanner implements FundingVenue {
 		solver: HexString,
 		tokenOutLower: string,
 		amountNeeded: bigint,
-	): Promise<{ calls: ERC7821Call[]; credited: bigint }> {
-		if (amountNeeded <= 0n) return { calls: [], credited: 0n }
-
-		const state = this.stateByChain.get(destChain)
-		if (!state || !state.isHydrated()) return { calls: [], credited: 0n }
-
-		// Refresh on-chain state for this chain right before planning so
-		// reserves and LP balances are as fresh as possible.
-		await state.refresh()
-
-		const tokenNeed = tokenOutLower.toLowerCase()
-		const candidatePools = state.poolsForToken(tokenNeed)
+	): Promise<FundingPlanResult> {
+		const noopResult: FundingPlanResult = { calls: [], credited: 0n }
 
-		for (const pool of candidatePools) {
-			const lpAvail = state.remaining(pool.pair)
-			if (lpAvail === 0n) continue
+		if (amountNeeded <= 0n) return noopResult
 
-			const [tokenA, tokenB] = sortTokens(pool.token0, pool.token1)
-
-			// --- solve LP amount ---
-			const liquidity =
-				this.solveLiquidityForDeficit(pool, tokenNeed, amountNeeded, lpAvail) ??
-				(await this.solveLiquidityForDeficitStable(
-					destChain,
-					pool,
+		const state = this.stateByChain.get(destChain)
+		if (!state || !state.isHydrated()) return noopResult
+
+		const mutex = this.mutexByChain.get(destChain)!
+		return mutex.runExclusive(async () => {
+			// Refresh on-chain state for this chain right before planning so
+			// reserves and LP balances are as fresh as possible.
+			await state.refresh()
+
+			const tokenNeed = tokenOutLower.toLowerCase()
+			const candidatePools = state.poolsForToken(tokenNeed)
+
+			for (const pool of candidatePools) {
+				const lpAvail = state.remaining(pool.pair)
+				if (lpAvail === 0n) continue
+
+				const [tokenA, tokenB] = sortTokens(pool.token0, pool.token1)
+
+				// --- solve LP amount ---
+				const liquidity =
+					this.solveLiquidityForDeficit(pool, tokenNeed, amountNeeded, lpAvail) ??
+					(await this.solveLiquidityForDeficitStable(
+						destChain,
+						pool,
+						tokenA,
+						tokenB,
+						tokenNeed,
+						amountNeeded,
+						lpAvail,
+					))
+				if (liquidity <= 0n) continue
+
+				const cappedL = liquidity > lpAvail ? lpAvail : liquidity
+
+				// --- quote expected output ---
+				const expected = await this.quoteExpectedAmounts(destChain, pool, tokenA, tokenB, cappedL)
+				if (!expected) continue
+
+				const { amount0, amount1 } = mapRouterAmountsToToken01(
+					pool.token0,
 					tokenA,
-					tokenB,
-					tokenNeed,
-					amountNeeded,
-					lpAvail,
-				))
-			if (liquidity <= 0n) continue
-
-			const cappedL = liquidity > lpAvail ? lpAvail : liquidity
-
-			// --- quote expected output ---
-			const expected = await this.quoteExpectedAmounts(destChain, pool, tokenA, tokenB, cappedL)
-			if (!expected) continue
-
-			const { amount0, amount1 } = mapRouterAmountsToToken01(
-				pool.token0,
-				tokenA,
-				expected.amountA,
-				expected.amountB,
-			)
-			const credit = tokenNeed === pool.token0.toLowerCase() ? amount0 : amount1
-			if (credit === 0n) continue
-
-			// --- slippage ---
-			// By the time the tx lands, reserves can change (other swaps, liquidity moves, ordering in the block).
-			const bps = BigInt(this.minAmountOutBps)
-			const amount0Min = (amount0 * bps) / 10000n
-			const amount1Min = (amount1 * bps) / 10000n
-			const { amountAMin, amountBMin } = mapToken01MinsToRouter(pool.token0, tokenA, amount0Min, amount1Min)
-
-			// --- build ERC-7821 calls ---
-			const deadline = BigInt(Math.floor(Date.now() / 1000) + 30 * 60)
-			const calls: ERC7821Call[] = []
-
-			// 1. Gauge withdraw (if needed)
-			if (pool.gauge) {
-				// Only withdraw the shortfall beyond what's already in the wallet.
-				const shortfall = cappedL > pool.walletLp ? cappedL - pool.walletLp : 0n
-				const withdrawAmt = shortfall > pool.gaugeLp ? pool.gaugeLp : shortfall
-				if (withdrawAmt > 0n) {
-					calls.push({
-						target: pool.gauge,
-						value: 0n,
-						data: encodeFunctionData({
-							abi: AERODROME_GAUGE_ABI,
-							functionName: "withdraw",
-							args: [withdrawAmt],
-						}) as HexString,
-					})
+					expected.amountA,
+					expected.amountB,
+				)
+				const credit = tokenNeed === pool.token0.toLowerCase() ? amount0 : amount1
+				if (credit === 0n) continue
+
+				// --- slippage ---
+				// By the time the tx lands, reserves can change (other swaps, liquidity moves, ordering in the block).
+				const bps = BigInt(this.minAmountOutBps)
+				const amount0Min = (amount0 * bps) / 10000n
+				const amount1Min = (amount1 * bps) / 10000n
+				const { amountAMin, amountBMin } = mapToken01MinsToRouter(pool.token0, tokenA, amount0Min, amount1Min)
+
+				// --- build ERC-7821 calls ---
+				const deadline = BigInt(Math.floor(Date.now() / 1000) + 30 * 60)
+				const calls: ERC7821Call[] = []
+
+				// 1. Gauge withdraw (if needed)
+				if (pool.gauge) {
+					// Only withdraw the shortfall beyond what's already in the wallet.
+					const shortfall = cappedL > pool.walletLp ? cappedL - pool.walletLp : 0n
+					const withdrawAmt = shortfall > pool.gaugeLp ? pool.gaugeLp : shortfall
+					if (withdrawAmt > 0n) {
+						calls.push({
+							target: pool.gauge,
+							value: 0n,
+							data: encodeFunctionData({
+								abi: AERODROME_GAUGE_ABI,
+								functionName: "withdraw",
+								args: [withdrawAmt],
+							}) as HexString,
+						})
+					}
 				}
-			}
 
-			// 2. Approve LP token to router
-			calls.push({
-				target: pool.pair,
-				value: 0n,
-				data: encodeFunctionData({
-					abi: ERC20_ABI,
-					functionName: "approve",
-					args: [pool.router, maxUint256],
-				}) as HexString,
-			})
-
-			// 3. Remove liquidity
-			calls.push({
-				target: pool.router,
-				value: 0n,
-				data: encodeFunctionData({
-					abi: AERODROME_ROUTER_ABI,
-					functionName: "removeLiquidity",
-					args: [tokenA, tokenB, pool.stable, cappedL, amountAMin, amountBMin, solver, deadline],
-				}) as HexString,
-			})
-
-			// --- bookkeeping ---
-			state.consume(pool.pair, cappedL)
-
-			logger.debug(
-				{
-					pair: pool.pair,
-					liquidity: cappedL.toString(),
-					tokenOut: tokenNeed,
-					credited: credit.toString(),
-				},
-				"Aerodrome funding planned",
-			)
+				// 2. Approve LP token to router
+				calls.push({
+					target: pool.pair,
+					value: 0n,
+					data: encodeFunctionData({
+						abi: ERC20_ABI,
+						functionName: "approve",
+						args: [pool.router, maxUint256],
+					}) as HexString,
+				})
+
+				// 3. Remove liquidity
+				calls.push({
+					target: pool.router,
+					value: 0n,
+					data: encodeFunctionData({
+						abi: AERODROME_ROUTER_ABI,
+						functionName: "removeLiquidity",
+						args: [tokenA, tokenB, pool.stable, cappedL, amountAMin, amountBMin, solver, deadline],
+					}) as HexString,
+				})
+
+				logger.debug(
+					{
+						pair: pool.pair,
+						liquidity: cappedL.toString(),
+						tokenOut: tokenNeed,
+						credited: credit.toString(),
+					},
+					"Aerodrome funding planned",
+				)
 
-			return { calls, credited: credit }
-		}
+				return { calls, credited: credit }
+			}
 
-		return { calls: [], credited: 0n }
+			return noopResult
+		}) // mutex.runExclusive
 	}
 
 	// =========================================================================

sdk/packages/simplex/src/funding/aerodrome/AerodromeLiquidityState.ts

@@ -14,8 +14,7 @@ const logger = getLogger("aerodrome-state")
  * refreshes live data (reserves, totalSupply, LP balances).  The planner
  * reads from this cache instead of hitting the chain per-order.
  *
- * `consume()` / `restore()` track LP earmarked for pending orders so
- * concurrent evaluations don't double-spend.
+ * Concurrent access is serialised by the planner's per-chain mutex.
  */
 export class AerodromeLiquidityState {
 	/** Keyed by `pair` address (lower-cased). */
@@ -143,6 +142,7 @@ export class AerodromeLiquidityState {
 		pool.reserve0 = reserves[0]
 		pool.reserve1 = reserves[1]
 		pool.totalSupply = totalSupply
+
 		pool.walletLp = walletLp
 		pool.gaugeLp = gaugeLp
 		pool.remainingLp = walletLp + gaugeLp
@@ -171,35 +171,8 @@ export class AerodromeLiquidityState {
 		return this.pools.get(pair.toLowerCase())
 	}
 
-	// =========================================================================
-	// LP accounting (for concurrent order evaluation)
-	// =========================================================================
-
-	/** Remaining LP available for a given pair after prior `consume()` calls. */
+	/** Remaining LP available for a given pair. */
 	remaining(pair: HexString): bigint {
 		return this.pools.get(pair.toLowerCase())?.remainingLp ?? 0n
 	}
-
-	/**
-	 * Earmark LP for a pending order.
-	 * Decrements `remainingLp` so parallel evaluations see an accurate picture.
-	 */
-	consume(pair: HexString, amount: bigint): void {
-		const pool = this.pools.get(pair.toLowerCase())
-		if (!pool) throw new Error(`Unknown pair ${pair}`)
-		if (amount > pool.remainingLp) {
-			throw new Error(`Aerodrome LP underflow for pair ${pair}: need ${amount}, have ${pool.remainingLp}`)
-		}
-		pool.remainingLp -= amount
-	}
-
-	/**
-	 * Restore LP if an order evaluation is abandoned (e.g. profitability check
-	 * fails after partial planning).  Prevents leaked reservations.
-	 */
-	restore(pair: HexString, amount: bigint): void {
-		const pool = this.pools.get(pair.toLowerCase())
-		if (!pool) throw new Error(`Unknown pair ${pair}`)
-		pool.remainingLp += amount
-	}
 }

sdk/packages/simplex/src/funding/index.ts

@@ -1,5 +1,6 @@
 export type {
 	FundingVenue,
+	FundingPlanResult,
 	AerodromePoolConfig,
 	AerodromeOutputFundingConfig,
 	HydratedPool,

sdk/packages/simplex/src/funding/types.ts

@@ -20,13 +20,21 @@ export interface FundingVenue {
 	 * Plans ERC-7821 calls to withdraw `amountNeeded` of `tokenOutLower`
 	 * from LP positions on `destChain`. Returns the calls and the credited
 	 * amount that will become available after execution.
+	 *
+	 * Access is serialised per chain via a mutex so concurrent evaluations
+	 * do not race on shared liquidity state.
 	 */
 	planWithdrawalForToken(
 		destChain: string,
 		solver: HexString,
 		tokenOutLower: string,
 		amountNeeded: bigint,
-	): Promise<{ calls: ERC7821Call[]; credited: bigint }>
+	): Promise<FundingPlanResult>
+}
+
+export interface FundingPlanResult {
+	calls: ERC7821Call[]
+	credited: bigint
 }
 
 // =========================================================================