[PT1-326] feat: add PeggedSwapReinvest strict additivity implementation and tests

[ifelsedeveloper]

PeggedSwap Strictly-Additive Fee Mechanism

Summary

Introduced PeggedSwapReinvest contract implementing a strictly-additive fee mechanism via semigroup D-update. This ensures that swap(a+b) = swap(a) + swap(b), providing path-independent swap outcomes regardless of how trades are chunked.

Key Changes

• New Instruction: PeggedSwapReinvest._peggedSwapReinvestXD (opcode index 50)
• Semigroup D-Update: Implements Γ(D, Δ) = D + f·Δ for deterministic pool growth
• Tests: Comprehensive test suite verifying strict additivity property
• Documentation: LaTeX document with mathematical proofs for the fee mechanism

Change Summary

What does this PR change?

Adds a new swap instruction that applies fees while maintaining strict additivity - the total output is the same whether a trade is executed in one shot or split into multiple chunks. This is achieved by growing the pool size D deterministically with each trade.

Related Issue/Ticket:
https://1inch.atlassian.net/browse/PT1-326

Files Changed

New Files

• src/instructions/PeggedSwapReinvest.sol - Strictly-additive fee mechanism instruction
• test/PeggedSwapReinvest.t.sol - Test suite for strict additivity
• docs/pegged-swap-reinvest-strict.tex - Mathematical documentation

Modified Files

• src/opcodes/Opcodes.sol - Added PeggedSwapReinvest to instruction set

Technical Details

Strict Additivity via Semigroup Law

The fee mechanism satisfies the semigroup property:

Γ(Γ(D, a), b) = Γ(D, a+b)

This ensures:

• Path Independence: Chunking trades doesn't affect outcome
• Deterministic Pool Growth: D increases by exactly f × volume
• Predictable LP Revenue: Fee accumulation is volume-based, not path-based

Comparison with Other Fee Rules

Mechanism	Additivity	For Trader	Path Dependent?
Fee-free PeggedSwap	Strictly additive	Neutral	No
Output-fee (Curve-style)	Superadditive	Split better	Yes
Input-fee reinvest	Subadditive	One-shot better	Yes
Semigroup D-update (this PR)	Strictly additive	Neutral	No

Testing & Verification

How was this tested?

• Unit tests
• Integration tests
• Manual testing
• Verified on staging

Test Results

test_StrictAdditivity_BasicSwap    - PASS (swap(2000) ≈ swap(1000) + swap(1000))
test_StrictAdditivity_MultipleChunks - PASS (swap(4000) ≈ 4×swap(1000))
test_FeeGrowsPool                  - PASS (fee reduces output as expected)
test_DeterministicPoolGrowth       - PASS (fee same regardless of chunking)

Run tests with:

forge test --match-contract PeggedSwapReinvestTest -vvv

Risk Assessment

Risk Level:

• Low - Minor changes, no operational impact

Risks & Impact

• No breaking changes: New instruction added at end of opcode array (index 50)
• Backward compatible: Existing instructions and their indices unchanged
• No migrations required: Pure addition of new functionality
• Uses audited libraries: OpenZeppelin Math for sqrt, mulDiv operations

Benefits

1. Aggregator/Router Neutrality: Routes can split trades arbitrarily without affecting outcome
2. Partial Fills & TWAP: Time-weighted execution benefits from path-independence
3. Deterministic Pool Growth: LPs can predict fee revenue from volume alone
4. Composability: Protocols building on SwapVM can reason about outcomes without simulating split patterns

[claude]

Claude finished @ifelsedeveloper's task —— View job

---

Todo List:

• Read and analyze implementation files
• Review code quality and best practices
• Identify potential bugs or issues
• Evaluate performance considerations
• Assess security concerns
• Review test coverage
• Provide comprehensive feedback

Code Review - PeggedSwapReinvest Implementation

Summary

This PR introduces a novel swap instruction PeggedSwapReinvest that implements a strictly-additive fee mechanism via semigroup D-update. The implementation appears mathematically sound and well-documented, though there are several areas for improvement.

Code Quality and Best Practices ✅

Strengths:

