You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Comprehensive integration of Ekubo v3 DEX support with full pool simulator, tracker, and event parsing implementations
Implements multiple pool types: Base, FullRange, Stableswap, Oracle, MEV-Capture, and TWAMM pools with quote calculations
Adds complete mathematical library for swap computations including tick conversions, amount deltas, sqrt ratio calculations, and TWAMM-specific exponential functions
Extensive test coverage with 30+ test files covering pool simulators, trackers, event parsers, and mathematical operations
Integrates on-chain data fetching with subgraph support and RPC fallback mechanisms for pool state management
Registers Ekubo v3 as a supported DEX type in factory and pool type systems with msgpack serialization support
Fixes address conversion utilities to use standardized ZeroToWrappedLower function and corrects zero value cloning in delta calculations
Refactors test utilities to use helper functions for CI detection and log sorting
Diagram Walkthrough
flowchart LR
A["Ekubo v3<br/>Integration"] --> B["Pool Types"]
A --> C["Math Library"]
A --> D["Data Fetching"]
A --> E["Event Parsing"]
A --> F["Pool Tracking"]
B --> B1["Base Pool"]
B --> B2["FullRange Pool"]
B --> B3["Stableswap Pool"]
B --> B4["Oracle Pool"]
B --> B5["MEV-Capture Pool"]
B --> B6["TWAMM Pool"]
C --> C1["Swap Computation"]
C --> C2["Tick Conversion"]
C --> C3["Amount Deltas"]
C --> C4["Sqrt Ratio"]
C --> C5["TWAMM Math"]
D --> D1["Subgraph Integration"]
D --> D2["RPC Fallback"]
E --> E1["Event Decoding"]
E --> E2["Pool Address Extraction"]
F --> F1["State Updates"]
F --> F2["Reorg Detection"]
A --> G["Pool Simulator"]
G --> H["Swap Calculations"]
A --> I["Factory Registration"]
I --> J["DEX Type Support"]
Loading
File Walkthrough
Relevant files
Tests
18 files
pool_simulator_test.go
Pool simulator test suite with comprehensive swap calculations
Below is a summary of compliance checks for this PR:
Security Compliance
⚪
Nil pointer DoS
Description: The new exp2 function returns nil when x exceeds exponentLimit, which can lead to a nil dereference panic (DoS) in production code if any caller uses the returned *uint256.Int without an explicit nil check. exp2.go [278-293]
Generic: Robust Error Handling and Edge Case Management
Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation
Status: Nil on overflow: The new exp2 helper returns nil when x exceeds exponentLimit, which may lead to downstream nil dereferences if callers do not explicitly handle the nil case.
Generic: Security-First Input Validation and Data Handling
Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities
Status: Missing nil guards: StableswapPool.Quote clones and dereferences inputs/state (amount.Clone(), p.SqrtRatio.Clone()) without nil checks, which could panic if externally constructed pool/state or parameters are nil.
✅ Recompute active tick indexSuggestion Impact:The commit sets ActiveTickIndex to -1 initially and then recomputes it using NearestInitializedTickIndex() after AddLiquidityCutoffs(), using the mutated state.SortedTicks and state.ActiveTick.
Why: The suggestion correctly identifies that AddLiquidityCutoffs() modifies SortedTicks, which can invalidate the pre-calculated ActiveTickIndex. This is a subtle but important bug that could lead to incorrect swap calculations.
Medium
Apply signed deltas safely
Correctly handle signed liquidity deltas in BasePool.ApplyEvent by using sign-aware addition/subtraction instead of casting, which can cause incorrect liquidity updates.
Why: This suggestion correctly identifies a critical bug where casting a negative int256 to uint256 causes it to wrap, leading to incorrect liquidity calculations. The proposed fix correctly handles both positive and negative deltas.
Medium
Deep-clone pool numeric state
Implement a deep copy in CloneState for the FullRangePoolState and its nested fields. This prevents state corruption across different pool instances during simulation by ensuring that mutable fields like SqrtRatio and Liquidity are not shared.
Why: The suggestion correctly identifies a critical bug where CloneState performs a shallow copy of *uint256.Int fields, which can lead to state corruption during simulation as these objects are mutable.
Medium
Avoid float precision in fees
Refactor the fee calculation in MevCapturePool.Quote to use integer arithmetic instead of float64. This will prevent potential precision loss and overflow issues when dealing with large fixed-point fee values, ensuring accurate quote amounts.
tickAfterSwap := ekubomath.ApproximateSqrtRatioToTick(quote.SwapInfo.SwapStateAfter.(*BasePoolSwapState).SqrtRatio)
poolConfig := &p.key.Config
-approximateFeeMultiplier := math.Abs(float64(tickAfterSwap-p.lastTick)) / float64(poolConfig.TypeConfig.TickSpacing)+tickDelta := tickAfterSwap - p.lastTick+if tickDelta < 0 {+ tickDelta = -tickDelta+}-fixedPointAdditionalFee := uint64(min(math.Round(approximateFeeMultiplier*float64(poolConfig.Fee)), math.MaxUint64))+// Integer math to avoid float64 precision loss on Q64 fees.+var fixedPointAdditionalFee uint64+if poolConfig.TypeConfig.TickSpacing > 0 && tickDelta > 0 {+ var num uint256.Int+ num.Mul(uint256.NewInt(uint64(poolConfig.Fee)), uint256.NewInt(uint64(tickDelta)))+ den := uint256.NewInt(uint64(poolConfig.TypeConfig.TickSpacing))+ q, _ := new(uint256.Int).DivMod(&num, den, new(uint256.Int))++ if q.BitLen() >= 64 {+ fixedPointAdditionalFee = math.MaxUint64+ } else {+ fixedPointAdditionalFee = q.Uint64()+ }+}+
Apply / Chat
Suggestion importance[1-10]: 8
__
Why: The suggestion correctly points out that using float64 for fee calculations involving Q64 fixed-point numbers can lead to precision loss and incorrect results, which is a significant issue for financial calculations.
Medium
✅ Prevent panics on short dataSuggestion Impact:The commit added an early guard `if len(data) < 116 { return nil, nil }` before slicing the data buffer, preventing panics on malformed/short event data.
Why: The suggestion correctly identifies that slicing the data byte array without a length check can lead to a panic, and the proposed fix improves the code's robustness against malformed inputs.
Medium
Handle empty tick list
In BasePoolState.UpdateTick, add a check to handle the case where s.SortedTicks is empty to prevent a panic from out-of-bounds slice access.
Why: The suggestion correctly identifies a potential panic when s.SortedTicks is empty, as ticks[0] would be an out-of-bounds access. The proposed fix adds a necessary guard to handle this edge case.
Medium
Sort time-ordered delta events
Sort the VirtualOrderDeltas by Time to ensure they are processed in the correct chronological order during simulation.
Why: The suggestion correctly points out that VirtualOrderDeltas should be sorted by time for correct simulation. While the contract is expected to return them sorted, adding an explicit sort is a good defensive measure against potential issues.
Low
Guard swap-state type assertions
Add a type assertion check in SetSwapState to safely handle incorrect or nil swap state types. This prevents potential panics and makes the function more robust by providing a clear error message.
func (p *FullRangePool) SetSwapState(state quoting.SwapState) {
- p.FullRangePoolSwapState = state.(*FullRangePoolSwapState)+ s, ok := state.(*FullRangePoolSwapState)+ if !ok || s == nil {+ panic("invalid swap state type for full range pool")+ }+ p.FullRangePoolSwapState = s
}
Apply / Chat
Suggestion importance[1-10]: 5
__
Why: The suggestion correctly identifies a potential panic from an unchecked type assertion, improving code robustness by adding a safe check. However, the likelihood of this specific error is low within the existing codebase structure.
Explicitly calculate the signed liquidity delta for the lower cutoff tick instead of relying on uint256 wraparound arithmetic. This improves code clarity and safety by handling positive and negative deltas explicitly.
Why: The suggestion correctly identifies that relying on uint256 wraparound for signed arithmetic is risky and unclear. The proposed change makes the calculation of liquidityDeltaMin explicit and safer by using int256 for signed operations, which improves code clarity and robustness against potential misinterpretations of two's complement representation.
Deep-clone the BasePoolSwapState and its pointer fields (SqrtRatio, Liquidity) within BasePoolState.CloneState() to prevent state corruption between cloned pool instances.
Why: This suggestion correctly identifies a critical bug where a shallow copy of *BasePoolSwapState would cause state corruption between concurrent simulations, leading to incorrect quotes. The fix is crucial for the correctness of the pool simulator.
High
Deep-copy TWAMM mutable fields
Deep-clone the token0SaleRate, token1SaleRate, and virtualOrderDeltas fields in TwammPool.CloneState() to prevent shared state and data corruption between pool simulations.
func (p *TwammPool) CloneState() any {
cloned := *p
cloned.FullRangePool = p.FullRangePool.CloneState().(*FullRangePool)
++ if p.token0SaleRate != nil {+ cloned.token0SaleRate = new(uint256.Int).Set(p.token0SaleRate)+ }+ if p.token1SaleRate != nil {+ cloned.token1SaleRate = new(uint256.Int).Set(p.token1SaleRate)+ }++ cloned.virtualOrderDeltas = slices.Clone(p.virtualOrderDeltas)+ for i := range cloned.virtualOrderDeltas {+ if cloned.virtualOrderDeltas[i].SaleRateDelta0 != nil {+ cloned.virtualOrderDeltas[i].SaleRateDelta0 = cloned.virtualOrderDeltas[i].SaleRateDelta0.Clone()+ }+ if cloned.virtualOrderDeltas[i].SaleRateDelta1 != nil {+ cloned.virtualOrderDeltas[i].SaleRateDelta1 = cloned.virtualOrderDeltas[i].SaleRateDelta1.Clone()+ }+ }+
return &cloned
}
Suggestion importance[1-10]: 9
__
Why: This suggestion correctly points out a critical bug where TwammPool.CloneState performs a shallow copy of mutable fields, which would lead to state corruption across different simulations. The proposed deep copy is essential for simulation correctness.
High
Apply signed liquidity deltas safely
Safely apply signed liquidity deltas in CalcBalances by using int256 arithmetic to prevent incorrect wrapping of negative values, and add a check to ensure liquidity does not become negative.
func (s *BasePoolState) CalcBalances() ([]uint256.Int, error) {
stateSqrtRatio := s.SqrtRatio
balances := make([]uint256.Int, 2)
var liquidity, sqrtRatio, minAmount1SqrtRatio, maxAmount0SqrtRatio uint256.Int
sqrtRatio.Set(math.MinSqrtRatio)
for _, tick := range s.SortedTicks {
...
sqrtRatio.Set(tickSqrtRatio)
- liquidity.Add(&liquidity, (*uint256.Int)(tick.LiquidityDelta))++ // Apply signed liquidity delta safely.+ var liqI int256.Int+ liqI.SetFromBig(liquidity.ToBig())++ liqI.Add(&liqI, tick.LiquidityDelta)+ if liqI.Sign() < 0 {+ return nil, fmt.Errorf("negative liquidity after applying tick delta")+ }++ liquidity.SetFromBig(liqI.ToBig())
}
return balances, nil
}
Suggestion importance[1-10]: 9
__
Why: The suggestion correctly identifies a critical bug where a direct pointer cast from a signed to an unsigned integer type can lead to incorrect liquidity calculations and potential overflows.
High
Guard TWAMM ratio division-by-zero
Prevent a potential division-by-zero panic in computeSqrtSaleRatioX128 by adding checks for zero saleRateToken0. Return a sensible ratio for one-sided or zero sale rates.
func computeSqrtSaleRatioX128(saleRateToken0, saleRateToken1 *uint256.Int) *uint256.Int {
+ // Avoid division-by-zero: handle one-sided / empty sale rates.+ if saleRateToken0.IsZero() {+ if saleRateToken1.IsZero() {+ return big256.U0.Clone()+ }+ // token0 rate is 0 while token1 > 0 => ratio tends to +inf; cap to max uint.+ return big256.UMax.Clone()+ }+
var saleRatio uint256.Int
saleRatio.Div(
saleRatio.Lsh(saleRateToken1, 128),
saleRateToken0,
)
if bitLen := saleRatio.BitLen(); bitLen <= 128 {
- // Full precision
return saleRatio.Sqrt(saleRatio.Lsh(&saleRatio, 128))
} else if bitLen <= 192 {
- // We know it only has 192 bits, so we can shift it 64 before rooting to get more precision
return saleRatio.Lsh(saleRatio.Sqrt(saleRatio.Lsh(&saleRatio, 64)), 32)
}
return saleRatio.Lsh(saleRatio.Sqrt(saleRatio.Lsh(&saleRatio, 16)), 56)
}
Suggestion importance[1-10]: 8
__
Why: The suggestion correctly identifies a potential division-by-zero panic and proposes a robust fix by handling edge cases where sale rates can be zero, which is a valid scenario in TWAMM pools.
Medium
Prevent NaN/Inf tick conversions
Add checks in ApproximateNumberOfTickSpacingsCrossed and ApproximateSqrtRatioToTick to handle non-finite float values (NaN, Inf) that can result from math.Log on edge-case inputs, preventing undefined behavior.
func ApproximateNumberOfTickSpacingsCrossed(startingSqrtRatio, endingSqrtRatio *uint256.Int, tickSpacing uint32) uint32 {
if tickSpacing == 0 {
return 0
}
start, end := U256ToFloatBaseX128(startingSqrtRatio), U256ToFloatBaseX128(endingSqrtRatio)
- ticksCrossed := uint32(math.Abs(math.Log(start/end)) / logBaseSqrtTickSize)+ if start <= 0 || end <= 0 || math.IsNaN(start) || math.IsNaN(end) || math.IsInf(start, 0) || math.IsInf(end, 0) {+ return 0+ }- return ticksCrossed / tickSpacing+ v := math.Abs(math.Log(start/end)) / logBaseSqrtTickSize+ if math.IsNaN(v) || math.IsInf(v, 0) || v < 0 {+ return 0+ }++ ticksCrossed := uint64(v)+ return uint32(ticksCrossed / uint64(tickSpacing))
}
func ApproximateSqrtRatioToTick(sqrtRatio *uint256.Int) int32 {
- return int32(math.Round(math.Log(U256ToFloatBaseX128(sqrtRatio)) / logBaseSqrtTickSize))+ x := U256ToFloatBaseX128(sqrtRatio)+ if x <= 0 || math.IsNaN(x) || math.IsInf(x, 0) {+ return 0+ }++ t := int64(math.Round(math.Log(x) / logBaseSqrtTickSize))+ if t < int64(MinTick) {+ return MinTick+ }+ if t > int64(MaxTick) {+ return MaxTick+ }+ return int32(t)
}
Suggestion importance[1-10]: 8
__
Why: The suggestion correctly points out that converting uint256 to float64 for logarithmic calculations can lead to NaN/Inf values in edge cases, causing undefined behavior. The proposed checks make the approximations more robust.
Medium
Avoid returning nil sentinel
Modify the exp2 function to return a safe, deterministic value or an explicit error instead of nil for out-of-range inputs to prevent potential nil pointer dereferences.
func exp2(x *uint256.Int) *uint256.Int {
if !x.Lt(exponentLimit) {
- return nil+ return new(uint256.Int) // 0, explicit safe value
}
result := big256.U2Pow127.Clone()
var helper uint256.Int
for _, maskAndFactor := range masksAndFactors {
if !helper.And(x, maskAndFactor.mask).IsZero() {
result.Rsh(result.Mul(result, maskAndFactor.factor), 128)
}
}
return result.Rsh(result, 63-uint(helper.Rsh(x, 64).Uint64()))
}
Suggestion importance[1-10]: 7
__
Why: The suggestion correctly identifies that returning nil can lead to panics and proposes safer alternatives, which improves the robustness of the math utility function.
Medium
Use the subtest handle consistently
*Use the subtest's testing.T handle consistently within subtests instead of the parent's handle to ensure correct error reporting.
Why: The suggestion correctly identifies an issue where the parent test's *testing.T is used within subtests, which can lead to incorrect test failure reporting.
Low
General
Make subtest names unique
Make subtest names unique by including more test case details to improve test output clarity and aid in debugging failures.
Why: The suggestion correctly points out that non-unique subtest names make debugging difficult and proposes a valid solution to improve test clarity and maintainability.
✅ Fix unsafe type cast bugSuggestion Impact:The commit removed the unsafe pointer casts and replaced them with a dedicated conversion helper (u256.SInt256), which safely converts the uint256 values to int256 before calling UpdateTick. An import for the conversion utility was also added.
**Fix an unsafe type cast from uint256.Int to int256.Int by using proper conversion methods to avoid incorrect value interpretation and bugs in liquidity calculations.
Why: The suggestion identifies a critical bug due to an unsafe type cast between *uint256.Int and *int256.Int, which would cause incorrect liquidity calculations and potentially corrupt pool state.
High
Fix incorrect liquidity update logic
Fix a bug in UpdateTick by removing incorrect special handling for boundary ticks and ensuring a new tick is always inserted if it does not exist.
Why: The suggestion correctly identifies a critical bug in the UpdateTick function where liquidity for new ticks outside the existing range is misattributed to boundary ticks, leading to incorrect liquidity accounting.
High
Fix incorrect sqrt ratio calculation
Correct the logic in nextSqrtRatioFromAmount1 to ensure sqrtRatio is updated correctly based on the sign of amount1 (add for exact-in, subtract for exact-out).
func nextSqrtRatioFromAmount1(sqrtRatio, liquidity, amount1 *uint256.Int) (*uint256.Int, error) {
if amount1.IsZero() {
return sqrtRatio.Clone(), nil
} else if liquidity.IsZero() {
return nil, ErrNoLiquidity
}
var tmp uint256.Int
amount1Abs := tmp.Abs(amount1)
+ // for exact-in, amount1 is positive, roundUp is false.+ // for exact-out, amount1 is negative, roundUp is true.
roundUp := amount1.Sign() < 0
quotient, err := MulDivOverflow(amount1Abs, big256.U2Pow128, liquidity, roundUp)
if err != nil {
return nil, err
}
- if roundUp {- res, overflow := quotient.SubOverflow(sqrtRatio, quotient)- if overflow {- return nil, ErrUnderflow- }- return res, nil- } else {+ if amount1.Sign() > 0 { // exact-in, add to current sqrtRatio
res, overflow := quotient.AddOverflow(sqrtRatio, quotient)
if overflow {
return nil, ErrOverflow
}
return res, nil
+ } else { // exact-out, subtract from current sqrtRatio+ res, overflow := sqrtRatio.SubOverflow(sqrtRatio, quotient)+ if overflow {+ return nil, ErrUnderflow+ }+ return res, nil
}
}
Suggestion importance[1-10]: 9
__
Why: The suggestion correctly identifies a logic error in the nextSqrtRatioFromAmount1 function where the sqrtRatio is updated in the wrong direction for one of the swap cases, leading to incorrect price calculations.
High
Fix incorrect offset for pool ID
Fix the parsing of the anonymous Swapped event by extracting the poolId from the correct offset (log.Data[0:32]) and adjusting the data length check accordingly.
func (e *EventParser) handleCoreLog(log types.Log) (string, error) {
if len(log.Topics) == 0 {
- if len(log.Data) < 52 {+ // This is for the anonymous Swapped event.+ // The first field in the data is the poolId (bytes32).+ if len(log.Data) < 32 {
return "", fmt.Errorf("invalid data length for Swapped event")
}
- return "0x" + common.Bytes2Hex(log.Data[20:52]), nil+ return "0x" + common.Bytes2Hex(log.Data[0:32]), nil
}
if log.Topics[0] == abis.PositionUpdatedEvent.ID {
...
Suggestion importance[1-10]: 9
__
Why: This suggestion correctly identifies that the poolId for an anonymous Swapped event is being parsed with an incorrect offset. The proposed fix aligns the parsing logic with how other anonymous events are handled in the codebase, ensuring correct pool identification from logs, which is critical for the event parser's functionality.
High
Fix swapped FilterReject assignments
Correct the variable assignment for the lo.FilterReject return values. The current code swaps twammPoolKeys and basicPoolKeys, leading to incorrect data fetching logic.
Why: This suggestion correctly identifies a critical bug where lo.FilterReject return values are assigned to the wrong variables, causing pools to be processed by the incorrect data fetcher. Fixing this is essential for the function's correctness.
Medium
Prevent division by zero in fee calculation
Prevent a potential division-by-zero panic in the MEV capture fee calculation by adding a check to ensure poolConfig.TypeConfig.TickSpacing is not zero before the division.
Why: This suggestion correctly identifies a potential division-by-zero panic if TickSpacing is 0. Adding a guard clause makes the fee calculation more robust and prevents a runtime crash, which is an important improvement for error handling.
Medium
Prevent potential division by zero panics
Add checks to prevent potential division-by-zero panics in the TWAMM sqrt_ratio calculation. Specifically, handle cases where the denominators in the c and final ratio calculations could be zero.
Why: This suggestion correctly points out two potential division-by-zero panics in the TWAMM sqrt_ratio calculation. The proposed checks for zero denominators make the mathematical operation safer and prevent runtime crashes, which is a critical improvement for the reliability of the logic.
Medium
✅ Guard data slice boundsSuggestion Impact:The commit added a guard clause checking `len(data) < 116` before slicing `data[20:52]`, preventing a potential out-of-bounds panic. It returns `nil, nil` instead of an error and uses a different minimum length than suggested.
Why: The suggestion correctly identifies a potential panic from slicing data without a length check, which is a good defensive programming practice to improve robustness.
Medium
Prevent mutating helper in exp2 loop
In the exp2 function, use separate temporary variables for bit-testing and the final shift calculation instead of reusing the helper variable to avoid mutation and improve clarity.
func exp2(x *uint256.Int) *uint256.Int {
if !x.Lt(exponentLimit) {
return nil
}
result := big256.U2Pow127.Clone()
- var helper uint256.Int- for _, maskAndFactor := range masksAndFactors {- if !helper.And(x, maskAndFactor.mask).IsZero() {- result.Rsh(result.Mul(result, maskAndFactor.factor), 128)+ // apply mask‐factor multipliers without mutating x+ for _, mf := range masksAndFactors {+ tmp := new(uint256.Int).And(x, mf.mask)+ if !tmp.IsZero() {+ result = new(uint256.Int).Rsh(new(uint256.Int).Mul(result, mf.factor), 128)
}
}
- return result.Rsh(result, 63-uint(helper.Rsh(x, 64).Uint64()))+ // extract the high bits for final right shift+ highBits := new(uint256.Int).Rsh(x.Clone(), 64).Uint64()+ shift := 63 - uint(highBits)+ return new(uint256.Int).Rsh(result, shift)
}
Suggestion importance[1-10]: 3
__
Why: The suggestion correctly identifies that reusing the helper variable can be confusing, although the original code is not buggy. The proposed change improves readability and makes the code's intent clearer by using separate variables, which is a good practice.
Low
General
set snapshot flag after first quote
In the OraclePool.Quote method, set p.swappedThisBlock = true after adding the oracle snapshot gas cost to prevent it from being added to subsequent quotes within the same block.
Why: This suggestion correctly identifies a logic error where a flag is not updated, leading to incorrect gas cost calculations for subsequent swaps. The fix is simple but important for ensuring the gas estimation for oracle pools is accurate.
Medium
✅ Replace debug printSuggestion Impact:The debug fmt.Println call was removed from pools_list_updater.go, eliminating unwanted console output (no structured logger was added).
-fmt.Println(u.config.Oracle, u.config.Twamm, u.config.MevCapture)+// Replace debug print with logger:+logger.WithFields(logger.Fields{+ "oracle": u.config.Oracle,+ "twamm": u.config.Twamm,+ "mevCapture": u.config.MevCapture,+}).Debug("pool list updater configuration")
Suggestion importance[1-10]: 3
__
Why: The suggestion correctly points out a debug fmt.Println statement that should be removed or replaced with a proper logger to avoid polluting logs in a production environment.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
minhnhathoang
requested review from
NgoKimPhu and
lehainam-dev
as code owners
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
User description
Follow-up to #1253
PR Type
Enhancement, Tests
Description
Comprehensive integration of Ekubo v3 DEX support with full pool simulator, tracker, and event parsing implementations
Implements multiple pool types: Base, FullRange, Stableswap, Oracle, MEV-Capture, and TWAMM pools with quote calculations
Adds complete mathematical library for swap computations including tick conversions, amount deltas, sqrt ratio calculations, and TWAMM-specific exponential functions
Extensive test coverage with 30+ test files covering pool simulators, trackers, event parsers, and mathematical operations
Integrates on-chain data fetching with subgraph support and RPC fallback mechanisms for pool state management
Registers Ekubo v3 as a supported DEX type in factory and pool type systems with msgpack serialization support
Fixes address conversion utilities to use standardized
ZeroToWrappedLowerfunction and corrects zero value cloning in delta calculationsRefactors test utilities to use helper functions for CI detection and log sorting
Diagram Walkthrough
File Walkthrough
18 files
pool_simulator_test.go
Pool simulator test suite with comprehensive swap calculationspkg/liquidity-source/ekubo/v3/pool_simulator_test.go
PoolSimulatorwith 5 real poolconfigurations (lvlUSD-USDC, ETH-USDC, ETH-EKUBO in multiple variants)
CalcAmountOutwith 20+ test cases covering various swapscenarios, amounts, and expected outputs
CalcAmountInfor all pool configurations using utility functionbalance updates
twamm_test.go
TWAMM pool quoting test suitepkg/liquidity-source/ekubo/v3/pools/twamm_test.go
functionality
virtual order deltas, and complex scenarios
various liquidity and sale rate configurations
base_test.go
Base pool quoting and tick management testspkg/liquidity-source/ekubo/v3/pools/base_test.go
tick configurations
NearestInitializedTickIndexfunction with edge cases andmultiple tick scenarios
AddLiquidityCutoffswith positive/negative liquidity deltasand tick boundary conditions
pool_tracker_test.go
Pool tracker integration tests with real transactionspkg/liquidity-source/ekubo/v3/pool_tracker_test.go
PoolTrackerwith real Ethereum transactions andevent logs
different pool types (base, oracle, TWAMM)
stableswap_test.go
Stableswap pool unit testspkg/liquidity-source/ekubo/v3/pools/stableswap_test.go
tick positions
ranges
accounting
swap_test.go
Swap computation unit testspkg/liquidity-source/ekubo/v3/math/swap_test.go
calculations
and overflow conditions
handling
muldiv_test.go
Multiplication and division unit testspkg/liquidity-source/ekubo/v3/math/muldiv_test.go
large numbers
overflow conditions
sqrt_ratio_test.go
TWAMM sqrt ratio calculation testspkg/liquidity-source/ekubo/v3/math/twamm/sqrt_ratio_test.go
rate combinations
time elapsed
delta_test.go
Amount delta calculation unit testspkg/liquidity-source/ekubo/v3/math/delta_test.go
price ranges
conditions
sqrt_ratio_test.go
Sqrt ratio conversion unit testspkg/liquidity-source/ekubo/v3/math/sqrt_ratio_test.go
liquidity levels
mev_capture_test.go
MEV capture pool unit testspkg/liquidity-source/ekubo/v3/pools/mev_capture_test.go
amounts
tick_test.go
Tick conversion unit testspkg/liquidity-source/ekubo/v3/math/tick_test.go
values
factory_test.go
Add ekubo-v3 to factory test DEX typespkg/pooltypes/factory_test.go
ekubov3to the list of supported DEX types inTestCanCalcAmountInekubov3to the list of supported DEX types inTestPoolListerFactoryekubov3to the list of supported DEX types inTestPoolTrackerFactoryevent_parser_test.go
Add ekubo-v3 event parser test suitepkg/liquidity-source/ekubo/v3/event_parser_test.go
VirtualOrdersExecuted, and OrderUpdated events
pools_list_updater_test.go
Add ekubo-v3 pool list updater testpkg/liquidity-source/ekubo/v3/pools_list_updater_test.go
full_range_test.go
Add full-range pool quote calculation testspkg/liquidity-source/ekubo/v3/pools/full_range_test.go
scenarios
exp2_test.go
Add exp2 function tests for TWAMM mathpkg/liquidity-source/ekubo/v3/math/twamm/exp2_test.go
oracle_test.go
Add oracle pool quote calculation testspkg/liquidity-source/ekubo/v3/pools/oracle_test.go
36 files
exp2.go
Fixed-point exponential base-2 computation implementationpkg/liquidity-source/ekubo/v3/math/twamm/exp2.go
exp2) using precomputedmasks and factors for fixed-point arithmetic
handling
data_fetchers.go
On-chain pool data fetching and state constructionpkg/liquidity-source/ekubo/v3/data_fetchers.go
fetchers
MEV-capture, and TWAMM pools
construction from RPC data
base.go
Base pool swap computation and tick managementpkg/liquidity-source/ekubo/v3/pools/base.go
management
Quotemethod for computing swap amounts with tick crossingand fee calculations
UpdateTick,AddLiquidityCutoffs,and
NearestInitializedTickIndexevents.go
Event parsing and state update handlers for Ekubo poolspkg/liquidity-source/ekubo/v3/pools/events.go
BasePool,StableswapPool,FullRangePool,TwammPool) withApplyEventmethodsSwappedandPositionUpdatedevents from blockchain logs toupdate pool state
VirtualOrdersExecuted,OrderUpdated)with virtual order delta tracking
pool identifiers
twamm.go
TWAMM pool implementation with virtual order executionpkg/liquidity-source/ekubo/v3/pools/twamm.go
TwammPooltype with time-weighted average market maker(TWAMM) functionality
over time periods
processing
GetState,CloneState,SetSwapState)keys.go
Pool key structures and serialization logicpkg/liquidity-source/ekubo/v3/pools/keys.go
PoolKeystructure with support for multiple pool typeconfigurations
computation using Keccak256
(Concentrated, FullRange, Stableswap)
generation
pools_list_updater.go
Pool list updater with subgraph integrationpkg/liquidity-source/ekubo/v3/pools_list_updater.go
tracking for incremental updates
when needed
entity.Poolobjects with propertoken and reserve formatting
stableswap parameters
pool_tracker.go
Pool state tracker with event and RPC updatespkg/liquidity-source/ekubo/v3/pool_tracker.go
fallback mechanisms
reorg detection
processing fails
timing
swap.go
Swap step computation logicpkg/liquidity-source/ekubo/v3/math/swap.go
calculations
rounding
error handling
pool_simulator.go
Pool simulator for swap calculationspkg/liquidity-source/ekubo/v3/pool_simulator.go
PoolSimulatorfor swap amount calculations (in/out) usingEkubo pool quotes
error handling
stableswap.go
Stableswap pool implementationpkg/liquidity-source/ekubo/v3/pools/stableswap.go
StableswapPoolwith quote calculation across priceboundaries
detection
sqrt_ratio.go
Sqrt ratio conversion and calculation utilitiespkg/liquidity-source/ekubo/v3/math/sqrt_ratio.go
and vice versa)
representation
event_parser.go
Event parser for pool address extractionpkg/liquidity-source/ekubo/v3/event_parser.go
addresses
Swapped,PositionUpdated,VirtualOrdersExecuted, andOrderUpdatedeventsbalances.go
Add balance calculation methods for ekubo-v3 poolspkg/liquidity-source/ekubo/v3/pools/balances.go
CalcBalances()method forBasePoolStateto calculate tokenbalances from ticks
CalcBalances()forFullRangePoolStateusing amount deltacalculations
CalcBalances()forStableswapPoolwith conditional amountcalculations
full_range.go
Add full-range pool implementation for ekubo-v3pkg/liquidity-source/ekubo/v3/pools/full_range.go
FullRangePoolstruct and related state types for full-rangeliquidity pools
unmarshal.go
Add pool unmarshaling for ekubo-v3 typespkg/liquidity-source/ekubo/v3/unmarshal.go
Stableswap, Concentrated)
mev_capture.go
Add MEV capture pool implementation for ekubo-v3pkg/liquidity-source/ekubo/v3/pools/mev_capture.go
MevCapturePoolextendingBasePoolwith MEV capture feelogic
configuration
sqrt_ratio.go
Add TWAMM sqrt ratio calculation logicpkg/liquidity-source/ekubo/v3/math/twamm/sqrt_ratio.go
CalculateNextSqrtRatio()for TWAMM pools with time-weightedcalculations
elapsed
constants.go
Add ekubo-v3 mathematical constantspkg/liquidity-source/ekubo/v3/math/constants.go
log base
calculations
pool_tracker_test.go
Refactor ekubo pool tracker test utilitiespkg/liquidity-source/ekubo/pool_tracker_test.go
test.SkipCI()helperfunction
valueobject.ZeroToWrappedLower()instead of
FromEkuboAddress()osandtypes)tick.go
Add tick-to-ratio conversion functions for ekubo-v3pkg/liquidity-source/ekubo/v3/math/tick.go
ToSqrtRatio()to convert tick numbers to sqrt ratio valuesApproximateNumberOfTickSpacingsCrossed()for tick spacingcalculations
ApproximateSqrtRatioToTick()for inverse conversiondelta.go
Add amount delta calculations for ekubo-v3pkg/liquidity-source/ekubo/v3/math/delta.go
Amount0Delta()andAmount1Delta()for calculating tokenamount changes
pool_tracker.go
Refactor log sorting in ekubo pool trackerpkg/liquidity-source/ekubo/pool_tracker.go
eth.SortLogs()utility functionslicesandtypes)pools_list_updater.go
Update address conversion in ekubo pool list updaterpkg/liquidity-source/ekubo/pools_list_updater.go
valueobject.ZeroToWrappedLower()instead of
FromEkuboAddress()oracle.go
Add oracle pool implementation for ekubo-v3pkg/liquidity-source/ekubo/v3/pools/oracle.go
OraclePoolextendingFullRangePoolwith oracle snapshot gascosts
type.go
Add ekubo-v3 core type definitionspkg/liquidity-source/ekubo/v3/type.go
Poolinterface with quote, balance, and state managementmethods
StaticExtraandMetastructures for pool metadataconfig.go
Add ekubo-v3 configuration structurepkg/liquidity-source/ekubo/v3/config.go
Configstruct with DEX configuration parametersSupportedExtensions()method for extension type mappingabis.go
Add ABI initialization for ekubo-v3 contractspkg/liquidity-source/ekubo/v3/abis/abis.go
TwammDataFetcher contracts
muldiv.go
Add multiplication and division utilities for ekubo-v3pkg/liquidity-source/ekubo/v3/math/muldiv.go
MulDivOverflow()for safe multiplication and division withrounding
div()helper for division with optional rounding upquote.go
Add quote and swap info types for ekubo-v3pkg/liquidity-source/ekubo/v3/quoting/quote.go
Quotestruct containing swap results and gas costsSwapInfostruct with swap state and routing informationgas.go
Add gas cost constants for ekubo-v3 operationspkg/liquidity-source/ekubo/v3/quoting/gas.go
errors.go
Add error definitions for ekubo-v3 mathpkg/liquidity-source/ekubo/v3/math/errors.go
constants.go
Add ekubo-v3 constants and error definitionspkg/liquidity-source/ekubo/v3/constants.go
DexTypeconstant for ekubo-v3exchange.go
Add ekubo-v3 exchange type constantpkg/valueobject/exchange.go
ExchangeEkuboV3constant with value"ekubo-v3"uint.go
Add uint256 to float conversion utilitypkg/liquidity-source/ekubo/v3/math/uint.go
U256ToFloatBaseX128()for converting uint256 to float64with X128 scaling
extension_type.go
Add extension type enumeration for ekubo-v3pkg/liquidity-source/ekubo/v3/extension_type.go
ExtensionTypeenum with Base, Oracle, Twamm, and MevCapturevariants
1 files
event_parser_test.go
Refactor CI skip condition to use utility functionpkg/liquidity-source/ekubo/event_parser_test.go
test.SkipCIutility functioninstead of manual environment variable check
2 files
pool_simulator_test.go
Update address conversion utility usagepkg/liquidity-source/ekubo/pool_simulator_test.go
valueobject.ZeroToWrappedLowerinstead of
FromEkuboAddressdelta.go
Fix zero value cloning in ekubo delta calculationspkg/liquidity-source/ekubo/math/delta.go
Amount0Delta()to return cloned zero value instead of sharedreference
Amount1Delta()to return cloned zero value instead of sharedreference
7 files
register_pool_types.gen.go
Register ekubo-v3 pool simulator for msgpackpkg/msgpack/register_pool_types.gen.go
pkg_liquiditysource_ekubo_v3packageekubov3.PoolSimulatoras a concrete msgpack typepooltypes.go
Register ekubo-v3 DEX type in pool typespkg/pooltypes/pooltypes.go
ekubov3packageEkuboV3field toTypesstructekubov3.DexTypein default types initializationembed.go
Embed ekubo-v3 contract ABI filespkg/liquidity-source/ekubo/v3/abis/embed.go
TwammDataFetcher contracts
Core.json
Add Core contract ABI for ekubo-v3pkg/liquidity-source/ekubo/v3/abis/Core.json
Twamm.json
Add TWAMM contract ABI for ekubo-v3pkg/liquidity-source/ekubo/v3/abis/Twamm.json
TwammDataFetcher.json
Add TWAMM data fetcher ABI for ekubo-v3pkg/liquidity-source/ekubo/v3/abis/TwammDataFetcher.json
QuoteDataFetcher.json
Add quote data fetcher ABI for ekubo-v3pkg/liquidity-source/ekubo/v3/abis/QuoteDataFetcher.json
1 files