Router: Composite Liquidity Router V3

[mkflow27]

balancer/balancer-deployments#317

[mkflow27]

CompositeLiquidityRouter V3 vs Deprecated V2 - Functional Differences Analysis

Overview

The new CompositeLiquidityRouter V3 represents an enhanced version that adds support for nested pools while maintaining backward compatibility with existing ERC4626 pool functionality.

Key Functional Differences

1. New Functions in V3

Function	Status	Purpose
addLiquidityUnbalancedNestedPool	NEW	Add liquidity to nested pools with unbalanced amounts
addLiquidityUnbalancedNestedPoolHook	NEW	Hook for unbalanced nested pool liquidity addition
queryAddLiquidityUnbalancedNestedPool	NEW	Query unbalanced nested pool liquidity addition
queryRemoveLiquidityProportionalNestedPool	NEW	Query proportional nested pool liquidity removal
removeLiquidityProportionalNestedPool	NEW	Remove liquidity from nested pools proportionally
removeLiquidityProportionalNestedPoolHook	NEW	Hook for proportional nested pool liquidity removal
getVault	NEW	Getter for Vault contract address

2. Enhanced Function Signatures

Nested Pool Support

V3 adds new nested pool functionality:

// NEW: Nested pool support
function addLiquidityUnbalancedNestedPool(
    address parentPool,
    address[] memory tokensIn,
    uint256[] memory exactAmountsIn,
    address[] memory tokensToWrap,
    uint256 minBptAmountOut,
    bool wethIsEth,
    bytes calldata userData
) external payable returns (uint256 bptAmountOut);

function removeLiquidityProportionalNestedPool(
    address parentPool,
    uint256 exactBptAmountIn,
    address[] memory tokensOut,
    uint256[] memory minAmountsOut,
    address[] memory tokensToUnwrap,
    bool wethIsEth,
    bytes calldata userData
) external payable returns (uint256[] memory amountsOut);

3. Enhanced Constructor

Deprecated V2:

constructor(
    IVault vault,
    IWETH weth,
    IPermit2 permit2,
    string routerVersion
)

V3:

constructor(
    IVault vault,
    IWETH weth,
    IPermit2 permit2,
    string routerVersion
)

Benefits:

• Same constructor interface - backward compatible
• Enhanced internal functionality for nested pools

4. Query Functions

V3 introduces additional query functions:

Function	Purpose
queryAddLiquidityUnbalancedNestedPool	Query unbalanced nested pool liquidity addition
queryRemoveLiquidityProportionalNestedPool	Query proportional nested pool liquidity removal

Benefits:

• Better user experience with nested pool queries
• Gas estimation for nested pool operations
• Predictable behavior for complex operations

5. Hook Functions

V3 adds new hook functions:

Function	Purpose
addLiquidityUnbalancedNestedPoolHook	Hook for unbalanced nested pool operations
removeLiquidityProportionalNestedPoolHook	Hook for proportional nested pool operations

Benefits:

• Modular architecture for nested pool operations
• Better separation of concerns
• Easier testing and maintenance

Architecture Improvements

Enhanced Design Philosophy

Aspect	Deprecated V2	V3
Nested Pool Support	None	Full support
Complexity	Medium	Higher (but modular)
Gas Efficiency	Good	Optimized for nested pools
Maintainability	Good	Excellent (modular hooks)
Security Surface	Medium	Well-controlled (hooks)

Added Functionality

• Nested Pool Support - Full support for nested pool operations
• Enhanced Query Functions - Better user experience with queries
• Modular Hooks - Cleaner architecture with hook functions
• Backward Compatibility - All V2 functions remain unchanged

Enhanced Error Handling

V3 adds new error types:

• DuplicateTokenIn - Prevents duplicate tokens in operations
• ElementNotFound - Better error handling for missing elements
• FailedCall - Enhanced error reporting for failed calls
• InvalidAddLiquidityKind - Better validation for liquidity operations
• InvalidTokenType - Enhanced token type validation
• OperationNotSupported - Clear error messages for unsupported operations
• TransientIndexOutOfBounds - Better array bounds checking

Migration Impact

Breaking Changes

None - V3 is fully backward compatible with V2

Benefits for Users

1. Nested Pool Support - Access to more complex liquidity operations
2. Better Error Handling - Clearer error messages and validation
3. Enhanced Queries - Better user experience with nested pool queries
4. Modular Architecture - Cleaner, more maintainable code
5. Gas Optimization - Optimized for nested pool operations

Summary

The V3 CompositeLiquidityRouter represents a significant enhancement:

• Nested Pool Support - Full support for complex nested pool operations
• Backward Compatibility - All V2 functionality preserved
• Enhanced Architecture - Modular design with hook functions
• Better User Experience - Improved queries and error handling
• Future-Proof - Extensible architecture for future enhancements

This represents a mature evolution that adds powerful new capabilities while maintaining full backward compatibility with existing integrations.