• Excellent mathematical documentation with clear explanations of the semigroup property
• Clean separation of concerns (args builder, math library, main logic)
• Proper use of custom errors for better gas efficiency
• Good use of OpenZeppelin's Math library for safe operations

Areas for Improvement:

1. Magic Numbers: Several constants like 192 bytes in args parsing should be defined as named constants
2. Code Comments: While the mathematical theory is well-documented, inline implementation comments could be clearer
3. Naming Consistency: Variables like x0_raw vs x0 could be named more clearly (e.g., balanceInRaw vs normalizedBalanceIn)

Potential Bugs or Issues 🐛

1. Exact Output Approximation (PeggedSwapReinvest.sol:219-250):

   • The exact-out case uses an approximation that may not converge to the correct value
   • The formula amountIn ≈ amountIn_nofee / (1 - f) is only accurate for small fees
   • Consider implementing an iterative solver or more accurate closed-form solution

2. Integer Division Precision Loss:

   • In line 189-192, the scale factor calculation could lose precision for small fee contributions
   • Consider using higher precision intermediate calculations

3. Edge Case - Zero Liquidity:

   • While zero balance check exists, consider what happens when balances are very small relative to x0, y0

Performance Considerations ⚡

1. Double Invariant Calculation (lines 171-173, 200-202):

   • Computing C0 and C1 involves expensive sqrt operations
   • Consider if C1 can be derived from C0 more efficiently

2. Storage vs Memory:

   • The args struct is marked calldata which is good, but consider if frequently accessed values should be cached in memory

3. Gas Optimization:

   • The Math.mulDiv operations are safe but gas-intensive
   • For known safe ranges, consider using unchecked blocks with proper justification

Security Concerns 🔒

1. Overflow Protection: ✅ Good use of Math.mulDiv throughout

2. Reentrancy: ✅ Pure function with no external calls

3. Input Validation: ✅ Comprehensive validation in args parser

4. Rounding Direction: ⚠️

   • Line 215: amountOut rounds down (good - protects maker)
   • Line 250: amountIn rounds up (good - protects maker)
   • However, ensure all intermediate calculations round in the correct direction

5. Fee Rate Bounds: ✅ Properly checked < 1e9 (100%)

Test Coverage 🧪

Strengths:

• Comprehensive tests for strict additivity property
• Multiple test scenarios (2 chunks, 4 chunks)
• Tests verify the mathematical properties claimed

Gaps:

1. Edge Cases: No tests for:

   • Very large trades relative to pool size
   • Very small trades (dust amounts)
   • Maximum fee rate scenarios
   • Exact-out swaps (critical given the approximation issue)

2. Fuzzing: Consider adding fuzz tests to verify additivity holds for random input values

3. Integration Tests: Test interaction with other SwapVM instructions

4. Gas Benchmarks: No gas consumption tests for different trade sizes

Additional Recommendations

1. Mathematical Documentation: The LaTeX document is excellent. Consider adding numerical examples showing the additivity property

2. Exact-Out Implementation: This needs the most attention - either:

   • Implement Newton-Raphson iteration for accurate solution
   • Document the approximation error bounds
   • Add tests to verify accuracy

3. Monitoring: Consider events or hooks to track pool growth (D changes) for analytics

4. Upgradability: The opcode index 50 is hardcoded - ensure this doesn't conflict with future upgrades

Conclusion

This is a well-thought-out implementation of a novel fee mechanism with strong mathematical foundations. The strict additivity property is valuable for composability. The main concerns are around the exact-out approximation and missing edge case tests. With these addressed, this would be a solid addition to SwapVM.

[claude]

Claude finished @ifelsedeveloper's task —— View job

---

Todo List:

• Read CLAUDE.md for repo-specific guidelines (no file found)
• Read and analyze implementation files
• Review code quality and best practices
• Identify potential bugs or issues
• Evaluate performance considerations
• Assess security concerns
• Review test coverage
• Provide comprehensive feedback

Code Review - PeggedSwapReinvest Implementation

Summary

