Superlend Looping Protocol Documentation

Overview

The Superlend Looping Protocol is a comprehensive DeFi system that enables users to perform leverage operations using Aave V3 flash loans and universal DEX swaps. It allows users to either increase their leverage (loop) or decrease it (unloop) in a single atomic transaction through a modular architecture consisting of looping helpers and user-specific strategy contracts.

Protocol Architecture

The protocol consists of two main layers:

1. Looping Layer (/src/looping/): Core flash loan and swap execution logic
2. Strategy Layer (/src/strategy/): User-specific strategy management contracts

Looping Layer Components

Core Contracts

• LoopingHelper: Main contract for executing loop/unloop operations via Aave V3 flash loans
• LoopingHelperSwaps: Handles token swaps through universal DEX module
• LoopingHelperEncoding: Manages parameter encoding/decoding for flash loan callbacks
• DataTypes: Library containing data structures for loop/unloop operations

Inheritance Structure

• LoopingHelper: Inherits from FlashLoanSimpleReceiverBase, ReentrancyGuard, LoopingHelperSwaps, LoopingHelperEncoding
• LoopingHelperSwaps: Abstract contract for swap operations
• LoopingHelperEncoding: Abstract contract for parameter encoding/decoding

Key Data Structures

• Operation enum: Defines two operations
  • LOOP: For increasing leverage
  • UNLOOP: For decreasing leverage
• LoopCallParams: Parameters for initiating loop operations
• UnloopCallParams: Parameters for initiating unloop operations
• LoopParams: Internal parameters for loop execution during flash loan callback
• UnloopParams: Internal parameters for unloop execution during flash loan callback

Core Functions

Public Functions

1. loop(DataTypes.LoopCallParams memory params)

   • Initiates a leverage increase operation
   • Transfers supply tokens from user to contract
   • Executes flash loan for additional leverage
   • Handles token approvals and supplies

2. unloop(DataTypes.UnloopCallParams memory params)

   • Initiates a leverage decrease operation
   • Uses flash loan to repay debt
   • Withdraws collateral and handles swaps

Flash Loan Callback

1. executeOperation(address, uint256 amount, uint256 premium, address, bytes calldata params)
   • Callback function for Aave V3 flash loans
   • Routes to appropriate operation based on encoded params
   • Handles both loop and unloop operations

Internal Functions

1. _executeLoop(DataTypes.LoopParams memory loopParams, uint256 amount, uint256 premium)

   • Core logic for loop operations during flash loan callback
   • Manages token supplies, borrows, and swaps
   • Handles leftover amounts and flash loan repayment

2. _executeUnloop(DataTypes.UnloopParams memory unloopParams, uint256 amount, uint256 premium)

   • Core logic for unloop operations during flash loan callback
   • Manages debt repayment and collateral withdrawal
   • Handles token swaps and flash loan repayment

3. _handleLeftOverAmounts(address supplyToken, address borrowToken, uint256 leftOverSupplyAmount, uint256 leftOverBorrowAmount, address user)

   • Handles any remaining tokens after operations
   • Supplies leftover yield tokens back to Aave
   • Repays leftover debt tokens

Strategy Layer Components

The Superlend Looping Strategy system enables each user to deploy dedicated strategy contracts that manage their leveraged positions. This pattern provides isolation, flexibility, and user-specific control over leverage and unloop operations.

Architecture

Inheritance Structure

• SuperlendLoopingStrategyFactory: Ownable factory for deploying user strategy contracts
• SuperlendLoopingStrategy: Ownable contract managing a user's looped position, inherits from SuperlendLoopingStrategyStorage
• SuperlendLoopingStrategyStorage: Abstract contract holding configuration and state for each strategy instance

Key Components

1. Data Structures

• userStrategies: Mapping from user address to their deployed strategy contracts
• existingStrategies: Mapping to prevent duplicate strategies for the same asset pair and eMode

2. Core Functions

Factory

• createStrategy(address _loopingHelper, address _pool, address _yieldAsset, address _debtAsset, uint8 _eMode)

  • Deploys a new strategy contract for the user
  • Ensures uniqueness per asset pair and eMode
  • Emits StrategyDeployed event

• getUserStrategies(address _user): Returns all strategy addresses for a user

• getUserStrategy(address _user, address _pool, address _yieldAsset, address _debtAsset, uint8 _emode): Returns a specific strategy address

• getStrategyId(address pool, address yieldAsset, address debtAsset, uint8 eMode): Generates unique strategy ID

Strategy

• openPosition(uint256 supplyAmount, uint256 flashLoanAmount, uint256 borrowAmount, ExecuteSwapParams memory swapParams, uint256 delegationAmount)

  • Transfers user collateral to the strategy
  • Delegates borrowing power to the looping helper contract
  • Calls loop on LoopingHelper to open a leveraged position