This PR introduces a novel swap instruction PeggedSwapReinvest that implements a strictly-additive fee mechanism via semigroup D-update. The implementation is mathematically rigorous and well-documented, with comprehensive theoretical backing. However, there are several areas that need attention before merging.

Code Quality and Best Practices ✅

Strengths:

• Excellent mathematical documentation with clear LaTeX explanations
• Clean separation of concerns (args builder, math library, main logic)
• Proper use of custom errors for gas efficiency
• Good use of OpenZeppelin's Math library for safe operations
• Clear and meaningful variable names

Areas for Improvement:

1. Magic Numbers: The value 192 bytes in args parsing (PeggedSwapReinvest.sol:54) should be defined as a named constant
2. Code Comments: While the mathematical theory is well-documented, inline implementation comments could be improved for clarity
3. Naming Clarity: Consider renaming x0_raw → balanceInRaw and x0 → normalizedBalanceIn for better readability

Potential Bugs or Issues 🐛

1. Critical: Exact Output Approximation (PeggedSwapReinvest.sol:219-250)

   • The exact-out implementation uses a crude approximation that may not converge correctly
   • Line 243-247: amountIn ≈ amountIn_nofee / (1 - f) is only accurate for small fees
   • This could lead to significant errors for larger fee rates or trades
   • Recommendation: Implement an iterative solver (Newton-Raphson) or derive a more accurate closed-form solution

2. Precision Loss in Scale Factor (lines 189-192)

   • Integer division when calculating scale factor could cause precision loss
   • Consider using higher precision intermediate calculations

3. Missing Edge Case Validation

   • While zero balance check exists, consider behavior when balances are very small relative to x0, y0
   • Add tests for dust amounts and extreme ratios

Performance Considerations ⚡

1. Double Invariant Calculation (lines 171-173, 200-202)

   • Computing C0 and C1 both involve expensive sqrt operations
   • Consider if C1 can be derived from C0 more efficiently using the scale factor relationship

2. Redundant Calculations

   • Some values like config.x0 + config.y0 could be cached if used multiple times

3. Gas Optimization Opportunities

   • Consider using unchecked blocks for operations that are mathematically guaranteed to be safe
   • Document safety assumptions clearly when doing so

Security Concerns 🔒

1. Overflow Protection: ✅ Excellent use of Math.mulDiv throughout

2. Reentrancy: ✅ Pure function with no external calls

3. Input Validation: ✅ Comprehensive validation in args parser

4. Rounding Direction: ⚠️

   • Line 215: amountOut rounds down (good - protects maker)
   • Line 250: amountIn rounds up (good - protects maker)
   • Ensure ALL intermediate calculations round correctly

5. Fee Rate Bounds: ✅ Properly checked < 1e9 (100%)

Test Coverage 🧪

Strengths:

• Comprehensive tests for strict additivity property
• Multiple test scenarios (2 chunks, 4 chunks)
• Clear console output showing mathematical properties

Critical Gaps:

1. No Exact-Out Tests: Given the approximation issues identified, this is critical
2. Edge Cases Missing:
   • Very large trades relative to pool size
   • Dust amounts (< 1000 wei)
   • Maximum fee rate (close to 100%)
   • Imbalanced pools (x >> y or y >> x)
3. No Fuzz Testing: Add fuzz tests to verify additivity holds for random inputs
4. No Gas Benchmarks: Add gas consumption tests for different trade sizes

Additional Recommendations

1. Exact-Out Implementation Priority: This needs immediate attention. Either:

   • Implement proper iterative solution with convergence criteria
   • Document approximation error bounds explicitly
   • Add comprehensive tests demonstrating accuracy

2. Error Analysis: Add tests that quantify the maximum deviation from strict additivity due to rounding

3. Integration Tests: Test interaction with other SwapVM instructions

4. Documentation: The LaTeX document is excellent. Consider adding:

   • Numerical examples showing additivity
   • Error bounds for the exact-out approximation
   • Comparison table with actual numbers

5. Monitoring Considerations: Consider events or metrics to track:

   • Pool growth (D changes) over time
   • Fee collection efficiency
   • Approximation errors in exact-out swaps

Conclusion

This is an innovative and well-thought-out implementation with strong mathematical foundations. The strict additivity property is valuable for composability and aggregator neutrality. However, the exact-out approximation issue is a blocker that must be addressed before merging. With the suggested improvements, particularly around exact-out accuracy and comprehensive edge case testing, this will be a solid addition to SwapVM.

Recommended Actions:

1. Fix exact-out implementation (critical)
2. Add comprehensive test coverage for edge cases
3. Add fuzz testing for additivity property
4. Consider performance optimizations
5. Document approximation error bounds if keeping current approach

[claude]

Claude finished @ifelsedeveloper's task —— View job

---

Todo List:

• Check for CLAUDE.md repo guidelines
• Review PeggedSwapReinvest.sol implementation
• Review test coverage in PeggedSwapReinvest.t.sol
• Check integration with Opcodes.sol
• Analyze security considerations
• Evaluate performance optimizations
• Provide comprehensive review feedback

Code Review - PeggedSwapReinvest Implementation

Summary

This PR introduces a mathematically rigorous implementation of a strictly-additive swap mechanism using a semigroup D-update approach. The implementation is well-documented and shows strong theoretical foundations. However, there are critical issues that need to be addressed before merging.

Code Quality and Best Practices ✅

Strengths:

• Excellent mathematical documentation with clear LaTeX explanations
• Clean separation of concerns (args builder, core logic)
• Proper use of custom errors for gas efficiency
• Good use of OpenZeppelin's Math library for safe operations
• Clear variable naming and structure

Areas for Improvement:

1. Magic Numbers: Line 54 uses 192 bytes directly - define as a named constant
2. Code Comments: While mathematical theory is documented, implementation details could use more inline comments
3. Consistency: Consider standardizing variable naming (e.g., x0_raw → balanceInRaw, x0 → normalizedBalanceIn)

Potential Bugs or Issues 🐛

1. CRITICAL: Exact Output Implementation (lines 219-250)

   • The exact-out case uses a crude approximation: amountIn ≈ amountIn_nofee / (1 - f)
   • This is only accurate for small fees and could lead to significant errors
   • For a 1% fee, the error could be ~0.01% which may be exploitable at scale
   • Recommendation: Implement iterative Newton-Raphson solver or derive closed-form solution

2. Precision Loss in Scale Factor (lines 189-192)

   • Integer division when calculating scale factor could accumulate precision loss
   • Consider using higher precision intermediate calculations

3. Missing Validation

   • No checks for extreme pool imbalances (when x >> y or y >> x)
   • Edge case behavior for very small trades (dust amounts) not validated

Performance Considerations ⚡

1. Redundant Invariant Calculations (lines 171-173, 200-202)

   • Both C0 and C1 require expensive sqrt operations
   • Consider if C1 can be derived more efficiently using the scale relationship

2. Gas Optimization Opportunities

   • Multiple Math.mulDiv calls could benefit from caching frequently used values
   • Consider using unchecked blocks where overflow is mathematically impossible (with clear documentation)

3. Storage Access Pattern

   • Good use of calldata for args, minimizing gas costs

Security Concerns 🔒

1. Overflow Protection: ✅ Excellent use of Math.mulDiv throughout
2. Reentrancy: ✅ Pure function with no external calls
3. Input Validation: ✅ Comprehensive validation in args parser
4. Fee Rate Bounds: ✅ Properly checked < 1e9 (100%)
5. Rounding Direction: ⚠️
   • Line 215: amountOut rounds down (good)
   • Line 250: amountIn rounds up via ceilDiv (good)
   • Ensure all intermediate calculations maintain correct rounding direction

Test Coverage 🧪

Strengths:

• Comprehensive strict additivity tests
• Multiple scenarios (2 chunks, 4 chunks, 100 swaps)
• Tests with different fee rates (0.3%, 1%)
• Round-trip tests verifying no arbitrage opportunities

Critical Gaps:

1. No Exact-Out Tests: Given the approximation issues, this is critical
2. Missing Edge Cases:
   • Extreme trades (50%+ of pool)
   • Dust amounts (< 1000 wei)
   • Maximum fee rate (close to 100%)
   • Highly imbalanced pools