• closePosition(uint256 repayAmount, uint256 withdrawAmount, ExecuteSwapParams memory swapParams, uint256 aTokenAmount, uint256 exitPositionAmount)

  • Optionally repays debt and unloops via LoopingHelper
  • Withdraws collateral from the lending pool to the user

• setLoopingHelper(address __loopingHelper): Updates the looping helper contract address

• skim(address[] memory tokens): Emergency function to recover stuck tokens

Storage

• Holds addresses for pool, yield asset, debt asset, aToken, variableDebtToken, and looping helper
• Manages eMode configuration and validation
• Provides getter functions for all configuration parameters

Security Features

Looping Layer

1. Reentrancy Protection

   • Uses OpenZeppelin's ReentrancyGuard
   • All public functions are marked with nonReentrant
   • Prevents reentrancy attacks during complex operations

2. Access Control

   • Flash loan callback verification
   • Strict checks for flash loan caller (only Aave pool)
   • User-specific operations with proper authorization

3. Input Validation

   • Parameter validation through structs
   • Swap parameter validation
   • Amount validation for operations

4. Safe Token Handling

   • Proper approval management using SafeERC20
   • Balance checks before operations
   • Safe transfer operations

Strategy Layer

1. Access Control

   • Only the owner (user) can operate their strategy contract
   • Factory ownership controls for administrative functions

2. Factory Uniqueness

   • Prevents duplicate strategies for the same asset pair/eMode
   • Unique strategy ID generation based on configuration

3. Delegation

   • Uses Aave credit delegation for safe borrowing
   • Proper approval management for aTokens

4. E-Mode Validation

   • Validates E-Mode consistency between yield and debt assets
   • Ensures proper asset correlation for higher collateralization ratios

Operational Flow

Loop Operation

1. User calls openPosition on their strategy contract
2. Strategy transfers yield tokens from user and approves looping helper
3. Strategy sets up credit delegation if specified
4. Strategy calls loop on LoopingHelper with parameters
5. LoopingHelper executes flash loan
6. During flash loan callback:
   • Supplies combined amount (user tokens + flash loan) to Aave
   • Borrows specified amount from Aave
   • Swaps borrowed tokens back to yield tokens
   • Handles leftover amounts
   • Repays flash loan

Unloop Operation

1. User calls closePosition on their strategy contract
2. Strategy approves aTokens for looping helper
3. Strategy calls unloop on LoopingHelper with parameters
4. LoopingHelper executes flash loan
5. During flash loan callback:
   • Repays borrowed tokens using flash loan funds
   • Withdraws supplied tokens from Aave
   • Swaps withdrawn tokens to repay flash loan
   • Handles leftover amounts
   • Repays flash loan
6. Strategy withdraws remaining tokens to user

Deploying a Strategy

1. User calls createStrategy on the factory
2. Factory generates unique strategy ID
3. Factory deploys new SuperlendLoopingStrategy contract
4. Factory registers strategy in user's strategy list
5. User interacts with their strategy contract to open/close positions

Integration Points

Aave V3

• Flash loan functionality
• Lending pool operations (supply, borrow, repay, withdraw)
• Reserve data access
• Credit delegation
• E-Mode configuration

Universal DEX Module

• Token swaps for loop/unloop operations
• Price execution
• Slippage protection
• Multi-DEX routing

Token Standards

• ERC20 token handling
• SafeERC20 for secure transfers
• Proper approval management

Limitations and Considerations

Market Risk

• Price impact during swaps
• Slippage considerations
• Market volatility effects
• Flash loan premium costs

Protocol Risk

• Aave protocol changes
• DEX protocol changes
• Token listing/delisting
• E-Mode category changes

Gas Considerations

• Complex operations may be gas-intensive
• Multiple token approvals required
• Strategy deployment costs per user
• Flash loan execution costs

Operational Limitations

• One strategy per asset pair/eMode per user
• Strategy uniqueness constraints
• E-Mode validation requirements
• Credit delegation limits

Recommendations for Usage

Pre-operation Checks

1. Token Approvals

   • Verify sufficient token approvals for strategy contract
   • Check looping helper approvals
   • Validate credit delegation amounts

2. Balance Verification

   • Ensure sufficient token balances
   • Check Aave position health factors
   • Validate swap parameters

3. Configuration Validation

   • Verify E-Mode compatibility
   • Check asset pair configuration
   • Validate strategy contract setup

Post-operation Verification

1. Execution Confirmation

   • Verify successful operation execution
   • Check final token balances
   • Monitor gas costs

2. Position Monitoring

   • Track health factors
   • Monitor collateralization ratios
   • Check for any leftover amounts

Risk Management

1. Position Monitoring

   • Regular health factor checks
   • Monitor market conditions
   • Track protocol updates

2. Fee Management

   • Account for flash loan premiums
   • Consider swap fees and slippage
   • Monitor gas costs

3. Emergency Procedures

   • Keep strategy contract addresses safe
   • Monitor for stuck tokens
   • Have emergency exit strategies