3. No Fuzz Testing: Property-based tests would strengthen confidence
4. No Gas Benchmarks: Important for comparing with other fee mechanisms

Mathematical Analysis 📐

The semigroup property Γ(Γ(D,a),b) = Γ(D,a+b) is elegantly implemented through additive pool growth. The mathematical documentation clearly explains how this achieves strict additivity.

Key Insight: By growing D deterministically with volume (D₁ = D₀ + f·Δ), the mechanism ensures path independence - a valuable property for composability.

Additional Recommendations

1. Exact-Out Priority: The approximation is the biggest blocker. Either:

   • Implement proper iterative solution with convergence criteria
   • Document maximum error bounds explicitly
   • Add comprehensive tests demonstrating accuracy across fee ranges

2. Error Analysis: Add tests quantifying maximum deviation from strict additivity due to rounding

3. Documentation Enhancement: The LaTeX document is excellent. Consider adding:

   • Numerical examples with actual values
   • Error bounds for the exact-out approximation
   • Comparison table with concrete numbers

4. Monitoring: Consider events to track:

   • Pool growth (D changes)
   • Approximation errors in exact-out swaps

Conclusion

This is an innovative implementation with strong theoretical foundations and clear benefits for aggregator neutrality. The strict additivity property is valuable for the DeFi ecosystem. However, the exact-out approximation is a critical issue that must be resolved before merging.

Recommended Actions:

1. Fix exact-out implementation (critical blocker)
2. Add comprehensive edge case tests
3. Add fuzz testing for additivity property
4. Document approximation error bounds if keeping current approach
5. Consider performance optimizations for invariant calculations

Once these issues are addressed, particularly the exact-out accuracy, this will be a solid addition to SwapVM.

[claude]

Claude finished @ifelsedeveloper's task —— View job

---

Todo List:

• Check for CLAUDE.md repo guidelines (no file found)
• Review PeggedSwapReinvest.sol implementation
• Review test coverage in PeggedSwapReinvest.t.sol
• Check integration with Opcodes.sol
• Analyze security considerations
• Evaluate performance optimizations
• Provide comprehensive review feedback

Code Review - PeggedSwapReinvest Implementation

Summary

This PR introduces an innovative strictly-additive swap mechanism using a semigroup D-update approach. The implementation is mathematically rigorous and addresses a real problem in DeFi - providing path-independent swap outcomes regardless of trade chunking. However, there are critical issues that need to be addressed before merging.

Code Quality and Best Practices ✅

Strengths:

• Excellent mathematical documentation with clear LaTeX explanations
• Clean separation of concerns (args builder, core swap logic)
• Proper use of custom errors for gas efficiency
• Good use of OpenZeppelin's Math library for safe operations
• Clear variable naming and logical structure

Areas for Improvement:

1. Magic Numbers: Line 54 in PeggedSwapReinvest.sol uses 192 directly. Define as a named constant:

   uint256 private constant ARGS_LENGTH = 192; // 6 * 32 bytes

2. Code Comments: While mathematical theory is well-documented, implementation details could use more inline comments explaining the "why" behind certain calculations.

3. Variable Naming: Consider more descriptive names:

   • x0_raw → balanceInRaw
   • y0_raw → balanceOutRaw
   • x0 → normalizedBalanceIn
   • y0 → normalizedBalanceOut

Potential Bugs or Issues 🐛

1. CRITICAL: Exact Output Implementation (PeggedSwapReinvest.sol:219-250)

   • The exact-out case uses a crude approximation that can lead to significant errors
   • Line 243-247: amountIn ≈ amountIn_nofee / (1 - f) is only accurate for small fees
   • For a 1% fee, the error could be ~0.01% which may be exploitable at scale
   • Recommendation: Implement iterative Newton-Raphson solver or derive a proper closed-form solution

2. Precision Loss in Scale Factor (PeggedSwapReinvest.sol:189-192)

   • Integer division when calculating scale factor could accumulate precision loss over many operations
   • Consider using higher precision intermediate calculations or rounding strategies

3. Missing Edge Case Validation

   • No validation for extreme pool imbalances (when x >> y or y >> x)
   • Edge case behavior for dust amounts not tested
   • Consider adding bounds checks for extreme scenarios

Performance Considerations ⚡

1. Redundant Invariant Calculations (PeggedSwapReinvest.sol:171-173, 200-202)

   • Both C0 and C1 require expensive sqrt operations
   • Consider if C1 can be derived more efficiently using the relationship: C1 = C0 * scaleFactor

2. Gas Optimization Opportunities

   // Current code performs multiple divisions
   uint256 scaleFactor = PeggedSwapMath.ONE + Math.mulDiv(
       feeContribution,
       PeggedSwapMath.ONE,
       refPoolSize
   );
   
   // Could cache frequently used values
   uint256 refPoolSize = config.x0 + config.y0; // Used multiple times

3. Unchecked Math Blocks

   • Some operations are mathematically guaranteed safe (e.g., after proper validation)
   • Consider using unchecked blocks with clear documentation for gas savings

Security Concerns 🔒

Strengths:

• ✅ Excellent overflow protection using Math.mulDiv throughout
• ✅ Pure function with no external calls (no reentrancy risk)
• ✅ Comprehensive input validation in args parser
• ✅ Fee rate properly bounded < 100%

Areas of Attention:

1. Rounding Direction:

   • Line 215: amountOut rounds down (good - protects maker)
   • Line 250: amountIn uses ceilDiv (good - protects maker)
   • Ensure ALL intermediate calculations maintain correct rounding direction

2. Exact-Out Accuracy: The approximation issue could lead to:

   • Traders getting better rates than intended
   • Pool imbalances over time
   • Potential arbitrage opportunities

Test Coverage 🧪

Strengths:

• Comprehensive strict additivity tests (2 chunks, 4 chunks, 100 swaps)
• Multiple fee rate scenarios (0.3%, 1%)
• Round-trip tests verifying no arbitrage
• Clear console output showing mathematical properties

Critical Gaps:

1. No Exact-Out Tests: Given the approximation issues, this is critical
2. Missing Edge Cases:
   • Very large trades (50%+ of pool)
   • Dust amounts (< 1000 wei)
   • Maximum fee rate scenarios (close to 100%)
   • Highly imbalanced pools (x:y ratio > 10:1)
3. No Fuzz Testing: Property-based tests would strengthen confidence in additivity
4. No Gas Benchmarks: Important for comparing with other fee mechanisms

Mathematical Analysis 📐

The semigroup property Γ(Γ(D,a),b) = Γ(D,a+b) is elegantly implemented through additive pool growth. The key insight of growing D deterministically with volume (D₁ = D₀ + f·Δ) ensures path independence.

Benefits verified:

• Aggregator neutrality ✅
• Predictable LP revenue ✅
• No gaming of execution paths ✅

Additional Recommendations

1. Exact-Out Priority (Critical):

   // Consider implementing iterative solution
   function solveExactOut(uint256 targetOut, uint256 maxIterations) internal pure returns (uint256) {
       // Newton-Raphson or binary search
   }

2. Error Analysis: Add tests quantifying maximum deviation from strict additivity due to rounding

3. Integration Tests: Test interaction with other SwapVM instructions, especially fee instructions

4. Documentation Enhancement: The LaTeX document is excellent. Consider adding:

   • Numerical examples with actual values
   • Error bounds for the exact-out approximation
   • Gas comparison with other fee mechanisms

5. Events/Monitoring: Consider emitting events for:

   • Pool growth (D changes) for analytics
   • Large approximation errors in exact-out swaps

Conclusion

This is an innovative implementation with strong theoretical foundations and clear benefits for the DeFi ecosystem. The strict additivity property is particularly valuable for composability. However, the exact-out approximation is a critical blocker that must be resolved.

Recommended Actions:

1. Fix exact-out implementation (critical blocker)
2. Add comprehensive edge case tests
3. **Add fuzz testing for additivity property
4. Document approximation error bounds if keeping current approach
5. Consider performance optimizations for invariant calculations

Once these issues are addressed, particularly the exact-out accuracy, this will be a solid addition to SwapVM. The mathematical rigor and clear benefits make this a valuable feature.